Eve library

HUD Framework Guide

Guide

Revision 1

On this page

@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.