Skip to Content
AwakenUnreal pluginIn-game panel and HUD

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.

ViewChecked on screen
In-game panelYes (Unreal Engine 5.9, macOS arm64).
In-game text HUDYes (Unreal Engine 5.9, macOS).
Gameplay Debugger categoryNot yet verified.
Editor tabNot yet verified.
Output Log dumpNot 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 1

Turn 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

InputWhat happens
A click on the panelThe panel takes it, with its release. The game does not see it.
A click anywhere elseIt reaches the game.
A click on a roster rowSelects that NPC. The inspector shows it.
A click on the roster’s filter fieldThe panel takes the keyboard so you can type. The game keeps running.
Esc, or a click elsewhereReturns the keyboard to the game.
F10Hides the panel, also while you type in the filter.
Page Down, Page Up, Awaken.SelectMove 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

VariableEffect
Awaken.Renderer eguiThe panel. This is the default, and it is used when the library is built.
Awaken.Renderer canvasThe text HUD.
Awaken.Debug.ScaleThe scale of either renderer. 0 is automatic.
Awaken.Egui.StatsLogs 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 madeWho 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.mjsnode Scripts/ue.mjs build, and test, before the Unreal build. It prints the same line.
GameGen’s New gameGameGen 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 AwakenEgui module 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

PlatformStatus
macOS arm64, Unreal Engine 5.9Built, tested and checked on screen.
macOS x86_64The build script’s --universal option builds it. Not tried.
Linux x86_64The Rust library compiles for Linux. Not linked into Unreal or run.
Windows x64The script and the build rules are written. Nothing of the panel was compiled or run on Windows.
Not yet verified

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:

LineContent
Name and idFor example Gate Guard (guard-1).
status:The status.
goal:The current goal.
position:X, Y and Z in Unreal units.
goalsThe goal list, numbered. Up to 8 are shown, then … N more.
blackboardkey = value lines. Up to 20 are shown, then … N more.
treeThe behaviour tree snapshot.

Select an NPC

ToDo
Select the next NPCPress Page Down, or enter Awaken.Select next.
Select the previous NPCPress Page Up, or enter Awaken.Select prev.
Select by idEnter 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 0 returns to automatic.
Not yet verified

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.

Not yet verified

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.

Not yet verified

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).

Not yet verified

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

Last updated on