HUD scenes
Build the heads-up display — score text, hearts, buttons, progress bars, panels — that floats above the gameplay.
The HUD (heads-up display) is the layer that floats over your gameplay scene — score counters, health bars, pause buttons, menus, hints. It's authored separately from the world so it doesn't move with the camera and its positions are anchored to viewport edges, not world coordinates.
Adding a HUD scene
By default the agent will create a HUD scene when your prompt mentions any HUD element (score, health, button, menu). If your project doesn't have one yet, ask:
Add a HUD scene attached to the main world. Show a score counter
top-left, a heart-icon health bar top-right, and a pause button
bottom-right.The agent wires manifest.scenes[].hud to point at the new HUD scene
and writes the HUD widget data. You'll see the HUD overlay the canvas
on the next preview.
Editing the HUD
In Edit mode, the toolbar's World / HUD pill toggles between editing the gameplay scene and editing the HUD.
In HUD mode:
- The canvas shows just the HUD (no world).
- The Scene tab palette switches to HUD widgets.
- The Float Inspector shows HUD fields (anchor + offset + layer) instead of transform.
Widget types
| Kind | What it is | Common uses |
|---|---|---|
| Text | Static or dynamic text | Score, level, timer, instructions |
| Image | A static image | Logo, icon, decoration |
| Icon-button | Clickable image with optional label | Pause, retry, menu, jump |
| Progress-bar | Filled rectangle with min/max + current value | Health, energy, XP, charge |
| Panel | Colored / bordered rectangle | Background for grouped widgets |
Drag any palette widget onto the canvas in HUD mode to add it.
Anchors instead of transforms
HUD widgets don't have free x/y. They have:
- Anchor — one of nine 9-grid positions (TL / TC / TR / ML / MC / MR / BL / BC / BR).
- Offset — pixel offset from the anchor point.
- Layer — Z order within the HUD.
This way the HUD adapts to different viewport sizes automatically. A widget anchored TR with offset (-16, 16) always sits 16px from the right edge, 16px from the top, regardless of window size.
Dynamic bindings
Text and progress-bar widgets can read live values from the game's registry instead of being hardcoded.
Static text:
Text widget — `text: "Score: 0"`Dynamic text (rebinds when the registry value changes):
Text widget — `source: 'registry'`, `key: 'score'`, `format: 'Score: {value}'`The game code calls scene.registry.set('score', 12) and every dynamic-
text widget bound to 'score' updates. This is the default pattern the
agent uses for score / lives / coins / health.
You won't usually set this up by hand — the agent does it when you ask for the corresponding game mechanic. But if you want to direct it:
Bind the score text to registry key 'score'. The coin-pickup behavior
already increments that registry value, so they should connect.Progress-bar widgets
Progress bars have separate value and max bindings — either can
be static or registry-driven. The visual fill ratio is value / max.
Typical setup:
Progress-bar — value bound to registry 'hp', max bound to registry 'maxHp'.Fields:
| Field | What it does |
|---|---|
width / height | Bar dimensions |
value | Current fill (static or registry) |
max | Maximum (static or registry) |
backgroundColor | Empty-portion color |
fillColor | Filled-portion color |
border | Border width + color (optional) |
borderRadius | Rounded corners (optional) |
Icon-button widgets
Icon-buttons emit a hud:press event with the button's id. The game
code listens for it.
Pause button — when pressed, the game's pause behavior toggles.Anchor + offset like other widgets. The button accepts an optional 9-slice background (atlas region from a UI pack) so it stretches to any size without losing its rounded corners. See Assets → Regions and 9-slice.
Panel widgets
Panels are decorative — a colored rectangle with optional border + corner radius. Drop a panel behind a cluster of HUD widgets to give them a visual group (modal background, sidebar fill, etc).
Panels can also use a 9-slice atlas region as their background.
Auto-toggle behavior
The HUD scene starts visible. The agent can show / hide it in response to gameplay (e.g. hide during a cutscene, show during gameplay). Ask:
Hide the HUD during the intro cutscene; show it when gameplay starts.Common workflows
"Add a score counter"
Add a Score text widget to the HUD, top-left, white text. Bind it to
registry key 'score'. Whenever a coin is collected, increment the
score by 1."Add a health bar"
Add a horizontal progress bar to the HUD, top-right, 200x16 pixels,
green fill with a dark border. Bind value to registry 'hp', max to
registry 'maxHp'. Start hp=100, maxHp=100."Add a pause menu"
Add a pause icon-button to the HUD bottom-right. When pressed, show
a centered modal panel with Resume / Restart / Quit text buttons.
Pause the world scene while the menu is open.