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.You can also do it yourself. HUDs are first-class resources, not a hidden property of a scene: in Edit mode, the control under the scene list assigns an existing HUD, detaches it, or creates a new one for the active world scene. One HUD can be shared by several scenes — it warns you when it is.
A freshly created HUD needs one build before you can edit it.
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 — the world is hidden, so you are laying out the interface on a neutral background rather than over a map.
- The palette switches to HUD widgets.
- The Inspector shows HUD fields (anchor, offset, layer) instead of transform.
- A HUD browser lists every HUD in the project and switches which one you are editing, independently of what any world scene binds.
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 |
| Text input | A single-line field | Name entry, a room code, a search box |
| Text area | A multi-line field | Chat, notes, anything the player types into |
Drag any palette widget onto the canvas in HUD mode to add it.
Text widgets have a font picker that offers both the fonts you uploaded and any Google Font the project uses — see Assets → Fonts. A sprite widget can name an animation to play, so an animated HUD element needs no code.
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 → Hitboxes, regions and atlases.
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.