Skip to Content
AwakenAwaken appOpen a project

Open a project in Awaken

You point Awaken at a game’s project folder. Awaken recognises the folder as an Unreal game, connects to the project’s daemon, and offers to attach the overlay to the game’s window.

Before you start

Awaken recognises a folder as an Unreal game when both of these are true:

  • The folder has a .uproject file at its root.
  • The folder has .unrest/gamegen.json, and its engine value is "unreal".

Projects made in GameGen have both. Detection only reads those two things; it never runs Unreal.

Open a project from the launcher window

Find the Game card

Start Awaken. On the Overview page, find the Game card. Under OPEN A PROJECT is a path field.

Give Awaken the folder

Do one of these:

  • Type or paste the project folder, or the path of its .uproject file, then choose Open or press Return.
  • Drop the folder or the .uproject file on the window.
  • On macOS, choose Browse… and pick the folder.

Check the card

The card now shows the project’s name, the label Unreal game, the note made in GameGen, and the path of the .uproject file. It offers Attach overlay.

If the folder is not recognised, the card shows the path and one line that says why:

MessageMeaning
Not a GameGen Unreal game: not a folder.The path is not a folder.
Not a GameGen Unreal game: no .uproject file at the folder's root.There is no .uproject at the top level. A .uproject in a sub-folder does not count.
Not a GameGen Unreal game: no .unrest/gamegen.json (not a GameGen project).The project was not made in GameGen.
Not a GameGen Unreal game: GameGen engine is "roblox", not "unreal".The project is a GameGen project for another engine.

An empty path field gives Enter a project folder.

Open a project from the command line

cargo run -p awaken-app -- --project /path/to/MyGame --overlay
FlagEffect
--project <path>The project folder or its .uproject file.
--overlayShow the overlay at once and attach it to the game’s window.
--no-autostartDo not start a daemon. Awaken then reads the game’s NPC file directly unless a daemon is already running.

You can also set AWAKEN_PROJECT_PATH. The --project flag overrides it. With neither, Awaken opens a project folder in its own data directory.

Reopen a recent project

Opened projects are remembered under RECENT on the Game card.

  • Select a project’s name to open it again.
  • Choose Forget to remove it from the list. This does not touch the project.

The list is kept in recent-projects.json in Awaken’s data directory. Set AWAKEN_RECENTS_FILE to keep it somewhere else.

Try it without Unreal

Awaken has a stand-in for a running game. It writes the NPC file the way the plugin does, with three NPCs that move and change state four times a second.

Start the stand-in

In the awaken folder, in one terminal:

cargo run -p awaken-app --example npc_fixture -- /tmp/ScratchBird --scaffold --window

--scaffold creates a scratch project shaped like a GameGen Unreal project. --window opens a stand-in game window the overlay can attach to.

Start Awaken

In a second terminal:

cargo run -p awaken-app -- --project /tmp/ScratchBird --overlay --no-autostart
Stand-in optionEffect
--seconds 20Stop publishing after 20 seconds, to see the “game stopped publishing” state.
--move-after 8Move and resize the window once, to see the overlay follow.
No --windowOnly write the file. The overlay is then a floating panel.

Next steps

Last updated on