Awaken reference
This page collects the fixed values of Awaken for Unreal in one place: the limits readers enforce, the limits the plugin applies when it writes, the timings, the environment variables the Awaken app reads, and the terms used in these docs.
Limits readers enforce
A file over any of these is rejected whole.
| Limit | Value |
|---|---|
| File size | 262,144 bytes (256 KiB), on disk |
| Rows | 64 |
| Row bytes | 32,768 bytes (32 KiB): the npcs array as compact JSON, brackets included |
source | 64 UTF-8 bytes, no control characters |
| Staleness | 5,000 ms, for the modification time and for updatedAtMs, in either direction |
| Schema | awaken-npcs/1 |
Limits of what the plugin writes
AwakenDebug stays inside the readers’ limits by cutting detail. The same state always produces the same bytes.
| Limit | What happens beyond it |
|---|---|
| 64 rows | With a local player, the 64 NPCs nearest the player’s view are kept. With no player, the first 64 registered. Rows stay in registration order. |
| Id and name: 96 characters | Cut, ending in …. |
| Status: 64 characters | Cut, ending in …. |
| Goal: 256 characters | Cut, ending in …. |
| 16 goals in the list | The rest are left out. |
| 32 blackboard keys | The first 32 by name are kept, plus a _truncated key that says how many more there are. |
| A blackboard text value over 256 characters | Replaced by a marker that gives its length, such as <truncated: 900 chars>. |
| A tree over 8 KB | Replaced by {"truncated":true,"bytes":N}. |
| Rows over 32 KB in total | From the last row backwards, a row’s tree becomes {"truncated":true}, then its blackboard becomes {"_truncated":true}, then its goal list becomes [], until the rows fit. If that is still too big, whole rows are dropped from the end. |
The in-game HUD, the editor tab and Awaken.Dump are not bound by these limits. They show the full values, cut only to fit a line.
Numbers are written in their shortest plain form: whole numbers, and everything from a million up, as plain integers with no exponent; smaller fractions with six significant digits. Positions are rounded to 0.1.
Timings
| What | Value |
|---|---|
| AwakenDebug writes the file | At most four times a second, and only when a row changed or one second has passed |
| AwakenDebug collects from registered components | Four times a second |
| AwakenDebug looks for AgentLoopBT actors | Once a second |
| The daemon checks the file | Four times a second while it exists; once a second while it does not |
| The Awaken app’s direct reader checks the file | Five times a second |
| Rows disappear after the last write | Within about 5.3 seconds |
| The overlay checks the game window’s bounds | Ten times a second |
| GameGen reads the QA runs | Every 10 seconds while its window is visible |
Console variables and commands
| Name | Kind | Default |
|---|---|---|
Awaken.Debug | Variable, 0 or 1 | 0 |
Awaken.Debug.Scale | Variable, 0 or 0.5 to 4 | 0 |
Awaken.Publish | Variable, 0 or 1 | 1 |
Awaken.Select | Command: an id, next or prev | |
Awaken.Dump | Command |
Details are on Console commands.
Hotkeys
| Key | Where | Effect |
|---|---|---|
| F10 | In the game | Show or hide the AwakenDebug HUD. |
| Page Down, Page Up | In the game, HUD shown | Select the next or previous NPC. |
| ⌘ Shift F12 (macOS), Ctrl Shift F12 (Windows, Linux) | System-wide, Awaken app | Show or hide the overlay. |
| ⌘ Shift F11 (macOS), Ctrl Shift F11 (Windows, Linux) | System-wide, Awaken app | Toggle Pin. |
| F10 | System-wide, Awaken app, while a game project is open | Show or hide the overlay. Off with AWAKEN_NO_F10=1. |
Environment variables
Read by the Awaken app
| Variable | Meaning |
|---|---|
AWAKEN_PROJECT_PATH | Project directory to open. It also selects the daemon socket. Default: a project folder in Awaken’s data directory. The --project flag overrides it. |
AWAKEN_DAEMON_BIN | Path to the agentloop-daemon program to start. Checked first. |
AGENTLOOP_RUST_DAEMON | The daemon override that GameGen and AgentLoop also use. Checked second. |
AWAKEN_SOCKET_PATH | Use this socket path instead of deriving it from the project path. |
AWAKEN_MODEL | Model passed to a daemon that Awaken starts. |
AWAKEN_NO_AUTOSTART=1 | Never start a daemon; only attach to a running one. Same as the --no-autostart flag. |
AGENTLOOP_DAEMON_EXTERNAL=1 | Same effect as AWAKEN_NO_AUTOSTART=1. |
AWAKEN_NO_F10=1 | Do not register F10 as an overlay hotkey for game projects. |
AWAKEN_RECENTS_FILE | Where the recent projects list is kept. Default: recent-projects.json in Awaken’s data directory. |
Read by the daemon
| Variable | Meaning |
|---|---|
AGENTLOOP_TEMPLATES_DIR | Directory that contains templates/. Needed when the daemon program is not next to a templates/ directory, for example a development build. |
AGENTLOOP_MEMORY_BIN | Path to the agentloop-memory server program. |
Read by the tutorial’s build wrapper
| Variable | Meaning |
|---|---|
UE_ROOT | The Unreal Engine installation, instead of --engine-root, for Scripts/ue.mjs in a GameGen Unreal project. |
The AwakenDebug plugin reads no environment variables. It is controlled by its console variables.
Files and paths
| Path | What it is |
|---|---|
.unrest/awaken/npcs.json in the project | The NPC file. |
.unrest/gamegen.json in the project | Marks a GameGen project. Its engine value must be "unreal" for Awaken to treat the folder as an Unreal game. |
Plugins/AwakenDebug/ in the project | The plugin. |
recent-projects.json in Awaken’s data directory | The Awaken app’s recent projects. |
Glossary
| Term | Meaning |
|---|---|
| NPC | Any character or agent a game registers with AwakenDebug. It need not be an actor: a squad or a director can be one. |
| Row | One NPC as written in the NPC file: one entry of the npcs array. |
| Status | A short word or phrase for what an NPC is doing, such as Patrolling. |
| Goal | The goal an NPC is working on now. |
| Goal list | An NPC’s queue, stack or plan of goals, most important first. |
| Blackboard | An NPC’s named values: text, numbers and booleans. |
| Tree | A snapshot of an NPC’s behaviour tree, as a JSON object. |
| NPC file | .unrest/awaken/npcs.json, written by the game while it runs. |
| Publisher | The program that writes the NPC file. For Unreal games, AwakenDebug. |
| Reader | A program that reads the NPC file: the project daemon, or the Awaken app’s direct reader. |
| Project daemon | The AgentLoop daemon serving one project folder. GameGen and the Awaken app share it. |
| Slice | One named part of the daemon’s state. The NPC rows are the npcs slice; agent runs are in the executions slice. |
| Stale | A file whose modification time or updatedAtMs is more than 5 seconds from the reader’s clock. It shows no rows. |
| Rejected | A file that breaks the contract. It shows no rows, and the reader gives a reason. |
| Overlay | The Awaken app’s transparent, always-on-top window over the game. |
| Pin | Makes the overlay click-through, so every click goes to the game. |
| QA run | One execution of a QA agent on a task. |
| Play In Editor | Running the game inside the Unreal editor. |
Next steps
- The NPC file for the contract in full.
- Troubleshooting.