In-game panel, HUD and debugger
AwakenDebug shows the registered NPCs in four places inside Unreal. The in-game view is the main one. It is Awaken’s panel, drawn inside the game’s own frame, when the plugin has Awaken’s egui library. Without the library it is a plain-text HUD. All four places read the plugin directly; none of them needs the NPC file, a daemon or another app.
| View | Checked on screen |
|---|---|
| In-game panel | Yes (Unreal Engine 5.9, macOS arm64). |
| In-game text HUD | Yes (Unreal Engine 5.9, macOS). |
| Gameplay Debugger category | Not yet verified. |
| Editor tab | Not yet verified. |
| Output Log dump | Not yet verified with live rows. |
The in-game panel
When the plugin’s AwakenEgui module is built with Awaken’s egui library, Awaken.Debug 1 or F10 shows Awaken’s own panel: the NPC roster with a filter field, and an inspector with the selected NPC’s goals, behaviour tree, blackboard and raw row. Unreal draws it inside the game’s own frame, in the game viewport. It is not a window laid over the game, and it needs no Awaken app and no daemon. The engine’s own screenshot (shot showui) contains it.
Without the library the same variable and key show the text HUD instead.
Show the panel
Start the game
Start Play In Editor, or run the project with -game.
Turn the panel on
Press F10, or open the console and enter:
Awaken.Debug 1Turn it off
Press F10 again, enter Awaken.Debug 0, or choose Hide on the panel.
To start a game with the panel already on, pass the command on the command line:
UnrealEditor MyGame.uproject -game -windowed -ExecCmds="Awaken.Debug 1"Use the mouse and the keyboard
| Input | What happens |
|---|---|
| A click on the panel | The panel takes it, with its release. The game does not see it. |
| A click anywhere else | It reaches the game. |
| A click on a roster row | Selects that NPC. The inspector shows it. |
| A click on the roster’s filter field | The panel takes the keyboard so you can type. The game keeps running. |
| Esc, or a click elsewhere | Returns the keyboard to the game. |
| F10 | Hides the panel, also while you type in the filter. |
Page Down, Page Up, Awaken.Select | Move the panel’s selection. |
While the panel is open, the mouse cursor is shown. Awaken.Egui.ShowCursor 0 leaves the cursor to the game. The panel can then be clicked only if the game shows a cursor itself.
Choose the renderer
| Variable | Effect |
|---|---|
Awaken.Renderer egui | The panel. This is the default, and it is used when the library is built. |
Awaken.Renderer canvas | The text HUD. |
Awaken.Debug.Scale | The scale of either renderer. 0 is automatic. |
Awaken.Egui.Stats | Logs what the panel costs a frame and what it draws. |
How a project gets the library
The library and its header are build products. They are staged into the plugin’s Source/ThirdParty/AwakenEguiLib/ folder. Building the library needs cargo and the awaken folder of an unrest checkout. The build script looks for that folder in --awaken DIR, then in AWAKEN_SOURCE_DIR, then in the checkout the plugin sits in.
| How the project was made | Who builds the library |
|---|---|
examples/gamegen/create.py unreal <dir> | create.py, before it copies the plugin. It prints one line that says whether the library was staged. |
Any project with this plugin and Scripts/ue.mjs | node Scripts/ue.mjs build, and test, before the Unreal build. It prints the same line. |
| GameGen’s New game | GameGen carries the library for its own platform if the library was staged when that GameGen was built. Otherwise the project gets the sources and the scripts, and ue.mjs build stages the library when it can. |
When the library was staged, the line reads Awaken egui library: followed by its state, then The in-game Awaken panel is drawn by egui. When cargo or the awaken sources are not on the machine, the line starts Awaken egui library: not built: and the project still builds. AWAKEN_EGUI=0 skips the step.
Fallback
The text HUD draws instead of the panel in these cases:
- The library was not staged. The
AwakenEguimodule still compiles, registers nothing and logs one line. - The library’s version does not match its header.
- A call into the library fails. The panel turns itself off for the rest of the run.
The module is left out of shipping builds. It is not started on a dedicated server or in a commandlet.
Cost
Measured on the test machine, an Apple M4 Max with Unreal Engine 5.9 Development editor binaries, in a -game window at 1280 by 720 and 120 frames a second: 0.2 to 0.4 milliseconds a frame on the game thread, for Floppy Bird with two to five rows. Nothing is built or drawn while the panel is hidden. stat Awaken shows the same figure.
Platform status
| Platform | Status |
|---|---|
| macOS arm64, Unreal Engine 5.9 | Built, tested and checked on screen. |
| macOS x86_64 | The build script’s --universal option builds it. Not tried. |
| Linux x86_64 | The Rust library compiles for Linux. Not linked into Unreal or run. |
| Windows x64 | The script and the build rules are written. Nothing of the panel was compiled or run on Windows. |
The panel is not yet verified in a packaged development build, on Windows, on Linux, with Unreal Engine 5.8, at a scale other than 1, or on a high-DPI game window. The mouse checks sent pointer events through the engine, not a hand on a real mouse. Mouse and keyboard input were checked in -game, not in Play In Editor.
Known gaps
- The cursor does not change shape over the panel.
- The filter field has no copy and paste.
- Colours assume a display that is not in HDR mode.
The text HUD
The text HUD is the plain-text renderer. It draws when the egui library is not built, and when you enter Awaken.Renderer canvas. F10 and Awaken.Debug show and hide it in the same way as the panel.
The HUD is drawn through the engine’s debug-draw service, on top of the game’s own HUD. It appears in Play In Editor and in -game. It does not appear in the editor’s level viewports, and shipping builds draw nothing.
Read the HUD
The first line reads Awaken NPCs (N) F10 hide, PgUp/PgDn select, where N is the number of NPCs.
Below it, the roster has one line per NPC: the name, the id in square brackets, the status and the goal. A > marks the selected NPC. When the roster is longer than the list, … N above and … N below show how many rows are out of view.
Under the roster, the selected NPC is shown in full:
| Line | Content |
|---|---|
| Name and id | For example Gate Guard (guard-1). |
status: | The status. |
goal: | The current goal. |
position: | X, Y and Z in Unreal units. |
goals | The goal list, numbered. Up to 8 are shown, then … N more. |
blackboard | key = value lines. Up to 20 are shown, then … N more. |
tree | The behaviour tree snapshot. |
Select an NPC
| To | Do |
|---|---|
| Select the next NPC | Press Page Down, or enter Awaken.Select next. |
| Select the previous NPC | Press Page Up, or enter Awaken.Select prev. |
| Select by id | Enter Awaken.Select guard-1. |
The selection wraps around at the ends of the roster.
When the HUD does not fit
The panel stays inside the view:
- Lines that do not fit below are replaced by
… N more lines (Awaken.Dump logs all). - Long lines are cut.
- The text is scaled with the view height: scale 1 up to 1,350 pixels, larger above. Set the scale yourself with
Awaken.Debug.Scale 1.5(0.5 to 4).Awaken.Debug.Scale 0returns to automatic.
The automatic scale above 1080p was checked by calculation and by forcing Awaken.Debug.Scale, not on a 4K display.
F10 in the editor
F10 is also “step over” in Unreal’s Blueprint debugger, and the Awaken app can register F10 as a system-wide key. If the key does not reach the game, use Awaken.Debug 1 instead. See Troubleshooting.
Gameplay Debugger
The plugin registers a Gameplay Debugger category named Awaken.
Open the Gameplay Debugger
Press the apostrophe key (the default) while the game runs.
Turn on the Awaken category
The category lists every NPC with name, status and goal. When the selected debug actor is a registered NPC, it is shown in full.
The category compiles and registers, but its drawing has not been checked on screen.
Editor tab
Open the tab
In the editor, choose Window > Tools > Debug > Awaken NPCs.
Start Play In Editor
The tab shows every NPC of the running session as text, refreshed four times a second, and the path of the file being written. With no session it reads No game is running. Start Play In Editor to list its NPCs.
The tab’s contents during a running session have not been checked on screen.
Output Log
Enter Awaken.Dump in the console. The plugin logs every NPC with all its fields under the LogAwakenDebug category. With no game running it logs Awaken.Dump: no game is running (start Play In Editor first).
Awaken.Dump has not been checked with live rows.
What the views show compared with the file
The HUD, the editor tab and Awaken.Dump show the values your game set in full, cut only to fit a line. The NPC file is bounded: long values are cut and large trees are replaced by a marker. See the limits table.
Next steps
- Console commands.
- See the same rows outside Unreal with GameGen’s Awaken view or the Awaken app.