Skip to Content
AwakenAwaken appThe overlay

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 lineMeaning
attached to UnrealEditor (pid 1234), game windowThe overlay covers a game’s own window.
attached to UnrealEditor (pid 1234), editor windowThe overlay covers the editor window. Play In Editor runs inside it.
floating panel: no Unreal editor or game is running MyGameNo matching process was found. The overlay floats until one appears.
floating panel: UnrealEditor (pid 1234) has no window on screenThe process is running, but its window is not on screen.
floating panel: attaching to a game window is not supported yet on this platformWindows 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 UnrealEditor whose command line contains the project’s .uproject path. A Play In Editor “Preview” window is preferred when its title can be read.
  • A game. UnrealEditor started with the project’s .uproject and -game; a program named after the project, such as MyGame or MyGame-Mac-Shipping; or any other process whose command line contains the .uproject path.

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.

Not yet verified

The overlay following a window while you drag it has not been verified on a live game.

Read the panel

PartContent
Top rowThe buttons Hide, Pin and Launcher.
Game lineThe project’s name, its engine, and the attach line.
Source lineWhere the rows come from and how fresh they are. See Sources and staleness.
QA stripThe five most recent QA runs, when a daemon is connected. See QA runs.
NPCSThe roster: each NPC’s name, status and current goal.
INSPECTORThe 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.

PlatformWhile the overlay is interactive
macOSClicks reach the game everywhere except over Awaken’s own panels.
Windows, LinuxThe overlay takes all mouse input on its monitor. Pin it to play.

Hotkeys

ActionmacOSWindows and Linux
Show or hide the overlay⌘ Shift F12Ctrl Shift F12
Toggle Pin⌘ Shift F11Ctrl Shift F11
Show or hide the overlay, while a game project is openF10F10

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.

Next steps

Last updated on