HUD Elegance Pass — Design

HUD Elegance Pass — Design

Purpose

Reduce the live-gameplay HUD to only what’s survival-critical by default, escalate visual weight with actual urgency rather than showing everything at a constant volume, and replace one abstract ability icon with a diegetic (in-world) indicator. Companion context files PRODUCT.md/DESIGN.md (project root) ground this and future UI work in this project’s established visual language, in place of /impeccable’s web-oriented teach interview, which doesn’t fit a Godot game.

Explicitly out of scope: the EVE-style drone combat rework (hull/armor/shield stats, enemy targeting, recall/dock/repair) raised during this conversation. That’s a separate, substantial system change deserving its own dedicated brainstorm — not decided here. For this pass, decoy’s ability icon is simply grouped with the other toggle-hidden elements (see below); nothing about the drone/decoy simulation itself changes.

Current State (verified against the live code + a real capture)

• Top-center: HP pill + “Lv N” label + a green XP-to-next-level bar (Hud._hp_group).
• Top-left: three tightly-stacked rows — weapon dock (up to 6 circular icons), drone dock (up to 4 icons), and a single warp-ability icon below them (WeaponPanel, DroneDock, Hud._AbilityBars) — all roughly equal visual weight, a repeated-circle-grid pattern.
• A separate decoy ability icon (also in Hud._AbilityBars).
• Bottom: a control-hint bar that already self-dismisses after 5s or first move (ControlHint) — confirmed NOT a persistent clutter problem, left untouched.
• Y (controller) / V (keyboard) currently opens a weapon-stat-details overlay (main._toggle_weapon_info) that freezes the sim. Chris confirmed this is superseded by the already-built Ship Configuration screen and should be removed entirely.

Changes

1. Level/XP leaves the live HUD

Remove the level label and XP bar from Hud._hp_group — the top-center block becomes HP only. Level number moves to two places that already exist and already show related info:

• The upgrade/level-up choice panel’s header (alongside its existing “LEVEL UP” title).
• The Ship Configuration screen (alongside the loadout it already shows).

A brief celebratory moment (“level up cheer”) fires at the instant of leveling, before the upgrade panel opens: a short particle burst at the player’s position plus a brief flashed “LEVEL UP” text, both fading within under 1 second, paired with the existing audio.level_up() sound cue (no new audio work needed — the hook already exists). This is NOT a replacement for the upgrade panel opening afterward; it’s a quick diegetic acknowledgment first, so the moment reads as a celebration rather than a silent cut to a menu.

2. HP bar: wider, and prominence scales with urgency

Two independent changes to the same _hp_group:

• Width: increase Hud.BAR_W (currently 170px) and the pill backing to give the bar more presence on screen — exact value decided during implementation by eye against the actual play resolution, not pre-committed to a specific pixel count here.
• Prominence-by-urgency: at full HP, the bar renders subtly — lower opacity, thinner visual weight, quiet. As HP drops, it becomes progressively more prominent — rising opacity/glow intensity — reaching full visual weight at low HP. This reuses the EXACT same fraction thresholds as the existing Hud._hp_color(frac) color ramp (>0.6 healthy, 0.3–0.6 transitional, <0.3 danger) as the driver for prominence, so color and visual weight escalate together rather than on separate, inconsistent curves. Implementation: a new pure function (e.g. Hud._hp_prominence(frac) -> float, mirroring _hp_color’s shape) feeding the group’s modulate alpha and/or border/shadow intensity, called every update_hud() tick alongside the existing color update.

3. Warp ability goes diegetic; the ability-bar warp icon is removed

PlayerRenderer already renders a continuously-pulsing thruster plume (_thruster, update_visual(level, dt), render/player_renderer.gd) with no awareness of dash/warp cooldown state today. Extend update_visual to accept the same warp-ready signal main.gd already computes for the current ability-bar HUD (dash_frac/dash_ready at main.gd:1192) and drive a visibly distinct “ready” look — brighter/more intense glow and/or a faster pulse — versus a dimmer, calmer baseline while on cooldown. The existing Hud._AbilityBars warp icon is removed once this ships; the HUD no longer shows a separate warp readout at all.

Decoy’s ability icon is NOT changed by this task — it moves into the toggle-hidden group below, unchanged in appearance or behavior, since the broader drone/decoy rework is explicitly out of scope for this pass.

4. Y becomes “show tactical HUD”; old weapon-info overlay removed

• Remove main._toggle_weapon_info(), its dedicated overlay panel, and its Y/V bindings entirely (dead code — Ship Configuration supersedes it, per Chris).
• Y (controller) is repurposed as a toggle for a single grouped visibility state covering: weapon dock, drone dock, and the decoy ability icon. Hidden by default; pressing Y shows the group, pressing it again hides it (a plain toggle, not a hold-to-peek — matching the existing debug-overlay toggle convention on X). A keyboard-accessible equivalent is added for desktop play (exact key decided during implementation, avoiding existing bindings — V is freed by this same change and is the natural candidate). Touch platforms (iPhone/iPad) need an equivalent on-screen affordance since there’s no physical Y button — TouchControls gets a small toggle button for this, styled consistently with its existing ability buttons.
• When shown, the group gets an actual layout pass (not just unhidden as-is): break the current “three identical tightly-stacked rows of circles” pattern with intentional hierarchy — e.g. varied spacing between the weapon/drone/decoy groupings (tight within a group, more generous between groups) rather than uniform gaps throughout, so it reads as three distinct groupings rather than one repeated grid. Exact spacing values decided during implementation against the real screen, following the DESIGN.md component conventions (restrained glass/glow, 1–2px borders) already established.

Testing

• Pure functions (_hp_prominence, the warp-ready thruster intensity calc) are unit-tested headlessly, following this project’s existing convention for Hud/PlayerRenderer pure helpers (e.g. _hp_color itself is directly testable).
• The Y-toggle’s visibility state and the removal of _toggle_weapon_info are covered by GUT tests in main.gd’s existing test suite pattern.
• Determinism baseline unaffected — this is entirely render/UI-side, never touches /sim.
• Visual verification (layout spacing, HP prominence curve feel, thruster glow distinction, level-up cheer timing) needs a real capture or hands-on playtest — headless tests can confirm the data/state machine is correct but not that it looks right. Follow this project’s established temp-capture-harness convention (build, screenshot, delete) before calling this done, the same way tonight’s other UI passes were verified.

Non-Goals

• The EVE-style drone rework (separate future brainstorm, see Purpose above).
• Redesigning the level-up choice panel or Ship Configuration screen beyond adding the level number display each already has room for — this pass moves data to them, not a redesign of them.
• Touch-platform HUD layout beyond adding the one new toggle button — the broader touch HUD isn’t being redesigned in this pass.