Quickstart: Awaken with an Unreal game
In this quickstart you build the Floppy Bird tutorial project, run it with its built-in pilot, and watch the same rows in the game itself, in the panel that the AwakenDebug plugin draws inside the game’s frame. You then see them in GameGen’s Awaken view and, for a game without the plugin’s egui library, in the Awaken app’s overlay. Floppy Bird has no NPCs of its own, so it lists what it has: the bird and each pair of pillars.
These steps were checked on macOS (Apple silicon) with Unreal Engine 5.9. Windows and Linux are not yet verified.
Before you start
| You need | Detail |
|---|---|
| GameGen | Install it from the Unrest Launcher. |
| Unreal Engine 5.9 | With its C++ toolchain for your platform. |
| A JavaScript runtime | Node 18 or later, Bun or Deno, for the project’s Scripts/ue.mjs wrapper. |
| The Awaken app (optional, for step 5) | Run from an awaken source checkout with a Rust toolchain. See Awaken app. |
1. Create and build the project
Create the tutorial project
In GameGen, open the New game dialog and choose the Floppy Bird tutorial. The project already contains the AwakenDebug plugin in Plugins/AwakenDebug/, turned on in the .uproject. See The tutorial project for the dialog.
Build it
Close the project’s Unreal editor if it is open. In a terminal, in the project folder, run:
node Scripts/ue.mjs build --engine-root /path/to/UE_5.9You can set UE_ROOT instead of passing --engine-root. A first build takes several minutes.
Before the Unreal build, the script prints one line about Awaken’s egui library. The in-game Awaken panel is drawn by egui. means the library is staged. A line that starts Awaken egui library: not built: means the game will show the text HUD instead. See How a project gets the library.
2. Run the game with the pilot
The tutorial has a built-in pilot, Floppy.Autopilot, that flaps for you so the rows keep changing.
Standalone window
Start the game in its own window, with the panel and the pilot already on. Use the UnrealEditor program of your engine installation:
UnrealEditor FloppyBird.uproject -game -windowed -resx=960 -resy=540 -ExecCmds="Awaken.Debug 1, Floppy.Autopilot 1"3. See the rows in the game
Show the panel
Press F10, or enter Awaken.Debug 1 in the console. If you started the game with the command above, the panel is already on.
With the egui library staged, the game draws Awaken’s roster and inspector inside its own frame. Without it, the game draws the text HUD, whose first line reads Awaken NPCs (N) F10 hide, PgUp/PgDn select.
Read the roster
The roster has one entry per row:
| Row | Status | Goal and blackboard |
|---|---|---|
| Bird | Ready, Playing or GameOver | Goal pass pillar pair N while playing. Blackboard keys tick, score, z, velocity, gapSeed, and for the next pair nextPair, nextGapZ, nextGapDistance and heightAboveGapCenter. |
| Pillar pair N | Ahead, AtBird or Passed | Blackboard keys x, gapCenterZ, gapBottomZ and gapTopZ. |
Select a row
In the panel, click a roster row. The click is taken by the panel; a click anywhere else reaches the game. Page Down and Page Up also move the selection, in the panel and in the text HUD. The inspector shows the selected row’s goals, blackboard and tree.
Filter the roster
In the panel, click the filter field and type, for example pair 1. The game keeps running. Press Esc to give the keyboard back to the game.
While the game runs, the plugin also writes .unrest/awaken/npcs.json in the project folder. The next two steps read it.
4. See the rows in GameGen
Open the project in GameGen
Open the Floppy Bird project folder in GameGen.
Open the Awaken view
Choose Awaken in the sidebar. In the Awaken (NPCs & QA) view, choose the NPCs tab.
Read the roster
While the game publishes, the status line reads Live: N NPCs. Each row under Roster shows the name, the status and the current goal.
Inspect a row
Click a row. Selected NPC shows its position, current goal, goals, blackboard and behaviour tree.
The NPCs tab was verified in the real app with a fixture publisher that writes the NPC file. A real Unreal game as the publisher into this tab is not yet verified. See GameGen view.
5. See the rows in the Awaken app
This step is for a game whose plugin was built without the egui library, and for what the in-game panel does not show: the daemon’s connection and the QA strip. With the in-game panel you can skip it.
Start Awaken on the project
In the awaken checkout, run:
cargo run -p awaken-app -- --project /path/to/FloppyBird --overlayFind the overlay
On macOS the overlay covers the game window. Its second line reads, for example, attached to UnrealEditor (pid 1234), game window.
Read the roster
The NPCS column lists the bird and the pillar pairs with status and goal. Next to it the panel says where the rows come from, from daemon or direct from game file, and how fresh they are, for example last update 0.3 s ago.
Inspect a row
Select a row. The INSPECTOR column shows its position, goals, behaviour tree and blackboard.
The overlay following the game window while you drag it has not been verified on a live game. On Windows and Linux the overlay does not attach to the game window: it is a floating panel on the primary monitor. See Platform support.
6. Stop the game
Quit the game or stop Play In Editor. The plugin deletes the NPC file, and the rosters empty. In GameGen the status line reads The game stopped publishing. If the game is killed instead, the file stays behind; five seconds later the Awaken app reads game stopped publishing, followed by the time of the last update.
Next steps
- Add your own NPCs: Register NPCs in C++ or in Blueprint.
- Use
Source/FloppyBird/FloppyAwakenDebug.cppin the tutorial as a pattern. - Read the NPC file contract.