Skip to Content
AwakenAwaken appSources and staleness

Sources and staleness

The Awaken app gets its NPC rows from one of two sources and always says which. Next to the source it says how fresh the rows are. This page explains each label so you can tell a quiet game from a stopped one.

The two sources

LabelWhenHow
from daemonThe project’s AgentLoop daemon is connected and publishes an npcs slice.The normal path. The daemon reads the NPC file and Awaken mirrors its npcs slice.
direct from game fileNo daemon is connected, or the connected daemon has no npcs slice.Awaken reads .unrest/awaken/npcs.json itself, read-only, five times a second.
no sourceNo daemon is connected and the project has no NPC file.Nothing to show. The panel adds no daemon connected and no .unrest/awaken/npcs.json in the project.

When the rows come straight from the file, the panel also shows the file’s source value in brackets, for example (unreal).

When a daemon is connected but has no npcs slice and there is no file either, the label is from daemon with the note the daemon has no npcs slice.

Both sources apply the same rules, so the rows are the same either way. The rules are the NPC file contract.

What the direct reader will open

The direct reader only opens a regular file that resolves inside the chosen project and is owned by the current user. It never follows a symlink out of the project, and it never writes.

The freshness line

After the source, the panel shows one of these:

TextMeaning
last update 0.3 s agoThe game is publishing. The time is measured from the file’s updatedAtMs, or from its modification time when it has no stamp.
game stopped publishing · last update 12 s agoThe file is stale: its modification time or its updatedAtMs is more than 5 seconds from now. No rows are shown.
last change from daemon 4 s agoOnly the daemon is available, with no file to measure from. The daemon sends the slice only when it changes, so this is the time of the last change, not of the last write.

Whenever the NPC file is there, the line uses the game’s own time, whichever source the rows come from.

With last change from daemon, a long time does not mean the game has stopped. It means no row has changed. A game with idle NPCs can show a large number here.

When rows go stale

A file is fresh only while its modification time and its updatedAtMs are both within 5 seconds of the clock. AwakenDebug rewrites the file at least once a second, so a running game stays fresh.

What happenedWhat you see
You stopped the game normally.The plugin deletes the file. The roster empties.
The game crashed or was killed.The file stays behind. About 5 seconds later the rows disappear and the line reads game stopped publishing.
You paused publishing with Awaken.Publish 0.The plugin deletes the file. The roster empties.

When the roster is empty

The roster explains itself with one of these lines:

TextMeaning
No NPCs yet. Start the game; it publishes its NPCs while it runs.A game project is open and nothing has been published.
The game is running and reports no NPCs.The file is fresh and its npcs array is empty. The game has registered nothing.
The game stopped publishing NPCs.The file is stale.
The game’s NPC file was rejected.The file breaks the contract. The source line gives the reason.
The daemon reports no NPCs for this game.The daemon’s npcs slice is empty.

A rejected file

When the file breaks the contract, the source line ends with game file rejected: and a reason, for example game file rejected: schema is not awaken-npcs/1. No rows are shown; Awaken never shows part of a file. The reasons are listed under Troubleshooting.

Next steps

Last updated on