mirror of
https://github.com/Donchitos/Claude-Code-Game-Studios.git
synced 2026-10-16 01:37:05 +00:00
Release 1.1.0 — one config file, and a process weight you choose
`project.yaml` at the repo root is now the single source of truth for a project's configuration, replacing `production/stage.txt`, `production/review-mode.txt` and `.claude/docs/technical-preferences.md` (all three still read as a fallback; nothing is force-deleted). **`modes.rigor` — one question instead of six.** `minimal`, `standard` or `full` fronts six knobs: `modes.workflow`, `docs.density`, `qa.level`, `modes.story_granularity`, `modes.review_mode` and `team.size`. It defaults to `minimal`, which is a change from 1.0's behaviour: the heavier tier was measured costing several times more to reach working code without producing a better result, and returning nothing when a fresh developer inherited the project. Pin `modes.rigor: standard` to keep 1.0's process level. Also in this release: - `/settings` to view or change any setting, and `project.local.yaml` for per-developer preferences that should not be committed. - `system_overrides` to hold one system to a higher standard than the rest of the project, and `testing.strict` to set per test type whether missing evidence blocks a story or warns. - A story that changes anything the player sees is not closed until the game has been launched, observed, and a screenshot retained in `production/qa/evidence/`. A parse check is not a run. This holds at every rigor level, including `minimal`, where automated tests are waived but the look is not. - The code root is engine-specific and enforced as such: Godot `src/`, Unity `Assets/`, Unreal `Source/<Module>/`. Two of the three will not build a project laid out any other way. - Migration tooling for existing projects: `.claude/scripts/migrate-v1-config.sh` converts a 1.0 layout, non-destructively by default, with a report to review before `--finalize` deletes anything. - Ask-before-write holds regardless of personal automation settings. Upgrading from 1.0 or earlier: see UPGRADING.md. Full list of changes: CHANGELOG.md. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_016xvzG3i7pWQg4LjyDwWMXd
This commit is contained in:
Donchitos
co-authored by
Claude Opus 5
Claude Opus 5
parent
984023ddac
commit
d05699707f
Vendored
+67
-242
@@ -1,5 +1,7 @@
|
||||
# HUD Design: [Game Name]
|
||||
|
||||
> Authoring guidance: .claude/docs/templates/guidance/hud-design-guide.md (load per-section as you author — do not read entirely).
|
||||
|
||||
> **Status**: Draft | In Review | Approved | Implemented
|
||||
> **Author**: [Name or agent — e.g., ui-designer]
|
||||
> **Last Updated**: [Date]
|
||||
@@ -20,89 +22,34 @@
|
||||
|
||||
## 1. HUD Philosophy
|
||||
|
||||
> **Why this section exists**: The HUD design philosophy is not decoration — it is a
|
||||
> design constraint that every subsequent decision is measured against. Without a
|
||||
> philosophy, individual elements get added on request ("the quest tracker wants a
|
||||
> bigger icon") without any principled way to push back. With a philosophy, there is
|
||||
> a shared, explicit standard. More importantly, the philosophy prevents the HUD from
|
||||
> slowly growing to cover the game world while each individual addition seemed
|
||||
> reasonable in isolation. Write this before specifying any elements.
|
||||
|
||||
**What is this game's relationship with on-screen information?**
|
||||
|
||||
[One paragraph. This is a design statement, not a description of features. Consider
|
||||
the game's genre, pacing, and player fantasy. A stealth game's HUD philosophy might
|
||||
be: "The world is the interface. If the player has to look away from the environment
|
||||
to survive, the HUD has failed." A tactics game might say: "Complete situational
|
||||
awareness is the game. The HUD is not an overlay — it is the battlefield."
|
||||
|
||||
Reference comparable games if helpful, but describe your specific stance:
|
||||
Example — diegetic-first action RPG: "We treat screen information as a concession,
|
||||
not a feature. Every HUD element must earn its pixel space by answering the question:
|
||||
would the player make demonstrably worse decisions without this information visible?
|
||||
If the answer is 'they'd adapt,' we put it in the environment instead."]
|
||||
[One-paragraph design statement — see guide Section 1 for framing and examples]
|
||||
|
||||
**Visibility principle** — when in doubt, show or hide?
|
||||
|
||||
[State the default resolution for ambiguous cases. Options:
|
||||
- Default to HIDE: information is available on demand (e.g., Dark Souls — no quest tracker, no minimap, stats are in a menu)
|
||||
- Default to SHOW: players prefer to be informed; cluttered is better than uncertain
|
||||
- Default to CONTEXTUAL: information appears when it becomes relevant and fades when it does not
|
||||
Most games benefit from contextual defaults. State your game's default clearly so every element decision is consistent.]
|
||||
[Default resolution for ambiguous cases: HIDE / SHOW / CONTEXTUAL — see guide]
|
||||
|
||||
**The Rule of Necessity for this game**:
|
||||
|
||||
[Complete this sentence: "A HUD element earns its place when ______________."
|
||||
|
||||
Example: "...the player would have to stop playing to find the same information
|
||||
elsewhere, or would make meaningfully worse decisions without it."
|
||||
|
||||
Example: "...removing it in playtesting causes measurable frustration or confusion
|
||||
in more than 25% of testers within the first hour of play."
|
||||
|
||||
This rule is the veto power over feature requests to add HUD elements. Document it
|
||||
so it can be cited in design reviews.]
|
||||
["A HUD element earns its place when ______________." — see guide for examples]
|
||||
|
||||
---
|
||||
|
||||
## 2. Information Architecture
|
||||
|
||||
> **Why this section exists**: Before specifying any HUD element's visual design,
|
||||
> position, or behavior, you must answer a more fundamental question: should this
|
||||
> information be on the HUD at all? This section is a forcing function — it requires
|
||||
> you to categorize EVERY piece of information the game world generates and make an
|
||||
> explicit, intentional decision about how each is presented. "We'll figure that out
|
||||
> later" is how games end up with 18 elements competing for the player's peripheral
|
||||
> vision. This table is the master inventory of game information, not just HUD information.
|
||||
> Categorize EVERY piece of information the game generates — this is the master
|
||||
> inventory of game information, not just HUD information. See guide Section 2
|
||||
> for a worked example covering typical information types.
|
||||
|
||||
| Information Type | Always Show | Contextual (show when relevant) | On Demand (menu/button) | Hidden (environmental / diegetic) | Reasoning |
|
||||
|-----------------|-------------|--------------------------------|------------------------|----------------------------------|-----------|
|
||||
| [Health / Vitality] | [X if action game — player needs constant awareness] | [X if exploration game — show only when injured] | [ ] | [ ] | [Example: always visible because health decisions (retreat, heal) must be instant in combat] |
|
||||
| [Primary resource (mana / stamina / ammo)] | [ ] | [X — show when resource is being consumed or is critically low] | [ ] | [ ] | [Example: contextual because stable resource levels are not decision-relevant] |
|
||||
| [Secondary resource (currency / materials)] | [ ] | [ ] | [X — check in inventory] | [ ] | [Example: on-demand because resource totals don't affect immediate gameplay decisions] |
|
||||
| [Minimap / Compass] | [X] | [ ] | [ ] | [ ] | [Example: always visible because navigation decisions are constant during exploration] |
|
||||
| [Quest objective] | [ ] | [X — show when objective changes or player is near it] | [ ] | [ ] | [Example: contextual — player knows their objective; only remind at key moments] |
|
||||
| [Enemy health bar] | [ ] | [X — show only during combat encounters] | [ ] | [ ] | [Example: contextual because enemy health is irrelevant outside combat] |
|
||||
| [Status effects (buffs/debuffs)] | [ ] | [X — show when active] | [ ] | [ ] | [Example: contextual because status effects only affect decisions when present] |
|
||||
| [Dialogue subtitles] | [X when dialogue is playing] | [ ] | [ ] | [ ] | [Example: always show while dialogue is active — accessibility requirement] |
|
||||
| [Combo / streak counter] | [ ] | [X — show while combo is active, hide on reset] | [ ] | [ ] | [Example: contextual because it communicates active performance, not baseline state] |
|
||||
| [Timer] | [ ] | [X — show only in timed sequences] | [ ] | [ ] | [Example: contextual because timers only exist in specific encounter types] |
|
||||
| [Tutorial prompts] | [ ] | [X — show for first-time situations only] | [ ] | [ ] | [Example: contextual and one-time; never repeat to experienced players] |
|
||||
| [Score / points] | [ ] | [X — show in score-relevant modes only] | [ ] | [ ] | [Example: contextual by game mode; hidden in modes where score is irrelevant] |
|
||||
| [XP / level progress] | [ ] | [ ] | [X — available via character screen] | [ ] | [Example: on-demand because progression does not affect in-moment gameplay decisions] |
|
||||
| [Waypoint / objective marker] | [ ] | [X — show when player is navigating to objective] | [ ] | [ ] | [Example: contextual — suppress during cutscenes, cinematic moments, and free exploration] |
|
||||
| [Information type — e.g., Health, resource, minimap, quest objective, subtitles, status effects, timer, XP] | [ ] | [ ] | [ ] | [ ] | [Why this presentation category] |
|
||||
|
||||
---
|
||||
|
||||
## 3. Layout Zones
|
||||
|
||||
> **Why this section exists**: The game world is the primary content — the HUD is a
|
||||
> frame around it. Before placing any element, divide the screen into named zones
|
||||
> with explicit positions and safe zone margins. This section prevents two failure
|
||||
> modes: (1) elements placed ad-hoc until the screen is cluttered, and (2) elements
|
||||
> that overlap platform-required safe zones and get rejected in certification.
|
||||
> Every element in Section 4 must be assigned to a zone defined here.
|
||||
|
||||
### 3.1 Zone Diagram
|
||||
|
||||
```
|
||||
@@ -139,84 +86,42 @@ so it can be cited in design reviews.]
|
||||
|
||||
| Zone Name | Screen Position | Safe Zone Compliant | Primary Elements | Max Simultaneous Elements | Notes |
|
||||
|-----------|----------------|---------------------|-----------------|--------------------------|-------|
|
||||
| [Top Left] | [Top-left corner, within safe margin] | [Yes — 10% from top, 10% from left] | [Health bar, stamina bar, shield bar] | [3] | [Vital status — player's own resources. Priority zone for player state.] |
|
||||
| [Top Center] | [Top edge, centered horizontally] | [Yes — 10% from top] | [Quest objective, area name (on enter)] | [1 — only one message at a time] | [Use for narrative context, not mechanical information. Keep text minimal.] |
|
||||
| [Top Right] | [Top-right corner, within safe margin] | [Yes — 10% from top, 10% from right] | [Ammo count, ability cooldowns] | [2] | [Weapon/ability state. Most relevant during active combat.] |
|
||||
| [Center] | [Screen center ±15%] | [N/A — not a margin zone] | [Crosshair, interaction prompt, hit marker] | [1 active at a time] | [CRITICAL: Nothing persistent here. Only momentary indicators.] |
|
||||
| [Bottom Left] | [Bottom-left corner, within safe margin] | [Yes — 10% from bottom, 10% from left] | [Minimap, ability icons] | [2] | [Navigation and ability readout. Small, non-intrusive.] |
|
||||
| [Bottom Center] | [Bottom edge, centered horizontally] | [Yes — 10% from bottom] | [Subtitles, tutorial prompts] | [2 — subtitle + tutorial may coexist] | [Highest-priority accessibility zone. Never place other elements here.] |
|
||||
| [Bottom Right] | [Bottom-right corner, within safe margin] | [Yes — 10% from bottom, 10% from right] | [Notification toasts, pick-up feedback] | [3 stacked] | [Transient notifications. Stack vertically. Oldest disappears first.] |
|
||||
| [Zone] | [Position] | [Yes/No + margins] | [Elements assigned] | [N] | [Zone purpose] |
|
||||
|
||||
**Safe zone margins by platform**:
|
||||
|
||||
| Platform | Top | Bottom | Left | Right | Notes |
|
||||
|----------|-----|--------|------|-------|-------|
|
||||
| [PC — windowed] | [0% — no safe zone required] | [0%] | [0%] | [0%] | [But respect minimum resolution — elements must not crowd at 1280x720] |
|
||||
| [PC — fullscreen] | [3%] | [3%] | [3%] | [3%] | [Slight margin for 4K TV-connected PCs] |
|
||||
| [Console — TV] | [10%] | [10%] | [10%] | [10%] | [Action-safe zone for broadcast-spec TVs. Some TVs overscan beyond this.] |
|
||||
| [Steam Deck] | [5%] | [5%] | [5%] | [5%] | [Small screen; safe zone is smaller but crowding risk is higher] |
|
||||
| [Mobile — portrait] | [15% top] | [10% bottom] | [5%] | [5%] | [15% top avoids notch/camera cutout on most devices] |
|
||||
| [Mobile — landscape] | [5%] | [5%] | [15% left] | [15% right] | [Thumb placement on landscape — side zones are obscured by hands] |
|
||||
| [Platform] | [%] | [%] | [%] | [%] | [Platform-specific notes] |
|
||||
|
||||
---
|
||||
|
||||
## 4. HUD Element Specifications
|
||||
|
||||
> **Why this section exists**: Each HUD element needs its own specification to be
|
||||
> built correctly. Ad-hoc implementation of HUD elements produces inconsistent
|
||||
> sizing, mismatched update frequencies, missing urgency states, and accessibility
|
||||
> failures. This section is the implementation brief for every element — fill it
|
||||
> completely before any element moves into development.
|
||||
|
||||
### 4.1 Element Overview Table
|
||||
|
||||
> One row per HUD element. This is the master inventory for implementation planning.
|
||||
|
||||
| Element Name | Zone | Always Visible | Visibility Trigger | Data Source | Update Frequency | Max Size (% screen W) | Min Readable Size | Overlap Priority | Accessibility Alt |
|
||||
|-------------|------|---------------|-------------------|-------------|-----------------|----------------------|------------------|-----------------|------------------|
|
||||
| [Health Bar] | [Top Left] | [Yes] | [N/A] | [PlayerStats] | [On value change] | [20%] | [120px wide] | [1 — highest] | [Numerical text label showing current/max: "80/100"] |
|
||||
| [Stamina Bar] | [Top Left] | [No — context] | [Show when consuming stamina; hide 3s after full] | [PlayerStats] | [Realtime during use] | [15%] | [80px wide] | [2] | [Numerical label, or hide if full (accessible assumption)] |
|
||||
| [Shield Indicator] | [Top Left] | [No — context] | [Show when shield is active or recently hit] | [PlayerStats] | [On value change] | [20%] | [120px wide] | [3] | [Numerical label. Must not use color alone — add shield icon.] |
|
||||
| [Ammo Counter] | [Top Right] | [No — context] | [Show when weapon is equipped; hide when unarmed] | [WeaponSystem] | [On fire / on reload] | [10%] | ["88/888" readable at game's min resolution] | [4] | [Text-only fallback: "32 / 120"] |
|
||||
| [Minimap] | [Bottom Left] | [Yes] | [N/A — but suppressed in cinematic mode] | [NavigationSystem] | [Realtime] | [18%] | [150x150px] | [5] | [Cardinal direction compass strip as fallback; must be toggleable] |
|
||||
| [Quest Objective] | [Top Center] | [No — context] | [Show on objective change; show when near objective location; hide after 5s] | [QuestSystem] | [On event] | [30%] | [Legible at body text size] | [6] | [Read aloud on objective change via screen reader] |
|
||||
| [Crosshair] | [Center] | [No — context] | [Show when ranged weapon equipped; hide in melee or unarmed] | [WeaponSystem / AimSystem] | [Realtime] | [3%] | [12px diameter minimum] | [1 — center zone priority] | [Reduce motion: static crosshair only. Option to enlarge.] |
|
||||
| [Interaction Prompt] | [Center] | [No — context] | [Show when player is within interaction range of an interactive object] | [InteractionSystem] | [On enter/exit interaction range] | [15%] | [24px icon + readable text] | [2 — center zone] | [Text description of interaction always present, not icon-only] |
|
||||
| [Subtitles] | [Bottom Center] | [No — always on when dialogue plays, if setting enabled] | [Show during any voiced line or ambient dialogue] | [DialogueSystem] | [Per dialogue line] | [60%] | [Minimum 24px font] | [1 — highest in zone] | [This IS the accessibility feature — see Section 8 for subtitle spec] |
|
||||
| [Damage Numbers] | [World-space / anchored to entity] | [No — context] | [Show on any damage event; duration 800ms] | [CombatSystem] | [On event] | [5% per number] | [18px minimum] | [3] | [Option to disable; numbers can overwhelm for photosensitive players] |
|
||||
| [Status Effect Icons] | [Top Left — below health bar] | [No — context] | [Show when any status effect is active on player] | [StatusSystem] | [On effect add/remove] | [3% per icon] | [24px per icon] | [3] | [Icon + text label on hover/focus. Never icon-only.] |
|
||||
| [Notification Toast] | [Bottom Right] | [No — event-driven] | [On loot, XP gain, achievement, quest update] | [Multiple — see Section 6] | [On event] | [25%] | [Legible at body text size] | [7 — lowest] | [Queued; never overlapping. Read by screen reader if subtitle mode on.] |
|
||||
| [Element] | [Zone] | [Yes/No] | [Trigger or N/A] | [Owning system] | [When it updates] | [%] | [px] | [N] | [Non-visual/non-color alternative] |
|
||||
|
||||
### 4.2 Element Detail Blocks
|
||||
|
||||
> For each element in the table above, write a detail block. Copy and complete
|
||||
> one block per element.
|
||||
> one block per element. See guide Section 4 for completed Health Bar and
|
||||
> Minimap examples.
|
||||
|
||||
---
|
||||
|
||||
**Health Bar**
|
||||
**[Element Name]**
|
||||
|
||||
- Visual description: [Horizontal fill bar. Left-to-right fill direction. Segmented at 25/50/75% to aid reading at a glance. Background: dark semi-transparent (40% opacity). Fill color: context-dependent — see Urgency States.]
|
||||
- Data displayed: [Current HP as fill percentage. Numerical value displayed as text below bar at all times: "80 / 100".]
|
||||
- Update behavior: [Bar fill decreases or increases smoothly using a lerp over 150ms per change. Large damage (>25% single hit) triggers a brief flash (1 frame white, then drain).]
|
||||
- Urgency states:
|
||||
- Normal (>50% HP): [Green fill, no special behavior]
|
||||
- Caution (25–50% HP): [Yellow fill, low warning pulse every 4 seconds]
|
||||
- Critical (<25% HP): [Red fill, persistent slow pulse (1 Hz), vignette appears at screen edges]
|
||||
- Zero (0% HP): [Bar empties and turns grey; death state begins]
|
||||
- Interaction: [Display only. Not interactive. Player cannot click, hover, or focus this element as an action target.]
|
||||
- Player customization: [Opacity adjustable (see Section 7 Tuning Knobs). Can be repositioned to any corner by player in accessibility settings.]
|
||||
|
||||
---
|
||||
|
||||
**Minimap**
|
||||
|
||||
- Visual description: [Circular mask, radius = 75px at reference resolution 1920x1080. Player icon at center. North always up unless player has unlocked "Rotate minimap" setting. Range = configurable, default 80 world units radius.]
|
||||
- Data displayed: [Player position, nearby enemies (if detection perk unlocked), quest markers within range, points of interest icons, traversal obstacles (walls, drops).]
|
||||
- Update behavior: [Realtime. Updates every frame. Enemy icons fade in/out as they enter/leave detection range over 300ms.]
|
||||
- Urgency states: [None for the map itself. Enemy icons turn red when they are in combat-alert state.]
|
||||
- Interaction: [Not interactive in-game. Press dedicated Map button to open the full map screen (separate UX spec).]
|
||||
- Player customization: [Size: S/M/L (70/90/110px radius). Opacity: 30–100%. Rotation: locked-north or player-relative. Can be disabled entirely (compass strip shows as fallback).]
|
||||
- Visual description: [Shape, fill direction, background, color behavior]
|
||||
- Data displayed: [Values shown, including any numerical text labels]
|
||||
- Update behavior: [Animation/lerp timing, flash behavior on large changes]
|
||||
- Urgency states: [Per-threshold visual states, e.g., Normal / Caution / Critical / Zero]
|
||||
- Interaction: [Interactive or display-only]
|
||||
- Player customization: [Opacity, repositioning, size options]
|
||||
|
||||
---
|
||||
|
||||
@@ -226,58 +131,32 @@ so it can be cited in design reviews.]
|
||||
|
||||
## 5. HUD States by Gameplay Context
|
||||
|
||||
> **Why this section exists**: The HUD is not a static overlay — it is a dynamic
|
||||
> system that must adapt to what the player is doing. A HUD designed only for
|
||||
> standard gameplay will look wrong in cutscenes, feel cluttered in exploration,
|
||||
> and occlude critical information in boss fights. This section defines the
|
||||
> transformations the HUD undergoes in each gameplay context. It is also the spec
|
||||
> for the system that manages HUD visibility — the HUD state machine.
|
||||
> Define the HUD transformation for every gameplay context — at minimum:
|
||||
> exploration, combat, dialogue/cutscene, and paused/menu. See guide Section 5
|
||||
> for a worked example covering nine contexts.
|
||||
|
||||
| Context | Elements Shown | Elements Hidden | Elements Modified | Transition Into This State |
|
||||
|---------|---------------|-----------------|------------------|---------------------------|
|
||||
| [Exploration — no threats] | [Minimap, Quest Objective (faded, 60%), Subtitles (if active)] | [Ammo Counter, Crosshair, Damage Numbers, Status Effects (if none active)] | [Health Bar fades to 40% opacity — visible but not dominant] | [Fade transition, 500ms, when no enemies detected for 10s] |
|
||||
| [Combat — active threat] | [Health Bar (full opacity), Stamina Bar (when used), Ammo Counter, Crosshair, Damage Numbers, Status Effects, Enemy Health Bars] | [Quest Objective (temporarily hidden), Notification Toasts (paused queue)] | [Minimap scales down 15% and raises opacity to 100%] | [Immediate snap in on first enemy detection — no fade. Combat readiness requires instant info.] |
|
||||
| [Dialogue / Cutscene] | [Subtitles, Dialogue speaker name] | [All gameplay HUD elements: health, ammo, minimap, crosshair, damage numbers] | [N/A] | [All gameplay elements fade out over 300ms when cutscene flag is set] |
|
||||
| [Cinematic (scripted camera sequence)] | [Subtitles only] | [Everything else including speaker name] | [Letterbox bars appear (if applicable to this game's style)] | [Immediate on cinematic flag; letterbox slides in from top/bottom over 400ms] |
|
||||
| [Inventory / Menu open] | [None — inventory renders full-screen or as overlay] | [All HUD elements] | [Game world visible but paused behind inventory screen] | [All HUD elements hide over 150ms as menu opens] |
|
||||
| [Death / Respawn pending] | [Death screen overlay — separate spec] | [All gameplay HUD elements] | [Screen desaturates and darkens over 800ms] | [Death state begins when HP reaches 0 — HUD elements fade over 600ms] |
|
||||
| [Loading / Transition] | [Loading indicator, tip text] | [All gameplay HUD elements] | [N/A] | [Instant on level transition trigger] |
|
||||
| [Tutorial — new mechanic] | [Standard context HUD + Tutorial Prompt overlay] | [Nothing additional hidden] | [Tutorial prompt dims background subtly to draw attention to prompt] | [Tutorial system fires ShowTutorial event; prompt fades in over 200ms] |
|
||||
| [Boss Encounter] | [Boss health bar appears (large, bottom of screen or top center), all combat elements] | [Quest Objective] | [Boss bar renders in a distinct visual style — must not be confused with player health] | [Boss health bar slides in on boss encounter trigger over 400ms] |
|
||||
| [Context — e.g., Exploration / Combat / Dialogue / Cinematic / Menu open / Death / Loading / Tutorial / Boss] | [Shown] | [Hidden] | [Modified] | [Transition timing + trigger] |
|
||||
|
||||
---
|
||||
|
||||
## 6. Information Hierarchy
|
||||
|
||||
> **Why this section exists**: Not all HUD information is equally important. When
|
||||
> screen space is limited, when the player is under high stress, or when elements
|
||||
> compete for the same zone, there must be a principled priority order that governs
|
||||
> which elements survive and which get suppressed. This section formalizes that
|
||||
> hierarchy so it can be enforced systematically and not just "feels obvious" decisions
|
||||
> made at implementation time.
|
||||
> Assign every element a priority tier (MUST KEEP / SHOULD KEEP / CAN HIDE /
|
||||
> ALWAYS HIDE) with reasoning. See guide Section 6 for a worked example.
|
||||
|
||||
| Element | Priority Tier | Reasoning | What Replaces It If Hidden |
|
||||
|---------|--------------|-----------|---------------------------|
|
||||
| [Subtitles] | [MUST KEEP — never hide during dialogue] | [Accessibility requirement. Legal requirement in some markets. Story clarity.] | [N/A — nothing replaces subtitles] |
|
||||
| [Health Bar] | [MUST KEEP — during any state where the player can be damaged] | [Without health visibility, survival decisions become impossible] | [Auditory cues (heartbeat, breathing) supplement but do not replace] |
|
||||
| [Crosshair] | [MUST KEEP — while aiming with a ranged weapon] | [Targeting without a crosshair is a precision failure, not a difficulty feature] | [Alternative: dot-only mode for minimalists; never fully hidden while aiming] |
|
||||
| [Interaction Prompt] | [MUST KEEP — when player is in interaction range] | [Without it, interactive objects are invisible to the player] | [Environmental visual cues can supplement but interaction affordance must be explicit] |
|
||||
| [Ammo Counter] | [SHOULD KEEP] | [Low ammo decisions (switch weapon, reload) require awareness; can be contextual] | [Auditory "click" on empty chamber is acceptable fallback for experienced players] |
|
||||
| [Minimap] | [SHOULD KEEP] | [Navigation requires spatial awareness; loss forces repeated map opens] | [Compass strip (simplified directional indicator) is acceptable fallback] |
|
||||
| [Status Effects] | [SHOULD KEEP — while active] | [Active debuffs change what actions are viable; invisible debuffs feel unfair] | [Character animation states can partially communicate status effects (limping, sparks)] |
|
||||
| [Quest Objective] | [CAN HIDE] | [Player can hold objective in memory for extended periods; contextual is correct default] | [Player remembers objective from context] |
|
||||
| [Damage Numbers] | [CAN HIDE] | [Feedback element, not decision-critical. Many players turn these off.] | [Hit sounds and enemy reactions communicate hit registration] |
|
||||
| [Notification Toasts] | [CAN HIDE in high-intensity moments] | [Mid-combat "You gained 50 XP" is noise, not signal. Queue and show after combat.] | [Queue held and released when combat ends] |
|
||||
| [Combo Counter] | [ALWAYS HIDE when combo resets or player is not attacking] | [Stale combo information is actively misleading] | [N/A — simply hidden] |
|
||||
| [Element] | [MUST KEEP / SHOULD KEEP / CAN HIDE / ALWAYS HIDE] | [Why] | [Fallback channel or N/A] |
|
||||
|
||||
---
|
||||
|
||||
## 7. Visual Budget
|
||||
|
||||
> **Why this section exists**: Without explicit budget constraints, HUD elements
|
||||
> accumulate until the game world is nearly invisible. These numbers are hard limits,
|
||||
> not guidelines. Every element addition that would breach a limit requires explicit
|
||||
> approval and must displace or reduce an existing element.
|
||||
> These numbers are hard limits, not guidelines. Every element addition that
|
||||
> would breach a limit requires explicit approval and must displace or reduce an
|
||||
> existing element. See guide Section 7 for how to apply the budgets.
|
||||
|
||||
| Budget Constraint | Limit | Measurement Method | Current Estimate | Status |
|
||||
|------------------|-------|--------------------|-----------------|--------|
|
||||
@@ -289,60 +168,37 @@ so it can be cited in design reviews.]
|
||||
| Maximum opacity for HUD background panels | [65%] | [Opacity of any panel behind HUD text — must preserve world visibility through panel] | [TBD] | [To verify] |
|
||||
| Minimum HUD element size at minimum supported resolution | [40px for icons, 18px for text] | [Measure at lowest target resolution] | [TBD] | [To verify] |
|
||||
|
||||
> **How to apply these budgets**: For every new HUD element proposed during
|
||||
> production, require the proposer to state (1) which budget line it affects,
|
||||
> (2) what the new total will be, and (3) what existing element will be reduced or
|
||||
> made contextual to stay within budget. "It's a small icon" is not an analysis.
|
||||
|
||||
---
|
||||
|
||||
## 8. Feedback & Notification Systems
|
||||
|
||||
> **Why this section exists**: Notifications are the most frequently-added and
|
||||
> worst-controlled part of most HUDs. Every system wants to tell the player
|
||||
> something. Without explicit rules about notification priority, stacking limits,
|
||||
> and queue behavior, the notification zone becomes a firehose of overlapping
|
||||
> toasts that players learn to ignore entirely. This section establishes the
|
||||
> notification contract for all systems.
|
||||
> One row per notification type. Every notification must have queue/priority
|
||||
> behavior defined. See guide Section 8 for a worked example table and queue rules.
|
||||
|
||||
| Notification Type | Trigger System | Screen Position | Duration (ms) | Animation In / Out | Max Simultaneous | Priority | Queue Behavior | Dismissible? |
|
||||
|------------------|---------------|-----------------|--------------|-------------------|-----------------|----------|---------------|-------------|
|
||||
| [Item Pickup] | [InventorySystem] | [Bottom Right — toast] | [2000] | [Slide in from right 200ms / fade out 300ms] | [3 stacked] | [Low] | [FIFO queue; older toasts pushed up as new ones enter] | [No — auto-dismiss] |
|
||||
| [XP Gain] | [ProgressionSystem] | [Bottom Right — toast, below item toasts] | [1500] | [Fade in 150ms / fade out 300ms] | [1 — XP messages merge: "XP +150"] | [Very Low — suppress during combat, queue for post-combat] | [Combat-aware queue] | [No] |
|
||||
| [Level Up] | [ProgressionSystem] | [Center screen — persistent until dismissed] | [Persistent — requires input to dismiss] | [Scale up from 80% + fade in 400ms] | [1] | [High — interrupts normal toasts] | [Pauses all other notifications until dismissed] | [Yes — any input] |
|
||||
| [Quest Update] | [QuestSystem] | [Top Center] | [4000] | [Slide down from top 250ms / fade out 400ms] | [1 — top center is single-message zone] | [Medium] | [If quest update arrives while previous is visible, extend duration by 2000ms; do not stack] | [No] |
|
||||
| [Objective Complete] | [QuestSystem] | [Top Center] | [3000] | [Same as Quest Update but with additional completion sound] | [1] | [Medium-High — preempts Quest Update] | [Preempts any queued top-center message] | [No] |
|
||||
| [Critical Warning (low health, hazard)] | [CombatSystem / EnvironmentSystem] | [Screen edge vignette + text at center-bottom] | [Persistent while condition active] | [Fade in 200ms; fades out 500ms when condition clears] | [1 per warning type] | [Critical — never suppressed] | [Renders immediately, bypasses all queues] | [No] |
|
||||
| [Achievement Unlocked] | [AchievementSystem] | [Bottom Right — distinct from item toasts] | [4000] | [Slide in from right with icon expansion 300ms / fade out 400ms] | [1] | [Low] | [Queues behind item toasts; never more than one achievement toast at a time] | [No] |
|
||||
| [Hint / Tutorial] | [TutorialSystem] | [Bottom Center] | [Persistent — until player performs the action or dismisses] | [Fade in 300ms] | [1] | [Medium] | [Only one tutorial hint at a time; queue others] | [Yes — B button / Esc] |
|
||||
| [Type] | [System] | [Zone] | [ms] | [In / out animation + timing] | [N] | [Priority] | [Queue/merge/preempt behavior] | [Yes/No] |
|
||||
|
||||
**Notification queue rules**:
|
||||
1. Combat-aware queue: notifications tagged as Low priority are queued, not displayed, when the player is in combat state. The queue is flushed in a batch when the player exits combat, with a max of 3 items displayed in sequence.
|
||||
2. Merge rule: identical notification types that fire within 500ms of each other are merged into a single notification with a combined value (e.g., "Item Pickup x3" rather than three separate toasts).
|
||||
3. Critical notifications (health warning, environmental hazard) are never queued, never merged, and always displayed immediately regardless of combat state or existing notifications.
|
||||
1. [Combat-aware queue rule — which priorities are held during combat and how the queue flushes]
|
||||
2. [Merge rule — when identical notification types merge into one]
|
||||
3. [Critical bypass rule — which notifications are never queued, never merged]
|
||||
|
||||
---
|
||||
|
||||
## 9. Platform Adaptation
|
||||
|
||||
> **Why this section exists**: A HUD designed at 1920x1080 on a monitor may be
|
||||
> illegible on a 55-inch TV at 4K, broken at 1280x720 on Steam Deck, or hidden
|
||||
> behind a notch on mobile. Platform adaptation is not optional post-ship work —
|
||||
> it is a design requirement that must be specified before implementation so the
|
||||
> architecture can support it from the start. Every platform listed here requires
|
||||
> explicit layout testing before certification.
|
||||
> Every target platform requires explicit layout testing before certification.
|
||||
> See guide Section 9 for a worked example.
|
||||
|
||||
| Platform | Safe Zone | Resolution Range | Input Method | HUD-Specific Notes |
|
||||
|----------|-----------|-----------------|-------------|-------------------|
|
||||
| [PC — Windows, 1920x1080 reference] | [3% margin] | [1280x720 min to 3840x2160 max] | [Mouse + keyboard, controller optional] | [HUD must scale correctly at all resolutions. Test at 1280x720 — minimum before cert. Consider ultrawide (21:9) — minimap must not stretch.] |
|
||||
| [PC — Steam Deck, 1280x800] | [5% margin] | [Fixed 1280x800] | [Controller + touchscreen] | [Smaller screen means minimum text sizes are critical. Test ALL elements at this resolution. Touch targets irrelevant (controller-only by default).] |
|
||||
| [PlayStation 5 / Xbox Series X] | [10% margin] | [1080p to 4K] | [Controller] | [Console certification requires TV safe zone compliance. Action-safe is 90% of screen area. Test on a real TV, not a monitor — overscan behavior differs.] |
|
||||
| [Mobile — iOS / Android] | [15% top, 10% other sides] | [360x640 min to 414x896 common] | [Touch] | [Notch/camera cutout avoidance at top. Bottom home indicator zone avoidance. Portrait and landscape layouts may differ significantly — specify both.] |
|
||||
| [Platform] | [Margin] | [Min–max resolution] | [Input] | [Platform-specific HUD constraints] |
|
||||
|
||||
**HUD repositionability requirement**: Players must be able to reposition at minimum the following elements using an in-game HUD layout editor (required for accessibility compliance on console):
|
||||
- Health bar
|
||||
- Minimap
|
||||
- Ability bar (if present)
|
||||
- [Health bar]
|
||||
- [Minimap]
|
||||
- [Ability bar (if present)]
|
||||
|
||||
Repositioning saves to player profile, not to a single slot. Applies across play sessions.
|
||||
|
||||
@@ -350,48 +206,30 @@ Repositioning saves to player profile, not to a single slot. Applies across play
|
||||
|
||||
## 10. Accessibility — HUD Specific
|
||||
|
||||
> **Why this section exists**: HUD accessibility failures are the most visible
|
||||
> accessibility failures in games — players encounter the HUD in every session,
|
||||
> in every gameplay moment. Color-blind failures, illegible text at minimum scale,
|
||||
> and inability to disable distracting animations are among the top accessibility
|
||||
> complaints in game reviews. This section defines HUD-specific requirements; refer
|
||||
> to the project's `docs/accessibility-requirements.md` for the full project standard.
|
||||
> HUD-specific requirements only — refer to the project's
|
||||
> `design/accessibility-requirements.md` for the full project standard.
|
||||
|
||||
### 10.1 Colorblind Modes
|
||||
|
||||
| Element | Color-Only Information Risk | Colorblind Mode Fix |
|
||||
|---------|----------------------------|---------------------|
|
||||
| [Health bar fill] | [Red = low health uses red/green distinction] | [Add icon pulse + vignette as non-color indicators. Red fill is supplemental, not sole indicator.] |
|
||||
| [Damage numbers] | [Red = taken, green = healed] | [Add minus (-) prefix for damage, plus (+) for healing. Symbols, not color.] |
|
||||
| [Enemy health bars] | [If colored by faction or threat level] | [Add text label or icon badge for faction/threat level. Never color-only.] |
|
||||
| [Status effect icons] | [If icon tint communicates status type] | [All status icons must have distinct shapes, not just distinct colors. Shape encodes meaning; color is secondary.] |
|
||||
| [Minimap icons] | [If player vs. enemy vs. objective distinguished by color] | [Distinct icon shapes: circle = player, triangle = enemy, star = objective. Color supplements shape.] |
|
||||
| [Element] | [Where color alone carries meaning] | [Non-color alternative: shape, icon, symbol, text] |
|
||||
|
||||
### 10.2 Text Scaling
|
||||
|
||||
[Describe what happens when the player sets the UI text scale to 150% (the maximum required for your Accessibility Tier). Which elements reflow? Which elements clip? Which elements are architecturally blocked from scaling (e.g., fixed-size canvases)?
|
||||
|
||||
Example: "Health bar numerical label grows with text scale — bar expands slightly to accommodate. Quest objective text wraps at 150% scale — verify Top Center zone can accommodate two-line objectives. Damage numbers do not scale (they are world-space, not screen-space) — this is an accepted limitation documented here."]
|
||||
[Describe what happens at 150% UI text scale: which elements reflow, clip, or are architecturally blocked from scaling — see guide Section 10 for an example narrative]
|
||||
|
||||
**Text scaling test matrix**:
|
||||
|
||||
| Element | 100% (baseline) | 125% | 150% | Overflow behavior |
|
||||
|---------|----------------|------|------|-------------------|
|
||||
| [Health bar label] | [Pass] | [Pass] | [TBD] | [Bar expands; does not overlap stamina bar] |
|
||||
| [Quest objective text] | [Pass] | [TBD] | [TBD] | [Wraps to second line; zone height expands] |
|
||||
| [Notification toast text] | [Pass] | [TBD] | [TBD] | [Toast width expands to max 35% screen width, then wraps] |
|
||||
| [Subtitle text] | [Pass] | [TBD] | [TBD] | [Dedicated subtitle zone — must accommodate scale] |
|
||||
| [Element] | [Pass/Fail/TBD] | [Pass/Fail/TBD] | [Pass/Fail/TBD] | [What happens on overflow] |
|
||||
|
||||
### 10.3 Motion Sensitivity
|
||||
|
||||
| Animation / Motion Element | Severity | Disabled by Reduced Motion Setting? | Replacement Behavior |
|
||||
|---------------------------|----------|-------------------------------------|---------------------|
|
||||
| [Health bar low-HP pulse] | [Mild] | [Yes] | [Solid fill, no pulse. Vignette remains as it is less likely to trigger sensitivity.] |
|
||||
| [Screen edge vignette] | [Moderate] | [Optional — separate toggle] | [Replace with static darkened corners at 30% opacity] |
|
||||
| [Damage numbers float upward] | [Mild] | [Yes] | [Instant appear/disappear in place, no float] |
|
||||
| [Notification toast slide-in] | [Mild] | [Yes] | [Instant appear at final position] |
|
||||
| [Level up center animation] | [High] | [Yes — required] | [Static level up card, no scale animation, no particle effects] |
|
||||
| [Combo counter scale pulse] | [Mild] | [Yes] | [Number increments without scale animation] |
|
||||
| [Animated element] | [Mild/Moderate/High] | [Yes/No/Optional] | [Static replacement] |
|
||||
|
||||
### 10.4 Subtitles Specification
|
||||
|
||||
@@ -400,15 +238,15 @@ Example: "Health bar numerical label grows with text scale — bar expands sligh
|
||||
> implementation discretion.
|
||||
|
||||
- **Default setting**: [ON or OFF — document your game's default and the rationale. Industry standard is ON by default.]
|
||||
- **Position**: Bottom Center zone, centered horizontally, above the bottom safe zone margin
|
||||
- **Max characters per line**: [42 characters — the readable limit for subtitle lines at minimum text size on TV viewing distance]
|
||||
- **Max simultaneous lines**: [2 lines before scrolling — do not display more than 2 lines at once]
|
||||
- **Speaker identification**: [Speaker name displayed in color or above subtitle text — never rely on color alone; add colon prefix: "ARIA: The door is locked."]
|
||||
- **Background**: [Semi-transparent black panel, 70% opacity, behind all subtitle text — ensures contrast against any game world background]
|
||||
- **Font size minimum**: [24px at 1080p reference — scales with text scale setting]
|
||||
- **Line break behavior**: [Break at natural language pause points — before conjunctions, after commas, never mid-word]
|
||||
- **Subtitle persistence**: [Each subtitle line holds for the duration of the spoken line plus 300ms after it ends — never disappear while audio is still playing]
|
||||
- **Non-dialogue captions**: [Document whether ambient sounds, music descriptions, and sound effects are captioned — e.g., "[tense music]", "[explosion in the distance]" — and where these appear if different from dialogue subtitles]
|
||||
- **Position**: [Zone, alignment, relationship to safe zone margin]
|
||||
- **Max characters per line**: [e.g., 42 characters — the readable limit at minimum text size on TV viewing distance]
|
||||
- **Max simultaneous lines**: [e.g., 2 lines before scrolling]
|
||||
- **Speaker identification**: [Name display method — never rely on color alone]
|
||||
- **Background**: [Panel treatment ensuring contrast against any game world background]
|
||||
- **Font size minimum**: [px at reference resolution — scales with text scale setting]
|
||||
- **Line break behavior**: [Break at natural language pause points — never mid-word]
|
||||
- **Subtitle persistence**: [Hold duration relative to spoken line — never disappear while audio is still playing]
|
||||
- **Non-dialogue captions**: [Whether ambient sounds, music, and SFX are captioned, and where these appear]
|
||||
|
||||
### 10.5 HUD Opacity and Visibility Controls
|
||||
|
||||
@@ -428,31 +266,20 @@ The following player-adjustable settings must be available from the Accessibilit
|
||||
|
||||
## 11. Tuning Knobs
|
||||
|
||||
> **Why this section exists**: HUD behavior should be data-driven to the same degree
|
||||
> as gameplay systems. Values that are hardcoded are values that require an engineer
|
||||
> to change. Values that are in config can be tuned by a designer or adjusted for
|
||||
> player preferences. Document all tunable parameters before implementation so the
|
||||
> programmer knows which values to externalize.
|
||||
> Document all tunable parameters before implementation so the programmer knows
|
||||
> which values to externalize. See guide Section 11 for a worked example.
|
||||
|
||||
| Parameter | Current Value | Range | Effect of Increase | Effect of Decrease | Player Adjustable? | Notes |
|
||||
|-----------|-------------|-------|-------------------|-------------------|-------------------|-------|
|
||||
| [Notification display duration (default)] | [2000ms] | [500ms – 5000ms] | [Toasts persist longer — less likely to be missed, more screen clutter] | [Toasts disappear faster — cleaner, higher miss risk] | [No — but player can adjust verbosity level] | [Per-type overrides in Section 8 take precedence] |
|
||||
| [Notification queue max size] | [8] | [3 – 15] | [More messages preserved but queue takes longer to clear] | [Older messages dropped earlier] | [No] | [Expand if playtesting reveals important messages being lost] |
|
||||
| [Health bar low-HP pulse frequency] | [1 Hz] | [0.5 – 2 Hz] | [More urgent feeling — can become fatiguing] | [Calmer — may fail to communicate urgency] | [No — but Reduced Motion disables it] | [Linked to accessibility setting] |
|
||||
| [Combat HUD reveal duration] | [0ms (instant)] | [0 – 300ms] | [Softer reveal — feels less jarring] | [Instant — highest responsiveness] | [No] | [Keep at 0ms — combat information must be instant] |
|
||||
| [Exploration HUD fade-out delay] | [10000ms (10s after last threat)] | [3000 – 30000ms] | [HUD fades sooner — cleaner exploration] | [HUD stays longer — more reassurance] | [No] | [Tune based on playtest; 10s is a starting estimate] |
|
||||
| [Minimap range (world units visible)] | [80] | [40 – 200] | [More map context visible] | [Tighter local view] | [Yes — Small/Medium/Large preset] | [Exposed as S/M/L, not raw unit value] |
|
||||
| [Minimap size (px radius at 1080p)] | [75] | [50 – 120] | [Larger map, more screen space consumed] | [Smaller, less intrusive] | [Yes — S/M/L preset] | [Three sizes exposed to player] |
|
||||
| [Damage number duration (ms)] | [800] | [400 – 1500] | [Numbers linger longer — easier to read, more cluttered] | [Numbers clear faster — cleaner, harder to parse] | [No] | [Tune based on visual noise in dense combat] |
|
||||
| [Global HUD opacity] | [100%] | [0 – 100%] | [Fully visible] | [Fully hidden] | [Yes — opacity slider in Accessibility settings] | [0% = full HUD off; some players prefer this] |
|
||||
| [Parameter] | [Value] | [Min–max] | [Effect] | [Effect] | [Yes/No + how exposed] | [Tuning notes] |
|
||||
|
||||
---
|
||||
|
||||
## 12. Acceptance Criteria
|
||||
|
||||
> **Why this section exists**: These criteria are the certification checklist for the
|
||||
> HUD. Every item must pass before the HUD can be marked Approved. QA must be able
|
||||
> to verify each item independently.
|
||||
> These criteria are the certification checklist for the HUD. Every item must
|
||||
> pass before the HUD can be marked Approved. QA must be able to verify each
|
||||
> item independently.
|
||||
|
||||
**Layout & Visibility**
|
||||
- [ ] All HUD elements are within platform safe zone margins on all target platforms
|
||||
@@ -495,11 +322,9 @@ The following player-adjustable settings must be available from the Accessibilit
|
||||
## 13. Open Questions
|
||||
|
||||
> Track unresolved design questions here. All questions must be resolved before
|
||||
> the HUD design document can be marked Approved.
|
||||
> the HUD design document can be marked Approved. See guide Section 13 for
|
||||
> example questions.
|
||||
|
||||
| Question | Owner | Deadline | Resolution |
|
||||
|----------|-------|----------|-----------|
|
||||
| [e.g., Should the minimap show enemy positions by default, or only after a detection skill is unlocked?] | [systems-designer + ui-designer] | [Sprint 5, Day 2] | [Pending — depends on progression GDD decision] |
|
||||
| [e.g., Does the game have a boss health bar, or do bosses use the standard enemy health bar? Bosses need a visually distinct treatment if they are significantly more important than normal enemies.] | [game-designer] | [Sprint 5, Day 1] | [Pending] |
|
||||
| [e.g., Damage numbers: diegetic (floating in world space, occluded by geometry) or screen space (always readable, overlaid on HUD layer)?] | [ui-designer + lead-programmer] | [Sprint 4, Day 5] | [Pending — architecture decision affects rendering layer choice] |
|
||||
| [e.g., Mobile portrait vs. landscape: does the game support both orientations? If yes, each requires its own zone layout.] | [producer] | [Sprint 3, Day 3] | [Pending — platform scope decision required first] |
|
||||
| [Add question] | [Owner] | [Deadline] | [Resolution] |
|
||||
|
||||
Reference in New Issue
Block a user