hud-stack

# HUD Stack

UI that only looks right on your monitor is unfinished. Anchor it. Scale it. Focus something. Push screens. Never poll.

Inspired by gamedev-skills/awesome-gamedev-agent-skills game-ui-ux (Apache-2.0). Original Grok remake. Complements stick-map (input), juice-pass (button pop / HUD juice), branch-talk (dialogue inside the shell), lens-rig, save-slot. Not godot-teacher.

Read `references/ui-rules.md` before you design. Fill the three templates under `templates/`.

## When to use

- HUD (health, ammo, score), main / pause / settings menus, inventory or shop overlays
- Fix UI that breaks on other resolutions, ignores notches, or cannot be used with a gamepad
- Replace boolean menu flags with a real screen stack
- Stop per-frame polling of game state for the HUD

## When NOT to use

- Concrete Godot Control / Unity uGUI widget tutorials → use godot-teacher
- Hit juice, damage numbers, button pop → use juice-pass
- Dialogue graph content → use branch-talk
- Input rebinding document → use stick-map
- Aimbots, overlay cheats, ESP injectors, malware

## Inputs

- Platforms in scope (phone, PC, TV, ultrawide)
- Reference resolution (default 1920×1080) and aspect policy (expand / letterbox)
- Screens needed (title, game HUD, pause, settings, …)
- Devices (mouse, keyboard, gamepad, touch)
- Current pain: clipped HUD, no focus, poll spam, flag soup

## Procedure

1. Read `references/ui-rules.md`. Refuse cheat overlays and malware.
2. Layout model: anchors + containers (rows/columns/grids). Never absolute pixel positions for critical chrome.
3. Scaling: pick a reference resolution and a policy for extra width/height. Anchor HUD corners that should move outward on expand.
4. Safe area: inset critical elements from notches, rounded corners, and TV overscan.
5. Focus: every screen opens with an initial focused control, neighbors defined, visible highlight. Mouse and focus coexist; last device wins prompts (pair with stick-map).
6. Screen stack: push (pause over game), pop (resume). Top screen owns input and visibility. "Back" pops.
7. Event-driven HUD: subscribe to `health_changed`, `score_changed`, and cousins. Do not read player internals every frame.
8. Accessibility: text size option, contrast, colorblind-safe state (not color alone), reduce-flash note.
9. Externalize strings so translations can grow buttons; containers size to content.
10. Fill `templates/layout-card.md`, `templates/screen-stack.md`, and `templates/verify.md`. Optional tiny original pseudocode only if asked — engine-neutral, no vendor dumps.

## Output format

- Layout card (anchors, scale, safe area, text size)
- Screen stack (push/pop list, default focus per screen, HUD event list)
- Verify card (resolutions, gamepad-only, safe area, no polling)
- One line: game UI architecture worksheet; not a cheat overlay

## Safety

- Follow `references/ui-rules.md` with no exceptions.
- No aimbots, ESP, wallhacks, injected overlays, or account theft.
- No CSAM in UI mock content.
- Engine-neutral notes only. Not a Godot tutor.

## Stop conditions

- Three templates delivered, or refused for cheats / wrong scope (godot-teacher / juice-pass / branch-talk / stick-map)