# HUD Framework Guide

`@aphrodite/game-hud` produces engine-portable HUD render plans. The package
does not assume DOM, Canvas, Unreal UMG, or a native renderer. A game runtime
can translate `HudRenderNode` payloads into its renderer of choice.

## Core Flow

1. Create a `HudManager`.
2. Register widgets or custom elements.
3. Update time-based state each frame with `update(deltaMs)`.
4. Call `render(viewport, playerPosition)` to receive sorted render nodes.
5. Send nodes to the platform renderer and screen-reader/accessibility bridge.

## Included Widgets

- HUD manager with registration, visibility, layering, anchors, global opacity,
  per-element opacity, safe-zone margins, and accessibility options.
- Resource bars with shape, fill direction, segments, high-contrast colors, and
  animated value changes.
- Minimap render-target descriptors with player arrow, zoom, rotation, blips,
  objective markers, and clamped marker projection.
- Compass bearing indicators with cardinal, POI, and quest markers.
- Damage indicators with directional angles and fade-out timing.
- Hit markers with critical-hit state and optional audio event IDs.
- Ammo counters with current/reserve/max, low-ammo state, and reload progress.
- Interaction prompts with action labels and distance-based auto-hide.
- Objective tracker progress with optional waypoint distance.
- Toast queue with priority sorting, visible stack limit, and auto-dismiss.
- Crosshair shape, thickness, and dynamic spread.
- Buff/debuff status icons with durations and stack counts.
- Accessibility descriptors, high-contrast color switching, UI scale, and
  reduced-motion handling.

## Renderer Contract

Each `HudRenderNode` includes:

- stable `id`, `type`, `anchor`, and `layer`
- safe-zone-adjusted `rect`
- final `visible` and `opacity`
- `ariaLabel` for screen-reader bridges
- `highContrast` flag
- widget-specific `payload`

Renderers should treat payloads as data, not behavior. Keep animation and input
policy in the manager or gameplay layer so HUD output stays deterministic in
tests and replays.
