Skip to Content
AwakenOverview

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.

Status

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

PieceWhat it isWhat it does
AwakenDebugAn 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 daemonThe 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 appA 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 viewThe 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:

  1. Game. Your game registers its NPCs with AwakenDebug, in C++ or Blueprint. Actors with an AgentLoopBT behaviour tree are picked up without any code.
  2. 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.
  3. Daemon. The project’s daemon reads the file four times a second. A file that passes the contract becomes the npcs slice. A missing, stale or rejected file becomes an empty slice.
  4. Viewers. The Awaken app and GameGen show the rows from the daemon’s npcs slice. 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

WhereNPC rosterGoals, tree and blackboard of one NPCQA runs
In-game panel or text HUD (AwakenDebug)YesYesNo
Awaken app overlayYesYesThe five most recent, when a daemon is connected
GameGen, Awaken (NPCs & QA)YesYesYes

In this section

Next steps

Last updated on