The Awaken overlay
The overlay is a transparent, always-on-top window with Awaken’s panel in it: a roster of NPCs and an inspector for the selected one. For an Unreal game on macOS it places itself over the game’s window and follows it. Nothing is injected into Unreal. Awaken lists processes and asks the window server for window bounds.
Attaching to the game window works on macOS only. On Windows and Linux the overlay is a floating panel on the primary monitor. See Platform support.
Attach the overlay
Open the project
See Open a project.
Start the game
Start Play In Editor, or run the game in its own window. The order does not matter: the overlay attaches by itself when the window appears.
Choose Attach overlay
On the Game card, choose Attach overlay. From the command line, pass --overlay.
Check the attach line
The second line of the overlay, and the Game card, say what the overlay is attached to.
| Attach line | Meaning |
|---|---|
attached to UnrealEditor (pid 1234), game window | The overlay covers a game’s own window. |
attached to UnrealEditor (pid 1234), editor window | The overlay covers the editor window. Play In Editor runs inside it. |
floating panel: no Unreal editor or game is running MyGame | No matching process was found. The overlay floats until one appears. |
floating panel: UnrealEditor (pid 1234) has no window on screen | The process is running, but its window is not on screen. |
floating panel: attaching to a game window is not supported yet on this platform | Windows or Linux. |
To stop following the window, choose Detach overlay.
How Awaken finds the window
Awaken looks for the window by process:
- The editor. A process named
UnrealEditorwhose command line contains the project’s.uprojectpath. A Play In Editor “Preview” window is preferred when its title can be read. - A game.
UnrealEditorstarted with the project’s.uprojectand-game; a program named after the project, such asMyGameorMyGame-Mac-Shipping; or any other process whose command line contains the.uprojectpath.
A game window is preferred over the editor’s window.
The overlay is sized to that window. Awaken checks the window’s position and size ten times a second and moves the overlay with it.
The overlay following a window while you drag it has not been verified on a live game.
Read the panel
| Part | Content |
|---|---|
| Top row | The buttons Hide, Pin and Launcher. |
| Game line | The project’s name, its engine, and the attach line. |
| Source line | Where the rows come from and how fresh they are. See Sources and staleness. |
| QA strip | The five most recent QA runs, when a daemon is connected. See QA runs. |
| NPCS | The roster: each NPC’s name, status and current goal. |
| INSPECTOR | The selected NPC: position, goals, behaviour tree and blackboard. Tree nodes are coloured by status. |
Select an NPC in the roster to inspect it. Until you do, the inspector reads Select an NPC to inspect it. An NPC that reports nothing for a section shows no goals reported, no behaviour tree reported or no blackboard reported.
Mouse input and Pin
Pin makes the whole overlay click-through, so every click goes to the game. Choose it again, or use the hotkey, to make the overlay interactive.
| Platform | While the overlay is interactive |
|---|---|
| macOS | Clicks reach the game everywhere except over Awaken’s own panels. |
| Windows, Linux | The overlay takes all mouse input on its monitor. Pin it to play. |
Hotkeys
| Action | macOS | Windows and Linux |
|---|---|---|
| Show or hide the overlay | ⌘ Shift F12 | Ctrl Shift F12 |
| Toggle Pin | ⌘ Shift F11 | Ctrl Shift F11 |
| Show or hide the overlay, while a game project is open | F10 | F10 |
These are system-wide hotkeys. A system-wide hotkey takes the key from every other application, and F10 is also the key of AwakenDebug’s in-game HUD and “step over” in Unreal’s Blueprint debugger. To leave F10 alone, start Awaken with AWAKEN_NO_F10=1. See Troubleshooting.
Limits
- A game in exclusive fullscreen cannot be covered. Run it windowed or borderless.
- Without the Screen Recording permission, macOS hides other apps’ window titles. Awaken then cannot tell the Play In Editor “Preview” window from the main editor window, and uses the largest one.
- For an Unreal game, the primary way to see NPCs is the in-game panel, which the AwakenDebug plugin draws inside the game’s own frame. Use the overlay for a game whose plugin was built without the egui library, and for what the in-game panel does not show: the daemon’s connection and the QA strip.