Troubleshooting Awaken
Work from the game outwards: first the in-game panel or text HUD, then the NPC file, then the viewer. The data flows in that order, so the first place that is wrong is where the fault is.
Find where the rows stop
Check the in-game HUD
In the running game, enter Awaken.Debug 1 in the console. If the in-game panel, or the text HUD, lists your NPCs, the plugin has them. If you see the text HUD where you expected the panel, see Fallback. If not, see No rows in the HUD.
Check the file
While the game runs, look for .unrest/awaken/npcs.json in the project folder. If it is missing, see The file is not written.
Check the viewer
If the HUD and the file are fine and a viewer is empty, see No rows in the Awaken app or No rows in GameGen.
No rows in the HUD
| Cause | Fix |
|---|---|
| The game registered nothing. | Register an NPC with the subsystem or add an Awaken Npc component. See Register NPCs in C++. |
| A setter was called with an id that is not registered. | Every setter returns false for an unknown id. Register first, and use the id that RegisterActor returned. |
| You are looking at an editor level viewport. | The HUD appears in Play In Editor and in -game, not in the editor’s level viewports. |
| The build is a shipping build. | Shipping builds draw nothing and write nothing. |
| The plugin is not enabled. | Check the Plugins list in the .uproject. See Install into a project. |
| An AgentLoopBT actor is missing. | AwakenDebug looks for such actors once a second. Check that the tree loaded; a tree that calls an unbound leaf fails to load. |
The file is not written
| Cause | Fix |
|---|---|
| No game is running. | The file exists only while a game or Play In Editor world runs. It is deleted when play ends. |
| Publishing is off. | Enter Awaken.Publish 1. Check Config/DefaultEngine.ini for Awaken.Publish=0 under [ConsoleVariables]. |
| The build is a shipping build. | Shipping builds never write the file. |
| Another game world owns the file. | When one process runs several game worlds, the first world to publish owns the file until it ends. |
| The game is a packaged build. | A packaged game writes under its own project directory, which may not be the folder you opened. This case is not yet verified. |
No rows in the Awaken app
Read the line the roster shows, and the source line next to it.
| What you see | Meaning | Fix |
|---|---|---|
| No NPCs yet. Start the game; it publishes its NPCs while it runs. | Nothing has been published for this project. | Start the game. Check that Awaken opened the same folder the game runs from. |
| The game is running and reports no NPCs. | The file is fresh and has no rows. | The game registered nothing. See No rows in the HUD. |
| The game stopped publishing NPCs. | The file is stale. | See Game stopped publishing. |
| The game’s NPC file was rejected. | The file breaks the contract. | See The game file is rejected. |
| The daemon reports no NPCs for this game. | The daemon’s npcs slice is empty. | The daemon found no fresh, valid file. Check the file as above. |
no source, with no daemon connected and no .unrest/awaken/npcs.json in the project | Awaken has neither a daemon nor a file. | Start the game, or check the project path. |
from daemon, with the daemon has no npcs slice | The connected daemon does not publish the slice and there is no file. | Start the game. Awaken then reads the file directly. An older daemon never publishes the slice. |
Game stopped publishing
The source line reads game stopped publishing · last update 12 s ago. The file’s modification time or its updatedAtMs is more than 5 seconds from the clock.
| Cause | Fix |
|---|---|
| The game crashed or was killed. | It left its last file behind. Start the game again; the plugin overwrites the file. |
| The file was copied in from elsewhere. | A copied file has a new modification time but an old updatedAtMs. Only a running game keeps the file fresh. |
| The clocks disagree. | A reader on another computer needs a clock within 5 seconds of the game’s. A time in the future is stale too. |
last change from daemon … ago is a different line. It appears when only the daemon is available, and a long time there means no row changed, not that the game stopped. See Sources and staleness.
The game file is rejected
The source line ends with game file rejected: and one of these reasons. No rows are shown, because a reader never shows part of a file. AwakenDebug does not write files that break these rules, so this usually means another program wrote the file.
| Reason shown | Code | Fix |
|---|---|---|
not a regular file inside the project owned by this user | unsafe-path | npcs.json is a symlink, resolves outside the project, or belongs to another user. Make it an ordinary file in the project, owned by you. |
file is larger than 256 KiB | too-large | Write less. The limit is 262,144 bytes on disk. |
not valid JSON | not-json | Write a temporary file and rename it over npcs.json, so a reader never sees half a file. |
top level is not an object | not-object | The file must be one JSON object. |
schema is not awaken-npcs/1 | schema | Set "schema":"awaken-npcs/1" exactly. |
source is not a short string | source | Use a string of at most 64 bytes with no control characters, or leave source out. |
updatedAtMs is not a time in milliseconds | updated-at | Use a number that is not negative, or leave it out. |
npcs is not an array | npcs | npcs is required and must be an array. |
more than 64 rows | too-many-rows | Publish at most 64 rows. |
a row is not an object | row | Every entry of npcs must be an object. |
a row has no string id | row-id | Every row needs a non-empty string id. |
a row has no string name | row-name | Every row needs a string name. It may be empty. |
rows are larger than 32 KiB | rows-too-large | The npcs array as compact JSON must fit in 32,768 bytes. |
The full rules are in The NPC file.
No rows in GameGen
Read the status line on the NPCs tab.
| Status line | Meaning | Fix |
|---|---|---|
| This project’s daemon is not running. | There is no daemon to ask. | Make sure the project is open and running in GameGen. |
| No game has published NPCs for this project yet. | The daemon has no npcs slice. It has not seen the project’s .unrest/awaken folder. | Follow How to see NPCs here on the tab: add the AwakenDebug plugin and run the game. |
| No game is publishing NPCs for this project right now. | The slice is empty and has held no row since GameGen started. | Run the game. Then check the NPC file. |
| The game stopped publishing. | The game stopped, or its file went stale or was refused. The second line names the size of the last roster. | Run the game again. If it is running, check the NPC file. |
| Live: N NPCs, with fewer rows than you expect | A later row that repeats an earlier id is dropped, and at most 64 rows are shown. | Give every NPC its own id. |
A real Unreal game as the publisher into this tab is not yet verified. See GameGen view.
The overlay does not attach
Read the attach line on the overlay’s second line or on the Game card.
| Attach line | Cause | Fix |
|---|---|---|
floating panel: attaching to a game window is not supported yet on this platform | You are on Windows or Linux. | None yet. Use the floating panel, and Pin it to play. |
floating panel: no Unreal editor or game is running MyGame | Awaken found no process for this project. | Start the editor or the game. Awaken matches UnrealEditor by the project’s .uproject path on its command line, so start it with that path. |
floating panel: UnrealEditor (pid 1234) has no window on screen | The process has no visible window. | Bring the window on screen. A headless run has none. |
| Attached to the editor window, not the Play In Editor window | macOS hides other apps’ window titles without the Screen Recording permission, so Awaken uses the largest window. | Grant Awaken the Screen Recording permission in System Settings. |
| The overlay does not cover the game | The game is in exclusive fullscreen. | Run it windowed or borderless. |
| The Game card shows no Attach overlay | The folder is not recognised as a GameGen Unreal game. | Read the reason on the card. See Open a project. |
F10 does something else
Three things use F10:
| User | What F10 does |
|---|---|
| AwakenDebug, in the game | Shows or hides the in-game HUD. |
| The Awaken app, while a game project is open | Shows or hides the overlay, as a system-wide hotkey. |
| Unreal’s Blueprint debugger | Step over. |
A system-wide hotkey takes the key from every other application. While the Awaken app runs with a game project open, F10 therefore may not reach the game or the editor.
Stop Awaken from taking F10
Quit Awaken, then start it with AWAKEN_NO_F10 set to 1:
AWAKEN_NO_F10=1 cargo run -p awaken-app -- --project /path/to/MyGame --overlayUse the other overlay hotkey
Show or hide the overlay with ⌘ Shift F12 on macOS, or Ctrl Shift F12 on Windows and Linux.
Use the console for the HUD
If F10 is still taken, for example by the Blueprint debugger, show the in-game HUD with Awaken.Debug 1 and hide it with Awaken.Debug 0.
Awaken cannot find the daemon
The launcher window’s Settings page shows the daemon program Awaken found, or not found (AWAKEN_DAEMON_BIN, next to awaken, or PATH).
| Fix | How |
|---|---|
| Point Awaken at the daemon | Set AWAKEN_DAEMON_BIN to the path of agentloop-daemon. |
| Work without a daemon | Start Awaken with --no-autostart. It reads the game’s NPC file directly. |
Next steps
- Reference for limits and environment variables.
- Platform support for what is not yet verified.