Skip to Content
AwakenThe NPC file

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:

ProgramRole
AwakenDebug, the Unreal pluginWrites the file.
The project’s AgentLoop daemonReads it and publishes the rows as its npcs state slice.
The Awaken appReads 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

.unrest/awaken/npcs.json
{"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

FieldRequiredRule
schemaYesExactly "awaken-npcs/1".
sourceNoAbsent, null, or a string of at most 64 UTF-8 bytes with no control characters. It names the publisher, for example "unreal".
updatedAtMsNoAbsent, 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.
npcsYesAn array of at most 64 rows.
Row idYesA string that is not empty.
Row nameYesA string. It may be empty.
Any other fieldNoPassed 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.

FieldTypeContent
idStringThe NPC’s id.
nameStringThe display name.
statusStringThe status.
goalStringThe current goal.
goalsArray of stringsThe goal list. [] when there is none.
treeObjectThe behaviour tree snapshot. {} when there is none.
blackboardObjectKeys sorted by name. Each value is a string, a number or a boolean, as it was set. {} when empty.
positionArray of three numbersUnreal 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

LimitValueHow it is measured
File262,144 bytes (256 KiB)The bytes on disk. A pretty-printed file is allowed.
Rows64Entries in npcs.
Row bytes32,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.

#ConditionOutcomeReason code
1There is no file.Absent
2The file is not a regular file inside the project, owned by the reader’s user.Rejectedunsafe-path
3The file’s modification time is more than 5,000 ms from the reader’s clock.Stale
4The file is larger than 262,144 bytes.Rejectedtoo-large
5The content is not JSON.Rejectednot-json
5The content is JSON but not an object.Rejectednot-object
6schema is not "awaken-npcs/1".Rejectedschema
7source breaks its rule.Rejectedsource
8updatedAtMs breaks its rule.Rejectedupdated-at
9npcs is missing or not an array.Rejectednpcs
10There are more than 64 rows.Rejectedtoo-many-rows
11A row is not an object.Rejectedrow
11A row’s id is missing, empty or not a string.Rejectedrow-id
11A row’s name is missing or not a string.Rejectedrow-name
12The rows take more than 32,768 bytes.Rejectedrows-too-large
13updatedAtMs is present and more than 5,000 ms from the reader’s clock.Stale
14None 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.

SituationWhat 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 10

The 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

Last updated on