Skip to Content
AwakenReference

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.

LimitValue
File size262,144 bytes (256 KiB), on disk
Rows64
Row bytes32,768 bytes (32 KiB): the npcs array as compact JSON, brackets included
source64 UTF-8 bytes, no control characters
Staleness5,000 ms, for the modification time and for updatedAtMs, in either direction
Schemaawaken-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.

LimitWhat happens beyond it
64 rowsWith 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 charactersCut, ending in ….
Status: 64 charactersCut, ending in ….
Goal: 256 charactersCut, ending in ….
16 goals in the listThe rest are left out.
32 blackboard keysThe first 32 by name are kept, plus a _truncated key that says how many more there are.
A blackboard text value over 256 charactersReplaced by a marker that gives its length, such as <truncated: 900 chars>.
A tree over 8 KBReplaced by {"truncated":true,"bytes":N}.
Rows over 32 KB in totalFrom 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

WhatValue
AwakenDebug writes the fileAt most four times a second, and only when a row changed or one second has passed
AwakenDebug collects from registered componentsFour times a second
AwakenDebug looks for AgentLoopBT actorsOnce a second
The daemon checks the fileFour times a second while it exists; once a second while it does not
The Awaken app’s direct reader checks the fileFive times a second
Rows disappear after the last writeWithin about 5.3 seconds
The overlay checks the game window’s boundsTen times a second
GameGen reads the QA runsEvery 10 seconds while its window is visible

Console variables and commands

NameKindDefault
Awaken.DebugVariable, 0 or 10
Awaken.Debug.ScaleVariable, 0 or 0.5 to 40
Awaken.PublishVariable, 0 or 11
Awaken.SelectCommand: an id, next or prev
Awaken.DumpCommand

Details are on Console commands.

Hotkeys

KeyWhereEffect
F10In the gameShow or hide the AwakenDebug HUD.
Page Down, Page UpIn the game, HUD shownSelect the next or previous NPC.
⌘ Shift F12 (macOS), Ctrl Shift F12 (Windows, Linux)System-wide, Awaken appShow or hide the overlay.
⌘ Shift F11 (macOS), Ctrl Shift F11 (Windows, Linux)System-wide, Awaken appToggle Pin.
F10System-wide, Awaken app, while a game project is openShow or hide the overlay. Off with AWAKEN_NO_F10=1.

Environment variables

Read by the Awaken app

VariableMeaning
AWAKEN_PROJECT_PATHProject 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_BINPath to the agentloop-daemon program to start. Checked first.
AGENTLOOP_RUST_DAEMONThe daemon override that GameGen and AgentLoop also use. Checked second.
AWAKEN_SOCKET_PATHUse this socket path instead of deriving it from the project path.
AWAKEN_MODELModel passed to a daemon that Awaken starts.
AWAKEN_NO_AUTOSTART=1Never start a daemon; only attach to a running one. Same as the --no-autostart flag.
AGENTLOOP_DAEMON_EXTERNAL=1Same effect as AWAKEN_NO_AUTOSTART=1.
AWAKEN_NO_F10=1Do not register F10 as an overlay hotkey for game projects.
AWAKEN_RECENTS_FILEWhere the recent projects list is kept. Default: recent-projects.json in Awaken’s data directory.

Read by the daemon

VariableMeaning
AGENTLOOP_TEMPLATES_DIRDirectory that contains templates/. Needed when the daemon program is not next to a templates/ directory, for example a development build.
AGENTLOOP_MEMORY_BINPath to the agentloop-memory server program.

Read by the tutorial’s build wrapper

VariableMeaning
UE_ROOTThe 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

PathWhat it is
.unrest/awaken/npcs.json in the projectThe NPC file.
.unrest/gamegen.json in the projectMarks a GameGen project. Its engine value must be "unreal" for Awaken to treat the folder as an Unreal game.
Plugins/AwakenDebug/ in the projectThe plugin.
recent-projects.json in Awaken’s data directoryThe Awaken app’s recent projects.

Glossary

TermMeaning
NPCAny character or agent a game registers with AwakenDebug. It need not be an actor: a squad or a director can be one.
RowOne NPC as written in the NPC file: one entry of the npcs array.
StatusA short word or phrase for what an NPC is doing, such as Patrolling.
GoalThe goal an NPC is working on now.
Goal listAn NPC’s queue, stack or plan of goals, most important first.
BlackboardAn NPC’s named values: text, numbers and booleans.
TreeA snapshot of an NPC’s behaviour tree, as a JSON object.
NPC file.unrest/awaken/npcs.json, written by the game while it runs.
PublisherThe program that writes the NPC file. For Unreal games, AwakenDebug.
ReaderA program that reads the NPC file: the project daemon, or the Awaken app’s direct reader.
Project daemonThe AgentLoop daemon serving one project folder. GameGen and the Awaken app share it.
SliceOne named part of the daemon’s state. The NPC rows are the npcs slice; agent runs are in the executions slice.
StaleA file whose modification time or updatedAtMs is more than 5 seconds from the reader’s clock. It shows no rows.
RejectedA file that breaks the contract. It shows no rows, and the reader gives a reason.
OverlayThe Awaken app’s transparent, always-on-top window over the game.
PinMakes the overlay click-through, so every click goes to the game.
QA runOne execution of a QA agent on a task.
Play In EditorRunning the game inside the Unreal editor.

Next steps

Last updated on