The NPC file
A running game writes .unrest/awaken/npcs.json in its project folder so that Awaken can show what its NPCs are doing. This page is the contract for that file: what a publisher writes and what every reader checks. Use it when you read the file yourself or write it from a game that does not use AwakenDebug.
Three programs implement the contract:
| Program | Role |
|---|---|
| AwakenDebug, the Unreal plugin | Writes the file. |
| The project’s AgentLoop daemon | Reads it and publishes the rows as its npcs state slice. |
| The Awaken app | Reads it directly when no daemon publishes the slice. |
Both readers give the same answer for the same file. They run the same table of accept, stale and reject cases.
Example
{"schema":"awaken-npcs/1","source":"unreal","updatedAtMs":1794400000123,"npcs":[
{"id":"guard-1","name":"Gate Guard","status":"Patrolling","goal":"walk to the north gate",
"goals":["walk to the north gate","report in"],
"tree":{"node":"Patrol","status":"running"},
"blackboard":{"alert":false,"distance":1240,"target":"north gate"},
"position":[120.5,-40,88]}
]}The file AwakenDebug writes is a single line. It is wrapped here.
The smallest valid file has no rows:
{"schema":"awaken-npcs/1","npcs":[]}Fields
| Field | Required | Rule |
|---|---|---|
schema | Yes | Exactly "awaken-npcs/1". |
source | No | Absent, null, or a string of at most 64 UTF-8 bytes with no control characters. It names the publisher, for example "unreal". |
updatedAtMs | No | Absent, null, or a number that is not negative: the publisher’s wall clock when it wrote the file, in Unix milliseconds. A fraction is dropped. |
npcs | Yes | An array of at most 64 rows. |
Row id | Yes | A string that is not empty. |
Row name | Yes | A string. It may be empty. |
| Any other field | No | Passed through untouched, at the top level and in rows. |
Readers do not check the other row fields. Awaken’s panels read status, goal, goals, tree, blackboard and position leniently. A position may be [x, y, z] or an object with x, y and z.
Readers do not check that ids are unique. A publisher must make them unique, because Awaken selects rows by id.
What AwakenDebug writes in each row
AwakenDebug writes all eight fields in every row.
| Field | Type | Content |
|---|---|---|
id | String | The NPC’s id. |
name | String | The display name. |
status | String | The status. |
goal | String | The current goal. |
goals | Array of strings | The goal list. [] when there is none. |
tree | Object | The behaviour tree snapshot. {} when there is none. |
blackboard | Object | Keys sorted by name. Each value is a string, a number or a boolean, as it was set. {} when empty. |
position | Array of three numbers | Unreal units (centimetres), rounded to 0.1. [0,0,0] for an NPC with no actor and no position set. |
source is "unreal" and updatedAtMs is always present.
Size limits
| Limit | Value | How it is measured |
|---|---|---|
| File | 262,144 bytes (256 KiB) | The bytes on disk. A pretty-printed file is allowed. |
| Rows | 64 | Entries in npcs. |
| Row bytes | 32,768 bytes (32 KiB) | The npcs array written as compact JSON, brackets included, after the reader has parsed it. White space in the file does not count. |
A file over any limit is rejected whole. Readers never show part of a file.
Readers measure the rows after parsing them, so their count can differ from the publisher’s own text when a number is written in a longer or shorter form. For example 1.5e+06 is 7 bytes, and a reader writes it as 1500000.0, 9 bytes. A publisher that fills the limit must count the brackets and write numbers in their shortest plain form. AwakenDebug does both.
AwakenDebug keeps its output inside these limits by cutting detail. See the limits table.
Checks, in order
A reader applies these checks in order. The first one that fails decides the outcome, so both readers report the same reason.
| # | Condition | Outcome | Reason code |
|---|---|---|---|
| 1 | There is no file. | Absent | |
| 2 | The file is not a regular file inside the project, owned by the reader’s user. | Rejected | unsafe-path |
| 3 | The file’s modification time is more than 5,000 ms from the reader’s clock. | Stale | |
| 4 | The file is larger than 262,144 bytes. | Rejected | too-large |
| 5 | The content is not JSON. | Rejected | not-json |
| 5 | The content is JSON but not an object. | Rejected | not-object |
| 6 | schema is not "awaken-npcs/1". | Rejected | schema |
| 7 | source breaks its rule. | Rejected | source |
| 8 | updatedAtMs breaks its rule. | Rejected | updated-at |
| 9 | npcs is missing or not an array. | Rejected | npcs |
| 10 | There are more than 64 rows. | Rejected | too-many-rows |
| 11 | A row is not an object. | Rejected | row |
| 11 | A row’s id is missing, empty or not a string. | Rejected | row-id |
| 11 | A row’s name is missing or not a string. | Rejected | row-name |
| 12 | The rows take more than 32,768 bytes. | Rejected | rows-too-large |
| 13 | updatedAtMs is present and more than 5,000 ms from the reader’s clock. | Stale | |
| 14 | None of the above. | Ready: all rows are shown, possibly none. |
Absent, stale and rejected files all show no rows.
Notes on check 2: a symlinked npcs.json is never followed. The folders .unrest and .unrest/awaken may be symlinks only when they resolve inside the project. A project that still has only the old .agentloop folder keeps the file at .agentloop/awaken/npcs.json, and Awaken reads it there.
Note on check 3: a stale file is not read, so an old file is stale even when its contents are invalid.
Staleness
A file is fresh only while both of these hold:
- Its modification time is within 5,000 ms of the reader’s clock.
- Its
updatedAtMs, when it has one, is within 5,000 ms of the reader’s clock.
Both are compared with the reader’s wall clock, in either direction. A time more than 5 seconds in the future is as stale as one more than 5 seconds in the past. Exactly 5,000 ms is still fresh.
| Situation | What happens |
|---|---|
| The game crashes or is killed. | Its last file stays behind. The modification time and updatedAtMs both stop, so the rows disappear 5 seconds later. |
| The file is copied, restored or touched. | It gets a new modification time, but updatedAtMs still says when the game wrote it. The stamp catches it. |
The publisher writes no updatedAtMs. | The file is judged by modification time alone. |
A publisher must therefore rewrite the file at least every few seconds while the game runs, also when nothing changed.
The daemon checks the file four times a second while it exists and once a second while it does not. The Awaken app’s direct reader checks five times a second. Rows therefore disappear within about 5.3 seconds of the last write.
Publisher and reader normally run on the same computer and share a clock. A reader on another computer, through a network share, needs clocks that agree within 5 seconds.
Write the file from your own game
Follow these rules if your game writes the file without AwakenDebug.
Write to a temporary file first
Write a temporary file in the same folder, then rename it over npcs.json. A reader then never sees half a file.
Rewrite it regularly
Rewrite the file at least once a second, and a few times a second at most. Set updatedAtMs to the current Unix time in milliseconds on every write.
Stay inside the limits
At most 64 rows, 32,768 bytes of rows and 262,144 bytes of file. Give every row a unique, non-empty id and a name.
Delete it when the game stops
AwakenDebug writes at most four times a second, and only when a row changed or one second has passed since the last write. It deletes the file when play ends. When one process runs several game worlds, such as Play In Editor with more than one client, the first world to publish owns the file until it ends.
What the daemon publishes
The daemon’s npcs slice is the npcs array of a ready file, unchanged, or [] for an absent, stale or rejected file. It is never a partial file.
The slice does not exist until the daemon has seen the .unrest/awaken folder. A project with no game integration therefore has no npcs slice at all, which is different from an empty one. From then on the slice is always present.
Nothing flows back. The daemon only reads the file and sends no command to the game.
Check a file
The AgentLoop repository has a script that checks a real file against the contract from outside Unreal:
node examples/gamegen/tests/awaken-npcs-check.mjs /path/to/MyGame/.unrest/awaken/npcs.json --watch 10The script is stricter than the readers. It requires all eight row fields, unique ids and source "unreal", because that is what AwakenDebug promises.
Next steps
- Sources and staleness in the Awaken app.
- Troubleshooting a rejected file.
- Reference for all limits in one place.