Awaken
Awaken is NPC and QA debugging for games. It shows who a game’s NPCs are, their status, current goal, goal list, behaviour tree and blackboard while the game runs, and it lists the project’s recent QA runs. It works with Unreal Engine games made in GameGen.
Awaken only reads. Nothing is sent back to the game, and no game state is changed.
Awaken for Unreal has been checked end to end on macOS (Apple silicon) with Unreal Engine 5.9. Windows and Linux are not yet verified. Each page says what has and has not been checked.
The pieces
| Piece | What it is | What it does |
|---|---|---|
| AwakenDebug | An Unreal Engine plugin in your game project. | Collects the NPCs your game registers. Draws the roster and the inspector inside the game’s own frame, or a text HUD when its egui library is not built. Writes the NPC file while the game runs. |
| The NPC file | .unrest/awaken/npcs.json in the project folder. | Carries the current NPC rows out of the game, a few times a second. |
| The project daemon | The AgentLoop daemon that serves the project. GameGen and the Awaken app both use it. | Reads the NPC file and publishes its rows as the npcs slice of its state. |
| The Awaken app | A desktop app with a launcher window, a tray icon and an overlay. | Shows the roster and an inspector in an overlay over the game window. This is the path for a game whose plugin has no egui library. |
| GameGen’s Awaken view | The Awaken (NPCs & QA) view in GameGen. | Lists the project’s QA runs, and shows the live NPC roster with an inspector. |
How the data flows
The data moves in one direction, from the game to the viewers:
- Game. Your game registers its NPCs with AwakenDebug, in C++ or Blueprint. Actors with an AgentLoopBT behaviour tree are picked up without any code.
- File. While a game or Play In Editor session runs, AwakenDebug writes the NPC file at most four times a second and at least once a second. It deletes the file when play ends.
- Daemon. The project’s daemon reads the file four times a second. A file that passes the contract becomes the
npcsslice. A missing, stale or rejected file becomes an empty slice. - Viewers. The Awaken app and GameGen show the rows from the daemon’s
npcsslice. When no daemon publishes that slice, the Awaken app reads the file itself and labels the rows direct from game file.
The in-game panel and the text HUD do not use the file at all. They draw straight from the plugin, so it works with no daemon and no other app running.
When the game stops, the file’s timestamps stop too. Five seconds later every reader treats it as stale and shows no rows.
What you can see where
| Where | NPC roster | Goals, tree and blackboard of one NPC | QA runs |
|---|---|---|---|
| In-game panel or text HUD (AwakenDebug) | Yes | Yes | No |
| Awaken app overlay | Yes | Yes | The five most recent, when a daemon is connected |
| GameGen, Awaken (NPCs & QA) | Yes | Yes | Yes |
In this section
See the Floppy Bird tutorial’s bird and pillars in all three places.
Quickstart: UnrealAdd AwakenDebug to a project and register NPCs.
Unreal pluginThe contract: fields, limits and staleness.
The NPC fileOpen a project and attach the overlay.
Awaken appThe QA and NPCs tabs.
GameGen viewTroubleshootingNext steps
- Follow the Unreal quickstart.
- Or go straight to installing the plugin in your own project.