references/layout-and-flow.md
# Layout, scaling & flow — depth for `game-ui-ux`
Detail the `game-ui-ux` body defers here: per-engine scaling modes, safe-area math, a complete
focus + screen-stack pattern, diegetic UI, accessibility, and localization-ready layout. Snippets
target **Godot 4.7** and **Unity 6.3 LTS**.
## 1. Scaling modes per engine
**Godot 4.7** (Project Settings → Display → Window → Stretch):
| Setting | Choose | Effect |
|---------|--------|--------|
| Mode | `canvas_items` | UI scales with the window (vs `viewport` = pixel-exact, `disabled` = none) |
| Aspect | `expand` | shows more world/UI space on odd ratios; `keep` letterboxes |
| Scale | `1.0`+ | global UI multiplier |
| Scale Mode | `fractional` / `integer` | `integer` keeps pixel-art UI crisp by scaling in whole steps |
Anchor HUD corners so `expand` puts the extra space where you want it. `keep_width`/`keep_height`
pin one axis for hard 16:9 designs.
**Unity 6.3 LTS** (`CanvasScaler` on each Canvas):
- `UI Scale Mode = Scale With Screen Size`.
- `Reference Resolution = 1920×1080` (or your art's design size).
- `Screen Match Mode = Match Width Or Height`, `Match = 0.5` (blend). Use `1.0` if vertical
layout must never clip, `0.0` if horizontal must not.
- `Reference Pixels Per Unit = 100` for sprite-based UI.
## 2. Safe-area math
The OS reports a safe rectangle inside the screen (excludes notch, rounded corners, and — on TVs
— overscan margins). Inset only **critical** UI (health, timers, prompts); decorative art can
bleed to the edge.
```text
# Normalized anchors from a pixel safe rect (engine-neutral):
anchorMin = (safe.x / screenW, safe.y / screenH)
anchorMax = ((safe.x + safe.w) / screenW, (safe.y + safe.h) / screenH)
# Re-apply on resolution change / orientation change, not once at startup.
```
- **Godot:** `DisplayServer.get_display_safe_area()` → `Rect2i` in pixels; reapply on
`size_changed`.
- **Unity:** `Screen.safeArea` → `Rect` in pixels; recompute when `Screen.width/height` or
`Screen.orientation` changes (cache the last applied rect to avoid per-frame work).
## 3. Focus navigation (full pattern)
Requirements for controller/keyboard usability:
1. **Initial focus** on every screen open (`grab_focus()` / `EventSystem.SetSelectedGameObject`).
2. **Explicit neighbors** for predictable movement (Godot `focus_neighbor_*`; Unity `Navigation`
= Explicit with up/down/left/right, or Automatic for simple grids).
3. **Visible focus style** distinct from hover (theme focus stylebox / Unity Selectable
transition). Never rely on color alone (see accessibility).
4. **Wrap or stop** intentionally at list ends; trap focus inside modal dialogs.
5. **Device coexistence:** moving the mouse can update selection; a gamepad press acts on the
focused control. Don't clear focus when the mouse moves.
```gdscript
# Godot 4.7: trap focus inside a modal so the stick can't escape to the menu behind it.
var _prev_focus: Control
func open_modal() -> void:
_prev_focus = get_viewport().gui_get_focus_owner()
$Menu.focus_behavior_recursive = Control.FOCUS_BEHAVIOR_DISABLED # Godot 4.5+
$Menu.mouse_behavior_recursive = Control.MOUSE_BEHAVIOR_DISABLED
$Modal.show()
$Modal/OK.grab_focus()
func close_modal() -> void:
$Modal.hide()
$Menu.focus_behavior_recursive = Control.FOCUS_BEHAVIOR_INHERITED
$Menu.mouse_behavior_recursive = Control.MOUSE_BEHAVIOR_INHERITED
if is_instance_valid(_prev_focus): _prev_focus.grab_focus()
```
Showing the modal and focusing its button is not a trap on its own: Godot's neighbor search
still reaches visible controls behind it. The two `*_behavior_recursive` switches turn a whole
subtree off without touching each button.
## 4. Screen/menu stack
Model screens as a stack of UI states; the top owns input and is visible. Push for overlays,
pop for "back". This generalizes pause, settings-over-pause, and confirm dialogs.
```gdscript
# Godot 4.7 sketch: screens are Controls under one CanvasLayer; only the top one is interactive.
# Each screen scene marks its default control with the unique name %DefaultFocus.
var _stack: Array[Control] = []
func push(screen: Control) -> void:
if not _stack.is_empty():
_set_interactive(_stack.back(), false)
_stack.append(screen)
add_child(screen)
screen.get_node("%DefaultFocus").grab_focus()
func pop() -> void:
var top: Control = _stack.pop_back()
top.queue_free()
if not _stack.is_empty():
var below: Control = _stack.back()
_set_interactive(below, true)
below.get_node("%DefaultFocus").grab_focus()
func _set_interactive(screen: Control, on: bool) -> void:
# Godot 4.5+. set_process_input(false) would not do this: buttons get GUI input, not _input.
screen.focus_behavior_recursive = Control.FOCUS_BEHAVIOR_INHERITED if on else Control.FOCUS_BEHAVIOR_DISABLED
screen.mouse_behavior_recursive = Control.MOUSE_BEHAVIOR_INHERITED if on else Control.MOUSE_BEHAVIOR_DISABLED
# Pause overlay: get_tree().paused = true and set the overlay's process_mode = PROCESS_MODE_ALWAYS.
```
This mirrors the state-stack idea in `love2d-core`'s `references/state-stack.md`, applied to UI.
## 5. Diegetic vs non-diegetic UI
- **Non-diegetic:** drawn on the screen plane, outside the fiction (most HUDs). Cheapest, clearest.
- **Diegetic:** UI that exists in the world (ammo counter on the gun, health on the suit). More
immersive, more work, can hurt readability. Use for key elements, keep a non-diegetic fallback.
- **Spatial/world-space:** floating health bars, damage numbers — anchor to world position,
clamp to screen edges when off-screen, and scale with distance (3D).
## 6. Accessibility (bake in, don't bolt on)
- **Text size option** and never hardcode tiny fonts; size to a percentage of reference height.
Xbox Accessibility Guideline 101 floors: 26 px at 1080p (52 px at 4K) on console/TV, 18 px at
1080p on PC, and player scaling up to 200% without clipping or lost meaning.
- **Contrast & color independence:** text that carries gameplay information needs at least
4.5:1 contrast with its background, large text and key visual elements at least 3:1 (Xbox
Accessibility Guideline 102). Don't encode state in color alone — add icon/shape/text.
Provide colorblind-safe palettes.
- **Scalable hit targets** for touch (≥ ~9 mm); padding around small buttons.
- **Reduce-motion / reduce-flashing** toggles (coordinate with `game-feel`).
- **Full keyboard + gamepad** reachability (section 3); don't gate actions behind mouse-only.
## 7. Localization-ready layout
- Externalize strings (Godot `tr()` + translation CSV/PO; Unity Localization package). Never bake
display text into layout logic.
- Let containers **size to content** so longer translations (German is ~30% longer) don't clip.
Avoid fixed-width buttons sized to English.
- Leave room for RTL mirroring and different number/date formats.
- Keep icons separate from text so only strings need translating.
## Primary sources
- [Godot 4.7: Multiple resolutions](https://docs.godotengine.org/en/4.7/tutorials/rendering/multiple_resolutions.html)
- [Unity Input System 1.14: UI support](https://docs.unity3d.com/Packages/com.unity.inputsystem@1.14/manual/UISupport.html)
- [Xbox Accessibility Guideline 101: Text display](https://learn.microsoft.com/en-us/xbox/accessibility/xbox-accessibility-guidelines/101)
- [Xbox Accessibility Guideline 102: Contrast](https://learn.microsoft.com/en-us/xbox/accessibility/xbox-accessibility-guidelines/102)
- [Game Accessibility Guidelines](https://gameaccessibilityguidelines.com/)
SKILL.md
---
name: game-ui-ux
description: >
Design and build game UI/UX — HUDs, menus, and overlays — that survive every screen: anchor-
based responsive layout, resolution/aspect scaling and safe areas, keyboard/gamepad focus
navigation, a screen/menu state stack, and event-driven (not polled) HUD updates. Engine-
neutral patterns that pair with the detected engine's UI skill. Use when the user mentions
HUD, health bar, main menu, pause menu, settings screen, UI layout, anchors, UI scaling,
aspect ratio, safe area, controller/keyboard menu navigation, or wiring UI to game state.
---
# Game UI/UX
Build HUDs and menus that stay correct on a phone, an ultrawide monitor, and a TV across a
gamepad and a mouse. This skill owns the engine-neutral UI architecture — responsive layout,
scaling, focus navigation, screen flow, and how UI talks to game state — and defers the
concrete widget API to the engine UI skill.
## When to use
- Use when building a HUD (health/ammo/score), a menu (main/pause/settings), an inventory or
shop screen, or any overlay, and you want it to scale and navigate correctly.
- Use to fix UI that breaks at other resolutions/aspect ratios, ignores notches/safe areas,
can't be used with a controller, or is wired to game state by per-frame polling.
- Use to structure screen flow (title → game → pause → settings) as a stack, not flag soup.
**When *not* to use:** for the engine's concrete UI nodes/components and styling, use
`godot-ui-control` or Unity UI (UGUI/UI Toolkit). For *visual* punch (button pop, damage
numbers, shake) use `game-feel`. For branching conversation UI use `dialogue-systems`. For
translating UI strings, that is localization (see `references/` and `input-systems` for
rebinding screens). For card/board layout specifics, the `card-game` genre composes this skill.
## Core workflow
1. **Pick a layout model: anchors + containers, never absolute pixels.** Anchor elements to
edges/corners/center and let containers (rows, columns, grids) flow children. Absolute
`(x, y)` positions break at the first new resolution.
2. **Choose a scaling strategy** for the whole UI: a reference resolution that scales to fit
(most games), plus a policy for extra width/height on other aspect ratios (letterbox,
expand, or anchor HUD corners outward).
3. **Respect the safe area.** Inset critical UI from screen edges so notches, rounded corners,
and TV overscan don't clip it.
4. **Make every screen keyboard/gamepad navigable.** Set an initial focused control per screen,
define focus order/neighbors, and show a clear focus highlight. Mouse and focus must coexist.
5. **Model screens as a stack.** Push (pause over game), pop (resume), with input + visibility
handed to the top screen. This makes overlays and "back" trivial.
6. **Drive the HUD from events, not polling.** The HUD subscribes to `health_changed`,
`score_changed`, etc. and updates only when they fire — it does not read game state every
frame.
7. **Verify across screens and devices.** Resize the window, switch aspect ratios, unplug the
mouse and navigate by gamepad only, and confirm focus, scaling, and safe-area insets. Report
what you actually observed at which resolutions.
## Patterns
### 1. Anchors + containers, not absolute coordinates
```gdscript
# Godot 4.7. Anchor a HUD label to the TOP-LEFT; let a container flow a row of hearts.
func _ready() -> void:
$Score.set_anchors_preset(Control.PRESET_TOP_LEFT) # sticks to the corner at any size
# An HBoxContainer auto-lays-out children left-to-right; never position hearts by hand.
for i in lives:
$Hearts.add_child(make_heart()) # HBoxContainer spaces them for you
# Unity 6.3 LTS uGUI: set RectTransform anchors to the corner; use a HorizontalLayoutGroup.
# RIGHT: anchors + layout groups. WRONG: rect.anchoredPosition = new Vector2(640, 360) (1080p-only).
```
### 2. Scale to a reference resolution (one UI, many screens)
```text
# Godot 4.7 — Project Settings > Display > Window > Stretch:
# Mode = "canvas_items", Aspect = "expand", reference size e.g. 1920x1080.
# UI scales to the window; "expand" reveals extra space you anchor HUD corners into.
# Unity 6.3 LTS — Canvas > CanvasScaler:
# UI Scale Mode = "Scale With Screen Size", Reference Resolution = 1920x1080,
# Match = 0.5 (blend width/height) — pick 1.0 if your HUD is height-critical.
# Unity 6.3 LTS — UI Toolkit: the same three settings live on the PanelSettings asset
# (Scale Mode = Scale With Screen Size, Reference Resolution, Screen Match Mode/Match).
```
### 3. Safe-area inset for notches / overscan
```gdscript
# Godot 4.7. Inset a MarginContainer to the OS safe rect. Only Android and iOS report a real
# safe area; elsewhere Godot returns the screen's usable rect, so desktop margins are ~0.
func _apply_safe_area() -> void:
var safe := Rect2(DisplayServer.get_display_safe_area()) # screen pixels
var win := Rect2(Rect2i(DisplayServer.window_get_position(), DisplayServer.window_get_size()))
var inner := safe.intersection(win)
var to_ui := get_viewport_rect().size / win.size # window pixels -> UI units under stretch
$Margin.add_theme_constant_override("margin_left", int((inner.position.x - win.position.x) * to_ui.x))
$Margin.add_theme_constant_override("margin_top", int((inner.position.y - win.position.y) * to_ui.y))
$Margin.add_theme_constant_override("margin_right", int((win.end.x - inner.end.x) * to_ui.x))
$Margin.add_theme_constant_override("margin_bottom", int((win.end.y - inner.end.y) * to_ui.y))
# Unity 6.3 LTS: read Screen.safeArea (Rect in pixels) and set a panel's anchorMin/anchorMax to
# safeArea.position / (position+size) normalized by Screen.width/height.
```
### 4. Gamepad/keyboard focus (UI is unusable on a controller without it)
```gdscript
# Godot 4.7. Give each screen a default focus; Godot guesses neighbors from layout, so set
# them only where its guess is wrong (grids, wrap-around, skipping a disabled row).
func _on_screen_shown() -> void:
$PlayButton.grab_focus() # always focus SOMETHING on open
$PlayButton.focus_neighbor_bottom = $SettingsButton.get_path()
$SettingsButton.focus_neighbor_top = $PlayButton.get_path()
# Unity 6.3 LTS uGUI: EventSystem.SetSelectedGameObject(playButton) on enable; set each Selectable's
# Navigation (Explicit or Automatic). With the Input System package, the EventSystem needs an
# InputSystemUIInputModule, not the old StandaloneInputModule. UI Toolkit: call Focus() on the
# first focusable element. RIGHT: a control is focused on open. WRONG: nothing
# selected → the gamepad does nothing and the player is stuck.
```
### 5. Event-driven HUD (decouple UI from game logic)
```gdscript
# RIGHT: HUD reacts to a signal; it updates only when health actually changes.
func _ready() -> void:
player.health_changed.connect(_on_health_changed) # emitted by gameplay
func _on_health_changed(current: int, max_health: int) -> void:
$HealthBar.value = float(current) / max_health
# WRONG: func _process(dt): $HealthBar.value = player.hp / player.max_hp # polls every frame,
# couples UI to the player's internals, and runs work even when nothing changed.
```
## Pitfalls
- **Absolute pixel positions / a single design resolution.** Looks right on your monitor, broken
everywhere else. Anchor to edges/center and flow with containers.
- **No aspect-ratio policy.** 16:9-only layouts crop or letterbox badly on ultrawide and phones.
Decide expand vs letterbox and anchor HUD to corners that move outward.
- **Ignoring the safe area.** HUD under a notch or lost to TV overscan. Inset critical elements.
- **No initial focus / no focus neighbors.** The game is unplayable on a gamepad; players land
on a menu with nothing selected. Always focus one control and define navigation.
- **Polling game state in `_process`/`Update`.** Couples UI to internals and wastes work. Push
updates via signals/events.
- **Tiny fixed font sizes.** Unreadable on a TV-at-distance or a small phone. Scale text with the
UI and offer a text-size option. Xbox Accessibility Guideline 101 sets floors of 26 px at 1080p
on console/TV and 18 px at 1080p on PC, and asks for scaling up to 200% without losing content.
- **Menu flow as boolean flags** (`isPaused`, `inSettings`, …) becomes unmanageable. Use a
screen stack with push/pop.
- **Hardcoded English strings baked into layout.** Translations overflow buttons. Externalize
strings and let containers size to content (see `references/`).
- **Mouse-only or focus-only.** Support both; switching input device should not strand the user.
- **Unity uGUI menu ignores the gamepad or throws on start** after switching Active Input
Handling to the Input System: the scene still has a `StandaloneInputModule`. Replace it with
`InputSystemUIInputModule` (the Inspector offers a one-click swap). UI Toolkit in Unity 6 reads
the project-wide UI actions directly and needs no module.
- **A corner-anchored uGUI element grows off-screen** when its size changes (longer translated
text, a bigger text-size setting): its pivot was left at (0.5, 0.5), so it grows in every
direction. Set the pivot to the anchored corner or edge as well.
## References
- For stretch/scale modes per engine, the safe-area math, a complete focus-navigation and
screen-stack pattern, diegetic vs non-diegetic UI, accessibility (text size, contrast,
colorblind-safe state), and localization-ready layout, read `references/layout-and-flow.md`.
## Related skills
- `godot-ui-control`, Unity UI (UGUI/UI Toolkit) — the concrete widgets, themes, and styling.
- `game-feel` — button pops, transitions, and HUD juice that ride on top of this layout.
- `dialogue-systems` — conversation/choice UI that lives inside this UI shell.
- `input-systems` — device switching, rebinding screens, and accessible controls.
- `rpg`, `card-game`, `tower-defense`, `visual-novel` — UI-heavy genres that compose this skill.