添加 claude code game studios 到项目
This commit is contained in:
panw
331
.claude/docs/templates/accessibility-requirements.md
vendored
Normal file
331
.claude/docs/templates/accessibility-requirements.md
vendored
Normal file
@@ -0,0 +1,331 @@
|
||||
# Accessibility Requirements: [Game Title]
|
||||
|
||||
> **Status**: Draft | Committed | Audited | Certified
|
||||
> **Author**: [ux-designer / producer]
|
||||
> **Last Updated**: [Date]
|
||||
> **Accessibility Tier Target**: [Basic / Standard / Comprehensive / Exemplary]
|
||||
> **Platform(s)**: [PC / Xbox / PlayStation 5 / Nintendo Switch / iOS / Android]
|
||||
> **External Standards Targeted**:
|
||||
> - WCAG 2.1 Level [A / AA / AAA]
|
||||
> - AbleGamers CVAA Guidelines
|
||||
> - Xbox Accessibility Guidelines (XAG) [Yes / No / Partial]
|
||||
> - PlayStation Accessibility (Sony Guidelines) [Yes / No / Partial]
|
||||
> - Apple / Google Accessibility Guidelines [Yes / No / N/A — mobile only]
|
||||
> **Accessibility Consultant**: [Name and organization, or "None engaged"]
|
||||
> **Linked Documents**: `design/gdd/systems-index.md`, `docs/ux/interaction-pattern-library.md`
|
||||
|
||||
> **Why this document exists**: Per-screen accessibility annotations belong in
|
||||
> UX specs. This document captures the project-wide accessibility commitments,
|
||||
> the feature matrix across all systems, the test plan, and the audit history.
|
||||
> It is created once during Technical Setup by the UX designer and producer,
|
||||
> then updated as features are added and audits are completed. If a feature
|
||||
> conflicts with a commitment made here, this document wins — change the feature,
|
||||
> not the commitment, unless the producer approves a formal revision.
|
||||
>
|
||||
> **When to update**: After each `/gate-check` pass, after any accessibility
|
||||
> audit, and whenever a new game system is added to `systems-index.md`.
|
||||
|
||||
---
|
||||
|
||||
## Accessibility Tier Definition
|
||||
|
||||
> **Why define tiers**: Accessibility is not binary. Defining four tiers gives
|
||||
> the team a shared vocabulary, forces an explicit commitment at the start of
|
||||
> production, and prevents scope creep in both directions ("we'll add it later"
|
||||
> and "we have to support everything"). The tiers below are this project's
|
||||
> definitions — the industry uses similar but not identical language. Commit to
|
||||
> a tier with specific feature targets, not just the tier name.
|
||||
|
||||
### Tier Definitions
|
||||
|
||||
| Tier | Core Commitment | Typical Effort |
|
||||
|------|----------------|----------------|
|
||||
| **Basic** | Critical player-facing text is readable at standard resolution. No feature requires color discrimination alone. Volume controls exist for music, SFX, and voice independently. The game is completable without photosensitivity risk. | Low — primarily design constraints |
|
||||
| **Standard** | All of Basic, plus: full input remapping on all platforms, subtitle support with speaker identification, adjustable text size, at least one colorblind mode, and no timed input that cannot be extended or toggled. | Medium — requires dedicated implementation work |
|
||||
| **Comprehensive** | All of Standard, plus: screen reader support for menus, mono audio option, difficulty assist modes, HUD element repositioning, reduced motion mode, and visual indicators for all gameplay-critical audio. | High — requires platform API integration and significant UI architecture |
|
||||
| **Exemplary** | All of Comprehensive, plus: full subtitle customization (font, size, color, background, position), high contrast mode, cognitive load assist tools, tactile/haptic alternatives for all audio-only cues, and external third-party accessibility audit. | Very High — requires dedicated accessibility budget and specialist consultation |
|
||||
|
||||
### This Project's Commitment
|
||||
|
||||
**Target Tier**: [Standard]
|
||||
|
||||
**Rationale**: [Write 3-5 sentences justifying the tier choice. Do not simply
|
||||
state the tier — explain the reasoning. Consider: What is the game's genre and
|
||||
how does it map to common accessibility barriers (e.g., fast-twitch games have
|
||||
motor barriers; reading-heavy games have visual barriers)? Who is the target
|
||||
player and what does the research say about disability prevalence in that group?
|
||||
What are the platform requirements (Xbox requires XAG compliance for ID@Xbox)?
|
||||
What is the team's capacity? What would dropping one tier cost the player base,
|
||||
in concrete terms?
|
||||
|
||||
Example: "This is a narrative RPG with turn-based combat targeted at players
|
||||
25-45. The turn-based structure eliminates the most severe motor barriers common
|
||||
in action games, but the reading-heavy design creates significant visual and
|
||||
cognitive barriers. Standard tier addresses all of these. Exemplary tier is not
|
||||
achievable without a dedicated accessibility engineer. Xbox ID@Xbox program
|
||||
requires XAG compliance for Game Pass consideration, which Standard meets.
|
||||
Dropping to Basic would exclude players who rely on colorblind modes or input
|
||||
remapping, estimated at 8-12% of the target audience based on AbleGamers data."]
|
||||
|
||||
**Features explicitly in scope (beyond tier baseline)**:
|
||||
- [e.g., "Full subtitle customization — elevated from Comprehensive because our
|
||||
game is dialogue-heavy and subtitles are a primary channel"]
|
||||
- [e.g., "One-hand mode for controller — we have hold inputs critical to combat"]
|
||||
|
||||
**Features explicitly out of scope**:
|
||||
- [e.g., "Screen reader for in-game world (not menus) — requires engine work
|
||||
beyond current capacity. Documented in Known Intentional Limitations."]
|
||||
|
||||
---
|
||||
|
||||
## Visual Accessibility
|
||||
|
||||
> **Why this section comes first**: Visual impairments affect the largest
|
||||
> proportion of players who use accessibility features. Color vision deficiency
|
||||
> alone affects approximately 8% of men and 0.5% of women. Text legibility at
|
||||
> TV viewing distance is frequently the single largest accessibility failure
|
||||
> in shipped games. Document every visual feature before implementation begins,
|
||||
> because retrofitting minimum text sizes or color decisions after assets are
|
||||
> locked is expensive.
|
||||
|
||||
| Feature | Target Tier | Scope | Status | Implementation Notes |
|
||||
|---------|-------------|-------|--------|---------------------|
|
||||
| Minimum text size — menu UI | Standard | All menu screens | Not Started | 24px minimum at 1080p. At 4K, scale proportionally. Reference: WCAG 2.1 SC 1.4.4 requires text resizable to 200% without loss of content. |
|
||||
| Minimum text size — subtitles | Standard | All voiced/captioned content | Not Started | 32px minimum at 1080p. Players viewing on TV at 3m are the constraint. |
|
||||
| Minimum text size — HUD | Standard | In-game HUD | Not Started | 20px minimum for critical information (health, ammo, objective). Non-critical HUD elements may be smaller. |
|
||||
| Text contrast — UI text on backgrounds | Standard | All UI text | Not Started | Minimum 4.5:1 ratio for body text (WCAG AA). 3:1 for large text (18px+ or 14px bold). Test with automated contrast checker on final color values. |
|
||||
| Text contrast — subtitles | Standard | Subtitle display | Not Started | Minimum 7:1 ratio (WCAG AAA) for subtitles — players read them quickly and cannot control background. Use drop shadow or opaque background box by default. |
|
||||
| Colorblind mode — Protanopia | Standard | All color-coded gameplay | Not Started | Red-green — affects ~6% of men. Primary concern: health bars, enemy indicators, map markers. Shift red signals to orange/yellow; shift green signals to teal. |
|
||||
| Colorblind mode — Deuteranopia | Standard | All color-coded gameplay | Not Started | Green-red — affects ~1% of men. Similar to Protanopia in practical impact. Often the same palette adjustment covers both. Verify with Coblis or Colour Blindness Simulator. |
|
||||
| Colorblind mode — Tritanopia | Standard | All color-coded gameplay | Not Started | Blue-yellow — rarer (~0.001%). Shift blue UI elements to purple; shift yellow to orange. |
|
||||
| Color-as-only-indicator audit | Basic | All UI and gameplay | Not Started | List every place color is the SOLE differentiator in the table below. Each must have a non-color backup (icon, shape, pattern, text label) before shipping. |
|
||||
| UI scaling | Standard | All UI elements | Not Started | Range: 75% to 150%. Default: 100%. Scaling must not break layout — test all screens at min and max. HUD scaling should be independent from menu scaling. |
|
||||
| High contrast mode | Comprehensive | Menus (minimum); HUD (preferred) | Not Started | Replace all semi-transparent backgrounds with fully opaque. Replace mid-tone UI colors with black/white/system-high-contrast colors. All interactive elements outlined. |
|
||||
| Brightness/gamma controls | Basic | Global | Not Started | Exposed in graphics settings. Include a reference calibration image (a gradient or symbol barely visible at correct calibration). Range: -50% to +50% from default. |
|
||||
| Screen flash / strobe warning | Basic | All cutscenes, VFX | Not Started | (1) Pre-launch warning screen with photosensitivity seizure notice. (2) Audit all flash-heavy VFX against Harding FPA standard (no more than 3 flashes per second above luminance threshold). (3) Optional: flash reduction mode that lowers flash amplitude by 80%. |
|
||||
| Motion/animation reduction mode | Standard | All UI transitions, camera shake, VFX | Not Started | Reduce or eliminate: screen shake, camera bob, motion blur, parallax scrolling in menus, looping background animations. Cannot fully eliminate: player movement animation (would break readability). Toggle in accessibility settings. |
|
||||
| Subtitles — on/off | Basic | All voiced content | Not Started | Default: OFF (industry standard — many players prefer immersion). Prominently offered at first launch. |
|
||||
| Subtitles — speaker identification | Standard | All voiced content | Not Started | Speaker name displayed before dialogue line. Color-coded by speaker IF colors differ by more than hue alone (test for colorblind compatibility). |
|
||||
| Subtitles — style customization | Comprehensive | Subtitle display | Not Started | Font size (4 sizes minimum), background opacity (0–100%), text color (white / yellow / custom), position (bottom / top / player-relative). |
|
||||
| Subtitles — sound effect captions | Comprehensive | Gameplay-critical SFX | Not Started | See Auditory Accessibility section for which SFX qualify. Format: [SOUND DESCRIPTION] in brackets, distinct from dialogue. |
|
||||
|
||||
### Color-as-Only-Indicator Audit
|
||||
|
||||
> Fill in every gameplay or UI element where color is currently the sole
|
||||
> differentiator. Resolve each before shipping. A resolved entry has a non-color
|
||||
> backup that works in all three colorblind modes above.
|
||||
|
||||
| Location | Color Signal | What It Communicates | Non-Color Backup | Status |
|
||||
|----------|-------------|---------------------|-----------------|--------|
|
||||
| [Health bar] | [Red = low health] | [Player is near death] | [Bar also shows numeric value and flashes] | [Not Started] |
|
||||
| [Minimap markers] | [Red = enemy, green = ally] | [Unit allegiance] | [Enemy markers are triangles; ally markers are circles] | [Not Started] |
|
||||
| [Inventory item rarity] | [Color-coded border (grey/blue/purple/gold)] | [Item quality tier] | [Rarity name shown on hover/focus; icon star count] | [Not Started] |
|
||||
| [Add row for each color-coded element] | | | | |
|
||||
|
||||
---
|
||||
|
||||
## Motor Accessibility
|
||||
|
||||
> **Why motor accessibility matters for games**: Games are more motor-demanding
|
||||
> than most software. A web form requires precise clicks; a game may require
|
||||
> rapid simultaneous button combinations held for specific durations. Motor
|
||||
> impairments span a wide range — from tremor (affecting precision) to
|
||||
> hemiplegia (one functional hand) to RSI (affecting hold duration). The AbleGamers
|
||||
> Able Assistance program estimates 35 million gamers in the US have a disability
|
||||
> affecting their ability to play. Many of the features below cost very little
|
||||
> to implement if planned from the start, and are extremely expensive to add post-launch.
|
||||
|
||||
| Feature | Target Tier | Scope | Status | Implementation Notes |
|
||||
|---------|-------------|-------|--------|---------------------|
|
||||
| Full input remapping | Standard | All gameplay inputs, all platforms | Not Started | Every input bound by default must be rebindable. Remapping applies to keyboard, mouse, controller, and any supported peripheral independently. No two actions may be bound to the same input simultaneously (warn on conflict). Persist remapping to player profile. |
|
||||
| Input method switching | Standard | PC | Not Started | Player must be able to switch between keyboard/mouse and gamepad at any moment without restarting. UI must update prompts dynamically (show correct button icons for active input method). |
|
||||
| One-hand mode | [Tier] | [Identify which features require two simultaneous hands] | Not Started | Audit every multi-input action. For each: can it be executed with a single hand? If not, provide a toggle alternative or hold-to-toggle version. Specify here which features have a one-hand path and which do not. |
|
||||
| Hold-to-press alternatives | Standard | All hold inputs | Not Started | Every "hold [button] to [action]" must offer a toggle alternative. Toggle mode: first press activates, second press deactivates. Example: "Hold to sprint" becomes optional "toggle sprint" mode. List all hold inputs in the game here. |
|
||||
| Rapid input alternatives | Standard | Any button mashing / rapid input sequences | Not Started | Any input requiring more than 3 presses per second sustained must offer a single-press toggle alternative. Example: Hades' "Hold to dash repeatedly" solves this elegantly. |
|
||||
| Input timing adjustments | Standard | QTEs, timed button presses, rhythm inputs | Not Started | Provide a timing window multiplier in accessibility settings. Minimum range: 0.5x to 3.0x. Default: 1.0x. At 3.0x, a 500ms window becomes 1500ms. Document every timed input in this game and test at all multiplier values. |
|
||||
| Aim assist | Standard | All ranged combat / targeting | Not Started | Not just on/off — provide granularity: Assist Strength (0–100%), Assist Radius, Aim Magnetism (snap-to-target), and Aim Slowdown (near-target deceleration) as separate sliders. Default values should be tuned to feel helpful, not intrusive. |
|
||||
| Auto-sprint / movement assists | Standard | Movement systems | Not Started | "Hold to sprint" toggle (covered above). Additionally: auto-run option (hold direction, player continues without input). Specify any movement input that is held continuously in normal gameplay. |
|
||||
| Platforming / traversal assists | [Tier] | [If game has platforming] | Not Started | Evaluate whether auto-grab (generous ledge detection), coyote time extension, and jump height adjustment are appropriate for this game's design. If platforming is not a game system, mark N/A. |
|
||||
| HUD element repositioning | Comprehensive | All HUD elements | Not Started | Allow players to move health bars, minimaps, and quest trackers to their preferred screen position. Particularly important for players using head-tracking or eye-gaze hardware who may have reduced peripheral vision coverage. |
|
||||
|
||||
---
|
||||
|
||||
## Cognitive Accessibility
|
||||
|
||||
> **Why cognitive accessibility is often under-specced**: Cognitive accessibility
|
||||
> affects players with ADHD, dyslexia, autism spectrum conditions, acquired brain
|
||||
> injuries, and anxiety disorders — a larger combined population than many studios
|
||||
> realize. It also benefits all players in high-stress moments. The most common
|
||||
> failures are: no pause anywhere, tutorial information that can only be seen once,
|
||||
> and systems that require tracking too many simultaneous states. Games like
|
||||
> Hades and Celeste have demonstrated that cognitive assist options (god mode,
|
||||
> persistent reminders, extended text display) do not harm the experience for
|
||||
> players who don't use them.
|
||||
|
||||
| Feature | Target Tier | Scope | Status | Implementation Notes |
|
||||
|---------|-------------|-------|--------|---------------------|
|
||||
| Difficulty options | Standard | All gameplay difficulty parameters | Not Started | Separate granular sliders where possible (damage dealt, damage received, enemy aggression, enemy speed) rather than a single Easy/Normal/Hard label. Document which parameters are adjustable and which are fixed. Fixed parameters require a design justification. |
|
||||
| Pause anywhere | Basic | All gameplay states | Not Started | Players must be able to pause during any gameplay state, including cutscenes, dialogue, and tutorial sequences. Document any state where pausing is currently prevented and the design justification for that restriction. Any restriction is a risk. |
|
||||
| Tutorial persistence | Standard | All tutorials and help text | Not Started | After dismissing a tutorial prompt, the player must be able to retrieve it from a Help section in the menu. Do not rely on players absorbing tutorials on first encounter — AbleGamers research shows many players dismiss prompts on reflex. |
|
||||
| Quest / objective clarity | Standard | Quest and objective systems | Not Started | The current active objective must be accessible within 2 button presses at all times during gameplay. Display the full objective text on demand, not just a truncated marker. Avoid objectives that require inference ("investigate the northern region" — where exactly?). |
|
||||
| Visual indicators for audio-only information | Standard | All SFX that carry gameplay information | Not Started | Audit every sound effect that communicates gameplay-critical state. For each: is there a visual equivalent? Directional audio (off-screen enemy) needs a screen-edge indicator. Critical warnings (boss phase transition, trap trigger) need visual cues. See Auditory Accessibility for full list. |
|
||||
| Reading time for UI | Standard | All auto-dismissing dialogs | Not Started | No dialog, notification, or tooltip that contains actionable information may auto-dismiss in less than 5 seconds. Preferred: do not auto-dismiss at all — require player confirmation. Document every auto-dismissing element here and its current duration. |
|
||||
| Cognitive load documentation | Comprehensive | Per game system | Not Started | For each system in systems-index.md, document the maximum number of things it asks the player to simultaneously track. Flag any system where the number exceeds 4. This is not a hard rule but a review trigger — high cognitive load systems need compensating UI clarity. See Per-Feature Accessibility Matrix below. |
|
||||
| Navigation assists | Standard | World navigation | Not Started | Fast travel (to previously visited locations), waypoint system for current objective, optional objective indicator always visible. Document which of these apply to this game's design and which are intentionally omitted. |
|
||||
|
||||
---
|
||||
|
||||
## Auditory Accessibility
|
||||
|
||||
> **Why auditory accessibility matters even for players without hearing loss**:
|
||||
> 7% of players are deaf or hard of hearing. Additionally, a large portion of
|
||||
> players regularly play in environments where audio is reduced or absent (commute,
|
||||
> shared household, infant sleeping). Any gameplay-critical information delivered
|
||||
> only through audio is a design failure even before accessibility is considered.
|
||||
> The guiding principle: every sound that changes what the player should DO next
|
||||
> must have a visual equivalent.
|
||||
|
||||
| Feature | Target Tier | Scope | Status | Implementation Notes |
|
||||
|---------|-------------|-------|--------|---------------------|
|
||||
| Subtitles for all spoken dialogue | Basic | All voiced content | Not Started | 100% coverage — no exceptions. Include narration, in-engine dialogue, radio/environmental dialogue heard from a distance. Test subtitle sync against voice acting timing. |
|
||||
| Closed captions for gameplay-critical SFX | Comprehensive | Identified SFX list (below) | Not Started | Not all SFX need captions — only those that communicate state the player cannot infer visually. See the SFX audit table below. |
|
||||
| Mono audio option | Comprehensive | Global audio output | Not Started | Folds stereo/spatial audio to mono. Preserves volume balance between channels rather than summing to full volume on both sides. Essential for players with single-sided deafness. |
|
||||
| Independent volume controls | Basic | Music / SFX / Voice / UI audio buses | Not Started | Four independent sliders minimum. Persist to player profile. Range: 0–100%, default 80%. Expose in both main settings and the pause menu. |
|
||||
| Visual representations for directional audio | Comprehensive | All off-screen threats and audio events | Not Started | Screen-edge indicator pointing toward the audio source. Opacity scales with audio volume (closer = more opaque). Two variants: threat indicators (red) and information indicators (neutral). Example: The Last of Us Part II uses screen-edge indicators for off-screen enemy positions. |
|
||||
| Hearing aid compatibility mode | Standard | High-frequency audio cues | Not Started | Audit all audio cues for frequency range. Any cue that communicates critical information only through high-frequency sound (above 4kHz) must have a low-frequency or visual equivalent. Hearing aids often filter high frequencies. |
|
||||
|
||||
### Gameplay-Critical SFX Audit
|
||||
|
||||
> Identify every sound effect that communicates state the player needs to act on.
|
||||
> Each entry in this table requires either a confirmed visual backup or a caption.
|
||||
|
||||
| Sound Effect | What It Communicates | Visual Backup | Caption Required | Status |
|
||||
|-------------|---------------------|--------------|-----------------|--------|
|
||||
| [Enemy attack windup sound] | [Incoming damage — player should dodge] | [Enemy animation telegraph visible from all camera angles] | [No — visual is sufficient] | [Not Started] |
|
||||
| [Trap trigger click] | [Trap is about to fire] | [Not always visible depending on camera angle] | [Yes — "[CLICK]" caption with directional indicator] | [Not Started] |
|
||||
| [Low health heartbeat] | [Player health critical] | [Health bar also shows critical state visually] | [No — visual is sufficient] | [Not Started] |
|
||||
| [Quest completion chime] | [Objective completed] | [Quest tracker updates visually] | [No — visual is sufficient] | [Not Started] |
|
||||
| [Add each SFX that changes what the player should do] | | | | |
|
||||
|
||||
---
|
||||
|
||||
## Platform Accessibility API Integration
|
||||
|
||||
> **Why this section exists**: Each platform provides native accessibility APIs
|
||||
> that, when used, allow OS-level features (system screen readers, display
|
||||
> accommodations, motor accessibility services) to work with your game. Ignoring
|
||||
> these APIs does not break the game, but it means players who rely on OS-level
|
||||
> accessibility tools get no benefit from them inside your game. Xbox in particular
|
||||
> requires XAG compliance for certification. Verify platform requirements before
|
||||
> committing to a tier — platform requirements set a floor, not a ceiling.
|
||||
|
||||
| Platform | API / Standard | Features Planned | Status | Notes |
|
||||
|----------|---------------|-----------------|--------|-------|
|
||||
| Xbox (GDK) | Xbox Game Core Accessibility / XAG | [Input remapping via Xbox Ease of Access, high contrast support, narrator integration for menus] | Not Started | XAG compliance is required for ID@Xbox Game Pass consideration. Review XAG checklist at https://docs.microsoft.com/gaming/accessibility/guidelines |
|
||||
| PlayStation 5 | Sony Accessibility Guidelines / AccessibilityNode API | [Screen reader passthrough for menus, mono audio, high contrast] | Not Started | PS5 natively supports system-level audio description and mono audio if the game exposes AccessibilityNode data on UI elements. |
|
||||
| Steam (PC) | Steam Accessibility Features / SDL | [Controller input remapping via Steam Input, subtitle support] | Not Started | Steam Input allows system-level remapping independent of in-game remapping. In-game remapping still required for keyboard/mouse. |
|
||||
| iOS | UIAccessibility / VoiceOver | [VoiceOver support for menus if mobile port planned] | N/A | Only required if mobile release is in scope. |
|
||||
| Android | AccessibilityService / TalkBack | [TalkBack support for menus if mobile port planned] | N/A | Only required if mobile release is in scope. |
|
||||
| PC (Screen Reader) | JAWS / NVDA / Windows Narrator | [Menu navigation announcements] | Not Started | Requires UI elements to expose accessible names and roles via platform UI layer. Godot 4.5+ AccessKit integration covers this for supported control types. Verify against engine-reference/godot/ docs. |
|
||||
|
||||
---
|
||||
|
||||
## Per-Feature Accessibility Matrix
|
||||
|
||||
> **Why this matrix exists**: Accessibility is not a list of settings — it is a
|
||||
> property of every game system. This matrix creates the "accessibility impact"
|
||||
> view of the game: which systems have which barriers, and whether those barriers
|
||||
> are addressed. When a new system is added to systems-index.md, a row must be
|
||||
> added here. If a system has an unaddressed accessibility concern, it cannot be
|
||||
> marked Approved in the systems index.
|
||||
|
||||
| System | Visual Concerns | Motor Concerns | Cognitive Concerns | Auditory Concerns | Addressed | Notes |
|
||||
|--------|----------------|---------------|-------------------|------------------|-----------|-------|
|
||||
| [Combat System] | [Enemy health bars are color-coded; attack animations may cause motion sickness] | [Rapid input required for combos; hold inputs for guard] | [Track enemy patterns + cooldowns + player resources simultaneously] | [Audio cues for off-screen attacks; critical damage warning sounds] | [Partial] | [Colorblind palette applied; hold-to-block toggle needed] |
|
||||
| [Inventory / Equipment] | [Item rarity conveyed by border color] | [No motor concerns — turn-based] | [Item stats comparison requires reading multiple values] | [None — no critical audio in this system] | [Partial] | [Non-color rarity indicators in progress] |
|
||||
| [Dialogue System] | [Subtitle display depends on contrast settings] | [No motor concerns] | [Long dialogue trees with time pressure on dialogue choices] | [All dialogue must be subtitled] | [Not Started] | [Timed dialogue choices must support extended timer option] |
|
||||
| [Navigation / World Map] | [Map marker colors] | [No motor concerns] | [Quest objective clarity; waypoint visibility] | [Audio pings for objectives have no visual equivalent] | [Not Started] | |
|
||||
| [Add system from systems-index.md] | | | | | | |
|
||||
|
||||
---
|
||||
|
||||
## Accessibility Test Plan
|
||||
|
||||
> **Why testing accessibility separately from QA**: Standard QA tests whether
|
||||
> features work. Accessibility testing tests whether features work for players
|
||||
> who use them. These are different tests. A subtitle system can pass QA (it
|
||||
> displays text) and fail accessibility testing (the text is unreadable at TV
|
||||
> distance by a player with low vision). Plan for three test types: automated
|
||||
> (contrast ratios, text sizes), manual internal (team members simulating
|
||||
> impairments using accessibility simulators), and user testing (players who
|
||||
> actually use these features).
|
||||
|
||||
| Feature | Test Method | Test Cases | Pass Criteria | Responsible | Status |
|
||||
|---------|------------|------------|--------------|-------------|--------|
|
||||
| Text contrast ratios | Automated — contrast analyzer tool on all UI screenshots | All text/background combinations at all game states | All body text ≥ 4.5:1; all large text ≥ 3:1; subtitle backgrounds ≥ 7:1 | ux-designer | Not Started |
|
||||
| Colorblind modes | Manual — Coblis simulator on all game screenshots with modes enabled | Gameplay screenshots in exploration, combat, inventory in each mode | No essential information is lost in any mode; player can complete all objectives without color discrimination | ux-designer | Not Started |
|
||||
| Input remapping | Manual — remap all inputs to non-default bindings, complete tutorial and first level | All default inputs rebound; gameplay functions correctly; no binding conflict possible | All actions accessible after remapping; conflict prevention works; bindings persist across restart | qa-tester | Not Started |
|
||||
| Subtitle accuracy | Manual — verify against voice script, check all lines | All voiced content; subtitle timing; speaker identification | 100% of voiced lines subtitled; speaker identified for all multi-character scenes; no subtitle display for more than 3 seconds after line ends | qa-tester | Not Started |
|
||||
| Hold input toggles | Manual — enable all toggle alternatives, complete all combat and traversal sequences | All hold inputs in toggle mode | All hold actions completable in toggle mode; no gameplay state requires sustained hold when toggle is enabled | qa-tester | Not Started |
|
||||
| Reduced motion mode | Manual — enable mode, navigate all menus and complete first hour of gameplay | All menu transitions; all HUD animations; all camera shake events | No looping animations in menus; no camera shake above threshold; all screen transitions are cross-fade or cut | ux-designer | Not Started |
|
||||
| Platform screen reader (menu) | Manual — enable OS screen reader, navigate all menus | Main menu, settings, pause menu, inventory, map | All interactive menu elements have screen reader announcements; navigation order is logical; no element unreachable by keyboard/D-pad | ux-designer | Not Started |
|
||||
| User testing — colorblind | User testing with colorblind participants | Full game session with each colorblind mode | Participants complete all content without requesting color clarification; no session-stopping confusion | producer | Not Started |
|
||||
| User testing — motor impairment | User testing with participants using one hand or adaptive controllers | Full game session with toggle and extended timing modes enabled | Participants complete all MVP content within tolerance of able-bodied completion time | producer | Not Started |
|
||||
|
||||
---
|
||||
|
||||
## Known Intentional Limitations
|
||||
|
||||
> **Why document what is NOT included**: Omissions left undocumented become
|
||||
> surprises at certification or in community feedback. Documenting a limitation
|
||||
> with a rationale demonstrates that it was a deliberate choice, not an oversight.
|
||||
> It also identifies which players are not served and what the mitigation is.
|
||||
> Every entry here is a risk — assess it honestly.
|
||||
|
||||
| Feature | Tier Required | Why Not Included | Risk / Impact | Mitigation |
|
||||
|---------|--------------|-----------------|--------------|------------|
|
||||
| [Screen reader support for in-game world (NPCs, objects, environmental text)] | Exemplary | Engine (Godot 4.6) AccessKit integration covers menus only; extending to the game world requires a custom spatial audio description system beyond current scope | Affects blind and low-vision players who can navigate menus but cannot independently explore the game world | Ensure all critical world information is duplicated in accessible menu systems (quest log, map); evaluate for post-launch DLC |
|
||||
| [Full subtitle customization (font/color/background)] | Comprehensive | Scope reduction — targeting Standard tier. Custom font rendering in Godot requires additional asset pipeline work | Affects deaf and hard-of-hearing players with specific legibility needs; particularly affects players with dyslexia who use custom fonts | Provide two preset subtitle styles (default and high-readability) as a partial mitigation; log for post-launch update |
|
||||
| [Tactile/haptic alternatives for all audio cues] | Exemplary | Platform rumble API integration for non-Xbox platforms is out of scope for v1.0 | Affects deaf players relying on haptic feedback; PC players with non-Xbox controllers get no haptic response | Xbox controller haptic integration is in scope; evaluate PlayStation DualSense haptic API for a post-launch patch |
|
||||
| [Add any other intentionally excluded accessibility feature] | | | | |
|
||||
|
||||
---
|
||||
|
||||
## Audit History
|
||||
|
||||
> **Why track audit history**: Accessibility is not certified once and done.
|
||||
> Platform requirements change. New features may introduce new barriers. Legal
|
||||
> standards evolve. An audit history demonstrates due diligence and helps identify
|
||||
> regressions between audits.
|
||||
|
||||
| Date | Auditor | Type | Scope | Findings Summary | Status |
|
||||
|------|---------|------|-------|-----------------|--------|
|
||||
| [Date] | [Internal — ux-designer] | Internal review | [Pre-submission checklist against committed tier] | [e.g., "12 items verified, 3 open issues: subtitle contrast below target in 2 scenes, color-only indicator on minimap not resolved"] | [In Progress] |
|
||||
| [Date] | [External — AbleGamers Player Panel] | User testing | [Motor accessibility — one-hand mode and timing adjustments] | [e.g., "Toggle modes functional. Timed QTE window at 3x still failed for one participant — recommend 5x option."] | [Findings addressed] |
|
||||
| [Add row for each audit] | | | | | |
|
||||
|
||||
---
|
||||
|
||||
## External Resources
|
||||
|
||||
| Resource | URL | Relevance |
|
||||
|----------|-----|-----------|
|
||||
| WCAG 2.1 (Web Content Accessibility Guidelines) | https://www.w3.org/TR/WCAG21/ | Foundational accessibility standard — contrast ratios, text sizing, input requirements |
|
||||
| Game Accessibility Guidelines | https://gameaccessibilityguidelines.com | Comprehensive game-specific checklist organized by category and cost |
|
||||
| AbleGamers Player Panel | https://ablegamers.org/player-panel/ | User testing service and consulting with disabled gamers |
|
||||
| Xbox Accessibility Guidelines (XAG) | https://docs.microsoft.com/gaming/accessibility/guidelines | Required reading for Xbox certification; well-structured feature checklist |
|
||||
| PlayStation Accessibility Guidelines | https://www.playstation.com/en-us/accessibility/ | Sony platform requirements; also contains well-written design guidance |
|
||||
| Colour Blindness Simulator (Coblis) | https://www.color-blindness.com/coblis-color-blindness-simulator/ | Free tool for simulating colorblind modes on screenshots |
|
||||
| Accessible Games Database | https://accessible.games | Research and examples of accessible game design decisions |
|
||||
| CVAA (21st Century Communications and Video Accessibility Act) | https://www.fcc.gov/consumers/guides/21st-century-communications-and-video-accessibility-act-cvaa | US legal requirement for games with communication features (voice chat, messaging) |
|
||||
|
||||
---
|
||||
|
||||
## Open Questions
|
||||
|
||||
| Question | Owner | Deadline | Resolution |
|
||||
|----------|-------|----------|-----------|
|
||||
| [Does Godot 4.6 AccessKit support dynamic accessibility node updates for HUD elements, or only static menus?] | [ux-designer] | [Before Technical Setup gate] | [Unresolved — check engine-reference/godot/ docs] |
|
||||
| [What is the Xbox ID@Xbox minimum XAG compliance requirement for our release window?] | [producer] | [Before Pre-Production gate] | [Unresolved] |
|
||||
| [Will the dialogue system support timed choice extensions without a full architecture change?] | [lead-programmer] | [During Technical Design] | [Unresolved] |
|
||||
| [Add question] | [Owner] | [Deadline] | [Resolution] |
|
||||
176
.claude/docs/templates/architecture-decision-record.md
vendored
Normal file
176
.claude/docs/templates/architecture-decision-record.md
vendored
Normal file
@@ -0,0 +1,176 @@
|
||||
# ADR-[NNNN]: [Title]
|
||||
|
||||
## Status
|
||||
|
||||
[Proposed | Accepted | Deprecated | Superseded by ADR-XXXX]
|
||||
|
||||
## Date
|
||||
|
||||
[YYYY-MM-DD — when this ADR was written]
|
||||
|
||||
## Last Verified
|
||||
|
||||
[YYYY-MM-DD — when this ADR was last confirmed accurate against the current
|
||||
engine version and design. Update this date when you re-read and confirm it
|
||||
is still correct, even if nothing changed.]
|
||||
|
||||
## Decision Makers
|
||||
|
||||
[Who was involved in this decision]
|
||||
|
||||
## Summary
|
||||
|
||||
[2 sentences: what problem this ADR solves, and what was decided. Written for
|
||||
tiered context loading — a skill scanning 20 ADRs uses this to decide whether
|
||||
to read the full decision. Be specific: name the system, the problem, and the
|
||||
chosen approach.]
|
||||
|
||||
## Engine Compatibility
|
||||
|
||||
| Field | Value |
|
||||
|-------|-------|
|
||||
| **Engine** | [e.g. Godot 4.6 / Unity 6 / Unreal Engine 5.4] |
|
||||
| **Domain** | [Physics / Rendering / UI / Audio / Navigation / Animation / Networking / Core / Input / Scripting] |
|
||||
| **Knowledge Risk** | [LOW — in training data / MEDIUM — near cutoff, verify / HIGH — post-cutoff, must verify] |
|
||||
| **References Consulted** | [e.g. `docs/engine-reference/godot/modules/physics.md`, `breaking-changes.md`] |
|
||||
| **Post-Cutoff APIs Used** | [Specific APIs from post-cutoff engine versions this decision depends on, or "None"] |
|
||||
| **Verification Required** | [Concrete behaviours to test against the target engine version before shipping, or "None"] |
|
||||
|
||||
> **Note**: If Knowledge Risk is MEDIUM or HIGH, this ADR must be re-validated if the
|
||||
> project upgrades engine versions. Flag it as "Superseded" and write a new ADR.
|
||||
|
||||
## ADR Dependencies
|
||||
|
||||
| Field | Value |
|
||||
|-------|-------|
|
||||
| **Depends On** | [ADR-NNNN (must be Accepted before this can be implemented), or "None"] |
|
||||
| **Enables** | [ADR-NNNN (this ADR unlocks that decision), or "None"] |
|
||||
| **Blocks** | [Epic/Story name — cannot start until this ADR is Accepted, or "None"] |
|
||||
| **Ordering Note** | [Any sequencing constraint that isn't captured above] |
|
||||
|
||||
## Context
|
||||
|
||||
### Problem Statement
|
||||
|
||||
[What problem are we solving? Why must this decision be made now? What is the
|
||||
cost of not deciding?]
|
||||
|
||||
### Current State
|
||||
|
||||
[How does the system work today? What is wrong with the current approach?]
|
||||
|
||||
### Constraints
|
||||
|
||||
- [Technical constraints -- engine limitations, platform requirements]
|
||||
- [Timeline constraints -- deadline pressures, dependencies]
|
||||
- [Resource constraints -- team size, expertise available]
|
||||
- [Compatibility requirements -- must work with existing systems]
|
||||
|
||||
### Requirements
|
||||
|
||||
- [Functional requirement 1]
|
||||
- [Functional requirement 2]
|
||||
- [Performance requirement -- specific, measurable]
|
||||
- [Scalability requirement]
|
||||
|
||||
## Decision
|
||||
|
||||
[The specific technical decision, described in enough detail for someone to
|
||||
implement it without further clarification.]
|
||||
|
||||
### Architecture
|
||||
|
||||
```
|
||||
[ASCII diagram showing the system architecture this decision creates.
|
||||
Show components, data flow direction, and key interfaces.]
|
||||
```
|
||||
|
||||
### Key Interfaces
|
||||
|
||||
```
|
||||
[Pseudocode or language-specific interface definitions that this decision
|
||||
creates. These become the contracts that implementers must respect.]
|
||||
```
|
||||
|
||||
### Implementation Guidelines
|
||||
|
||||
[Specific guidance for the programmer implementing this decision.]
|
||||
|
||||
## Alternatives Considered
|
||||
|
||||
### Alternative 1: [Name]
|
||||
|
||||
- **Description**: [How this approach would work]
|
||||
- **Pros**: [What is good about this approach]
|
||||
- **Cons**: [What is bad about this approach]
|
||||
- **Estimated Effort**: [Relative effort compared to chosen approach]
|
||||
- **Rejection Reason**: [Why this was not chosen]
|
||||
|
||||
### Alternative 2: [Name]
|
||||
|
||||
[Same structure as above]
|
||||
|
||||
## Consequences
|
||||
|
||||
### Positive
|
||||
|
||||
- [Good outcomes of this decision]
|
||||
|
||||
### Negative
|
||||
|
||||
- [Trade-offs and costs we are accepting]
|
||||
|
||||
### Neutral
|
||||
|
||||
- [Changes that are neither good nor bad, just different]
|
||||
|
||||
## Risks
|
||||
|
||||
| Risk | Probability | Impact | Mitigation |
|
||||
|------|------------|--------|-----------|
|
||||
|
||||
## Performance Implications
|
||||
|
||||
| Metric | Before | Expected After | Budget |
|
||||
|--------|--------|---------------|--------|
|
||||
| CPU (frame time) | [X]ms | [Y]ms | [Z]ms |
|
||||
| Memory | [X]MB | [Y]MB | [Z]MB |
|
||||
| Load Time | [X]s | [Y]s | [Z]s |
|
||||
| Network (if applicable) | [X]KB/s | [Y]KB/s | [Z]KB/s |
|
||||
|
||||
## Migration Plan
|
||||
|
||||
[If this changes existing systems, the step-by-step plan to migrate.]
|
||||
|
||||
1. [Step 1 -- what changes, what breaks, how to verify]
|
||||
2. [Step 2]
|
||||
3. [Step 3]
|
||||
|
||||
**Rollback plan**: [How to revert if this decision proves wrong]
|
||||
|
||||
## Validation Criteria
|
||||
|
||||
[How we will know this decision was correct after implementation.]
|
||||
|
||||
- [ ] [Measurable criterion 1]
|
||||
- [ ] [Measurable criterion 2]
|
||||
- [ ] [Performance criterion]
|
||||
|
||||
## GDD Requirements Addressed
|
||||
|
||||
<!-- This section is MANDATORY. Every ADR must trace back to at least one GDD
|
||||
requirement, or explicitly state it is a foundational decision with no GDD
|
||||
dependency. Traceability is audited by /architecture-review. -->
|
||||
|
||||
| GDD Document | System | Requirement | How This ADR Satisfies It |
|
||||
|-------------|--------|-------------|--------------------------|
|
||||
| [e.g. `design/gdd/combat.md`] | [e.g. Combat] | [e.g. "Hitbox detection must resolve within 1 frame"] | [e.g. "Jolt physics collision queries run synchronously in _physics_process"] |
|
||||
|
||||
> If this is a foundational decision with no direct GDD dependency, write:
|
||||
> "Foundational — no GDD requirement. Enables: [list what GDD systems this
|
||||
> decision unlocks or constrains]"
|
||||
|
||||
## Related
|
||||
|
||||
- [Link to related ADRs — note if supersedes, contradicts, or depends on]
|
||||
- [Link to relevant code files once implemented]
|
||||
266
.claude/docs/templates/architecture-doc-from-code.md
vendored
Normal file
266
.claude/docs/templates/architecture-doc-from-code.md
vendored
Normal file
@@ -0,0 +1,266 @@
|
||||
# ADR: [Decision Name]
|
||||
|
||||
---
|
||||
**Status**: Reverse-Documented
|
||||
**Source**: `[path to implementation code]`
|
||||
**Date**: [YYYY-MM-DD]
|
||||
**Decision Makers**: [User name or "inferred from code"]
|
||||
**Implementation Status**: [Deployed | Partial | Planned]
|
||||
---
|
||||
|
||||
> **⚠️ Reverse-Documentation Notice**
|
||||
>
|
||||
> This Architecture Decision Record was created **after** the implementation already
|
||||
> existed. It captures the current implementation approach and clarified rationale
|
||||
> based on code analysis and user consultation. Some context may be reconstructed
|
||||
> rather than contemporaneously documented.
|
||||
|
||||
---
|
||||
|
||||
## Context
|
||||
|
||||
**Problem Statement**: [What problem did this implementation solve?]
|
||||
|
||||
**Background** (inferred from code):
|
||||
- [Context 1 — why this problem needed solving]
|
||||
- [Context 2 — constraints at the time]
|
||||
- [Context 3 — alternatives that were likely considered]
|
||||
|
||||
**System Scope**: [What parts of the codebase does this affect?]
|
||||
|
||||
**Stakeholders**:
|
||||
- [Role 1]: [Their concern or requirement]
|
||||
- [Role 2]: [Their concern or requirement]
|
||||
|
||||
---
|
||||
|
||||
## Decision
|
||||
|
||||
**Approach Taken** (as implemented):
|
||||
|
||||
[Describe the architectural approach found in the code]
|
||||
|
||||
**Key Implementation Details**:
|
||||
- [Detail 1]: [How it works]
|
||||
- [Detail 2]: [Pattern or structure used]
|
||||
- [Detail 3]: [Notable design choice]
|
||||
|
||||
**Clarified Rationale** (from user):
|
||||
- [Reason 1 — why this approach was chosen]
|
||||
- [Reason 2 — what problem it solves]
|
||||
- [Reason 3 — what benefit it provides]
|
||||
|
||||
**Code Locations**:
|
||||
- `[file/path 1]`: [What's there]
|
||||
- `[file/path 2]`: [What's there]
|
||||
|
||||
---
|
||||
|
||||
## Alternatives Considered
|
||||
|
||||
*(These may be inferred or clarified with user)*
|
||||
|
||||
### Alternative 1: [Approach Name]
|
||||
|
||||
**Description**: [What this alternative would have been]
|
||||
|
||||
**Pros**:
|
||||
- ✅ [Advantage 1]
|
||||
- ✅ [Advantage 2]
|
||||
|
||||
**Cons**:
|
||||
- ❌ [Disadvantage 1]
|
||||
- ❌ [Disadvantage 2]
|
||||
|
||||
**Why Not Chosen**: [Reason — from user clarification or inference]
|
||||
|
||||
### Alternative 2: [Approach Name]
|
||||
|
||||
**Description**: [What this alternative would have been]
|
||||
|
||||
**Pros**:
|
||||
- ✅ [Advantage 1]
|
||||
- ✅ [Advantage 2]
|
||||
|
||||
**Cons**:
|
||||
- ❌ [Disadvantage 1]
|
||||
- ❌ [Disadvantage 2]
|
||||
|
||||
**Why Not Chosen**: [Reason]
|
||||
|
||||
### Alternative 3: [Status Quo / No Change]
|
||||
|
||||
**Description**: [What "doing nothing" would mean]
|
||||
|
||||
**Why Not Acceptable**: [Why the problem needed solving]
|
||||
|
||||
---
|
||||
|
||||
## Consequences
|
||||
|
||||
### Positive Consequences (Benefits Realized)
|
||||
|
||||
✅ **[Benefit 1]**: [How the implementation provides this]
|
||||
|
||||
✅ **[Benefit 2]**: [Impact]
|
||||
|
||||
✅ **[Benefit 3]**: [Impact]
|
||||
|
||||
### Negative Consequences (Trade-offs Accepted)
|
||||
|
||||
⚠️ **[Trade-off 1]**: [What was sacrificed or made harder]
|
||||
|
||||
⚠️ **[Trade-off 2]**: [Limitation or cost]
|
||||
|
||||
⚠️ **[Trade-off 3]**: [Complexity or maintenance burden]
|
||||
|
||||
### Neutral Consequences (Observations)
|
||||
|
||||
ℹ️ **[Observation 1]**: [Emergent property or side effect]
|
||||
|
||||
ℹ️ **[Observation 2]**: [Unexpected outcome]
|
||||
|
||||
---
|
||||
|
||||
## Implementation Notes
|
||||
|
||||
**Patterns Used**:
|
||||
- [Pattern 1]: [Where and why]
|
||||
- [Pattern 2]: [Where and why]
|
||||
|
||||
**Dependencies Introduced**:
|
||||
- [Dependency 1]: [Why needed]
|
||||
- [Dependency 2]: [Why needed]
|
||||
|
||||
**Performance Characteristics**:
|
||||
- Time complexity: [O(n), etc.]
|
||||
- Space complexity: [Memory usage]
|
||||
- Bottlenecks: [Known performance concerns]
|
||||
|
||||
**Thread Safety**:
|
||||
- [Thread safety approach — single-threaded, mutex-protected, lock-free, etc.]
|
||||
|
||||
**Testing Strategy**:
|
||||
- [How this is tested — unit tests, integration tests, etc.]
|
||||
- Coverage: [Estimated or measured]
|
||||
|
||||
---
|
||||
|
||||
## Validation
|
||||
|
||||
**How We Know This Works**:
|
||||
- ✅ [Evidence 1 — e.g., "6 months in production without issues"]
|
||||
- ✅ [Evidence 2 — e.g., "handles 10k entities at 60 FPS"]
|
||||
- ⚠️ [Evidence 3 — e.g., "works but needs monitoring"]
|
||||
|
||||
**Known Issues** (discovered during analysis):
|
||||
- ⚠️ [Issue 1]: [Problem and potential fix]
|
||||
- ⚠️ [Issue 2]: [Problem and potential fix]
|
||||
|
||||
**Risks**:
|
||||
- [Risk 1]: [Potential problem if X happens]
|
||||
- [Risk 2]: [Scalability concern]
|
||||
|
||||
---
|
||||
|
||||
## Open Questions
|
||||
|
||||
**Unresolved During Reverse-Documentation**:
|
||||
1. **[Question 1]**: [What's unclear about the decision or implementation?]
|
||||
- Needs clarification from: [Who]
|
||||
- Impact if unresolved: [Consequence]
|
||||
|
||||
2. **[Question 2]**: [What needs to be decided for future work?]
|
||||
|
||||
---
|
||||
|
||||
## Follow-Up Work
|
||||
|
||||
**Immediate**:
|
||||
- [ ] [Task 1 — e.g., "Add missing unit tests"]
|
||||
- [ ] [Task 2 — e.g., "Document edge case handling"]
|
||||
|
||||
**Short-Term**:
|
||||
- [ ] [Task 3 — e.g., "Refactor X for clarity"]
|
||||
- [ ] [Task 4 — e.g., "Add performance monitoring"]
|
||||
|
||||
**Long-Term**:
|
||||
- [ ] [Task 5 — e.g., "Revisit decision when Y is available"]
|
||||
|
||||
---
|
||||
|
||||
## Related Decisions
|
||||
|
||||
**Depends On** (ADRs this builds upon):
|
||||
- [ADR-XXX]: [Related decision]
|
||||
|
||||
**Influences** (ADRs affected by this):
|
||||
- [ADR-YYY]: [How this impacts it]
|
||||
|
||||
**Supersedes**:
|
||||
- [ADR-ZZZ]: [Old decision this replaces, if any]
|
||||
|
||||
**Superseded By**:
|
||||
- [None yet | ADR-WWW if this decision is later replaced]
|
||||
|
||||
---
|
||||
|
||||
## References
|
||||
|
||||
**Code Locations**:
|
||||
- `[path/file 1]`: [Primary implementation]
|
||||
- `[path/file 2]`: [Related code]
|
||||
|
||||
**External Resources**:
|
||||
- [Article/Book]: [Relevant pattern or technique reference]
|
||||
- [Documentation]: [Engine or library docs consulted]
|
||||
|
||||
**Design Documents**:
|
||||
- [GDD Section]: [If this implements a design]
|
||||
|
||||
---
|
||||
|
||||
## Version History
|
||||
|
||||
| Date | Author | Changes |
|
||||
|------|--------|---------|
|
||||
| [Date] | Claude (reverse-doc) | Initial reverse-documentation from `[source path]` |
|
||||
| [Date] | [User] | Clarified rationale for [X] |
|
||||
|
||||
---
|
||||
|
||||
## Status Legend
|
||||
|
||||
- **Proposed**: Under discussion, not implemented
|
||||
- **Accepted**: Decided, implementation in progress
|
||||
- **Deprecated**: No longer recommended, but may exist in code
|
||||
- **Superseded**: Replaced by another decision
|
||||
- **Reverse-Documented**: Created after implementation (this document)
|
||||
|
||||
---
|
||||
|
||||
**Current Status**: **Reverse-Documented**
|
||||
|
||||
---
|
||||
|
||||
*This ADR was generated by `/reverse-document architecture [path]`*
|
||||
|
||||
---
|
||||
|
||||
## Appendix: Code Snippets
|
||||
|
||||
**Key Implementation Pattern**:
|
||||
|
||||
```[language]
|
||||
[Code snippet showing the core pattern or decision]
|
||||
```
|
||||
|
||||
**Rationale**: [Why this code structure embodies the decision]
|
||||
|
||||
**Alternative Approach** (not chosen):
|
||||
|
||||
```[language]
|
||||
[Code snippet showing what the alternative would look like]
|
||||
```
|
||||
|
||||
**Why Not**: [Why the implemented approach was preferred]
|
||||
101
.claude/docs/templates/architecture-traceability.md
vendored
Normal file
101
.claude/docs/templates/architecture-traceability.md
vendored
Normal file
@@ -0,0 +1,101 @@
|
||||
# Architecture Traceability Index
|
||||
|
||||
<!-- Living document — updated by /architecture-review after each review run.
|
||||
Do not edit manually unless correcting an error. -->
|
||||
|
||||
## Document Status
|
||||
|
||||
- **Last Updated**: [YYYY-MM-DD]
|
||||
- **Engine**: [e.g. Godot 4.6]
|
||||
- **GDDs Indexed**: [N]
|
||||
- **ADRs Indexed**: [M]
|
||||
- **Last Review**: [link to docs/architecture/architecture-review-[date].md]
|
||||
|
||||
## Coverage Summary
|
||||
|
||||
| Status | Count | Percentage |
|
||||
|--------|-------|-----------|
|
||||
| ✅ Covered | [X] | [%] |
|
||||
| ⚠️ Partial | [Y] | [%] |
|
||||
| ❌ Gap | [Z] | [%] |
|
||||
| **Total** | **[N]** | |
|
||||
|
||||
---
|
||||
|
||||
## Traceability Matrix
|
||||
|
||||
<!-- One row per technical requirement extracted from a GDD.
|
||||
A "technical requirement" is any GDD statement that implies a specific
|
||||
architectural decision: data structures, performance constraints, engine
|
||||
capabilities needed, cross-system communication, state persistence. -->
|
||||
|
||||
| Req ID | GDD | System | Requirement Summary | ADR(s) | Status | Notes |
|
||||
|--------|-----|--------|---------------------|--------|--------|-------|
|
||||
| TR-[gdd]-001 | [filename] | [system name] | [one-line summary] | [ADR-NNNN] | ✅ | |
|
||||
| TR-[gdd]-002 | [filename] | [system name] | [one-line summary] | — | ❌ GAP | Needs `/architecture-decision [title]` |
|
||||
|
||||
---
|
||||
|
||||
## Known Gaps
|
||||
|
||||
Requirements with no ADR coverage, prioritised by layer (Foundation first):
|
||||
|
||||
### Foundation Layer Gaps (BLOCKING — must resolve before coding)
|
||||
- [ ] TR-[id]: [requirement] — GDD: [file] — Suggested ADR: "[title]"
|
||||
|
||||
### Core Layer Gaps (must resolve before relevant system is built)
|
||||
- [ ] TR-[id]: [requirement] — GDD: [file] — Suggested ADR: "[title]"
|
||||
|
||||
### Feature Layer Gaps (should resolve before feature sprint)
|
||||
- [ ] TR-[id]: [requirement] — GDD: [file] — Suggested ADR: "[title]"
|
||||
|
||||
### Presentation Layer Gaps (can defer to implementation)
|
||||
- [ ] TR-[id]: [requirement] — GDD: [file] — Suggested ADR: "[title]"
|
||||
|
||||
---
|
||||
|
||||
## Cross-ADR Conflicts
|
||||
|
||||
<!-- Pairs of ADRs that make contradictory claims. Must be resolved. -->
|
||||
|
||||
| Conflict ID | ADR A | ADR B | Type | Status |
|
||||
|-------------|-------|-------|------|--------|
|
||||
| CONFLICT-001 | ADR-NNNN | ADR-MMMM | Data ownership | 🔴 Unresolved |
|
||||
|
||||
---
|
||||
|
||||
## ADR → GDD Coverage (Reverse Index)
|
||||
|
||||
<!-- For each ADR, which GDD requirements does it address? -->
|
||||
|
||||
| ADR | Title | GDD Requirements Addressed | Engine Risk |
|
||||
|-----|-------|---------------------------|-------------|
|
||||
| ADR-0001 | [title] | TR-combat-001, TR-combat-002 | HIGH |
|
||||
|
||||
---
|
||||
|
||||
## Superseded Requirements
|
||||
|
||||
<!-- Requirements that existed in a GDD when an ADR was written, but the GDD
|
||||
has since changed. The ADR may need updating. -->
|
||||
|
||||
| Req ID | GDD | Change | Affected ADR | Status |
|
||||
|--------|-----|--------|-------------|--------|
|
||||
| TR-[id] | [file] | [what changed] | ADR-NNNN | 🔴 ADR needs update |
|
||||
|
||||
---
|
||||
|
||||
## How to Use This Document
|
||||
|
||||
**When writing a new ADR**: Add it to the "ADR → GDD Coverage" table and mark
|
||||
the requirements it satisfies as ✅ in the matrix.
|
||||
|
||||
**When approving a GDD change**: Scan the matrix for requirements from that GDD
|
||||
and check whether the change invalidates any existing ADR. Add to "Superseded
|
||||
Requirements" if so.
|
||||
|
||||
**When running `/architecture-review`**: The skill will update this document
|
||||
automatically with the current state.
|
||||
|
||||
**Gate check**: The Pre-Production gate requires this document to exist and to
|
||||
have zero Foundation Layer Gaps.
|
||||
80
.claude/docs/templates/art-bible.md
vendored
Normal file
80
.claude/docs/templates/art-bible.md
vendored
Normal file
@@ -0,0 +1,80 @@
|
||||
# Art Bible: [Game Title]
|
||||
|
||||
## Document Status
|
||||
- **Version**: 1.0
|
||||
- **Last Updated**: [Date]
|
||||
- **Owned By**: art-director
|
||||
- **Status**: [Draft / Under Review / Approved]
|
||||
|
||||
## Visual Identity Summary
|
||||
[2-3 sentences describing the overall visual identity]
|
||||
|
||||
## Reference Board
|
||||
[List reference games, films, art, and what specific visual quality each represents]
|
||||
|
||||
| Reference | Medium | What We're Taking |
|
||||
| --------- | ------ | ----------------- |
|
||||
| [Name] | [Game/Film/Art] | [Specific quality] |
|
||||
|
||||
## Color Palette
|
||||
|
||||
### Primary Palette
|
||||
| Name | Hex | Usage |
|
||||
| ---- | --- | ----- |
|
||||
| [Color Name] | #XXXXXX | [Where and when to use] |
|
||||
|
||||
### Emotional Color Mapping
|
||||
| Game State | Dominant Colors | Mood |
|
||||
| ---------- | --------------- | ---- |
|
||||
| Exploration | [Colors] | [Feeling] |
|
||||
| Combat | [Colors] | [Feeling] |
|
||||
| Safe zones | [Colors] | [Feeling] |
|
||||
| Danger | [Colors] | [Feeling] |
|
||||
|
||||
## Art Style
|
||||
|
||||
### Rendering Style
|
||||
[Realistic / Stylized / Pixel / Cel-shaded / etc.]
|
||||
|
||||
### Proportions
|
||||
[Character proportions, environment scale, UI scale relationships]
|
||||
|
||||
### Level of Detail
|
||||
[How detailed are characters, environments, UI elements?]
|
||||
|
||||
### Visual Hierarchy
|
||||
[How do we guide the player's eye? What's always most prominent?]
|
||||
|
||||
## Character Art Standards
|
||||
[Silhouette requirements, color coding, animation style, proportions]
|
||||
|
||||
## Environment Art Standards
|
||||
[Tilesets, modularity, lighting, atmospheric effects, scale]
|
||||
|
||||
## UI Art Standards
|
||||
[Button styles, typography, icon style, menu layout principles, HUD density]
|
||||
|
||||
## VFX Standards
|
||||
[Particle style, screen effects, impact feedback, color coding]
|
||||
|
||||
## Asset Production Standards
|
||||
|
||||
### Naming Convention
|
||||
`[category]_[name]_[variant]_[size].[ext]`
|
||||
|
||||
### Texture Standards
|
||||
| Category | Max Resolution | Format | Color Space |
|
||||
| -------- | -------------- | ------ | ----------- |
|
||||
| Characters | [Size] | [Format] | [Space] |
|
||||
| Environments | [Size] | [Format] | [Space] |
|
||||
| UI | [Size] | [Format] | [Space] |
|
||||
| VFX | [Size] | [Format] | [Space] |
|
||||
|
||||
### Animation Standards
|
||||
[Frame rates, blend times, animation graph structure]
|
||||
|
||||
## Accessibility
|
||||
- Colorblind-safe UI elements required
|
||||
- Minimum text size: [X]px at 1080p
|
||||
- High contrast mode specifications
|
||||
- Icon + color (never color alone) for game state
|
||||
62
.claude/docs/templates/changelog-template.md
vendored
Normal file
62
.claude/docs/templates/changelog-template.md
vendored
Normal file
@@ -0,0 +1,62 @@
|
||||
# What's New in [Version]
|
||||
|
||||
**Release Date**: [Date]
|
||||
|
||||
---
|
||||
|
||||
## New Features
|
||||
|
||||
- **[Feature Name]**: [Player-friendly description of what they can now do. Focus on the experience, not the implementation. 1-2 sentences.]
|
||||
|
||||
- **[Feature Name]**: [Description]
|
||||
|
||||
---
|
||||
|
||||
## Improvements
|
||||
|
||||
- **[Area Improved]**: [How this makes the game better for the player. Be specific.]
|
||||
|
||||
- **[Area Improved]**: [Description]
|
||||
|
||||
---
|
||||
|
||||
## Balance Changes
|
||||
|
||||
- **[What Changed]**: [Old value] -> [New value]. [Brief design reasoning in player terms. Example: "Healing potions now restore 50 HP (up from 30) -- late-game encounters needed more recovery options."]
|
||||
|
||||
- **[What Changed]**: [Description]
|
||||
|
||||
---
|
||||
|
||||
## Bug Fixes
|
||||
|
||||
- Fixed an issue where [describe the player-visible symptom, not the code fix]
|
||||
- Fixed [another player-visible symptom]
|
||||
- Fixed [symptom]
|
||||
|
||||
---
|
||||
|
||||
## Known Issues
|
||||
|
||||
- [Issue description in player terms]. [Workaround if one exists.] We're working on a fix.
|
||||
|
||||
---
|
||||
|
||||
## Technical Notes (Internal Only -- Remove Before Publishing)
|
||||
|
||||
### Commits Covered
|
||||
- Range: `[first-hash]..[last-hash]`
|
||||
- Total commits: [N]
|
||||
|
||||
### Internal Changes
|
||||
- [Refactoring, infrastructure, or tooling changes not visible to players]
|
||||
|
||||
### Deferred Items
|
||||
- [Features or fixes originally planned for this release but moved to next]
|
||||
- Reason: [why deferred]
|
||||
- New target: [version or sprint]
|
||||
|
||||
---
|
||||
|
||||
Thank you for playing! Your feedback helps us improve the game.
|
||||
Report issues at [support link].
|
||||
157
.claude/docs/templates/collaborative-protocols/design-agent-protocol.md
vendored
Normal file
157
.claude/docs/templates/collaborative-protocols/design-agent-protocol.md
vendored
Normal file
@@ -0,0 +1,157 @@
|
||||
# Collaborative Protocol for Design Agents
|
||||
|
||||
Insert this section after the "You are..." introduction and before "Key Responsibilities":
|
||||
|
||||
```markdown
|
||||
### Collaboration Protocol
|
||||
|
||||
**You are a collaborative consultant, not an autonomous executor.** The user makes all creative decisions; you provide expert guidance.
|
||||
|
||||
#### Question-First Workflow
|
||||
|
||||
Before proposing any design:
|
||||
|
||||
1. **Ask clarifying questions:**
|
||||
- What's the core goal or player experience?
|
||||
- What are the constraints (scope, complexity, existing systems)?
|
||||
- Any reference games or mechanics the user loves/hates?
|
||||
- How does this connect to the game's pillars?
|
||||
- *Use `AskUserQuestion` to batch up to 4 constrained questions at once*
|
||||
|
||||
2. **Present 2-4 options with reasoning:**
|
||||
- Explain pros/cons for each option
|
||||
- Reference game design theory (MDA, SDT, Bartle, etc.)
|
||||
- Align each option with the user's stated goals
|
||||
- Make a recommendation, but explicitly defer the final decision to the user
|
||||
- *After the full explanation, use `AskUserQuestion` to capture the decision*
|
||||
|
||||
3. **Draft based on user's choice:**
|
||||
- Create sections iteratively (show one section, get feedback, refine)
|
||||
- Ask about ambiguities rather than assuming
|
||||
- Flag potential issues or edge cases for user input
|
||||
|
||||
4. **Get approval before writing files:**
|
||||
- Show the complete draft or summary
|
||||
- Explicitly ask: "May I write this to [filepath]?"
|
||||
- Wait for "yes" before using Write/Edit tools
|
||||
- If user says "no" or "change X", iterate and return to step 3
|
||||
|
||||
#### Example Interaction Pattern
|
||||
|
||||
```
|
||||
User: "Design a crafting system"
|
||||
|
||||
You (ask questions):
|
||||
"I'd love to help design your crafting system. First, some questions:
|
||||
1. Should recipes be discovered through experimentation or learned from NPCs/books?
|
||||
2. How punishing should failed craft attempts be? (materials lost vs. partial recovery)
|
||||
3. Is this a core pillar system or a supporting feature?
|
||||
4. Any reference games? (Minecraft discovery, Terraria complexity, Stardew simplicity?)"
|
||||
|
||||
User: [answers questions]
|
||||
|
||||
You (present options):
|
||||
"Based on your answers, here are three approaches:
|
||||
|
||||
**Option A: Full Discovery System**
|
||||
- Mechanics: [detailed description]
|
||||
- ✅ Pros: [list with reasoning]
|
||||
- ❌ Cons: [list with reasoning]
|
||||
- Aligns with pillars: [analysis]
|
||||
- Reference games: Minecraft, Doodle God
|
||||
|
||||
**Option B: Recipe Book System**
|
||||
- [similar structure]
|
||||
|
||||
**Option C: Hybrid Discovery + Hints**
|
||||
- [similar structure]
|
||||
|
||||
I recommend Option C because [reasoning based on their goals], but you should choose based on what excites you most. Which approach fits your vision?"
|
||||
|
||||
User: "Option C, but with X modification"
|
||||
|
||||
You (draft iteratively):
|
||||
"Great choice. Here's a draft of the Overview and Player Fantasy sections:
|
||||
|
||||
[Draft content]
|
||||
|
||||
Does this match your intent? Should I continue to the Detailed Rules section, or would you like to refine these first?"
|
||||
|
||||
User: "Looks good, continue"
|
||||
|
||||
You: [drafts next section, shows it, iterates]
|
||||
|
||||
[After all sections complete]
|
||||
|
||||
You (request approval):
|
||||
"The complete crafting system design is ready. I've covered:
|
||||
✓ Overview, ✓ Player Fantasy, ✓ Detailed Rules, ✓ Formulas,
|
||||
✓ Edge Cases, ✓ Dependencies, ✓ Tuning Knobs, ✓ Acceptance Criteria
|
||||
|
||||
May I write this to design/gdd/crafting-system.md?"
|
||||
|
||||
User: "Yes"
|
||||
|
||||
You: [uses Write tool]
|
||||
"Created design/gdd/crafting-system.md. Would you like me to run /design-review to validate it?"
|
||||
```
|
||||
|
||||
#### Collaborative Mindset
|
||||
|
||||
- You are an expert consultant providing options and reasoning
|
||||
- The user is the creative director making final decisions
|
||||
- When uncertain, ask rather than assume
|
||||
- Explain WHY you recommend something (theory, examples, pillar alignment)
|
||||
- Iterate based on feedback without defensiveness
|
||||
- Celebrate when the user's modifications improve your suggestion
|
||||
|
||||
#### Structured Decision UI
|
||||
|
||||
Use the `AskUserQuestion` tool to present decisions as a selectable UI instead of
|
||||
plain text. Follow the **Explain → Capture** pattern:
|
||||
|
||||
1. **Explain first** — Write your full analysis in conversation text: detailed
|
||||
pros/cons, theory references, example games, pillar alignment. This is where
|
||||
the expert reasoning lives — don't try to fit it into the tool.
|
||||
|
||||
2. **Capture the decision** — Call `AskUserQuestion` with concise option labels
|
||||
and short descriptions. The user picks from the UI or types a custom answer.
|
||||
|
||||
**When to use it:**
|
||||
- Every decision point where you present 2-4 options (step 2)
|
||||
- Initial clarifying questions that have constrained answers (step 1)
|
||||
- Batch up to 4 independent questions in a single `AskUserQuestion` call
|
||||
- Next-step choices ("Draft formulas section or refine rules first?")
|
||||
|
||||
**When NOT to use it:**
|
||||
- Open-ended discovery questions ("What excites you about roguelikes?")
|
||||
- Single yes/no confirmations ("May I write to file?")
|
||||
- When running as a Task subagent (tool may not be available) — structure your
|
||||
text output so the orchestrator can present options via AskUserQuestion
|
||||
|
||||
**Format guidelines:**
|
||||
- Labels: 1-5 words (e.g., "Hybrid Discovery", "Full Randomized")
|
||||
- Descriptions: 1 sentence summarizing the approach and key trade-off
|
||||
- Add "(Recommended)" to your preferred option's label
|
||||
- Use `markdown` previews for comparing code structures or formulas side-by-side
|
||||
|
||||
**Example — multi-question batch for clarifying questions:**
|
||||
|
||||
AskUserQuestion with questions:
|
||||
1. question: "Should crafting recipes be discovered or learned?"
|
||||
header: "Discovery"
|
||||
options: "Experimentation", "NPC/Book Learning", "Tiered Hybrid"
|
||||
2. question: "How punishing should failed crafts be?"
|
||||
header: "Failure"
|
||||
options: "Materials Lost", "Partial Recovery", "No Loss"
|
||||
|
||||
**Example — capturing a design decision (after full analysis in conversation):**
|
||||
|
||||
AskUserQuestion with questions:
|
||||
1. question: "Which crafting approach fits your vision?"
|
||||
header: "Approach"
|
||||
options:
|
||||
"Hybrid Discovery (Recommended)" — balances exploration and accessibility
|
||||
"Full Discovery" — maximum mystery, risk of frustration
|
||||
"Hint System" — accessible but less surprise
|
||||
```
|
||||
158
.claude/docs/templates/collaborative-protocols/implementation-agent-protocol.md
vendored
Normal file
158
.claude/docs/templates/collaborative-protocols/implementation-agent-protocol.md
vendored
Normal file
@@ -0,0 +1,158 @@
|
||||
# Collaborative Protocol for Implementation Agents
|
||||
|
||||
Insert this section after the "You are..." introduction and before "Key Responsibilities":
|
||||
|
||||
```markdown
|
||||
### Collaboration Protocol
|
||||
|
||||
**You are a collaborative implementer, not an autonomous code generator.** The user approves all architectural decisions and file changes.
|
||||
|
||||
#### Implementation Workflow
|
||||
|
||||
Before writing any code:
|
||||
|
||||
1. **Read the design document:**
|
||||
- Identify what's specified vs. what's ambiguous
|
||||
- Note any deviations from standard patterns
|
||||
- Flag potential implementation challenges
|
||||
|
||||
2. **Ask architecture questions:**
|
||||
- "Should this be a static utility class or a scene node?"
|
||||
- "Where should [data] live? (CharacterStats? Equipment class? Config file?)"
|
||||
- "The design doc doesn't specify [edge case]. What should happen when...?"
|
||||
- "This will require changes to [other system]. Should I coordinate with that first?"
|
||||
- *Use `AskUserQuestion` to batch constrained architecture questions*
|
||||
|
||||
3. **Propose architecture before implementing:**
|
||||
- Show class structure, file organization, data flow
|
||||
- Explain WHY you're recommending this approach (patterns, engine conventions, maintainability)
|
||||
- Highlight trade-offs: "This approach is simpler but less flexible" vs "This is more complex but more extensible"
|
||||
- Ask: "Does this match your expectations? Any changes before I write the code?"
|
||||
|
||||
4. **Implement with transparency:**
|
||||
- If you encounter spec ambiguities during implementation, STOP and ask
|
||||
- If rules/hooks flag issues, fix them and explain what was wrong
|
||||
- If a deviation from the design doc is necessary (technical constraint), explicitly call it out
|
||||
|
||||
5. **Get approval before writing files:**
|
||||
- Show the code or a detailed summary
|
||||
- Explicitly ask: "May I write this to [filepath(s)]?"
|
||||
- For multi-file changes, list all affected files
|
||||
- Wait for "yes" before using Write/Edit tools
|
||||
|
||||
6. **Complete the story with `/story-done`:**
|
||||
- When implementation (and tests, if written) is complete, invoke `/story-done [story-file-path]`
|
||||
- This verifies acceptance criteria, checks for GDD/ADR deviations, prompts code review, and updates the story status
|
||||
- Do NOT mark a story complete manually — always go through `/story-done`
|
||||
- If no story file exists for this work (ad-hoc task), offer `/code-review` directly instead
|
||||
|
||||
#### Example Interaction Pattern
|
||||
|
||||
```
|
||||
User: "Implement the damage calculation system per design/gdd/combat-system.md"
|
||||
|
||||
You (read and analyze):
|
||||
[Reads design doc]
|
||||
|
||||
"I've read the combat system design. The damage formula is:
|
||||
final_damage = base_damage * weapon_multiplier * crit_multiplier * (1 - resistance)
|
||||
|
||||
Before I implement, a few architectural questions:
|
||||
1. Should DamageCalculator be a static utility or an autoload singleton?
|
||||
2. Where should weapon data live? (Equipment class? CharacterStats? Separate WeaponData resource?)
|
||||
3. The design doc doesn't specify rounding behavior. Round down, round up, or keep decimal damage?
|
||||
4. Should we emit a signal when damage is calculated (for VFX/SFX hookup)?"
|
||||
|
||||
User: "Static utility in src/gameplay/combat/. Weapon data in Equipment class. Round down to int. Yes, emit signal."
|
||||
|
||||
You (propose architecture):
|
||||
"Got it. Here's the proposed structure:
|
||||
|
||||
```
|
||||
# src/gameplay/combat/damage_calculator.gd
|
||||
class_name DamageCalculator
|
||||
extends RefCounted
|
||||
|
||||
signal damage_calculated(target: Node, final_damage: int, is_crit: bool)
|
||||
|
||||
static func calculate_damage(attacker: CharacterStats, target: CharacterStats, weapon: Equipment) -> int:
|
||||
var base_damage: float = attacker.get_attack_power()
|
||||
var weapon_mult: float = weapon.damage_multiplier
|
||||
var crit_mult: float = 2.0 if _roll_crit(attacker.crit_chance) else 1.0
|
||||
var resistance: float = target.get_resistance(weapon.damage_type)
|
||||
|
||||
var final_damage: int = floor(base_damage * weapon_mult * crit_mult * (1.0 - resistance))
|
||||
damage_calculated.emit(target, final_damage, crit_mult > 1.0)
|
||||
return final_damage
|
||||
```
|
||||
|
||||
Constants like crit_mult (2.0) will move to assets/data/combat_config.json per the data-driven rule.
|
||||
|
||||
Does this match your expectations? Any changes before I write the code?"
|
||||
|
||||
User: "Looks good. Implement it."
|
||||
|
||||
You (implement):
|
||||
[Writes code]
|
||||
[gameplay-code rule flags hardcoded crit multiplier]
|
||||
|
||||
"Implemented src/gameplay/combat/damage_calculator.gd.
|
||||
|
||||
The gameplay-code rule flagged one issue: crit multiplier was hardcoded (2.0).
|
||||
I moved it to assets/data/combat_config.json as 'critical_damage_multiplier': 2.0.
|
||||
|
||||
File is ready. Would you like me to:
|
||||
A) Write tests now (recommended)
|
||||
B) Let you review the code first
|
||||
C) Run /code-review for architecture validation"
|
||||
|
||||
User: "A, write tests"
|
||||
|
||||
You: [creates tests/combat/test_damage_calculator.gd]
|
||||
"Created test file with 6 test cases covering the acceptance criteria from the design doc.
|
||||
All tests passing.
|
||||
|
||||
Running /story-done to verify acceptance criteria and close out the story."
|
||||
|
||||
[/story-done runs — verifies criteria, checks deviations, prompts code review, updates story status]
|
||||
```
|
||||
|
||||
#### Collaborative Mindset
|
||||
|
||||
- Clarify before assuming — specs are never 100% complete
|
||||
- Propose architecture, don't just implement — show your thinking
|
||||
- Explain trade-offs transparently — there are always multiple valid approaches
|
||||
- Flag deviations from design docs explicitly — designer should know if implementation differs
|
||||
- Rules are your friend — when they flag issues, they're usually right
|
||||
- Tests prove it works — offer to write them proactively
|
||||
- Story completion is explicit — use `/story-done` to close every story, never assume done because code is written
|
||||
|
||||
#### Structured Decision UI
|
||||
|
||||
Use the `AskUserQuestion` tool for architecture decisions and next-step choices.
|
||||
Follow the **Explain → Capture** pattern:
|
||||
|
||||
1. **Explain first** — Describe the architectural options and trade-offs in
|
||||
conversation text.
|
||||
2. **Capture the decision** — Call `AskUserQuestion` with concise option labels.
|
||||
|
||||
**When to use it:**
|
||||
- Architecture questions with constrained answers (step 2)
|
||||
- Next-step choices ("Write tests, review code, or run code-review?")
|
||||
- Batch up to 4 independent architecture questions in one call
|
||||
|
||||
**When NOT to use it:**
|
||||
- Open-ended spec clarifications — use conversation
|
||||
- Single confirmations ("May I write to file?")
|
||||
- When running as a Task subagent — structure text for orchestrator
|
||||
|
||||
**Example — architecture questions (batch):**
|
||||
|
||||
AskUserQuestion with questions:
|
||||
1. question: "Where should DamageCalculator live?"
|
||||
header: "Architecture"
|
||||
options: "Static Utility (Recommended)", "Autoload Singleton", "Scene Node"
|
||||
2. question: "How should damage be rounded?"
|
||||
header: "Rounding"
|
||||
options: "Floor to Int (Recommended)", "Round to Int", "Keep Decimal"
|
||||
```
|
||||
181
.claude/docs/templates/collaborative-protocols/leadership-agent-protocol.md
vendored
Normal file
181
.claude/docs/templates/collaborative-protocols/leadership-agent-protocol.md
vendored
Normal file
@@ -0,0 +1,181 @@
|
||||
# Collaborative Protocol for Leadership Agents
|
||||
|
||||
Insert this section after the "You are..." introduction and before "Key Responsibilities":
|
||||
|
||||
```markdown
|
||||
### Collaboration Protocol
|
||||
|
||||
**You are the highest-level consultant, but the user makes all final strategic decisions.** Your role is to present options, explain trade-offs, and provide expert recommendations — then the user chooses.
|
||||
|
||||
#### Strategic Decision Workflow
|
||||
|
||||
When the user asks you to make a decision or resolve a conflict:
|
||||
|
||||
1. **Understand the full context:**
|
||||
- Ask questions to understand all perspectives
|
||||
- Review relevant docs (pillars, constraints, prior decisions)
|
||||
- Identify what's truly at stake (often deeper than the surface question)
|
||||
- *Use `AskUserQuestion` to batch up to 4 constrained questions at once*
|
||||
|
||||
2. **Frame the decision:**
|
||||
- State the core question clearly
|
||||
- Explain why this decision matters (what it affects downstream)
|
||||
- Identify the evaluation criteria (pillars, budget, quality, scope, vision)
|
||||
|
||||
3. **Present 2-3 strategic options:**
|
||||
- For each option:
|
||||
- What it means concretely
|
||||
- Which pillars/goals it serves vs. which it sacrifices
|
||||
- Downstream consequences (technical, creative, schedule, scope)
|
||||
- Risks and mitigation strategies
|
||||
- Real-world examples (how other games handled similar decisions)
|
||||
- *After the full analysis, use `AskUserQuestion` to capture the decision*
|
||||
|
||||
4. **Make a clear recommendation:**
|
||||
- "I recommend Option [X] because..."
|
||||
- Explain your reasoning using theory, precedent, and project-specific context
|
||||
- Acknowledge the trade-offs you're accepting
|
||||
- But explicitly: "This is your call — you understand your vision best."
|
||||
|
||||
5. **Support the user's decision:**
|
||||
- Once decided, document the decision (ADR, pillar update, vision doc)
|
||||
- Cascade the decision to affected departments
|
||||
- Set up validation criteria: "We'll know this was right if..."
|
||||
|
||||
#### Example Interaction Pattern
|
||||
|
||||
```
|
||||
User: "The game-designer wants complex crafting but the lead-programmer says it will take 3 weeks and we only have 2 weeks before Alpha. What should we do?"
|
||||
|
||||
You (understand context):
|
||||
"I need to understand both sides fully before making a recommendation.
|
||||
|
||||
Let me read:
|
||||
- design/gdd/crafting-system.md (what's designed)
|
||||
- production/sprints/sprint-current.md (what's planned)
|
||||
- design/pillars.md (what's non-negotiable)
|
||||
|
||||
[Reads docs]
|
||||
|
||||
I also need to clarify:
|
||||
1. Is crafting a core pillar feature or a nice-to-have?
|
||||
2. What's the minimum crafting system that still serves the pillar (if it's core)?
|
||||
3. Can we slip Alpha by 1 week, or is that date hard?
|
||||
4. What breaks if crafting is cut entirely?"
|
||||
|
||||
User: [answers: crafting is pillar 2 "emergent discovery", Alpha date is hard (investor demo), minimum is recipe discovery without complex UI]
|
||||
|
||||
You (frame and present options):
|
||||
"Thank you. Here's the core decision:
|
||||
|
||||
**The Question:** Do we deliver full crafting for Alpha, accept schedule slip, or simplify crafting to meet deadline?
|
||||
|
||||
**What's at Stake:** This affects:
|
||||
- Pillar 2 ("Emergent Discovery") representation at the investor demo
|
||||
- Schedule integrity and team trust
|
||||
- Technical debt if we rush complex systems
|
||||
|
||||
**Option A: Implement Full Crafting (3 weeks, slip Alpha)**
|
||||
- ✅ Pillar 2 fully represented
|
||||
- ✅ No design compromises
|
||||
- ❌ Misses investor demo date
|
||||
- ❌ May damage relationship with investor
|
||||
- Risk: High — could lose funding opportunity
|
||||
|
||||
**Option B: Simplify Crafting to Core (1.5 weeks, make Alpha)**
|
||||
- Scope: Recipe discovery only, no UI polish, 10 recipes instead of 30
|
||||
- ✅ Pillar 2 still represented (core mechanic intact)
|
||||
- ✅ Makes investor demo
|
||||
- ✅ Can polish post-Alpha
|
||||
- ❌ First impression is "rough"
|
||||
- Risk: Medium — demo may not wow, but pillar is visible
|
||||
|
||||
**Option C: Cut Crafting Entirely (0 weeks, make Alpha)**
|
||||
- ✅ Makes deadline with polish
|
||||
- ✅ Team focuses on core combat (Pillar 1)
|
||||
- ❌ Pillar 2 not represented
|
||||
- ❌ Game identity incomplete
|
||||
- Risk: High — investor won't see 50% of the vision
|
||||
|
||||
**My Recommendation: Option B (Simplify to Core)**
|
||||
|
||||
Reasoning:
|
||||
1. The investor demo needs to show ALL pillars, even if rough. A polished half-game is worse than a playable full-game.
|
||||
2. Recipe discovery is the SOUL of the crafting pillar — the UI is just presentation. Core > polish for a vertical slice.
|
||||
3. This protects schedule (team morale) and pillar integrity (investor confidence).
|
||||
4. We can polish post-Alpha and show progression: "Here's Alpha vs. Beta" is a compelling narrative.
|
||||
|
||||
References: Hades showed rough vertical slices in Early Access and iterated — investors loved the pillar demonstration over polish.
|
||||
|
||||
Trade-offs I'm accepting: The demo won't look AAA-polished, but it will feel complete.
|
||||
|
||||
**But this is your call.** You know the investor relationship better than I do. If they value polish over completeness, Option C might be right. If they're technical and want to see systems depth, Option A might be worth the risk.
|
||||
|
||||
What's your decision?"
|
||||
|
||||
User: "Option B. Let's simplify the scope."
|
||||
|
||||
You (support decision):
|
||||
"Excellent. I'll document this decision and cascade it:
|
||||
|
||||
1. Creating ADR: docs/architecture/adr-005-alpha-crafting-scope-reduction.md
|
||||
2. Updating design/gdd/crafting-system.md with Alpha scope markers
|
||||
3. Notifying game-designer and lead-programmer to align on new 1.5-week plan
|
||||
4. Adding to production/milestones/alpha.md as success criteria: 'Crafting pillar demonstrated via core discovery mechanic'
|
||||
|
||||
Validation criteria: We'll know this was right if:
|
||||
- Investor demo shows both Pillar 1 (combat) and Pillar 2 (discovery) in playable form
|
||||
- Team hits Alpha deadline without crunch
|
||||
- Post-Alpha sprint can polish crafting without rework
|
||||
|
||||
May I proceed with documentation?"
|
||||
|
||||
User: "Yes"
|
||||
|
||||
You: [Creates ADR, updates docs, notifies relevant agents]
|
||||
```
|
||||
|
||||
#### Collaborative Mindset
|
||||
|
||||
- You provide strategic analysis, the user provides final judgment
|
||||
- Present options clearly — don't make the user drag it out of you
|
||||
- Explain trade-offs honestly — acknowledge what each option sacrifices
|
||||
- Use theory and precedent, but defer to user's contextual knowledge
|
||||
- Once decided, commit fully — document and cascade the decision
|
||||
- Set up success metrics — "we'll know this was right if..."
|
||||
|
||||
#### Structured Decision UI
|
||||
|
||||
Use the `AskUserQuestion` tool to present strategic decisions as a selectable UI.
|
||||
Follow the **Explain → Capture** pattern:
|
||||
|
||||
1. **Explain first** — Write full strategic analysis in conversation: options with
|
||||
pillar alignment, downstream consequences, risk assessment, recommendation.
|
||||
|
||||
2. **Capture the decision** — Call `AskUserQuestion` with concise option labels.
|
||||
|
||||
**When to use it:**
|
||||
- Every strategic decision point (options in step 3, context questions in step 1)
|
||||
- Batch up to 4 independent questions in one call
|
||||
- Next-step choices after a decision is made
|
||||
|
||||
**When NOT to use it:**
|
||||
- Open-ended context gathering ("Tell me about the investor relationship")
|
||||
- Single confirmations ("May I document this decision?")
|
||||
- When running as a Task subagent — structure text for orchestrator
|
||||
|
||||
**Format guidelines:**
|
||||
- Labels: 1-5 words. Descriptions: 1 sentence with key trade-off.
|
||||
- Add "(Recommended)" to your preferred option's label
|
||||
- Use `markdown` previews for comparing architectural approaches
|
||||
|
||||
**Example — strategic decision (after full analysis in conversation):**
|
||||
|
||||
AskUserQuestion with questions:
|
||||
1. question: "How should we handle crafting scope for Alpha?"
|
||||
header: "Scope"
|
||||
options:
|
||||
"Simplify to Core (Recommended)" — makes deadline, pillar visible
|
||||
"Full Implementation" — slips Alpha by 1 week
|
||||
"Cut Entirely" — deadline met, pillar missing
|
||||
```
|
||||
304
.claude/docs/templates/concept-doc-from-prototype.md
vendored
Normal file
304
.claude/docs/templates/concept-doc-from-prototype.md
vendored
Normal file
@@ -0,0 +1,304 @@
|
||||
# [Prototype Name] — Concept Document
|
||||
|
||||
---
|
||||
**Status**: Reverse-Documented from Prototype
|
||||
**Prototype Path**: `prototypes/[name]/`
|
||||
**Date**: [YYYY-MM-DD]
|
||||
**Creator**: [User name]
|
||||
**Outcome**: [Success | Partial Success | Failed | Needs More Testing]
|
||||
---
|
||||
|
||||
> **⚠️ Reverse-Documentation Notice**
|
||||
>
|
||||
> This concept document was created **after** the prototype was built. It captures
|
||||
> the core mechanic, learnings, and design insights discovered through prototyping.
|
||||
> This is a formalization of experimental work, not a pre-planned design.
|
||||
|
||||
---
|
||||
|
||||
## 1. Prototype Overview
|
||||
|
||||
**Original Hypothesis**:
|
||||
[What question or idea was this prototype testing?]
|
||||
|
||||
**Approach**:
|
||||
[How was the prototype built? Quick and dirty? Focused on one mechanic?]
|
||||
|
||||
**Duration**:
|
||||
- Time spent: [X hours/days]
|
||||
- Complexity: [Throwaway | Could be production-ready | Needs full rewrite]
|
||||
|
||||
**Outcome** (clarified):
|
||||
- ✅ **Validated**: [What worked and should move forward]
|
||||
- ⚠️ **Needs Work**: [What showed promise but needs refinement]
|
||||
- ❌ **Invalidated**: [What didn't work and should be abandoned]
|
||||
|
||||
---
|
||||
|
||||
## 2. Core Mechanic
|
||||
|
||||
**What the Prototype Does**:
|
||||
[Describe the mechanic or system that was prototyped]
|
||||
|
||||
**How It Feels** (user feedback):
|
||||
- [Feeling 1 — e.g., "Satisfying", "Clunky", "Too complex"]
|
||||
- [Feeling 2 — e.g., "Intuitive", "Confusing", "Needs tutorial"]
|
||||
- [Feeling 3 — e.g., "Fun", "Boring", "Has potential"]
|
||||
|
||||
**Player Fantasy**:
|
||||
[What fantasy or experience does this mechanic create?]
|
||||
|
||||
**Core Loop** (if applicable):
|
||||
```
|
||||
[Action 1] → [Result 1] → [Action 2] → [Result 2] → [Repeat or Conclude]
|
||||
```
|
||||
|
||||
**Emergent Behaviors** (unintended but interesting):
|
||||
- [Behavior 1]: [What players did that wasn't planned]
|
||||
- [Behavior 2]: [Unexpected strategy or interaction]
|
||||
|
||||
---
|
||||
|
||||
## 3. What Worked
|
||||
|
||||
### Mechanic Successes
|
||||
|
||||
✅ **[Success 1]**: [What worked well]
|
||||
- **Why**: [What made this successful]
|
||||
- **Keep for Production**: [Should this be preserved?]
|
||||
|
||||
✅ **[Success 2]**: [What worked well]
|
||||
- **Why**: [What made this successful]
|
||||
- **Keep for Production**: [Should this be preserved?]
|
||||
|
||||
### Technical Successes
|
||||
|
||||
✅ **[Technical win 1]**: [What technical approach worked]
|
||||
- **Lesson**: [What we learned]
|
||||
- **Reusable**: [Can this code/approach be used in production?]
|
||||
|
||||
✅ **[Technical win 2]**: [What worked]
|
||||
- **Lesson**: [What we learned]
|
||||
|
||||
---
|
||||
|
||||
## 4. What Didn't Work
|
||||
|
||||
### Mechanic Failures
|
||||
|
||||
❌ **[Failure 1]**: [What didn't work]
|
||||
- **Why**: [Root cause]
|
||||
- **Could It Be Fixed**: [Is it salvageable or fundamentally flawed?]
|
||||
|
||||
❌ **[Failure 2]**: [What didn't work]
|
||||
- **Why**: [Root cause]
|
||||
- **Could It Be Fixed**: [Yes/No + how]
|
||||
|
||||
### Technical Failures
|
||||
|
||||
❌ **[Technical issue 1]**: [What caused problems]
|
||||
- **Lesson**: [What to avoid in production]
|
||||
|
||||
❌ **[Technical issue 2]**: [What caused problems]
|
||||
- **Lesson**: [What to avoid]
|
||||
|
||||
---
|
||||
|
||||
## 5. What Needs Refinement
|
||||
|
||||
⚠️ **[Element 1]**: [What showed promise but needs work]
|
||||
- **Issue**: [What's wrong with it currently]
|
||||
- **Path Forward**: [How to improve it]
|
||||
- **Effort**: [Small | Medium | Large refactor]
|
||||
|
||||
⚠️ **[Element 2]**: [What needs refinement]
|
||||
- **Issue**: [Current problem]
|
||||
- **Path Forward**: [Improvement approach]
|
||||
- **Effort**: [Estimate]
|
||||
|
||||
---
|
||||
|
||||
## 6. Key Learnings
|
||||
|
||||
### Design Insights
|
||||
|
||||
💡 **[Insight 1]**: [What we learned about game design]
|
||||
- **Implication**: [How this affects future work]
|
||||
|
||||
💡 **[Insight 2]**: [Design learning]
|
||||
- **Implication**: [Impact on GDD or other systems]
|
||||
|
||||
### Technical Insights
|
||||
|
||||
💡 **[Insight 3]**: [Technical learning]
|
||||
- **Implication**: [Architecture or implementation guidance]
|
||||
|
||||
💡 **[Insight 4]**: [Technical learning]
|
||||
- **Implication**: [Future technical decisions]
|
||||
|
||||
### Player Psychology Insights
|
||||
|
||||
💡 **[Insight 5]**: [What we learned about player behavior]
|
||||
- **Implication**: [How this affects design philosophy]
|
||||
|
||||
---
|
||||
|
||||
## 7. Production Readiness Assessment
|
||||
|
||||
**Should This Become a Full Feature?**: [Yes | No | Needs More Testing | Pivot to Different Approach]
|
||||
|
||||
**If Yes — Production Requirements**:
|
||||
- [ ] [Requirement 1 — e.g., "Rewrite for performance"]
|
||||
- [ ] [Requirement 2 — e.g., "Add proper UI"]
|
||||
- [ ] [Requirement 3 — e.g., "Design 10 more variations"]
|
||||
- [ ] [Requirement 4 — e.g., "Integrate with progression system"]
|
||||
|
||||
**Estimated Production Effort**: [Small | Medium | Large]
|
||||
- Prototype reusability: [X%] of code can be kept
|
||||
- From-scratch effort: [X hours/days to production-ready]
|
||||
|
||||
**If No — Why Not?**:
|
||||
- [Reason 1 — e.g., "Fun but doesn't fit game pillars"]
|
||||
- [Reason 2 — e.g., "Too complex for target audience"]
|
||||
- [Reason 3 — e.g., "Technically infeasible at scale"]
|
||||
|
||||
**If Pivot — Suggested Direction**:
|
||||
- [Alternative approach 1]
|
||||
- [Alternative approach 2]
|
||||
|
||||
---
|
||||
|
||||
## 8. Design Pillars Alignment
|
||||
|
||||
**How This Relates to Game Pillars** (if game pillars are defined):
|
||||
|
||||
| Pillar | Alignment | Notes |
|
||||
|--------|-----------|-------|
|
||||
| [Pillar 1] | ✅ Strong / ⚠️ Weak / ❌ Conflicts | [Explanation] |
|
||||
| [Pillar 2] | ✅ Strong / ⚠️ Weak / ❌ Conflicts | [Explanation] |
|
||||
| [Pillar 3] | ✅ Strong / ⚠️ Weak / ❌ Conflicts | [Explanation] |
|
||||
|
||||
**Overall Pillar Fit**: [Does this belong in the game?]
|
||||
|
||||
---
|
||||
|
||||
## 9. Next Steps
|
||||
|
||||
### Immediate (If Moving Forward)
|
||||
1. **[Task 1]**: [e.g., "Create full design doc for this system"]
|
||||
2. **[Task 2]**: [e.g., "Write ADR for technical approach"]
|
||||
3. **[Task 3]**: [e.g., "Add to backlog for Sprint X"]
|
||||
|
||||
### Before Production (If Needs More Work)
|
||||
1. **[Task 1]**: [e.g., "Build second prototype testing X variation"]
|
||||
2. **[Task 2]**: [e.g., "Playtest with 5+ people"]
|
||||
3. **[Task 3]**: [e.g., "Investigate technical feasibility of Y"]
|
||||
|
||||
### If Abandoning
|
||||
1. **[Task 1]**: [e.g., "Archive prototype with this document"]
|
||||
2. **[Task 2]**: [e.g., "Extract reusable code/learnings"]
|
||||
3. **[Task 3]**: [e.g., "Update game pillars if this changed thinking"]
|
||||
|
||||
---
|
||||
|
||||
## 10. Technical Notes
|
||||
|
||||
**Prototype Implementation**:
|
||||
- Language/Engine: [What was used]
|
||||
- Architecture: [How it was structured]
|
||||
- Shortcuts taken: [What was hacky or throwaway]
|
||||
|
||||
**Reusable Code** (if any):
|
||||
- `[file/path 1]`: [What it does, reusability]
|
||||
- `[file/path 2]`: [What it does, reusability]
|
||||
|
||||
**Technical Debt** (if moving to production):
|
||||
- [Debt 1]: [What needs rewriting]
|
||||
- [Debt 2]: [What needs proper implementation]
|
||||
|
||||
---
|
||||
|
||||
## 11. Playtest Feedback
|
||||
|
||||
*(If prototype was playtested)*
|
||||
|
||||
**Testers**: [N people, [internal/external]]
|
||||
|
||||
**Positive Feedback**:
|
||||
- "[Quote 1]" — [Tester name/role]
|
||||
- "[Quote 2]" — [Tester name/role]
|
||||
|
||||
**Negative Feedback**:
|
||||
- "[Quote 1]" — [Tester name/role]
|
||||
- "[Quote 2]" — [Tester name/role]
|
||||
|
||||
**Suggestions**:
|
||||
- "[Suggestion 1]" — [Tester name]
|
||||
- "[Suggestion 2]" — [Tester name]
|
||||
|
||||
**Themes**:
|
||||
- [Theme 1]: [What multiple testers agreed on]
|
||||
- [Theme 2]: [Common feedback]
|
||||
|
||||
---
|
||||
|
||||
## 12. Related Work
|
||||
|
||||
**Inspired By** (games/mechanics this was influenced by):
|
||||
- [Game 1]: [What mechanic or feeling]
|
||||
- [Game 2]: [What was borrowed or adapted]
|
||||
|
||||
**Differs From** (how this is unique or different):
|
||||
- [Difference 1]
|
||||
- [Difference 2]
|
||||
|
||||
**Integrates With** (existing game systems):
|
||||
- [System 1]: [How they would connect]
|
||||
- [System 2]: [How they would connect]
|
||||
|
||||
---
|
||||
|
||||
## 13. Open Questions
|
||||
|
||||
**Design Questions**:
|
||||
1. **[Question 1]**: [What's still undecided about the design?]
|
||||
2. **[Question 2]**: [What needs playtesting or iteration?]
|
||||
|
||||
**Technical Questions**:
|
||||
3. **[Question 3]**: [What technical unknowns remain?]
|
||||
4. **[Question 4]**: [What needs feasibility testing?]
|
||||
|
||||
---
|
||||
|
||||
## 14. Appendix: Prototype Assets
|
||||
|
||||
**Code**:
|
||||
- Location: `prototypes/[name]/src/`
|
||||
- Status: [Archival | Partial reuse | Full reuse]
|
||||
|
||||
**Art/Audio** (if any):
|
||||
- Location: `prototypes/[name]/assets/`
|
||||
- Status: [Placeholder | Production-ready | Needs replacement]
|
||||
|
||||
**Documentation**:
|
||||
- README: [Exists | Missing]
|
||||
- Build instructions: [Exists | Missing]
|
||||
|
||||
---
|
||||
|
||||
## Version History
|
||||
|
||||
| Date | Author | Changes |
|
||||
|------|--------|---------|
|
||||
| [Date] | Claude (reverse-doc) | Initial concept doc from prototype analysis |
|
||||
| [Date] | [User] | Clarified outcomes, added playtest feedback |
|
||||
|
||||
---
|
||||
|
||||
**Final Recommendation**: [GO | NO-GO | PIVOT]
|
||||
|
||||
**Rationale**: [1-2 sentence summary of why]
|
||||
|
||||
---
|
||||
|
||||
*This concept document was generated by `/reverse-document concept prototypes/[name]`*
|
||||
204
.claude/docs/templates/design-doc-from-implementation.md
vendored
Normal file
204
.claude/docs/templates/design-doc-from-implementation.md
vendored
Normal file
@@ -0,0 +1,204 @@
|
||||
# [System Name] — Design Document
|
||||
|
||||
---
|
||||
**Status**: Reverse-Documented
|
||||
**Source**: `[path to implementation code]`
|
||||
**Date**: [YYYY-MM-DD]
|
||||
**Verified By**: [User name or "pending review"]
|
||||
**Implementation Status**: [Fully implemented | Partially implemented | Needs extension]
|
||||
---
|
||||
|
||||
> **⚠️ Reverse-Documentation Notice**
|
||||
>
|
||||
> This design document was created **after** the implementation already existed.
|
||||
> It captures current behavior and clarified design intent based on code analysis
|
||||
> and user consultation. Some sections may be incomplete where implementation is
|
||||
> partial or design intent was unclear during reverse-engineering.
|
||||
|
||||
---
|
||||
|
||||
## 1. Overview
|
||||
|
||||
**Purpose**: [What problem does this system solve?]
|
||||
|
||||
**Scope**: [What is included/excluded from this system?]
|
||||
|
||||
**Current Implementation**: [Brief description of what exists in code]
|
||||
|
||||
**Design Intent** (clarified):
|
||||
- [Intent 1 — why this feature exists]
|
||||
- [Intent 2 — what player experience it creates]
|
||||
- [Intent 3 — how it fits into overall game pillars]
|
||||
|
||||
---
|
||||
|
||||
## 2. Detailed Design
|
||||
|
||||
### 2.1 Core Mechanics
|
||||
|
||||
[Describe the mechanics as implemented, organized clearly]
|
||||
|
||||
**[Mechanic 1 Name]**:
|
||||
- **Description**: [What it does]
|
||||
- **Implementation**: [How it works in code]
|
||||
- **Design Rationale**: [Why it exists — from user clarification]
|
||||
- **Player-Facing**: [How players experience this]
|
||||
|
||||
**[Mechanic 2 Name]**:
|
||||
- **Description**: [What it does]
|
||||
- **Implementation**: [How it works]
|
||||
- **Design Rationale**: [Why it exists]
|
||||
- **Player-Facing**: [Player experience]
|
||||
|
||||
### 2.2 Rules and Formulas
|
||||
|
||||
**Formulas Discovered in Code**:
|
||||
|
||||
| Formula | Expression | Purpose | Verified? |
|
||||
|---------|-----------|---------|-----------|
|
||||
| [Formula 1] | `[mathematical expression]` | [What it calculates] | ✅ / ⚠️ needs tuning |
|
||||
| [Formula 2] | `[expression]` | [Purpose] | ✅ / ⚠️ needs tuning |
|
||||
|
||||
**Clarifications**:
|
||||
- [Formula X]: Originally [value/approach], user clarified intent is [corrected intent]
|
||||
- [Formula Y]: Implemented as [X], but should be [Y] — flagged for update
|
||||
|
||||
### 2.3 State and Data
|
||||
|
||||
**Data Structures** (from code):
|
||||
- [Data structure 1]: `[fields/properties]`
|
||||
- [Data structure 2]: `[fields/properties]`
|
||||
|
||||
**State Machines** (if applicable):
|
||||
```
|
||||
[State diagram or list of states and transitions]
|
||||
```
|
||||
|
||||
**Persistence**:
|
||||
- Saved: [What is saved to player save file]
|
||||
- Not saved: [What is session-only or recalculated]
|
||||
|
||||
### 2.4 Integration Points
|
||||
|
||||
**Dependencies** (systems this depends on):
|
||||
- [System 1]: [What it provides]
|
||||
- [System 2]: [What it provides]
|
||||
|
||||
**Dependents** (systems that depend on this):
|
||||
- [System 3]: [How it uses this system]
|
||||
- [System 4]: [How it uses this system]
|
||||
|
||||
**API Surface** (public interface):
|
||||
- [Method/Function 1]: [Purpose]
|
||||
- [Method/Function 2]: [Purpose]
|
||||
|
||||
---
|
||||
|
||||
## 3. Edge Cases
|
||||
|
||||
**Handled in Code**:
|
||||
- ✅ [Edge case 1]: [How it's handled]
|
||||
- ✅ [Edge case 2]: [How it's handled]
|
||||
|
||||
**Not Yet Handled** (discovered during analysis):
|
||||
- ⚠️ [Edge case 3]: [What happens? Needs implementation]
|
||||
- ⚠️ [Edge case 4]: [What happens? Needs implementation]
|
||||
|
||||
**Unclear** (need user clarification):
|
||||
- ❓ [Edge case 5]: [What should happen? Pending decision]
|
||||
|
||||
---
|
||||
|
||||
## 4. Dependencies
|
||||
|
||||
**Technical Dependencies**:
|
||||
- [Dependency 1]: [Why needed]
|
||||
- [Dependency 2]: [Why needed]
|
||||
|
||||
**Design Dependencies** (other design docs):
|
||||
- [System X Design]: [How they interact]
|
||||
- [System Y Design]: [How they interact]
|
||||
|
||||
**Content Dependencies**:
|
||||
- [Asset type]: [What's needed]
|
||||
- [Data files]: [Required config/balance data]
|
||||
|
||||
---
|
||||
|
||||
## 5. Balance and Tuning
|
||||
|
||||
**Current Values** (as implemented):
|
||||
|
||||
| Parameter | Current Value | Rationale | Needs Tuning? |
|
||||
|-----------|--------------|-----------|---------------|
|
||||
| [Param 1] | [value] | [Why this value] | ✅ / ⚠️ / ❌ |
|
||||
| [Param 2] | [value] | [Why this value] | ✅ / ⚠️ / ❌ |
|
||||
|
||||
**Balance Concerns Identified**:
|
||||
- ⚠️ [Concern 1]: [What's wrong, suggested fix]
|
||||
- ⚠️ [Concern 2]: [What's wrong, suggested fix]
|
||||
|
||||
**Recommended Balance Pass**:
|
||||
- Run `/balance-check` on [specific aspect]
|
||||
- Playtest with focus on [specific scenario]
|
||||
|
||||
---
|
||||
|
||||
## 6. Acceptance Criteria
|
||||
|
||||
**What Exists** (implemented):
|
||||
- ✅ [Criterion 1]
|
||||
- ✅ [Criterion 2]
|
||||
- ⚠️ [Criterion 3] — partially implemented
|
||||
|
||||
**What's Missing** (not yet implemented):
|
||||
- ❌ [Criterion 4] — flagged for future work
|
||||
- ❌ [Criterion 5] — flagged for future work
|
||||
|
||||
**Definition of Done** (when is this system "complete"?):
|
||||
- [ ] [Requirement 1]
|
||||
- [ ] [Requirement 2]
|
||||
- [ ] [Requirement 3]
|
||||
|
||||
---
|
||||
|
||||
## 7. Open Questions and Follow-Up Work
|
||||
|
||||
### Questions Needing User Decision
|
||||
1. **[Question 1]**: [What needs to be decided?]
|
||||
- Option A: [Approach A]
|
||||
- Option B: [Approach B]
|
||||
|
||||
2. **[Question 2]**: [What needs to be decided?]
|
||||
|
||||
### Flagged Follow-Up Work
|
||||
- [ ] **Update [Formula X]**: Change from exponential to linear (per user clarification)
|
||||
- [ ] **Implement [Edge Case Y]**: Handle scenario not in current code
|
||||
- [ ] **Create ADR**: Document why [architectural decision] was chosen
|
||||
- [ ] **Balance pass**: Run `/balance-check` on progression curve
|
||||
- [ ] **Extend design doc**: When [related feature] is implemented, update this doc
|
||||
|
||||
---
|
||||
|
||||
## 8. Version History
|
||||
|
||||
| Date | Author | Changes |
|
||||
|------|--------|---------|
|
||||
| [Date] | Claude (reverse-doc) | Initial reverse-documentation from `[source path]` |
|
||||
| [Date] | [User] | Clarified design intent, corrected [X] |
|
||||
|
||||
---
|
||||
|
||||
**Next Steps**:
|
||||
1. [Priority 1 task based on gaps identified]
|
||||
2. [Priority 2 task]
|
||||
3. [Priority 3 task]
|
||||
|
||||
**Related Skills**:
|
||||
- `/balance-check` — Validate formulas and progression
|
||||
- `/architecture-decision` — Document technical decisions
|
||||
- `/code-review` — Ensure code matches clarified design
|
||||
|
||||
---
|
||||
|
||||
*This document was generated by `/reverse-document design [path]`*
|
||||
330
.claude/docs/templates/difficulty-curve.md
vendored
Normal file
330
.claude/docs/templates/difficulty-curve.md
vendored
Normal file
@@ -0,0 +1,330 @@
|
||||
# Difficulty Curve: [Game Title]
|
||||
|
||||
> **Status**: Draft | In Review | Approved
|
||||
> **Author**: [game-designer / systems-designer]
|
||||
> **Last Updated**: [Date]
|
||||
> **Links To**: `design/gdd/game-concept.md`
|
||||
> **Relevant GDDs**: [e.g., `design/gdd/combat.md`, `design/gdd/progression.md`]
|
||||
|
||||
---
|
||||
|
||||
## Difficulty Philosophy
|
||||
|
||||
[One paragraph establishing this game's relationship with difficulty. This is
|
||||
not a mechanical description — it is a design value statement that all tuning
|
||||
decisions must serve.
|
||||
|
||||
The four common difficulty philosophies are:
|
||||
|
||||
1. **Masochistic challenge as the core fantasy**: Difficulty is the product.
|
||||
Overcoming it is the emotional reward. Reducing difficulty removes the
|
||||
point. (Dark Souls, Celeste at max assist off)
|
||||
2. **Accessible entry, optional depth**: The base experience is completable by
|
||||
most players; depth and challenge are opt-in for those who want them.
|
||||
(Hades, Hollow Knight with accessibility modes)
|
||||
3. **Difficulty serves narrative pacing**: Challenge rises and falls to match
|
||||
story beats. The player must feel capable during story resolution and
|
||||
threatened during story crisis. (The Last of Us, God of War)
|
||||
4. **Relaxed engagement**: Challenge is present but never the focus. Failure
|
||||
is gentle and infrequent. The experience prioritizes comfort and expression
|
||||
over obstacle. (Stardew Valley, Animal Crossing)
|
||||
|
||||
State the philosophy explicitly, then add one sentence on what the player is
|
||||
permitted to feel: are they allowed to feel frustrated? For how long before the
|
||||
design must intervene? What is the acceptable cost of failure?]
|
||||
|
||||
---
|
||||
|
||||
## Difficulty Axes
|
||||
|
||||
> **Guidance**: Most games have multiple independent dimensions of challenge.
|
||||
> Identifying them explicitly prevents the mistake of tuning only one axis
|
||||
> (usually execution difficulty) while leaving others unexamined. A game can
|
||||
> feel "easy" on execution but overwhelming on decision complexity — players
|
||||
> experience this as confusing, not engaging.
|
||||
>
|
||||
> For each axis, answer: can the player control or reduce this axis through
|
||||
> choices, builds, or settings? If not, it is a forced challenge dimension —
|
||||
> be very intentional about how it is used.
|
||||
|
||||
| Axis | Description | Primary Systems | Player Control? |
|
||||
|------|-------------|----------------|-----------------|
|
||||
| **Execution difficulty** | [The precision and timing demands of core actions. e.g., "Dodging enemy attacks requires correct timing within a 200ms window."] | [e.g., Combat, movement] | [Yes — practice reduces this / No — fixed mechanical threshold] |
|
||||
| **Knowledge difficulty** | [The cost of not knowing information. e.g., "Enemy weaknesses are not telegraphed; players who have not discovered them take significantly more damage."] | [e.g., Enemy design, UI, lore] | [Yes — through in-game discovery / No — requires external knowledge] |
|
||||
| **Resource pressure** | [How scarce are the resources needed to progress? e.g., "Health consumables are limited; efficient play is required to sustain long dungeon runs."] | [e.g., Economy, loot, crafting] | [Yes — through build optimization / Partially] |
|
||||
| **Time pressure** | [Does the player have time to think, or does the game demand rapid decisions? e.g., "Enemy spawn timers and attack windows require real-time response."] | [e.g., Combat pacing, timers] | [Yes — through difficulty settings / No — core to genre] |
|
||||
| **Decision complexity** | [How many meaningful choices must the player evaluate simultaneously? e.g., "Build decisions interact across 4 systems; suboptimal combinations create compounding disadvantage."] | [e.g., Progression, inventory, skills] | [Yes — through UI and tutorialization / No — inherent to strategy depth] |
|
||||
| **[Add axis]** | [Description] | [Systems] | [Player control] |
|
||||
|
||||
---
|
||||
|
||||
## Difficulty Curve Overview
|
||||
|
||||
> **Guidance**: This table describes the intended challenge arc across the whole
|
||||
> game. Difficulty levels use a 1-10 scale where 1 = no meaningful challenge,
|
||||
> 10 = maximum challenge the game can produce. The scale is relative to THIS game's
|
||||
> design intent — a 6/10 in a soulslike is not the same as a 6/10 in a cozy sim.
|
||||
>
|
||||
> "Primary challenge type" refers to the difficulty axis (from the table above)
|
||||
> that is doing the most work in this phase. New systems introduced should list
|
||||
> only systems introduced for the FIRST TIME — the cognitive load of learning
|
||||
> a new system is itself a form of difficulty.
|
||||
>
|
||||
> "Target player state" is the emotional state the designer intends. If the actual
|
||||
> playtested state diverges from the intended state, this column is what needs
|
||||
> to be achieved.
|
||||
|
||||
| Phase | Duration | Difficulty Level (1-10) | Primary Challenge Type | New Systems Introduced | Target Player State |
|
||||
|-------|----------|------------------------|----------------------|----------------------|---------------------|
|
||||
| [Prologue / Tutorial] | [e.g., 0-15 min] | [2/10] | [Knowledge] | [Core movement, basic interaction] | [Safe, curious, building confidence] |
|
||||
| [Early game] | [e.g., 15 min - 2 hrs] | [3-5/10] | [Execution] | [Combat, inventory, first upgrade path] | [Learning, occasional failure, clear cause-effect] |
|
||||
| [Mid game - opening] | [e.g., 2-6 hrs] | [5-7/10] | [Decision complexity] | [Build choices, advanced enemies, crafting] | [Engaged, strategizing, feeling growth] |
|
||||
| [Mid game - depth] | [e.g., 6-15 hrs] | [6-8/10] | [Resource pressure] | [Elite enemies, optional hard content, endgame previews] | [Challenged, invested, approaching mastery] |
|
||||
| [Late game] | [e.g., 15-25 hrs] | [7-9/10] | [Execution + knowledge] | [Endgame systems, NG+ or equivalent] | [Mastery, confident in build identity, seeking peak challenge] |
|
||||
| [Optional / Endgame] | [e.g., 25+ hrs] | [8-10/10] | [All axes combined] | [Mastery challenges, achievement targets] | [Expert play, self-imposed goals, community comparison] |
|
||||
|
||||
---
|
||||
|
||||
## Onboarding Ramp
|
||||
|
||||
> **Guidance**: The first hour deserves its own detailed breakdown because it
|
||||
> does the most difficult design work: it must teach every foundational skill
|
||||
> without feeling like a lesson, and it must create enough investment that the
|
||||
> player commits to the journey ahead. Research on player retention shows that
|
||||
> most players who leave a game do so in the first 30 minutes — not because
|
||||
> the game is bad, but because onboarding failed to connect them.
|
||||
>
|
||||
> The scaffolding principle (Vygotsky's Zone of Proximal Development, adapted
|
||||
> for game design): introduce each mechanic in isolation before combining it
|
||||
> with others. A player cannot learn two skills simultaneously under pressure.
|
||||
|
||||
### What the Player Knows at Each Stage
|
||||
|
||||
| Time | What the Player Knows | What They Do Not Know Yet |
|
||||
|------|-----------------------|--------------------------|
|
||||
| [0 min] | [Literally nothing — treat this row as your most important UX audit. What can a player infer from the title screen alone?] | [Everything] |
|
||||
| [5 min] | [Core movement verb, basic world reading] | [All progression systems, all secondary mechanics] |
|
||||
| [15 min] | [Core interaction loop, first goal] | [Build depth, advanced mechanics, danger severity] |
|
||||
| [30 min] | [Has made at least one strategic choice] | [Whether that choice was optimal] |
|
||||
| [60 min] | [Has a working model of the core loop] | [Late-game depth, optional systems] |
|
||||
|
||||
### Mechanic Introduction Sequence
|
||||
|
||||
> The order mechanics are introduced is a design decision with real consequences.
|
||||
> Introduce the most essential verb first. Introduce mechanics that modify other
|
||||
> mechanics AFTER the base mechanic is internalized. Never introduce two new
|
||||
> mechanics in the same encounter.
|
||||
|
||||
| Mechanic | Introduced At | Introduction Method | Stakes at Introduction |
|
||||
|----------|--------------|--------------------|-----------------------|
|
||||
| [Core movement / primary verb] | [e.g., First 30 seconds] | [Tutorial prompt / environmental design / NPC instruction] | [None — safe space to experiment] |
|
||||
| [Primary interaction / action] | [e.g., First 2 minutes] | [Method] | [Low — reversible, forgiving window] |
|
||||
| [First resource mechanic] | [e.g., 5 min] | [Method] | [Low — abundant at introduction] |
|
||||
| [First strategic choice] | [e.g., 15 min] | [Method] | [Low — choice can be changed or revisited] |
|
||||
| [First real failure risk] | [e.g., 20-30 min] | [Method] | [Moderate — player should feel genuine threat but have fair tools to respond] |
|
||||
| [Add mechanic] | [Timing] | [Method] | [Stakes] |
|
||||
|
||||
### The First Failure
|
||||
|
||||
[Describe the intended design of the first moment the player can meaningfully
|
||||
fail. This is one of the most important beats in the game.
|
||||
|
||||
A well-designed first failure teaches rather than punishes. The player should
|
||||
be able to immediately identify what they did wrong and what they would do
|
||||
differently. If the cause of failure is ambiguous, the player blames the game.
|
||||
|
||||
Answer: What causes the first failure? What does the player learn from it?
|
||||
How quickly can they retry? What is the cost? Does the game provide any
|
||||
feedback that bridges cause and effect?]
|
||||
|
||||
### When the Player First Feels Competent
|
||||
|
||||
[Identify the specific moment — not a vague window, but a specific beat —
|
||||
where the player should shift from "learning" to "doing." This is the moment
|
||||
of first competence: the first time their prediction about the game comes true,
|
||||
or the first time they execute a plan and it works.
|
||||
|
||||
This moment must happen within the first hour. If it does not, the player
|
||||
will not reach Phase 3 of the journey (First Mastery). Design this moment
|
||||
deliberately — do not leave it to chance.
|
||||
|
||||
What is the moment? What systems create it? What does the player do to
|
||||
trigger it? How does the game communicate that they have succeeded?]
|
||||
|
||||
---
|
||||
|
||||
## Difficulty Spikes and Valleys
|
||||
|
||||
> **Guidance**: A healthy difficulty curve follows a sawtooth pattern
|
||||
> (Csikszentmihalyi's flow model applied to macro-structure): tension builds
|
||||
> through a sequence, then releases at a milestone, then re-engages at a
|
||||
> slightly higher baseline. Flat difficulty creates boredom; uninterrupted
|
||||
> escalation creates fatigue.
|
||||
>
|
||||
> Spikes are intentional peaks that test accumulated skills. Valleys are
|
||||
> intentional troughs that give the player space to breathe, experiment, and
|
||||
> feel powerful before the next escalation. Both are designed, not emergent.
|
||||
>
|
||||
> "Recovery design" is critical: what happens immediately after a spike? The
|
||||
> player should exit a hard moment feeling accomplished, not depleted. Give
|
||||
> them a valley, a reward, or a narrative payoff.
|
||||
|
||||
| Name | Location in Game | Type | Purpose | Recovery Design |
|
||||
|------|-----------------|------|---------|-----------------|
|
||||
| [e.g., "The First Boss"] | [e.g., End of Area 1, ~1 hr] | [Spike] | [Tests all skills introduced in Area 1. Acts as a gate confirming the player is ready for increased complexity.] | [Post-boss: safe area, upgrade opportunity, story beat that provides emotional relief before Area 2 escalation begins.] |
|
||||
| [e.g., "The Safe Zone"] | [e.g., Hub area between Areas 1 and 2, ~1.5 hrs] | [Valley] | [Player feels powerful from boss win. Space to experiment with build options before stakes rise.] | [N/A — this IS the recovery from the preceding spike.] |
|
||||
| [e.g., "The Knowledge Wall"] | [e.g., Area 3 first encounter, ~4 hrs] | [Spike — knowledge type] | [Forces players to engage with a mechanic they may have been avoiding. Survival requires understanding it.] | [Clear feedback on what killed them. Tutorial hint surfaces on third failure. Mechanic becomes standard after this point.] |
|
||||
| [e.g., "Pre-Climax Valley"] | [e.g., Just before final act, ~20 hrs] | [Valley] | [Emotional breathing room before the final escalation. Player reflects on how far they have come.] | [N/A — designed as relief before the finale's spike.] |
|
||||
| [Add spike/valley] | [Location] | [Type] | [Purpose] | [Recovery] |
|
||||
|
||||
---
|
||||
|
||||
## Balancing Levers
|
||||
|
||||
> **Guidance**: Balancing levers are the specific values and parameters that
|
||||
> tune difficulty at each phase. Centralizing them here makes it possible to
|
||||
> tune the whole-game difficulty curve without hunting through individual GDDs.
|
||||
> For each lever, the GDD that owns it should be cross-referenced.
|
||||
>
|
||||
> "Current setting" is the design intent at the time of writing — implementation
|
||||
> values live in `assets/data/`. The tuning range is the safe operating range:
|
||||
> values outside this range reliably break the intended experience.
|
||||
|
||||
| Lever | Phase(s) | Effect | Current Setting | Tuning Range | Notes |
|
||||
|-------|----------|--------|----------------|-------------|-------|
|
||||
| [Enemy health multiplier] | [All] | [Higher = longer fights = more resource pressure and execution time] | [1.0x] | [0.7x - 1.5x] | [Below 0.7x, fights end before player can read enemy patterns. Above 1.5x, attrition replaces skill.] |
|
||||
| [Enemy aggression timer] | [Mid game onward] | [Time between enemy attacks; lower = less time to react] | [e.g., 2.0s] | [1.2s - 3.0s] | [Below 1.2s, reaction window is sub-human. Above 3.0s, encounters feel passive.] |
|
||||
| [Resource drop rate] | [Early game] | [Lower = more resource pressure = punishes inefficiency harder] | [e.g., 1.5x baseline] | [0.8x - 2.0x] | [Onboarding generosity; reduces in mid-game as player skill assumed.] |
|
||||
| [New mechanic introduction density] | [First hour] | [How many new concepts per minute of play; too high = cognitive overload] | [e.g., 1 new mechanic per 8 min] | [1 per 5 min (max) to 1 per 15 min (slow)] | [Above 1 per 5 min in early game causes retention drop. Below 1 per 15 min causes boredom.] |
|
||||
| [Failure cost] | [All] | [Time lost on failure; higher = more punishing = more tension] | [e.g., 2 min setback] | [30s - 8 min] | [Must scale with encounter frequency. Frequent failures need fast recovery.] |
|
||||
| [Add lever] | [Phase] | [Effect] | [Setting] | [Range] | [Notes] |
|
||||
|
||||
---
|
||||
|
||||
## Player Skill Assumptions
|
||||
|
||||
> **Guidance**: Every game implicitly assumes players develop a set of skills
|
||||
> over the course of play. Making these assumptions explicit allows the team to
|
||||
> verify that each skill is actually taught before it is tested, and that the
|
||||
> gap between "introduced" and "tested hard" is long enough for internalization.
|
||||
>
|
||||
> A skill introduced and tested in the same encounter is a surprise difficulty
|
||||
> spike. A skill assumed but never formally introduced is an undocumented knowledge
|
||||
> wall. Both are fixable — but only if they are documented.
|
||||
>
|
||||
> "Taught by" refers to the mechanism: tutorial prompt, environmental design,
|
||||
> safe practice opportunity, NPC instruction, or organic discovery.
|
||||
>
|
||||
> "Tested by" refers to the first encounter that REQUIRES this skill to survive
|
||||
> without taking significant damage or cost.
|
||||
|
||||
| Skill | Introduced In | Expected Mastered By | Taught By | First Hard Test |
|
||||
|-------|--------------|---------------------|-----------|-----------------|
|
||||
| [Core movement / dodging] | [Tutorial area, 0-5 min] | [End of Area 1, ~1 hr] | [Safe practice zone with visible hazards] | [First Elite enemy, ~45 min] |
|
||||
| [Resource management] | [First shop encounter, ~10 min] | [Mid game, ~4 hrs] | [Resource scarcity in Area 2 forces planning] | [Boss that requires consumables to survive efficiently] |
|
||||
| [Build decision-making] | [First upgrade choice, ~20 min] | [End of mid game, ~10 hrs] | [Multiple playthroughs / community discussion / in-game build advisor] | [Endgame encounters that punish build incoherence] |
|
||||
| [Enemy pattern reading] | [Area 1 basic enemies] | [Area 3, ~4 hrs] | [Enemy telegraphs visible and consistent from introduction] | [Elite enemy with 3+ distinct attack patterns] |
|
||||
| [Add skill] | [When introduced] | [When mastered] | [Taught by] | [First hard test] |
|
||||
|
||||
---
|
||||
|
||||
## Accessibility Considerations
|
||||
|
||||
> **Guidance**: Accessibility in difficulty design is not about making the game
|
||||
> easier — it is about ensuring players with different needs and skill profiles
|
||||
> can reach the intended emotional experience. Be explicit about what CAN be
|
||||
> adjusted and what CANNOT, and justify both.
|
||||
>
|
||||
> The principle from Self-Determination Theory: players need to feel competent.
|
||||
> Accessibility options that help players feel competent without removing the
|
||||
> feeling of agency are always worth including. Options that make competence
|
||||
> meaningless undermine the core experience.
|
||||
|
||||
### What Can Be Adjusted
|
||||
|
||||
| Adjustment | Method | Effect on Experience | Tradeoff |
|
||||
|-----------|--------|---------------------|----------|
|
||||
| [e.g., Enemy speed reduction] | [Difficulty setting / accessibility menu] | [Lowers execution difficulty without changing knowledge or decision requirements] | [Reduces the tension of combat timing; acceptable for narrative players] |
|
||||
| [e.g., Extended input windows] | [Accessibility menu] | [Allows players with motor impairments to achieve the same skill outcomes with more time] | [Minimal — skill expression preserved, threshold relaxed] |
|
||||
| [e.g., Hint frequency] | [Settings toggle] | [Surfaces contextual guidance more or less aggressively based on player preference] | [Higher hints reduce knowledge difficulty; players who want to discover organically may feel over-guided] |
|
||||
| [Add option] | [Method] | [Effect] | [Tradeoff] |
|
||||
|
||||
### What Cannot Be Adjusted (and Why)
|
||||
|
||||
| Fixed Element | Why It Cannot Change | Design Reasoning |
|
||||
|--------------|---------------------|-----------------|
|
||||
| [e.g., Permadeath in roguelike run] | [Removing it eliminates the resource pressure axis that all encounter balance is built around] | [The weight of each decision comes from permanence; without it, the core loop loses meaning] |
|
||||
| [e.g., Core narrative pacing] | [Difficulty valleys are timed to story beats; adjustable pacing would decouple challenge from narrative intention] | [Story and difficulty are designed as one arc, not two independent tracks] |
|
||||
| [Add fixed element] | [Why] | [Reasoning] |
|
||||
|
||||
---
|
||||
|
||||
## Cross-System Difficulty Interactions
|
||||
|
||||
> **Guidance**: When two systems operate simultaneously, their combined
|
||||
> difficulty is often greater than the sum of their parts — or sometimes
|
||||
> less. These interactions are frequently unintended and only surface during
|
||||
> playtesting. Documenting anticipated interactions here creates a checklist
|
||||
> for QA and playtest sessions.
|
||||
>
|
||||
> "Is this intended?" Yes means the interaction is a designed feature.
|
||||
> No means it should be mitigated. Partial means the interaction is
|
||||
> acceptable in small doses but problematic if it becomes the dominant
|
||||
> experience.
|
||||
|
||||
| System A | System B | Combined Effect | Intended? |
|
||||
|----------|----------|----------------|-----------|
|
||||
| [Combat difficulty] | [Resource scarcity] | [Resource-poor players face combat encounters with fewer options, compounding difficulty for players already struggling. Can create a death spiral where failing creates worse conditions.] | [Partial — intended as stakes, not as a trap. Pity mechanics required to prevent unrecoverable states.] |
|
||||
| [Build complexity] | [Time pressure] | [Players who are still learning their build take longer to make decisions under time pressure, increasing cognitive load beyond the intended challenge of either system alone.] | [No — reduce decision complexity demand in high time-pressure encounters.] |
|
||||
| [New mechanic introduction] | [Resource pressure] | [Introducing a new system while the player is already under resource pressure forces them to learn and optimize simultaneously.] | [No — new mechanics should be introduced in low-resource-pressure environments.] |
|
||||
| [Enemy density] | [Execution difficulty] | [High enemy counts with individually demanding enemies produce difficulty that scales exponentially, not linearly.] | [Partial — intended for optional challenge content only; not acceptable on the critical path.] |
|
||||
| [Add System A] | [Add System B] | [Combined effect description] | [Yes / No / Partial] |
|
||||
|
||||
---
|
||||
|
||||
## Validation Checklist
|
||||
|
||||
> **Guidance**: These checkpoints structure playtesting sessions to verify
|
||||
> the difficulty curve is achieving its intent. Each item should be checked
|
||||
> with at least 3 playtester sessions before being marked complete. Note the
|
||||
> playtester profile that revealed issues — difficulty problems are almost
|
||||
> always player-profile-specific.
|
||||
|
||||
### Onboarding (0-30 min)
|
||||
- [ ] Players with no prior genre experience complete the tutorial area without external help
|
||||
- [ ] Zero players cite confusion about what they are supposed to be doing in the first 5 minutes
|
||||
- [ ] At least one playtester spontaneously says "I want to see what's next" within 15 minutes
|
||||
- [ ] First failure moment produces a visible learning response (player verbalizes what went wrong)
|
||||
|
||||
### Early Game (30 min - 2 hrs)
|
||||
- [ ] Average player reaches the first competence moment within 60 minutes
|
||||
- [ ] First major encounter (boss or equivalent) is passed within 3-5 attempts on average
|
||||
- [ ] No player cites a mechanic introduced "too suddenly without warning"
|
||||
- [ ] Players can describe their current goal without prompting
|
||||
|
||||
### Mid Game (2-10 hrs)
|
||||
- [ ] Players discover at least one depth mechanic through organic play (without guide)
|
||||
- [ ] Playtest sessions report "I want to try a different build / strategy next run"
|
||||
- [ ] No single difficulty axis dominates player complaints — frustration is distributed
|
||||
- [ ] Players who fail a mid-game encounter correctly identify the cause without being told
|
||||
|
||||
### Late Game (10+ hrs)
|
||||
- [ ] Players report the final challenge feels like a culmination of everything they have learned
|
||||
- [ ] Failure at late-game content does not feel unfair (even if it is hard)
|
||||
- [ ] Players who complete the main content express a reason to continue playing
|
||||
|
||||
### Accessibility
|
||||
- [ ] All listed accessibility options function without breaking encounter intent
|
||||
- [ ] Players using accessibility settings report feeling competent, not patronized
|
||||
- [ ] Fixed difficulty elements are encountered and accepted without negative reception from accessibility playtesters
|
||||
|
||||
---
|
||||
|
||||
## Open Questions
|
||||
|
||||
| Question | Owner | Deadline | Resolution |
|
||||
|----------|-------|----------|-----------|
|
||||
| [Is the onboarding ramp correctly calibrated for players without prior genre experience?] | [game-designer] | [Date] | [Unresolved — schedule genre-naive playtester sessions] |
|
||||
| [Does the first boss represent the correct difficulty spike or is it a wall?] | [game-designer, systems-designer] | [Date] | [Unresolved — requires 5+ playtester sessions to establish average attempt count] |
|
||||
| [Do any cross-system interactions produce unrecoverable states?] | [systems-designer] | [Date] | [Unresolved — requires targeted playtest with resource-constrained starting conditions] |
|
||||
| [Add question] | [Owner] | [Date] | [Resolution] |
|
||||
130
.claude/docs/templates/economy-model.md
vendored
Normal file
130
.claude/docs/templates/economy-model.md
vendored
Normal file
@@ -0,0 +1,130 @@
|
||||
# Economy Model: [System Name]
|
||||
|
||||
*Created: [Date]*
|
||||
*Owner: economy-designer*
|
||||
*Status: [Draft / Balanced / Live]*
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
[What resources, currencies, and exchange systems does this economy cover?
|
||||
What player behaviors does it incentivize?]
|
||||
|
||||
---
|
||||
|
||||
## Currencies
|
||||
|
||||
| Currency | Type | Earn Rate | Sink Rate | Cap | Notes |
|
||||
| ---- | ---- | ---- | ---- | ---- | ---- |
|
||||
| [Gold] | Soft | [per hour] | [per hour] | [max or none] | [Primary transaction currency] |
|
||||
| [Gems] | Premium | [per day F2P] | [varies] | [max] | [Premium currency, purchasable] |
|
||||
| [XP] | Progression | [per action] | [level-up cost] | [none] | [Cannot be traded] |
|
||||
|
||||
### Currency Rules
|
||||
- [Rule 1 — e.g., "Soft currency has no cap but inflation is controlled via sinks"]
|
||||
- [Rule 2 — e.g., "Premium currency cannot be converted back to real money"]
|
||||
- [Rule 3]
|
||||
|
||||
---
|
||||
|
||||
## Sources (Faucets)
|
||||
|
||||
| Source | Currency | Amount | Frequency | Conditions |
|
||||
| ---- | ---- | ---- | ---- | ---- |
|
||||
| [Quest completion] | Gold | [50-200] | [per quest] | [Scales with quest difficulty] |
|
||||
| [Enemy drops] | Gold | [1-10] | [per kill] | [Modified by luck stat] |
|
||||
| [Daily login] | Gems | [5] | [daily] | [Streak bonus: +1 per consecutive day] |
|
||||
| [Achievement] | XP | [100-500] | [one-time] | [Per achievement tier] |
|
||||
|
||||
---
|
||||
|
||||
## Sinks (Drains)
|
||||
|
||||
| Sink | Currency | Cost | Frequency | Purpose |
|
||||
| ---- | ---- | ---- | ---- | ---- |
|
||||
| [Equipment purchase] | Gold | [100-5000] | [as needed] | [Power progression] |
|
||||
| [Repair costs] | Gold | [10-100] | [per death] | [Death penalty, gold drain] |
|
||||
| [Cosmetic shop] | Gems | [50-500] | [optional] | [Vanity, premium sink] |
|
||||
| [Respec] | Gold | [1000] | [rare] | [Build experimentation tax] |
|
||||
|
||||
---
|
||||
|
||||
## Balance Targets
|
||||
|
||||
| Metric | Target | Rationale |
|
||||
| ---- | ---- | ---- |
|
||||
| Time to first meaningful purchase | [X minutes] | [Player should feel spending power early] |
|
||||
| Hourly gold earn rate (mid-game) | [X gold/hr] | [Based on session length and purchase cadence] |
|
||||
| Days to max level (F2P) | [X days] | [Enough to retain, not so long it frustrates] |
|
||||
| Sink-to-source ratio | [0.7-0.9] | [Slight surplus keeps players feeling wealthy] |
|
||||
| Premium currency F2P earn rate | [X/week] | [Enough to buy something monthly, not everything] |
|
||||
|
||||
---
|
||||
|
||||
## Progression Curves
|
||||
|
||||
### Level XP Requirements
|
||||
| Level | XP Required | Cumulative XP | Estimated Time |
|
||||
| ---- | ---- | ---- | ---- |
|
||||
| 1→2 | [100] | [100] | [10 min] |
|
||||
| 5→6 | [500] | [1,500] | [2 hrs] |
|
||||
| 10→11 | [1,500] | [7,500] | [8 hrs] |
|
||||
| 20→21 | [5,000] | [50,000] | [40 hrs] |
|
||||
|
||||
*Formula*: `XP(n) = [formula, e.g., 100 * n^1.5]`
|
||||
|
||||
### Item Price Scaling
|
||||
*Formula*: `Price(tier) = [formula, e.g., base_price * 2^(tier-1)]`
|
||||
|
||||
---
|
||||
|
||||
## Loot Tables
|
||||
|
||||
### [Drop Source Name]
|
||||
| Item | Rarity | Drop Rate | Pity Timer | Notes |
|
||||
| ---- | ---- | ---- | ---- | ---- |
|
||||
| [Common item] | Common | [60%] | [N/A] | [Always useful, never feels bad] |
|
||||
| [Uncommon item] | Uncommon | [25%] | [N/A] | [Noticeable upgrade] |
|
||||
| [Rare item] | Rare | [12%] | [10 drops] | [Exciting, build-defining] |
|
||||
| [Legendary item] | Legendary | [3%] | [30 drops] | [Game-changing, celebration moment] |
|
||||
|
||||
### Pity System
|
||||
[Describe how the pity system works to prevent extreme bad luck streaks.]
|
||||
|
||||
---
|
||||
|
||||
## Economy Health Metrics
|
||||
|
||||
| Metric | Healthy Range | Warning Threshold | Action if Breached |
|
||||
| ---- | ---- | ---- | ---- |
|
||||
| Average player gold | [X-Y at level Z] | [>Y or <X] | [Adjust faucets/sinks] |
|
||||
| Gold Gini coefficient | [<0.4] | [>0.5] | [Wealth too concentrated] |
|
||||
| % players hitting currency cap | [<5%] | [>10%] | [Raise cap or add sinks] |
|
||||
| Premium conversion rate | [2-5%] | [<1% or >10%] | [Rebalance F2P earn rate] |
|
||||
| Average time between purchases | [X minutes] | [>Y minutes] | [Nothing worth buying] |
|
||||
|
||||
---
|
||||
|
||||
## Ethical Guardrails
|
||||
|
||||
- [No pay-to-win: premium currency cannot buy gameplay power advantages]
|
||||
- [Pity timers on all random drops: guaranteed outcome within X attempts]
|
||||
- [Transparent drop rates displayed to players]
|
||||
- [Spending limits for minor accounts]
|
||||
- [No artificial scarcity pressure (FOMO timers) on essential items]
|
||||
|
||||
---
|
||||
|
||||
## Simulation Results
|
||||
|
||||
[Include results from economy simulations if available: player wealth
|
||||
distribution over time, sink effectiveness, inflation rate, etc.]
|
||||
|
||||
---
|
||||
|
||||
## Dependencies
|
||||
|
||||
- Depends on: [combat balance, quest design, crafting system]
|
||||
- Affects: [difficulty curve, player retention, monetization]
|
||||
- Must coordinate with: `game-designer`, `live-ops-designer`, `analytics-engineer`
|
||||
166
.claude/docs/templates/faction-design.md
vendored
Normal file
166
.claude/docs/templates/faction-design.md
vendored
Normal file
@@ -0,0 +1,166 @@
|
||||
# Faction Design: [Faction Name]
|
||||
|
||||
*Created: [Date]*
|
||||
*Owner: world-builder*
|
||||
*Status: [Draft / Approved / Implemented]*
|
||||
|
||||
---
|
||||
|
||||
## Identity
|
||||
|
||||
| Aspect | Detail |
|
||||
| ---- | ---- |
|
||||
| **Full Name** | [Official faction name] |
|
||||
| **Common Name** | [What people call them] |
|
||||
| **Type** | [Nation / Guild / Cult / Corporation / Tribe / etc.] |
|
||||
| **Alignment** | [Not D&D alignment — their moral complexity in 1 sentence] |
|
||||
| **Symbol** | [Description of their emblem/flag/sigil] |
|
||||
| **Colors** | [Primary and secondary colors associated with this faction] |
|
||||
| **Motto** | [Their defining phrase or creed] |
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
[2-3 paragraphs describing who this faction is, what they want, and why they
|
||||
matter to the game world. Write as if briefing someone who knows nothing.]
|
||||
|
||||
---
|
||||
|
||||
## History
|
||||
|
||||
### Origin
|
||||
[How did this faction form? What event or need brought them together?]
|
||||
|
||||
### Key Historical Events
|
||||
1. **[Event Name]** ([Date/Era]): [What happened and how it shaped the faction]
|
||||
2. **[Event Name]** ([Date/Era]): [Impact]
|
||||
3. **[Event Name]** ([Date/Era]): [Impact]
|
||||
|
||||
### Current State
|
||||
[Where is this faction now? Are they ascendant, declining, stable, fractured?]
|
||||
|
||||
---
|
||||
|
||||
## Beliefs and Values
|
||||
|
||||
### Core Beliefs
|
||||
- [Belief 1 — what they hold as fundamental truth]
|
||||
- [Belief 2]
|
||||
- [Belief 3]
|
||||
|
||||
### What They Value
|
||||
- [Value 1 — what they reward and respect]
|
||||
- [Value 2]
|
||||
|
||||
### What They Despise
|
||||
- [Thing 1 — what they punish or reject]
|
||||
- [Thing 2]
|
||||
|
||||
---
|
||||
|
||||
## Structure and Leadership
|
||||
|
||||
### Hierarchy
|
||||
[How is the faction organized? Military ranks? Council of elders? Meritocracy?
|
||||
Describe the power structure.]
|
||||
|
||||
### Key Figures
|
||||
| Name | Role | Personality | Motivation |
|
||||
| ---- | ---- | ---- | ---- |
|
||||
| [Leader] | [Title] | [2-3 adjectives] | [What drives them] |
|
||||
| [Second] | [Title] | [Personality] | [Motivation] |
|
||||
| [Notable] | [Title] | [Personality] | [Motivation] |
|
||||
|
||||
### Membership
|
||||
- **How to join**: [Birth? Initiation? Purchase? Invitation?]
|
||||
- **How to leave**: [Can they? What happens?]
|
||||
- **Population**: [Rough size and composition]
|
||||
|
||||
---
|
||||
|
||||
## Territory and Resources
|
||||
|
||||
### Holdings
|
||||
[Where does this faction control territory? What are their key locations?]
|
||||
|
||||
### Resources
|
||||
- **Primary resource**: [What they have abundance of]
|
||||
- **Scarcity**: [What they lack and need]
|
||||
- **Trade goods**: [What they export/sell]
|
||||
|
||||
### Military Strength
|
||||
[How powerful are they? Standing army? Special forces? Magical capabilities?
|
||||
Technology level?]
|
||||
|
||||
---
|
||||
|
||||
## Relationships
|
||||
|
||||
| Faction | Relationship | Reason | Trend |
|
||||
| ---- | ---- | ---- | ---- |
|
||||
| [Faction A] | [Allied / Friendly / Neutral / Tense / Hostile / War] | [Why] | [Improving / Stable / Deteriorating] |
|
||||
| [Faction B] | [Relationship] | [Why] | [Trend] |
|
||||
| [Player] | [Starting disposition] | [Why] | [Player-influenced] |
|
||||
|
||||
---
|
||||
|
||||
## Reputation System (if applicable)
|
||||
|
||||
| Tier | Points | Benefits | Requirements |
|
||||
| ---- | ---- | ---- | ---- |
|
||||
| Hostile | [-1000 to -500] | [Attacked on sight] | [Betrayal, war crimes] |
|
||||
| Unfriendly | [-500 to -100] | [No services, higher prices] | [Opposing actions] |
|
||||
| Neutral | [-100 to 100] | [Basic services] | [Default] |
|
||||
| Friendly | [100 to 500] | [Discounts, quests] | [Complete tasks] |
|
||||
| Honored | [500 to 1000] | [Unique items, areas, abilities] | [Major questline] |
|
||||
| Exalted | [1000+] | [Best rewards, title, housing] | [Full faction commitment] |
|
||||
|
||||
---
|
||||
|
||||
## Gameplay Role
|
||||
|
||||
### Player Interaction
|
||||
[How does the player encounter and interact with this faction? Quests?
|
||||
Trading? Combat? Diplomacy?]
|
||||
|
||||
### Unique Mechanics
|
||||
[Does this faction introduce any unique gameplay mechanics? Crafting recipes?
|
||||
Combat styles? Magic systems?]
|
||||
|
||||
### Questlines
|
||||
[Brief overview of the major questlines associated with this faction.]
|
||||
|
||||
---
|
||||
|
||||
## Aesthetic Guide
|
||||
|
||||
### Architecture
|
||||
[What do their buildings look like? Materials, shapes, scale.]
|
||||
|
||||
### Clothing/Armor
|
||||
[What do members wear? Identifying visual elements.]
|
||||
|
||||
### Technology/Magic Level
|
||||
[What tools, weapons, and abilities do they use?]
|
||||
|
||||
### Audio Palette
|
||||
[What sounds are associated with this faction? Musical themes, ambient sounds.]
|
||||
|
||||
---
|
||||
|
||||
## Lore Consistency Notes
|
||||
|
||||
- **Canon level**: [Core / Extended / Flavor — how important is this to the main story?]
|
||||
- **Contradictions to watch**: [Any potential conflicts with other lore]
|
||||
- **Open questions**: [Things not yet decided about this faction]
|
||||
- **Off-limits**: [Things that must NOT be true about this faction]
|
||||
|
||||
---
|
||||
|
||||
## Dependencies
|
||||
|
||||
- Related factions: [List factions that interact with this one]
|
||||
- Related areas: [Levels/regions where this faction appears]
|
||||
- Related questlines: [Story arcs involving this faction]
|
||||
- Affects: [economy, combat encounters, narrative branches]
|
||||
317
.claude/docs/templates/game-concept.md
vendored
Normal file
317
.claude/docs/templates/game-concept.md
vendored
Normal file
@@ -0,0 +1,317 @@
|
||||
# Game Concept: [Working Title]
|
||||
|
||||
*Created: [Date]*
|
||||
*Status: [Draft / Under Review / Approved]*
|
||||
|
||||
---
|
||||
|
||||
## Elevator Pitch
|
||||
|
||||
> [1-2 sentences that capture the entire game. Should be compelling enough to
|
||||
> make someone want to hear more. Format: "It's a [genre] where you [core
|
||||
> action] in a [setting] to [goal]."
|
||||
>
|
||||
> Test: Can someone who has never heard of this game understand what they'd
|
||||
> be doing in 10 seconds? If not, simplify.]
|
||||
|
||||
---
|
||||
|
||||
## Core Identity
|
||||
|
||||
| Aspect | Detail |
|
||||
| ---- | ---- |
|
||||
| **Genre** | [Primary genre + subgenre(s)] |
|
||||
| **Platform** | [PC / Console / Mobile / Cross-platform] |
|
||||
| **Target Audience** | [See Player Profile section below] |
|
||||
| **Player Count** | [Single-player / Co-op / Multiplayer / MMO] |
|
||||
| **Session Length** | [Typical play session: 10 min / 30 min / 1 hr / 2+ hr] |
|
||||
| **Monetization** | [Premium / F2P / Subscription / none yet] |
|
||||
| **Estimated Scope** | [Small (1-3 months) / Medium (3-9 months) / Large (9+ months)] |
|
||||
| **Comparable Titles** | [2-3 existing games in the same space] |
|
||||
|
||||
---
|
||||
|
||||
## Core Fantasy
|
||||
|
||||
[What power, experience, or feeling does the player get from this game?
|
||||
What can they do here that they can't do anywhere else?
|
||||
|
||||
The core fantasy is the emotional promise. It's not a feature list — it's the
|
||||
answer to "why would someone choose THIS game over anything else they could
|
||||
be doing?"
|
||||
|
||||
Examples of strong core fantasies:
|
||||
- "You are a lone survivor building a new life in a hostile wilderness" (survival)
|
||||
- "You command a civilization across millennia" (strategy)
|
||||
- "You explore a vast, beautiful world at your own pace" (open world)
|
||||
- "You master intricate combat and overcome impossible odds" (soulslike)]
|
||||
|
||||
---
|
||||
|
||||
## Unique Hook
|
||||
|
||||
[What makes this game different from everything else in its genre? This is
|
||||
the single most important differentiator.
|
||||
|
||||
A strong hook passes the "and also" test: "It's like [comparable game],
|
||||
AND ALSO [unique thing]." If the "and also" doesn't spark curiosity, the
|
||||
hook needs work.
|
||||
|
||||
The hook should be:
|
||||
- Explainable in one sentence
|
||||
- Genuinely novel (not just a combination of existing features)
|
||||
- Connected to the core fantasy (not a gimmick bolted on)
|
||||
- Something that affects gameplay, not just aesthetics]
|
||||
|
||||
---
|
||||
|
||||
## Player Experience Analysis (MDA Framework)
|
||||
|
||||
The MDA (Mechanics-Dynamics-Aesthetics) framework ensures we design from the
|
||||
player's emotional experience backward to the systems that create it.
|
||||
|
||||
### Target Aesthetics (What the player FEELS)
|
||||
Rank the following aesthetic goals for this game (1 = primary, mark N/A if not
|
||||
relevant). These come from the MDA framework's 8 aesthetic categories:
|
||||
|
||||
| Aesthetic | Priority | How We Deliver It |
|
||||
| ---- | ---- | ---- |
|
||||
| **Sensation** (sensory pleasure) | [1-8 or N/A] | [Visual beauty, audio design, haptics] |
|
||||
| **Fantasy** (make-believe, role-playing) | [Priority] | [World, characters, player identity] |
|
||||
| **Narrative** (drama, story arc) | [Priority] | [Plot structure, player-driven stories] |
|
||||
| **Challenge** (obstacle course, mastery) | [Priority] | [Difficulty curve, skill ceiling] |
|
||||
| **Fellowship** (social connection) | [Priority] | [Co-op, guilds, shared experiences] |
|
||||
| **Discovery** (exploration, secrets) | [Priority] | [Hidden areas, emergent systems, lore] |
|
||||
| **Expression** (self-expression, creativity) | [Priority] | [Build variety, cosmetics, creation tools] |
|
||||
| **Submission** (relaxation, comfort zone) | [Priority] | [Low-stress loops, ambient gameplay] |
|
||||
|
||||
### Key Dynamics (Emergent player behaviors)
|
||||
[What behaviors do we WANT to emerge from our mechanics? What should players
|
||||
naturally start doing without being told?
|
||||
|
||||
Example: "Players will experiment with ability combinations to find synergies"
|
||||
Example: "Players will share discoveries with the community"]
|
||||
|
||||
### Core Mechanics (Systems we build)
|
||||
[What are the 3-5 mechanical systems that generate the dynamics and aesthetics
|
||||
above? These are the rules, verbs, and systems we actually implement.]
|
||||
|
||||
1. [Mechanic 1 — e.g., "Real-time combat with stamina management"]
|
||||
2. [Mechanic 2 — e.g., "Procedurally generated dungeons with hand-crafted rooms"]
|
||||
3. [Mechanic 3 — e.g., "Crafting system with discoverable recipes"]
|
||||
|
||||
---
|
||||
|
||||
## Player Motivation Profile
|
||||
|
||||
Understanding WHY players play helps us make every design decision. Based on
|
||||
Self-Determination Theory (SDT) and the Player Experience of Need Satisfaction
|
||||
(PENS) model.
|
||||
|
||||
### Primary Psychological Needs Served
|
||||
|
||||
| Need | How This Game Satisfies It | Strength |
|
||||
| ---- | ---- | ---- |
|
||||
| **Autonomy** (freedom, meaningful choice) | [How does the player feel in control?] | [Core / Supporting / Minimal] |
|
||||
| **Competence** (mastery, skill growth) | [How does the player feel skilled?] | [Core / Supporting / Minimal] |
|
||||
| **Relatedness** (connection, belonging) | [How does the player feel connected?] | [Core / Supporting / Minimal] |
|
||||
|
||||
### Player Type Appeal (Bartle Taxonomy)
|
||||
|
||||
Which player types does this game primarily serve?
|
||||
|
||||
- [ ] **Achievers** (goal completion, collection, progression) — How: [...]
|
||||
- [ ] **Explorers** (discovery, understanding systems, finding secrets) — How: [...]
|
||||
- [ ] **Socializers** (relationships, cooperation, community) — How: [...]
|
||||
- [ ] **Killers/Competitors** (domination, PvP, leaderboards) — How: [...]
|
||||
|
||||
### Flow State Design
|
||||
|
||||
Flow occurs when challenge matches skill. How does this game maintain flow?
|
||||
|
||||
- **Onboarding curve**: [How do the first 10 minutes teach the player?]
|
||||
- **Difficulty scaling**: [How does challenge grow with player skill?]
|
||||
- **Feedback clarity**: [How does the player know they're improving?]
|
||||
- **Recovery from failure**: [How quickly can they try again? Is failure punishing or educational?]
|
||||
|
||||
---
|
||||
|
||||
## Core Loop
|
||||
|
||||
### Moment-to-Moment (30 seconds)
|
||||
[What is the player physically doing most of the time? The most basic, repeated
|
||||
action. This MUST be intrinsically satisfying — if the 30-second loop isn't
|
||||
fun in isolation, no amount of progression will save the game.]
|
||||
|
||||
### Short-Term (5-15 minutes)
|
||||
[What objective or cycle structures the moment-to-moment play? Encounters,
|
||||
puzzles, rounds, quests. This is where "one more turn" or "one more run"
|
||||
psychology lives.]
|
||||
|
||||
### Session-Level (30-120 minutes)
|
||||
[What does a full play session look like? What does the player accomplish?
|
||||
This should end with a natural stopping point AND a reason to come back.]
|
||||
|
||||
### Long-Term Progression
|
||||
[How does the player grow over days/weeks? Character progression, unlocks,
|
||||
story advancement, mastery. What is the player working toward?]
|
||||
|
||||
### Retention Hooks
|
||||
[What specifically brings the player back for their next session?]
|
||||
- **Curiosity**: [Unanswered questions, unexplored areas, locked content]
|
||||
- **Investment**: [Progress they don't want to lose, characters they care about]
|
||||
- **Social**: [Friends playing, guild obligations, shared goals]
|
||||
- **Mastery**: [Skills to improve, challenges to overcome, rankings to climb]
|
||||
|
||||
---
|
||||
|
||||
## Game Pillars
|
||||
|
||||
Design pillars are non-negotiable principles that guide EVERY decision. When
|
||||
two design choices conflict, pillars break the tie. Keep to 3-5 pillars.
|
||||
|
||||
Real AAA examples:
|
||||
- God of War: "Intense combat", "Father-son story", "World exploration"
|
||||
- Hades: "Fast fluid combat", "Narrative depth through repeated runs"
|
||||
- The Last of Us: "Story as essential", "AI partners build relationships", "Stealth encouraged"
|
||||
|
||||
### Pillar 1: [Name]
|
||||
[One sentence defining this non-negotiable design principle.]
|
||||
|
||||
*Design test*: [A concrete decision this pillar would resolve. "If we're
|
||||
debating between X and Y, this pillar says we choose __."]
|
||||
|
||||
### Pillar 2: [Name]
|
||||
[Definition]
|
||||
|
||||
*Design test*: [Decision it resolves]
|
||||
|
||||
### Pillar 3: [Name]
|
||||
[Definition]
|
||||
|
||||
*Design test*: [Decision it resolves]
|
||||
|
||||
### Anti-Pillars (What This Game Is NOT)
|
||||
|
||||
Anti-pillars are equally important — they prevent scope creep and keep the
|
||||
vision focused. Every "no" protects the "yes."
|
||||
|
||||
- **NOT [thing]**: [Why this is explicitly excluded and what it would compromise]
|
||||
- **NOT [thing]**: [Why]
|
||||
- **NOT [thing]**: [Why]
|
||||
|
||||
---
|
||||
|
||||
## Inspiration and References
|
||||
|
||||
| Reference | What We Take From It | What We Do Differently | Why It Matters |
|
||||
| ---- | ---- | ---- | ---- |
|
||||
| [Game 1] | [Specific mechanic, feeling, or approach] | [Our twist] | [What it validates about our concept] |
|
||||
| [Game 2] | [What we learn] | [Our twist] | [Validation] |
|
||||
| [Game 3] | [What we learn] | [Our twist] | [Validation] |
|
||||
|
||||
**Non-game inspirations**: [Films, books, music, art, real-world experiences
|
||||
that influence the tone, world, or feel. Great games often pull from outside
|
||||
the medium.]
|
||||
|
||||
---
|
||||
|
||||
## Target Player Profile
|
||||
|
||||
[Be specific. "Gamers" is not a target audience.]
|
||||
|
||||
| Attribute | Detail |
|
||||
| ---- | ---- |
|
||||
| **Age range** | [e.g., 18-35] |
|
||||
| **Gaming experience** | [Casual / Mid-core / Hardcore] |
|
||||
| **Time availability** | [e.g., "30-minute sessions on weeknights, longer on weekends"] |
|
||||
| **Platform preference** | [Where they play most] |
|
||||
| **Current games they play** | [2-3 specific titles] |
|
||||
| **What they're looking for** | [The unmet need this game fills] |
|
||||
| **What would turn them away** | [Dealbreakers for this audience] |
|
||||
|
||||
---
|
||||
|
||||
## Technical Considerations
|
||||
|
||||
| Consideration | Assessment |
|
||||
| ---- | ---- |
|
||||
| **Recommended Engine** | [Godot / Unity / Unreal and why — consider scope, team expertise, platform targets] |
|
||||
| **Key Technical Challenges** | [What's technically hard about this game?] |
|
||||
| **Art Style** | [Pixel / 2D / 2.5D / 3D stylized / 3D realistic] |
|
||||
| **Art Pipeline Complexity** | [Low (asset store + modifications) / Medium (custom 2D) / High (custom 3D)] |
|
||||
| **Audio Needs** | [Minimal / Moderate / Music-heavy / Adaptive] |
|
||||
| **Networking** | [None / P2P / Client-Server / Dedicated Servers] |
|
||||
| **Content Volume** | [Estimate: X levels, Y items, Z hours of gameplay] |
|
||||
| **Procedural Systems** | [Any procedural generation? What scope?] |
|
||||
|
||||
---
|
||||
|
||||
## Risks and Open Questions
|
||||
|
||||
### Design Risks
|
||||
[Things that could make the game unfun or uncompelling]
|
||||
- [Risk 1 — e.g., "Core loop may not sustain sessions > 30 minutes"]
|
||||
- [Risk 2 — e.g., "Player motivation unclear after main story ends"]
|
||||
|
||||
### Technical Risks
|
||||
[Things that could be hard or impossible to build]
|
||||
- [Risk 1 — e.g., "Procedural generation quality is unproven"]
|
||||
- [Risk 2 — e.g., "Networking for 100+ players may require dedicated infrastructure"]
|
||||
|
||||
### Market Risks
|
||||
[Things that could prevent commercial success]
|
||||
- [Risk 1 — e.g., "Genre is saturated with established competitors"]
|
||||
- [Risk 2 — e.g., "Target audience may be too niche for financial sustainability"]
|
||||
|
||||
### Scope Risks
|
||||
[Things that could blow the timeline]
|
||||
- [Risk 1 — e.g., "Content volume exceeds team capacity"]
|
||||
- [Risk 2 — e.g., "Feature X depends on technology we haven't prototyped"]
|
||||
|
||||
### Open Questions
|
||||
[Things that need prototyping or research before we can answer]
|
||||
- [Question 1 — and how we plan to answer it]
|
||||
- [Question 2 — and what prototype would resolve it]
|
||||
|
||||
---
|
||||
|
||||
## MVP Definition
|
||||
|
||||
[The absolute minimum version that validates the core hypothesis. The MVP
|
||||
answers ONE question: "Is the core loop fun?"]
|
||||
|
||||
**Core hypothesis**: [The single statement the MVP tests, e.g., "Players find
|
||||
the combat-crafting loop engaging for 30+ minute sessions"]
|
||||
|
||||
**Required for MVP**:
|
||||
1. [Essential feature 1 — directly tests the hypothesis]
|
||||
2. [Essential feature 2]
|
||||
3. [Essential feature 3]
|
||||
|
||||
**Explicitly NOT in MVP** (defer to later):
|
||||
- [Feature that's nice but doesn't test the hypothesis]
|
||||
- [Feature that adds scope without validating the core]
|
||||
|
||||
### Scope Tiers (if budget/time shrinks)
|
||||
|
||||
| Tier | Content | Features | Timeline |
|
||||
| ---- | ---- | ---- | ---- |
|
||||
| **MVP** | [Minimal] | [Core loop only] | [X weeks] |
|
||||
| **Vertical Slice** | [One complete area] | [Core + progression] | [X weeks] |
|
||||
| **Alpha** | [All areas, placeholder] | [All features, rough] | [X weeks] |
|
||||
| **Full Vision** | [Complete content] | [All features, polished] | [X weeks] |
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
- [ ] Get concept approval from creative-director
|
||||
- [ ] Fill in CLAUDE.md technology stack based on engine choice (`/setup-engine`)
|
||||
- [ ] Create game pillars document (`/design-review` to validate)
|
||||
- [ ] **Prototype core idea** (`/prototype [core-mechanic]`) — before writing GDDs, validate the concept is worth designing
|
||||
- [ ] If prototype PROCEEDS: Decompose concept into systems (`/map-systems`)
|
||||
- [ ] Design each system (`/design-system [system-name]`) — use prototype learnings in Tuning Knobs and Formulas sections
|
||||
- [ ] Build vertical slice in Pre-Production (`/vertical-slice`) — validate full game loop before committing to Production
|
||||
- [ ] Validate core loop with playtest (`/playtest-report`)
|
||||
- [ ] Plan first milestone (`/sprint-plan new`)
|
||||
219
.claude/docs/templates/game-design-document.md
vendored
Normal file
219
.claude/docs/templates/game-design-document.md
vendored
Normal file
@@ -0,0 +1,219 @@
|
||||
# [Mechanic/System Name]
|
||||
|
||||
> **Status**: Draft | In Review | Approved | Implemented
|
||||
> **Author**: [Agent or person]
|
||||
> **Last Updated**: [Date]
|
||||
> **Last Verified**: [Date — when this doc was last confirmed accurate against current design]
|
||||
> **Implements Pillar**: [Which game pillar this supports]
|
||||
|
||||
## Summary
|
||||
|
||||
[2–3 sentences: what this system is, what it does for the player, and why it
|
||||
exists in this game. Written for tiered context loading — a skill scanning
|
||||
20 GDDs uses this section to decide whether to read further. No jargon.]
|
||||
|
||||
> **Quick reference** — Layer: `[Foundation | Core | Feature | Presentation]` · Priority: `[MVP | Vertical Slice | Alpha | Full Vision]` · Key deps: `[System names or "None"]`
|
||||
|
||||
## Overview
|
||||
|
||||
[One paragraph that explains this mechanic to someone who knows nothing about
|
||||
the project. What is it, what does the player do, and why does it exist?]
|
||||
|
||||
## Player Fantasy
|
||||
|
||||
[What should the player FEEL when engaging with this mechanic? What is the
|
||||
emotional or power fantasy being served? This section guides all detail
|
||||
decisions below.]
|
||||
|
||||
## Detailed Design
|
||||
|
||||
### Core Rules
|
||||
|
||||
[Precise, unambiguous rules. A programmer should be able to implement this
|
||||
section without asking questions. Use numbered rules for sequential processes
|
||||
and bullet points for properties.]
|
||||
|
||||
### States and Transitions
|
||||
|
||||
[If this system has states (e.g., weapon states, status effects, phases),
|
||||
document every state and every valid transition between states.]
|
||||
|
||||
| State | Entry Condition | Exit Condition | Behavior |
|
||||
|-------|----------------|----------------|----------|
|
||||
|
||||
### Interactions with Other Systems
|
||||
|
||||
[How does this system interact with combat? Inventory? Progression? UI?
|
||||
For each interaction, specify the interface: what data flows in, what flows
|
||||
out, and who is responsible for what.]
|
||||
|
||||
## Formulas
|
||||
|
||||
[Every mathematical formula used by this system. For each formula:]
|
||||
|
||||
### [Formula Name]
|
||||
|
||||
```
|
||||
result = base_value * (1 + modifier_sum) * scaling_factor
|
||||
```
|
||||
|
||||
| Variable | Type | Range | Source | Description |
|
||||
|----------|------|-------|--------|-------------|
|
||||
| base_value | float | 1-100 | data file | The base amount before modifiers |
|
||||
| modifier_sum | float | -0.9 to 5.0 | calculated | Sum of all active modifiers |
|
||||
| scaling_factor | float | 0.5-2.0 | data file | Level-based scaling |
|
||||
|
||||
**Expected output range**: [min] to [max]
|
||||
**Edge case**: When modifier_sum < -0.9, clamp to -0.9 to prevent negative results.
|
||||
|
||||
## Edge Cases
|
||||
|
||||
[Explicitly document what happens in unusual situations. Each edge case
|
||||
should have a clear resolution.]
|
||||
|
||||
| Scenario | Expected Behavior | Rationale |
|
||||
|----------|------------------|-----------|
|
||||
| [What if X is zero?] | [This happens] | [Because of this reason] |
|
||||
| [What if both effects trigger?] | [Priority rule] | [Design reasoning] |
|
||||
|
||||
## Dependencies
|
||||
|
||||
[List every system this mechanic depends on or that depends on this mechanic.]
|
||||
|
||||
| System | Direction | Nature of Dependency |
|
||||
|--------|-----------|---------------------|
|
||||
| [Combat] | This depends on Combat | Needs damage calculation results |
|
||||
| [Inventory] | Inventory depends on this | Provides item effect data |
|
||||
|
||||
## Tuning Knobs
|
||||
|
||||
[Every value that should be adjustable for balancing. Include the current
|
||||
value, the safe range, and what happens at the extremes.]
|
||||
|
||||
| Parameter | Current Value | Safe Range | Effect of Increase | Effect of Decrease |
|
||||
|-----------|--------------|------------|-------------------|-------------------|
|
||||
|
||||
## Visual/Audio Requirements
|
||||
|
||||
[What visual and audio feedback does this mechanic need?]
|
||||
|
||||
| Event | Visual Feedback | Audio Feedback | Priority |
|
||||
|-------|----------------|---------------|----------|
|
||||
|
||||
## Game Feel
|
||||
|
||||
> **Why this section exists separately from Visual/Audio Requirements**: Visual/Audio
|
||||
> Requirements document WHAT feedback events occur (tables of events mapped to assets).
|
||||
> Game Feel documents HOW the mechanic feels to operate — the responsiveness, weight,
|
||||
> snap, and kinesthetic quality of the interaction. These are design targets for timing,
|
||||
> frame data, and physical sensation of control. Game feel must be specified at design
|
||||
> time because it drives animation budgets, input handling architecture, and hitbox
|
||||
> timing. Retrofitting feel targets after implementation is expensive and often requires
|
||||
> fundamental rework.
|
||||
|
||||
### Feel Reference
|
||||
|
||||
[Name a specific game, mechanic, or moment that captures the target feel. Be precise —
|
||||
cite the exact mechanic, not just the game. Explain what quality you are borrowing.
|
||||
Optionally include an anti-reference (what this should NOT feel like).]
|
||||
|
||||
> Example: "Should feel like Dark Souls weapon swings — weighty, committed, and
|
||||
> telegraphed, but satisfying on contact. NOT floaty like early Halo melee."
|
||||
|
||||
### Input Responsiveness
|
||||
|
||||
[Maximum acceptable latency from player input to visible/audible response, per action.]
|
||||
|
||||
| Action | Max Input-to-Response Latency (ms) | Frame Budget (at 60fps) | Notes |
|
||||
|--------|-----------------------------------|------------------------|-------|
|
||||
| [Primary action] | [e.g., 50ms] | [e.g., 3 frames] | |
|
||||
| [Secondary action] | | | |
|
||||
|
||||
### Animation Feel Targets
|
||||
|
||||
[Frame data targets for each animation in this mechanic. Startup = windup before the
|
||||
action has any effect. Active = frames when the action is "happening" (hitbox live,
|
||||
ability firing, etc.). Recovery = committed/vulnerable frames after the action resolves.]
|
||||
|
||||
| Animation | Startup Frames | Active Frames | Recovery Frames | Feel Goal | Notes |
|
||||
|-----------|---------------|--------------|----------------|-----------|-------|
|
||||
| [e.g., Light attack] | | | | [e.g., Snappy, low commitment] | |
|
||||
| [e.g., Heavy attack] | | | | [e.g., Weighty, high commitment] | |
|
||||
|
||||
### Impact Moments
|
||||
|
||||
[Defines the punctuation of the mechanic — the moments of peak feedback intensity that
|
||||
make actions feel consequential. Every high-stakes event should have at least one entry.]
|
||||
|
||||
| Impact Type | Duration (ms) | Effect Description | Configurable? |
|
||||
|-------------|--------------|-------------------|---------------|
|
||||
| Hit-stop (freeze frames) | [e.g., 80ms] | [Freeze both objects on contact] | Yes |
|
||||
| Screen shake | [e.g., 150ms] | [Directional, decaying] | Yes |
|
||||
| Camera impact | | | |
|
||||
| Controller rumble | | | |
|
||||
| Time-scale slowdown | | | |
|
||||
|
||||
### Weight and Responsiveness Profile
|
||||
|
||||
[A short prose description of the overall feel target. Answer the following:]
|
||||
|
||||
- **Weight**: Does this feel heavy and deliberate, or light and reactive?
|
||||
- **Player control**: How much does the player feel in control at every moment?
|
||||
(High control = can course-correct mid-action; Low control = committed, momentum-based)
|
||||
- **Snap quality**: Does this feel crisp and binary, or smooth and analog?
|
||||
- **Acceleration model**: Does movement/action start instantly (arcade feel) or
|
||||
ramp up from zero (simulation feel)? Same question for deceleration.
|
||||
- **Failure texture**: When the player makes an error, does the mechanic feel fair
|
||||
or punishing? What is the read on WHY they failed?
|
||||
|
||||
### Feel Acceptance Criteria
|
||||
|
||||
[Specific, testable criteria a playtester can verify without measurement instruments.
|
||||
These are subjective targets stated precisely enough to get consistent verdicts.]
|
||||
|
||||
- [ ] [e.g., "Combat feels impactful — playtesters comment on weight unprompted"]
|
||||
- [ ] [e.g., "No reviewer uses the words 'floaty', 'slippery', or 'unresponsive'"]
|
||||
- [ ] [e.g., "Input latency is imperceptible at target 60fps framerate"]
|
||||
- [ ] [e.g., "Hit-stop reads as satisfying, not as lag or stutter"]
|
||||
|
||||
## UI Requirements
|
||||
|
||||
[What information needs to be displayed to the player and when?]
|
||||
|
||||
| Information | Display Location | Update Frequency | Condition |
|
||||
|-------------|-----------------|-----------------|-----------|
|
||||
|
||||
## Cross-References
|
||||
|
||||
[Declare every explicit dependency on another GDD's specific mechanic, value, or
|
||||
rule. This table is machine-checked by `/review-all-gdds` Phase 2c — it replaces
|
||||
implicit prose references with verifiable declarations. If you reference another
|
||||
system's behaviour anywhere in this document, it must appear here.]
|
||||
|
||||
| This Document References | Target GDD | Specific Element Referenced | Nature |
|
||||
|--------------------------|-----------|----------------------------|--------|
|
||||
| [e.g., "combo multiplier feeds score"] | `design/gdd/score.md` | `combo_multiplier` output value | Data dependency |
|
||||
| [e.g., "death triggers respawn"] | `design/gdd/respawn.md` | Death state transition | State trigger |
|
||||
| [e.g., "stamina gates dodge"] | `design/gdd/stamina.md` | Stamina depletion rule | Rule dependency |
|
||||
|
||||
> **Note on "Nature"**: use one of — `Data dependency` (we consume their output),
|
||||
> `State trigger` (their state change triggers our behaviour), `Rule dependency`
|
||||
> (our rule assumes their rule is also true), `Ownership handoff` (we hand off
|
||||
> ownership of a value to them).
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
[Testable criteria that confirm this mechanic is working as designed.]
|
||||
|
||||
- [ ] [Criterion 1: specific, measurable, testable]
|
||||
- [ ] [Criterion 2]
|
||||
- [ ] [Criterion 3]
|
||||
- [ ] Performance: System update completes within [X]ms
|
||||
- [ ] No hardcoded values in implementation
|
||||
|
||||
## Open Questions
|
||||
|
||||
[Anything not yet decided. Each question should have an owner and deadline.]
|
||||
|
||||
| Question | Owner | Deadline | Resolution |
|
||||
|----------|-------|----------|-----------|
|
||||
313
.claude/docs/templates/game-pillars.md
vendored
Normal file
313
.claude/docs/templates/game-pillars.md
vendored
Normal file
@@ -0,0 +1,313 @@
|
||||
# Game Pillars: [Game Title]
|
||||
|
||||
## Document Status
|
||||
- **Version**: 1.0
|
||||
- **Last Updated**: [Date]
|
||||
- **Approved By**: creative-director
|
||||
- **Status**: [Draft / Under Review / Approved]
|
||||
|
||||
---
|
||||
|
||||
## What Are Game Pillars?
|
||||
|
||||
Pillars are the 3-5 non-negotiable principles that define this game's identity.
|
||||
Every design, art, audio, narrative, and technical decision must serve at least
|
||||
one pillar. If a feature doesn't serve a pillar, it doesn't belong in the game.
|
||||
|
||||
**Why pillars matter**: In a typical development cycle, the team makes thousands
|
||||
of small creative decisions. Pillars ensure all those decisions push in the same
|
||||
direction, creating a coherent player experience rather than a collection of
|
||||
disconnected features.
|
||||
|
||||
### What Makes a Good Pillar
|
||||
|
||||
A good pillar is:
|
||||
- **Falsifiable**: "Fun gameplay" is not a pillar. "Combat rewards patience over
|
||||
aggression" is — it makes a testable claim about design choices.
|
||||
- **Constraining**: If a pillar never forces you to say no to something, it's
|
||||
too vague. Good pillars eliminate options.
|
||||
- **Cross-departmental**: A pillar that only constrains game design but says
|
||||
nothing about art, audio, or narrative is incomplete. Real pillars shape
|
||||
every discipline.
|
||||
- **Memorable**: The team should be able to recite the pillars from memory.
|
||||
If they can't, the pillars are too numerous or too complex.
|
||||
|
||||
### Real AAA Examples
|
||||
|
||||
These studios publicly shared their game pillars, showing how concrete and
|
||||
specific effective pillars can be:
|
||||
|
||||
| Game | Pillars | Why They Work |
|
||||
| ---- | ---- | ---- |
|
||||
| **God of War (2018)** | Visceral combat; Father-son emotional journey; Continuous camera (no cuts); Norse mythology reimagined | "Continuous camera" is radical — it cut a standard cinematic tool. "Father-son journey" constrains narrative, level design, AND combat (Atreus as companion). |
|
||||
| **Hades** | Fast fluid combat; Story depth through repetition; Every run teaches something new | "Story through repetition" justified the roguelike structure narratively — death IS the story. "Every run teaches" constrains level and encounter design. |
|
||||
| **The Last of Us** | Story is essential, not optional; AI partners build relationships; Stealth is always an option | "AI partners build relationships" drove massive investment in companion AI — not just pathfinding, but emotional presence. |
|
||||
| **Celeste** | Tough but fair; Accessibility without compromise; Story and mechanics are the same thing | "Story and mechanics are the same thing" — climbing IS the struggle, the dash IS the anxiety. Pillar prevented mechanics from being "just gameplay." |
|
||||
| **Hollow Knight** | Atmosphere over explanation; Earned mastery; World tells its own story | "Atmosphere over explanation" — no tutorials, no hand-holding, the world teaches through environmental design. |
|
||||
| **Dead Cells** | Every weapon is viable; Combat is a dance; Permanent death creates meaning | "Every weapon is viable" is extremely constraining — it demands constant balance work across hundreds of items. |
|
||||
|
||||
---
|
||||
|
||||
## Core Fantasy
|
||||
|
||||
> [What power, experience, or feeling does the player get from this game? What
|
||||
> can they do here that they can't do anywhere else? The core fantasy is the
|
||||
> emotional promise — the answer to "why would someone choose THIS game?"
|
||||
>
|
||||
> Strong core fantasies are visceral and immediate:
|
||||
> - "You are a lone survivor building a new life in a hostile wilderness"
|
||||
> - "You command a civilization across millennia"
|
||||
> - "You explore a vast, beautiful world at your own pace"
|
||||
> - "You master intricate combat and overcome impossible odds"]
|
||||
|
||||
---
|
||||
|
||||
## Target MDA Aesthetics
|
||||
|
||||
[Rank the aesthetic goals this game serves, from the MDA Framework. This ranking
|
||||
guides every pillar — your pillars should collectively deliver your top 2-3
|
||||
aesthetics.]
|
||||
|
||||
| Rank | Aesthetic | How Our Game Delivers It |
|
||||
| ---- | ---- | ---- |
|
||||
| 1 | [e.g., Challenge] | [Specific delivery mechanism] |
|
||||
| 2 | [e.g., Discovery] | [Specific delivery mechanism] |
|
||||
| 3 | [e.g., Fantasy] | [Specific delivery mechanism] |
|
||||
| 4 | [e.g., Narrative] | [Specific delivery mechanism] |
|
||||
| N/A | [Aesthetics not targeted] | [Why this isn't a priority] |
|
||||
|
||||
**Aesthetics reference** (Hunicke, LeBlanc, Zubek):
|
||||
- **Sensation**: Sensory pleasure (visual beauty, satisfying audio, haptic feedback)
|
||||
- **Fantasy**: Make-believe, inhabiting a role or world
|
||||
- **Narrative**: Drama, story arcs, emotional plot progression
|
||||
- **Challenge**: Obstacle course, skill mastery, overcoming difficulty
|
||||
- **Fellowship**: Social connection, cooperation, shared experience
|
||||
- **Discovery**: Exploration, uncovering secrets, understanding hidden systems
|
||||
- **Expression**: Self-expression, creativity, personal identity
|
||||
- **Submission**: Relaxation, comfort, meditative play
|
||||
|
||||
---
|
||||
|
||||
## The Pillars
|
||||
|
||||
### Pillar 1: [Name]
|
||||
|
||||
**One-Sentence Definition**: [A clear, falsifiable statement of what this pillar
|
||||
means. Must be specific enough that two people would reach the same conclusion
|
||||
when applying it to a design question.]
|
||||
|
||||
**Target Aesthetics Served**: [Which MDA aesthetics from the ranking above does
|
||||
this pillar primarily deliver?]
|
||||
|
||||
**Design Test**: [A concrete decision this pillar resolves. "If we're debating
|
||||
between X and Y, this pillar says we choose __."]
|
||||
|
||||
#### What This Means for Each Department
|
||||
|
||||
| Department | This Pillar Says... | Example |
|
||||
| ---- | ---- | ---- |
|
||||
| **Game Design** | [How this constrains and inspires mechanics] | [Concrete example] |
|
||||
| **Art** | [How this constrains and inspires visuals] | [Concrete example] |
|
||||
| **Audio** | [How this constrains and inspires sound/music] | [Concrete example] |
|
||||
| **Narrative** | [How this constrains and inspires story/writing] | [Concrete example] |
|
||||
| **Engineering** | [Technical implications and priorities] | [Concrete example] |
|
||||
|
||||
#### Serving This Pillar
|
||||
- [Concrete example of a feature/decision that embodies this pillar]
|
||||
- [Another example]
|
||||
|
||||
#### Violating This Pillar
|
||||
- [Concrete example of what would betray this pillar — things we must never do]
|
||||
- [Another example]
|
||||
|
||||
---
|
||||
|
||||
### Pillar 2: [Name]
|
||||
|
||||
**One-Sentence Definition**: [Specific, falsifiable statement]
|
||||
|
||||
**Target Aesthetics Served**: [MDA aesthetics]
|
||||
|
||||
**Design Test**: [Concrete decision it resolves]
|
||||
|
||||
#### What This Means for Each Department
|
||||
|
||||
| Department | This Pillar Says... | Example |
|
||||
| ---- | ---- | ---- |
|
||||
| **Game Design** | [Constraint/inspiration] | [Example] |
|
||||
| **Art** | [Constraint/inspiration] | [Example] |
|
||||
| **Audio** | [Constraint/inspiration] | [Example] |
|
||||
| **Narrative** | [Constraint/inspiration] | [Example] |
|
||||
| **Engineering** | [Constraint/inspiration] | [Example] |
|
||||
|
||||
#### Serving This Pillar
|
||||
- [Example]
|
||||
- [Example]
|
||||
|
||||
#### Violating This Pillar
|
||||
- [Example]
|
||||
- [Example]
|
||||
|
||||
---
|
||||
|
||||
### Pillar 3: [Name]
|
||||
|
||||
**One-Sentence Definition**: [Specific, falsifiable statement]
|
||||
|
||||
**Target Aesthetics Served**: [MDA aesthetics]
|
||||
|
||||
**Design Test**: [Concrete decision it resolves]
|
||||
|
||||
#### What This Means for Each Department
|
||||
|
||||
| Department | This Pillar Says... | Example |
|
||||
| ---- | ---- | ---- |
|
||||
| **Game Design** | [Constraint/inspiration] | [Example] |
|
||||
| **Art** | [Constraint/inspiration] | [Example] |
|
||||
| **Audio** | [Constraint/inspiration] | [Example] |
|
||||
| **Narrative** | [Constraint/inspiration] | [Example] |
|
||||
| **Engineering** | [Constraint/inspiration] | [Example] |
|
||||
|
||||
#### Serving This Pillar
|
||||
- [Example]
|
||||
- [Example]
|
||||
|
||||
#### Violating This Pillar
|
||||
- [Example]
|
||||
- [Example]
|
||||
|
||||
---
|
||||
|
||||
### Pillar 4: [Name] (Optional)
|
||||
|
||||
[Same structure as Pillars 1-3]
|
||||
|
||||
### Pillar 5: [Name] (Optional)
|
||||
|
||||
[Same structure as Pillars 1-3]
|
||||
|
||||
---
|
||||
|
||||
## Anti-Pillars (What This Game Is NOT)
|
||||
|
||||
Anti-pillars are equally important as pillars — they prevent scope creep and
|
||||
keep the vision focused. Every "no" protects the "yes."
|
||||
|
||||
Great anti-pillars are things the team might actually want to do. "NOT a racing
|
||||
game" is obvious and useless. "NOT an open-world game" is useful if the genre
|
||||
could plausibly support it.
|
||||
|
||||
- **NOT [thing]**: [Why this is explicitly excluded, what pillar it would
|
||||
compromise, and what it would cost in development focus]
|
||||
- **NOT [thing]**: [Why excluded]
|
||||
- **NOT [thing]**: [Why excluded]
|
||||
|
||||
---
|
||||
|
||||
## Pillar Conflict Resolution
|
||||
|
||||
When two pillars conflict (and they will), use this priority order. The ranking
|
||||
reflects which aspects of the experience are most essential to the core fantasy.
|
||||
|
||||
| Priority | Pillar | Rationale |
|
||||
| ---- | ---- | ---- |
|
||||
| 1 | [Highest priority pillar] | [Why this wins when it conflicts with others] |
|
||||
| 2 | [Second priority] | [Why] |
|
||||
| 3 | [Third priority] | [Why] |
|
||||
|
||||
**Resolution Process**:
|
||||
1. Identify which pillars are in tension
|
||||
2. Consult the priority ranking above
|
||||
3. If the lower-priority pillar can be served partially without compromising the
|
||||
higher-priority one, do so
|
||||
4. If not, the higher-priority pillar wins
|
||||
5. Document the decision and rationale in the relevant design document
|
||||
6. If the conflict is fundamental (two pillars are irreconcilable), escalate to
|
||||
the creative-director to consider revising the pillars themselves
|
||||
|
||||
---
|
||||
|
||||
## Player Motivation Alignment
|
||||
|
||||
[Verify that the pillars collectively serve the target player's psychological needs.
|
||||
Based on Self-Determination Theory (Deci & Ryan) and the Player Experience of
|
||||
Need Satisfaction model.]
|
||||
|
||||
| Need | Which Pillar Serves It | How |
|
||||
| ---- | ---- | ---- |
|
||||
| **Autonomy** (meaningful choice, player agency) | [Pillar name] | [How this pillar creates autonomy] |
|
||||
| **Competence** (mastery, skill growth, clear feedback) | [Pillar name] | [How this pillar creates competence] |
|
||||
| **Relatedness** (connection, belonging, emotional bond) | [Pillar name] | [How this pillar creates relatedness] |
|
||||
|
||||
**Gap check**: If any of the three needs is not served by at least one pillar,
|
||||
consider whether the pillar set is complete. A game that satisfies all three
|
||||
SDT needs has the strongest foundation for sustained engagement.
|
||||
|
||||
---
|
||||
|
||||
## Emotional Arc
|
||||
|
||||
[Map the intended emotional journey of a play session. This should be a
|
||||
deliberate design, not an accident.]
|
||||
|
||||
### Session Emotional Arc
|
||||
|
||||
| Phase | Duration | Target Emotion | Pillar(s) Driving It | Mechanics Delivering It |
|
||||
| ---- | ---- | ---- | ---- | ---- |
|
||||
| Opening | [e.g., 0-5 min] | [e.g., Curiosity, anticipation] | [Which pillar] | [What the player does] |
|
||||
| Rising | [e.g., 5-20 min] | [e.g., Tension, focus, flow] | [Which pillar] | [What the player does] |
|
||||
| Climax | [e.g., 20-30 min] | [e.g., Triumph, relief, awe] | [Which pillar] | [What the player does] |
|
||||
| Resolution | [e.g., 30-40 min] | [e.g., Satisfaction, reflection] | [Which pillar] | [What the player does] |
|
||||
| Hook | [End of session] | [e.g., Curiosity, unfinished business] | [Which pillar] | [What makes them return] |
|
||||
|
||||
### Long-Term Emotional Progression
|
||||
|
||||
[How does the emotional experience evolve across the full game? Early game vs
|
||||
mid game vs late game vs endgame should each feel distinct.]
|
||||
|
||||
---
|
||||
|
||||
## Reference Games
|
||||
|
||||
| Reference | What We Take From It | What We Do Differently | Which Pillar It Validates |
|
||||
| ---- | ---- | ---- | ---- |
|
||||
| [Game 1] | [Specific mechanic, feeling, or approach] | [Our twist] | [Pillar name] |
|
||||
| [Game 2] | [What we learn] | [Our twist] | [Pillar name] |
|
||||
| [Game 3] | [What we learn] | [Our twist] | [Pillar name] |
|
||||
|
||||
**Non-game inspirations**: [Films, books, music, art, real-world experiences
|
||||
that inform the tone, world, or feel. Great games pull from outside the medium.]
|
||||
|
||||
---
|
||||
|
||||
## Pillar Validation Checklist
|
||||
|
||||
Before finalizing the pillars, verify:
|
||||
|
||||
- [ ] **Count**: 3-5 pillars (no more, no fewer)
|
||||
- [ ] **Falsifiable**: Each pillar makes a claim that could be wrong
|
||||
- [ ] **Constraining**: Each pillar forces saying "no" to some plausible ideas
|
||||
- [ ] **Cross-departmental**: Each pillar has implications for design, art, audio, narrative, AND engineering
|
||||
- [ ] **Design-tested**: Each pillar has a concrete design test that resolves a real decision
|
||||
- [ ] **Anti-pillars defined**: At least 3 explicit "this game is NOT" statements
|
||||
- [ ] **Priority-ranked**: Clear order for resolving conflicts between pillars
|
||||
- [ ] **MDA-aligned**: Pillars collectively deliver the top-ranked target aesthetics
|
||||
- [ ] **SDT coverage**: At least one pillar serves Autonomy, one Competence, one Relatedness
|
||||
- [ ] **Memorable**: The team can recite all pillars from memory
|
||||
- [ ] **Core fantasy served**: Every pillar traces back to the core fantasy promise
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
- [ ] Get pillar approval from creative-director
|
||||
- [ ] Distribute to all department leads for sign-off
|
||||
- [ ] Create design tests for each pillar using real upcoming decisions
|
||||
- [ ] Schedule first pillar review (after 2 weeks of development)
|
||||
- [ ] Add pillars to the game-concept document and pitch document
|
||||
|
||||
---
|
||||
|
||||
*This document is the creative north star. It lives in `design/gdd/game-pillars.md`
|
||||
and is referenced by every design, art, audio, and narrative document in the project.
|
||||
Review quarterly or after major milestone pivots.*
|
||||
505
.claude/docs/templates/hud-design.md
vendored
Normal file
505
.claude/docs/templates/hud-design.md
vendored
Normal file
@@ -0,0 +1,505 @@
|
||||
# HUD Design: [Game Name]
|
||||
|
||||
> **Status**: Draft | In Review | Approved | Implemented
|
||||
> **Author**: [Name or agent — e.g., ui-designer]
|
||||
> **Last Updated**: [Date]
|
||||
> **Game**: [Game name — this is a single document per game, not per element]
|
||||
> **Platform Targets**: [All platforms this HUD must work on — e.g., PC, PS5, Xbox Series X, Steam Deck]
|
||||
> **Related GDDs**: [Every system that exposes information through the HUD — e.g., `design/gdd/combat.md`, `design/gdd/progression.md`, `design/gdd/quests.md`]
|
||||
> **Accessibility Tier**: Basic | Standard | Comprehensive | Exemplary
|
||||
> **Style Reference**: [Link to art bible HUD section if it exists — e.g., `design/art/art-bible.md § HUD Visual Language`]
|
||||
|
||||
> **Note — Scope boundary**: This document specifies all elements that overlay the
|
||||
> game world during active gameplay — health bars, ammo counters, minimaps, quest
|
||||
> trackers, subtitles, damage numbers, and notification toasts. For menu screens,
|
||||
> pause menus, inventory, and dialogs that the player navigates explicitly, use
|
||||
> `ux-spec.md` instead. The test: if it appears while the player is directly
|
||||
> controlling their character, it belongs here.
|
||||
|
||||
---
|
||||
|
||||
## 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."]
|
||||
|
||||
**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.]
|
||||
|
||||
**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.]
|
||||
|
||||
---
|
||||
|
||||
## 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.
|
||||
|
||||
| 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] |
|
||||
|
||||
---
|
||||
|
||||
## 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
|
||||
|
||||
```
|
||||
[Draw your HUD layout zones. Customize this to match your game's actual layout.
|
||||
Axes represent approximate screen percentage. Adjust zone names and sizes.]
|
||||
|
||||
0% 100%
|
||||
┌──────────────────────────────────────────────────┐ 0%
|
||||
│ [SAFE MARGIN — 10% from edge on all sides] │
|
||||
│ ┌────────────────────────────────────────────┐ │
|
||||
│ │ [TOP-LEFT] [TOP-CENTER] [TOP-RIGHT] │ ~15%
|
||||
│ │ Health, resource Quest name Ammo, magazine │
|
||||
│ │ │ │
|
||||
│ │ │ │
|
||||
│ │ [CENTER-SCREEN] │ │ ~50%
|
||||
│ │ Crosshair / reticle │ │
|
||||
│ │ (minimize HUD here) │ │
|
||||
│ │ │ │
|
||||
│ │ │ │
|
||||
│ │ [BOTTOM-LEFT] [BOTTOM-CENTER] [BOTTOM-RIGHT] │ ~85%
|
||||
│ │ Minimap Subtitles Notifications │
|
||||
│ │ Ability icons Tutorial prompts │ │
|
||||
│ └────────────────────────────────────────────┘ │
|
||||
│ │
|
||||
└──────────────────────────────────────────────────┘ 100%
|
||||
```
|
||||
|
||||
> Rule for zone placement: the center 40% of the screen (both horizontally and
|
||||
> vertically) is the player's primary focus area. Keep this zone as clear as
|
||||
> possible at all times. HUD elements that appear in the center zone — crosshairs,
|
||||
> interaction prompts, hit markers — must be minimal, high-contrast, and brief.
|
||||
|
||||
### 3.2 Zone Specification Table
|
||||
|
||||
| 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.] |
|
||||
|
||||
**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] |
|
||||
|
||||
---
|
||||
|
||||
## 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.] |
|
||||
|
||||
### 4.2 Element Detail Blocks
|
||||
|
||||
> For each element in the table above, write a detail block. Copy and complete
|
||||
> one block per element.
|
||||
|
||||
---
|
||||
|
||||
**Health Bar**
|
||||
|
||||
- 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).]
|
||||
|
||||
---
|
||||
|
||||
**[Repeat this block for every element in Section 4.1]**
|
||||
|
||||
---
|
||||
|
||||
## 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.
|
||||
|
||||
| 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] |
|
||||
|
||||
---
|
||||
|
||||
## 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.
|
||||
|
||||
| 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] |
|
||||
|
||||
---
|
||||
|
||||
## 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.
|
||||
|
||||
| Budget Constraint | Limit | Measurement Method | Current Estimate | Status |
|
||||
|------------------|-------|--------------------|-----------------|--------|
|
||||
| Maximum simultaneous active HUD elements | [8] | [Count all visible, non-faded elements at any one frame] | [TBD — verify at implementation] | [To verify] |
|
||||
| Maximum % of screen occupied by HUD (exploration mode) | [12%] | [Pixel area of all HUD elements / total screen pixels] | [TBD] | [To verify] |
|
||||
| Maximum % of screen occupied by HUD (combat mode) | [22%] | [Same method — combat adds ammo, crosshair, enemy bars] | [TBD] | [To verify] |
|
||||
| Maximum % of center screen zone (40% of screen W/H) occupied | [5%] | [Only crosshair and interaction prompt allowed here] | [TBD] | [To verify] |
|
||||
| Minimum contrast ratio — HUD text on any background | [4.5:1 (WCAG AA)] | [Measured against the darkest and lightest game world areas the element will appear over] | [TBD] | [To verify] |
|
||||
| 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.
|
||||
|
||||
| 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] |
|
||||
|
||||
**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.
|
||||
|
||||
---
|
||||
|
||||
## 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.
|
||||
|
||||
| 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.] |
|
||||
|
||||
**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)
|
||||
|
||||
Repositioning saves to player profile, not to a single slot. Applies across play sessions.
|
||||
|
||||
---
|
||||
|
||||
## 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.
|
||||
|
||||
### 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.] |
|
||||
|
||||
### 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."]
|
||||
|
||||
**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] |
|
||||
|
||||
### 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] |
|
||||
|
||||
### 10.4 Subtitles Specification
|
||||
|
||||
> Subtitles are the highest-impact accessibility feature in the HUD. Specify them
|
||||
> with the same rigor as the rest of the HUD. Do not leave subtitle behavior to
|
||||
> 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]
|
||||
|
||||
### 10.5 HUD Opacity and Visibility Controls
|
||||
|
||||
The following player-adjustable settings must be available from the Accessibility menu:
|
||||
|
||||
| Setting | Range | Default | Effect |
|
||||
|---------|-------|---------|--------|
|
||||
| [HUD Opacity — Global] | [0% (HUD hidden) to 100%] | [100%] | [Scales all HUD element opacities simultaneously] |
|
||||
| [HUD Text Scale] | [75% to 150%] | [100%] | [Scales all HUD text elements; layout adapts] |
|
||||
| [Damage Number Visibility] | [On / Off] | [On] | [Enables or disables all floating damage numbers] |
|
||||
| [Minimap Visibility] | [On / Off / Compass Only] | [On] | [Compass strip shown as fallback when minimap off] |
|
||||
| [Notification Verbosity] | [All / Important Only / Off] | [All] | [All = all toasts; Important Only = quest + level up; Off = no toasts] |
|
||||
| [Motion Reduction] | [On / Off] | [Off] | [When On, replaces all animated HUD transitions with instant state changes] |
|
||||
| [High Contrast Mode] | [On / Off] | [Off] | [Applies high contrast visual theme to all HUD elements — see art bible for HC variants] |
|
||||
|
||||
---
|
||||
|
||||
## 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.
|
||||
|
||||
| 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] |
|
||||
|
||||
---
|
||||
|
||||
## 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.
|
||||
|
||||
**Layout & Visibility**
|
||||
- [ ] All HUD elements are within platform safe zone margins on all target platforms
|
||||
- [ ] No two HUD elements overlap in any documented gameplay context
|
||||
- [ ] HUD occupies less than [12]% of screen area in exploration context (measure at reference resolution)
|
||||
- [ ] HUD occupies less than [22]% of screen area in combat context
|
||||
- [ ] No HUD element occupies the center [40]% of screen during exploration (crosshair excepted during combat)
|
||||
- [ ] All HUD elements are visible and legible at minimum supported resolution on all platforms
|
||||
|
||||
**Per-Context Correctness**
|
||||
- [ ] HUD correctly shows only specified elements in every context defined in Section 5
|
||||
- [ ] Context transitions (combat enter/exit, dialogue, cinematic) show correct elements within transition timing spec
|
||||
- [ ] Boss health bar appears correctly on boss encounter trigger and disappears after boss defeat
|
||||
- [ ] Death state correctly hides all gameplay HUD elements
|
||||
|
||||
**Accessibility**
|
||||
- [ ] All HUD text elements meet 4.5:1 contrast ratio against all backgrounds they appear over (test light AND dark scenes)
|
||||
- [ ] No HUD element uses color as the ONLY differentiator (verify: remove color from each element and confirm information is still communicated)
|
||||
- [ ] Subtitles appear for all voiced lines and ambient dialogue when subtitle setting is enabled
|
||||
- [ ] Subtitle text never disappears while audio is still playing
|
||||
- [ ] Reduced Motion setting disables all HUD animations listed in Section 10.3
|
||||
- [ ] Text Scale 150% does not cause any HUD text to overflow its container or overlap another element
|
||||
- [ ] All player-adjustable HUD settings in Section 10.5 are functional and persist between sessions
|
||||
|
||||
**Notifications**
|
||||
- [ ] Notifications of the same type that fire within 500ms merge into a single notification
|
||||
- [ ] Low-priority notifications are queued (not displayed) during combat and released post-combat
|
||||
- [ ] Critical warnings (low health, hazard) appear immediately regardless of queue state or combat state
|
||||
- [ ] No more than [3] notification toasts are visible simultaneously
|
||||
- [ ] Notification queue is cleared correctly on level transition (no stale notifications from previous area)
|
||||
|
||||
**Platform**
|
||||
- [ ] All elements respect 10% safe zone margins on console (test on physical TV — not monitor)
|
||||
- [ ] HUD displays correctly at 1280x720 (Steam Deck) with no element clipping or overlap
|
||||
- [ ] HUD elements are repositionable (Health, Minimap, Ability Bar) and reposition settings persist
|
||||
- [ ] Controller disconnection during play does not cause HUD state corruption
|
||||
|
||||
---
|
||||
|
||||
## 13. Open Questions
|
||||
|
||||
> Track unresolved design questions here. All questions must be resolved before
|
||||
> the HUD design document can be marked Approved.
|
||||
|
||||
| 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] |
|
||||
135
.claude/docs/templates/incident-response.md
vendored
Normal file
135
.claude/docs/templates/incident-response.md
vendored
Normal file
@@ -0,0 +1,135 @@
|
||||
# Incident Response: [Incident Title]
|
||||
|
||||
**Severity**: [S1-Critical / S2-Major / S3-Moderate / S4-Minor]
|
||||
**Status**: [Active / Mitigated / Resolved / Post-Mortem Complete]
|
||||
**Detected**: [Date Time UTC]
|
||||
**Resolved**: [Date Time UTC or ONGOING]
|
||||
**Duration**: [Total time from detection to resolution]
|
||||
**Incident Commander**: [Name/Role]
|
||||
|
||||
---
|
||||
|
||||
## Impact Summary
|
||||
|
||||
[2-3 sentences describing what players experienced. Write from the player
|
||||
perspective, not the technical perspective.]
|
||||
|
||||
- **Players affected**: [estimated count or percentage]
|
||||
- **Platforms affected**: [PC / Console / Mobile / All]
|
||||
- **Regions affected**: [All / specific regions]
|
||||
- **Revenue impact**: [estimated if applicable]
|
||||
|
||||
---
|
||||
|
||||
## Timeline
|
||||
|
||||
| Time (UTC) | Event | Action Taken |
|
||||
| ---- | ---- | ---- |
|
||||
| [HH:MM] | Incident detected via [monitoring/player report/etc.] | Incident commander assigned |
|
||||
| [HH:MM] | Root cause identified | [Brief description of cause] |
|
||||
| [HH:MM] | Mitigation deployed | [What was done] |
|
||||
| [HH:MM] | Service restored / Fix confirmed | Monitoring for recurrence |
|
||||
| [HH:MM] | All-clear declared | Post-mortem scheduled |
|
||||
|
||||
---
|
||||
|
||||
## Root Cause
|
||||
|
||||
### What Happened
|
||||
[Technical description of the root cause. Be specific about the chain of events
|
||||
that led to the incident.]
|
||||
|
||||
### Why It Happened
|
||||
[Systemic cause — why did existing processes, tests, or safeguards fail to
|
||||
prevent this? This is more important than the technical cause.]
|
||||
|
||||
### Contributing Factors
|
||||
- [Factor 1 — e.g., "Insufficient load testing for the new matchmaking system"]
|
||||
- [Factor 2 — e.g., "Monitoring alert threshold was set too high"]
|
||||
- [Factor 3]
|
||||
|
||||
---
|
||||
|
||||
## Mitigation and Resolution
|
||||
|
||||
### Immediate Actions (during incident)
|
||||
1. [Action taken to stop the bleeding]
|
||||
2. [Action taken to restore service]
|
||||
3. [Action taken to verify resolution]
|
||||
|
||||
### Follow-Up Actions (after resolution)
|
||||
1. [Permanent fix if immediate action was a workaround]
|
||||
2. [Additional testing or monitoring added]
|
||||
3. [Process changes to prevent recurrence]
|
||||
|
||||
---
|
||||
|
||||
## Player Communication
|
||||
|
||||
### Initial Acknowledgment
|
||||
*Sent: [Time] via [channel]*
|
||||
> [Exact text of the first public message acknowledging the issue]
|
||||
|
||||
### Status Updates
|
||||
*Sent: [Time] via [channel]*
|
||||
> [Text of each subsequent update]
|
||||
|
||||
### Resolution Notice
|
||||
*Sent: [Time] via [channel]*
|
||||
> [Text announcing the fix and any compensation]
|
||||
|
||||
### Compensation (if applicable)
|
||||
- **What**: [description of compensation — e.g., "500 premium currency + 24-hour XP boost"]
|
||||
- **Who**: [all players / affected players only / players who logged in during incident]
|
||||
- **When**: [delivery date and method]
|
||||
- **Rationale**: [why this compensation is appropriate for the impact]
|
||||
|
||||
---
|
||||
|
||||
## Prevention
|
||||
|
||||
### What We Are Changing
|
||||
|
||||
| Action Item | Owner | Deadline | Status |
|
||||
| ---- | ---- | ---- | ---- |
|
||||
| [Specific preventive measure] | [Role] | [Date] | [TODO/Done] |
|
||||
| [Add monitoring for X] | [Role] | [Date] | [TODO/Done] |
|
||||
| [Add test coverage for Y] | [Role] | [Date] | [TODO/Done] |
|
||||
| [Update runbook for Z] | [Role] | [Date] | [TODO/Done] |
|
||||
|
||||
### Process Improvements
|
||||
- [Process change to prevent similar incidents]
|
||||
- [Monitoring/alerting improvement]
|
||||
- [Testing improvement]
|
||||
|
||||
---
|
||||
|
||||
## Lessons Learned
|
||||
|
||||
### What Went Well
|
||||
- [Positive aspect of incident response — e.g., "Detection was fast due to
|
||||
monitoring alerts"]
|
||||
- [Positive aspect]
|
||||
|
||||
### What Went Poorly
|
||||
- [Problem with response — e.g., "Took 20 minutes to identify the correct
|
||||
on-call person"]
|
||||
- [Problem]
|
||||
|
||||
### Where We Got Lucky
|
||||
- [Factor that reduced impact by chance rather than design — these are hidden
|
||||
risks to address]
|
||||
|
||||
---
|
||||
|
||||
## Sign-Offs
|
||||
|
||||
- [ ] Technical Director — Root cause accurate, prevention plan sufficient
|
||||
- [ ] QA Lead — Test coverage gaps addressed
|
||||
- [ ] Producer — Timeline and communication reviewed
|
||||
- [ ] Community Manager — Player communication reviewed
|
||||
|
||||
---
|
||||
|
||||
*This document is filed in `production/hotfixes/` and linked from the
|
||||
release notes for the fix version.*
|
||||
1072
.claude/docs/templates/interaction-pattern-library.md
vendored
Normal file
1072
.claude/docs/templates/interaction-pattern-library.md
vendored
Normal file
File diff suppressed because it is too large
Load Diff
111
.claude/docs/templates/level-design-document.md
vendored
Normal file
111
.claude/docs/templates/level-design-document.md
vendored
Normal file
@@ -0,0 +1,111 @@
|
||||
# Level: [Level Name]
|
||||
|
||||
## Quick Reference
|
||||
|
||||
- **Area/Region**: [Where in the game world]
|
||||
- **Type**: [Combat / Exploration / Puzzle / Hub / Boss / Mixed]
|
||||
- **Estimated Play Time**: [X-Y minutes]
|
||||
- **Difficulty**: [1-10 relative scale]
|
||||
- **Prerequisite**: [What the player must have done to reach this level]
|
||||
- **Status**: [Concept | Layout | Graybox | Art Pass | Polish | Final]
|
||||
|
||||
## Narrative Context
|
||||
|
||||
- **Story Moment**: [Where in the narrative arc does this level occur]
|
||||
- **Narrative Purpose**: [What story beat this level delivers]
|
||||
- **Emotional Target**: [What the player should feel during this level]
|
||||
- **Lore Discoveries**: [What world-building the player can find here]
|
||||
|
||||
## Layout
|
||||
|
||||
### Overview Map
|
||||
|
||||
```
|
||||
[ASCII diagram of the level layout. Use these symbols:]
|
||||
[S] = Start point
|
||||
[E] = Exit/end point
|
||||
[C] = Combat encounter
|
||||
[P] = Puzzle
|
||||
[R] = Reward/loot
|
||||
[!] = Story beat
|
||||
[?] = Secret/optional
|
||||
[>] = One-way passage
|
||||
[=] = Two-way passage
|
||||
[@] = NPC
|
||||
[B] = Boss encounter
|
||||
```
|
||||
|
||||
### Critical Path
|
||||
|
||||
[The mandatory route through the level, step by step.]
|
||||
|
||||
1. Player enters at [S]
|
||||
2. [Description of what happens along the path]
|
||||
3. Player exits at [E]
|
||||
|
||||
### Optional Paths
|
||||
|
||||
| Path | Access Requirement | Reward | Discovery Hint |
|
||||
|------|-------------------|--------|---------------|
|
||||
|
||||
### Points of Interest
|
||||
|
||||
| Location | Type | Description | Purpose |
|
||||
|----------|------|-------------|---------|
|
||||
|
||||
## Encounters
|
||||
|
||||
### Combat Encounters
|
||||
|
||||
| ID | Position | Enemy Composition | Difficulty | Arena Notes |
|
||||
|----|----------|------------------|-----------|-------------|
|
||||
| E-01 | [Map ref] | [2x Grunt, 1x Ranged] | 3/10 | Open area, cover on flanks |
|
||||
| E-02 | [Map ref] | [1x Elite, 3x Grunt] | 5/10 | Narrow corridor, no retreat |
|
||||
|
||||
### Non-Combat Encounters
|
||||
|
||||
| ID | Position | Type | Description | Solution Hint |
|
||||
|----|----------|------|-------------|---------------|
|
||||
|
||||
## Pacing Chart
|
||||
|
||||
```
|
||||
Intensity
|
||||
10 | *
|
||||
8 | * * *
|
||||
6 | * * * * * *
|
||||
4 | * * * ** * * *
|
||||
2 | * ** ** * * * * *
|
||||
0 |S-----------------------------------------E
|
||||
[Start] [Mid] [Climax] [Exit]
|
||||
```
|
||||
|
||||
[Describe the intended rhythm: where are the peaks, valleys, rest points?]
|
||||
|
||||
## Audio Direction
|
||||
|
||||
| Zone/Moment | Music Track | Ambience | Key SFX |
|
||||
|-------------|------------|----------|---------|
|
||||
| [Entry] | [Track] | [Ambient sounds] | [Door opening] |
|
||||
| [Combat] | [Combat music] | [Muted ambience] | [Combat SFX] |
|
||||
| [Post-combat] | [Calm transition] | [Return to ambience] | |
|
||||
|
||||
## Visual Direction
|
||||
|
||||
- **Lighting**: [Key, fill, ambient description]
|
||||
- **Color Palette**: [Dominant colors and why]
|
||||
- **Mood Board References**: [Description of visual references]
|
||||
- **Landmarks**: [Visible navigation aids and their locations]
|
||||
- **Sight Lines**: [What the player should see from key positions]
|
||||
|
||||
## Collectibles and Secrets
|
||||
|
||||
| Item | Location | Visibility | Hint | Required For |
|
||||
|------|----------|-----------|------|-------------|
|
||||
|
||||
## Technical Notes
|
||||
|
||||
- **Estimated Object Count**: [N]
|
||||
- **Streaming Zones**: [Where to break the level for streaming]
|
||||
- **Performance Concerns**: [Any known heavy areas]
|
||||
- **Required Systems**: [What game systems are active in this level]
|
||||
79
.claude/docs/templates/milestone-definition.md
vendored
Normal file
79
.claude/docs/templates/milestone-definition.md
vendored
Normal file
@@ -0,0 +1,79 @@
|
||||
# Milestone: [Name]
|
||||
|
||||
## Overview
|
||||
|
||||
- **Target Date**: [Date]
|
||||
- **Type**: [Prototype | Vertical Slice | Alpha | Beta | Gold | Post-Launch]
|
||||
- **Duration**: [N weeks]
|
||||
- **Number of Sprints**: [N]
|
||||
|
||||
## Milestone Goal
|
||||
|
||||
[2-3 sentences describing what this milestone achieves and why it matters.
|
||||
What can we demonstrate or evaluate at the end of this milestone?]
|
||||
|
||||
## Success Criteria
|
||||
|
||||
[Specific, measurable criteria. The milestone is complete ONLY when all of
|
||||
these are met.]
|
||||
|
||||
- [ ] [Criterion 1 -- specific and testable]
|
||||
- [ ] [Criterion 2]
|
||||
- [ ] [Criterion 3]
|
||||
- [ ] All S1 and S2 bugs resolved
|
||||
- [ ] Performance within budget on target hardware
|
||||
- [ ] Build stable for [X] consecutive days
|
||||
|
||||
## Feature List
|
||||
|
||||
### Must Ship (Milestone Fails Without These)
|
||||
|
||||
| Feature | Design Doc | Owner | Sprint Target | Status |
|
||||
|---------|-----------|-------|--------------|--------|
|
||||
|
||||
### Should Ship (Planned but Cuttable)
|
||||
|
||||
| Feature | Design Doc | Owner | Sprint Target | Cut Impact | Status |
|
||||
|---------|-----------|-------|--------------|-----------|--------|
|
||||
|
||||
### Stretch Goals (Only if Ahead of Schedule)
|
||||
|
||||
| Feature | Design Doc | Owner | Value Add |
|
||||
|---------|-----------|-------|----------|
|
||||
|
||||
## Quality Gates
|
||||
|
||||
| Gate | Threshold | Measurement Method |
|
||||
|------|-----------|-------------------|
|
||||
| Crash rate | < [X] per hour | Automated crash reporting |
|
||||
| Frame rate | > [X] FPS on min spec | Performance profiling |
|
||||
| Load time | < [X] seconds | Automated timing |
|
||||
| Critical bugs | 0 open S1 | Bug tracker |
|
||||
| Major bugs | < [X] open S2 | Bug tracker |
|
||||
| Test coverage | > [X]% | Test framework report |
|
||||
|
||||
## Risk Register
|
||||
|
||||
| Risk | Probability | Impact | Mitigation | Owner | Status |
|
||||
|------|------------|--------|-----------|-------|--------|
|
||||
|
||||
## Dependencies
|
||||
|
||||
### Internal Dependencies
|
||||
|
||||
| Feature | Depends On | Owner of Dependency | Status |
|
||||
|---------|-----------|-------------------|--------|
|
||||
|
||||
### External Dependencies
|
||||
|
||||
| Dependency | Provider | Status | Risk if Delayed |
|
||||
|-----------|---------|--------|----------------|
|
||||
|
||||
## Review Schedule
|
||||
|
||||
| Date | Review Type | Attendees |
|
||||
|------|-----------|-----------|
|
||||
| [Week 2] | Early progress check | Producer, Directors |
|
||||
| [Midpoint] | Mid-milestone review | Full team |
|
||||
| [Week N-1] | Pre-milestone review | Full team |
|
||||
| [Target Date] | Milestone review | Full team |
|
||||
111
.claude/docs/templates/narrative-character-sheet.md
vendored
Normal file
111
.claude/docs/templates/narrative-character-sheet.md
vendored
Normal file
@@ -0,0 +1,111 @@
|
||||
# Character: [Name]
|
||||
|
||||
## Quick Reference
|
||||
|
||||
- **Full Name**: [Name]
|
||||
- **Role in Story**: [Protagonist / Antagonist / Ally / Mentor / etc.]
|
||||
- **Role in Gameplay**: [Playable / NPC / Boss / Merchant / Quest Giver / etc.]
|
||||
- **First Appearance**: [Level/Area/Quest]
|
||||
- **Status**: [Canon Level: Established / Provisional / Under Review]
|
||||
|
||||
## Concept
|
||||
|
||||
[One paragraph describing who this character is, what they want, and why the
|
||||
player should care about them.]
|
||||
|
||||
## Appearance
|
||||
|
||||
[Physical description sufficient for the art team to create concept art.
|
||||
Reference the art bible for style constraints.]
|
||||
|
||||
- **Build**: [Body type, height relative to player]
|
||||
- **Distinguishing Features**: [What makes them visually recognizable at a distance]
|
||||
- **Color Palette**: [Key colors associated with this character]
|
||||
- **Costume/Armor**: [What they wear and why it makes sense for them]
|
||||
|
||||
## Personality
|
||||
|
||||
### Core Traits
|
||||
|
||||
- [Trait 1 -- e.g., Loyal to a fault]
|
||||
- [Trait 2 -- e.g., Distrusts authority]
|
||||
- [Trait 3 -- e.g., Dark sense of humor]
|
||||
|
||||
### Voice Profile
|
||||
|
||||
- **Speech Pattern**: [Formal/casual, verbose/terse, accent/dialect notes]
|
||||
- **Vocabulary Level**: [Simple/educated/archaic/technical]
|
||||
- **Verbal Tics**: [Any recurring phrases or speech habits]
|
||||
- **Tone Reference**: [Reference character from another work, if helpful]
|
||||
|
||||
### Emotional Range
|
||||
|
||||
| Emotion | Trigger | Expression | Example Line |
|
||||
|---------|---------|-----------|-------------|
|
||||
|
||||
## Motivation and Arc
|
||||
|
||||
### Primary Motivation
|
||||
|
||||
[What does this character want more than anything? This drives every scene.]
|
||||
|
||||
### Character Arc
|
||||
|
||||
| Phase | State | Turning Point |
|
||||
|-------|-------|---------------|
|
||||
| Introduction | [Who they are when the player meets them] | [What event starts their arc] |
|
||||
| Development | [How they change through the middle] | [Key moment of growth/change] |
|
||||
| Resolution | [Who they become by the end] | [Final transformative event] |
|
||||
|
||||
### Internal Conflict
|
||||
|
||||
[What contradictory desires or beliefs create internal tension?]
|
||||
|
||||
## Relationships
|
||||
|
||||
| Character | Relationship | Dynamic | Player Can Affect? |
|
||||
|-----------|-------------|---------|-------------------|
|
||||
|
||||
## Gameplay Function
|
||||
|
||||
### What This Character Provides to the Player
|
||||
|
||||
- [Services: shop, training, quests, etc.]
|
||||
- [Information: lore, hints, quest objectives]
|
||||
- [Mechanical interactions: buffs, unlocks, gates]
|
||||
|
||||
### Encounter Design Notes
|
||||
|
||||
[If this character is fought as an enemy or boss, include combat design notes
|
||||
or reference the relevant combat design document.]
|
||||
|
||||
## Dialogue Notes
|
||||
|
||||
### Topics This Character Can Discuss
|
||||
|
||||
- [Topic 1 -- what they know and their perspective]
|
||||
- [Topic 2]
|
||||
|
||||
### Topics This Character Avoids or Lies About
|
||||
|
||||
- [Topic -- and why]
|
||||
|
||||
### Dialogue State Dependencies
|
||||
|
||||
[What game states affect this character's dialogue?]
|
||||
|
||||
| Game State | Dialogue Change |
|
||||
|-----------|----------------|
|
||||
|
||||
## Lore Connections
|
||||
|
||||
- [Connection to world history]
|
||||
- [Connection to factions]
|
||||
- [Connection to locations]
|
||||
|
||||
## Cross-References
|
||||
|
||||
- **Design Doc**: [Link to relevant gameplay design]
|
||||
- **Quest Doc**: [Link to quests involving this character]
|
||||
- **Art Reference**: [Link to concept art or art bible section]
|
||||
- **Audio Reference**: [Link to voice/theme direction]
|
||||
140
.claude/docs/templates/pitch-document.md
vendored
Normal file
140
.claude/docs/templates/pitch-document.md
vendored
Normal file
@@ -0,0 +1,140 @@
|
||||
# Game Pitch: [Title]
|
||||
|
||||
*Version: [Draft Number]*
|
||||
*Date: [Date]*
|
||||
|
||||
---
|
||||
|
||||
## The Hook
|
||||
|
||||
> [One powerful sentence. If someone reads nothing else, this should make them
|
||||
> curious.]
|
||||
|
||||
---
|
||||
|
||||
## What Is It?
|
||||
|
||||
[2-3 sentences expanding the hook into a clear picture. Genre, setting, core
|
||||
mechanic, and what makes it special.]
|
||||
|
||||
---
|
||||
|
||||
## Why Now?
|
||||
|
||||
[Why is this the right game at the right time? Market trends, audience gaps,
|
||||
technology enablers, cultural relevance.]
|
||||
|
||||
---
|
||||
|
||||
## Target Audience
|
||||
|
||||
**Primary**: [Who is the core audience? Be specific — not "gamers" but
|
||||
"roguelike fans who enjoy build-crafting and short sessions"]
|
||||
|
||||
**Secondary**: [Adjacent audience who would also enjoy this]
|
||||
|
||||
**Market Size**: [Estimated TAM based on comparable titles]
|
||||
|
||||
---
|
||||
|
||||
## Comparable Titles
|
||||
|
||||
| Title | Similarity | Our Differentiation | Commercial Performance |
|
||||
| ---- | ---- | ---- | ---- |
|
||||
| [Game 1] | [What's similar] | [What's different/better] | [Revenue/units if known] |
|
||||
| [Game 2] | [What's similar] | [What's different/better] | [Performance] |
|
||||
| [Game 3] | [What's similar] | [What's different/better] | [Performance] |
|
||||
|
||||
---
|
||||
|
||||
## Core Experience
|
||||
|
||||
### The Player Fantasy
|
||||
[What does the player get to BE or DO? The emotional promise.]
|
||||
|
||||
### Core Loop (30 seconds)
|
||||
[Describe the primary activity]
|
||||
|
||||
### Session Flow (30 minutes)
|
||||
[What does a typical session look like start to finish?]
|
||||
|
||||
### Progression Hook
|
||||
[Why do players come back tomorrow?]
|
||||
|
||||
---
|
||||
|
||||
## Key Features
|
||||
|
||||
1. **[Feature Name]**: [1-2 sentence description of what it is and why it
|
||||
matters to the player]
|
||||
2. **[Feature Name]**: [Description]
|
||||
3. **[Feature Name]**: [Description]
|
||||
4. **[Feature Name]**: [Description]
|
||||
5. **[Feature Name]**: [Description]
|
||||
|
||||
---
|
||||
|
||||
## Visual Identity
|
||||
|
||||
[Brief description of the art style, mood, and visual tone. Include reference
|
||||
images or mood board link if available.]
|
||||
|
||||
**Art Style**: [e.g., "Hand-painted 2D with dynamic lighting, inspired by
|
||||
Hollow Knight's atmosphere but with warmer colors"]
|
||||
|
||||
---
|
||||
|
||||
## Audio Identity
|
||||
|
||||
[Brief description of the sonic palette and musical direction.]
|
||||
|
||||
**Music**: [e.g., "Adaptive orchestral with folk instruments, shifting based
|
||||
on biome and combat intensity"]
|
||||
|
||||
**SFX**: [e.g., "Crunchy, satisfying impact sounds. Tactile feedback on every
|
||||
player action."]
|
||||
|
||||
---
|
||||
|
||||
## Business Model
|
||||
|
||||
| Aspect | Plan |
|
||||
| ---- | ---- |
|
||||
| **Model** | [Premium $X / F2P / etc.] |
|
||||
| **Platforms** | [Steam, Console, Mobile] |
|
||||
| **Price Point** | [$X.XX] |
|
||||
| **DLC/Expansion Plans** | [Post-launch content strategy] |
|
||||
| **Monetization Ethics** | [What we will and won't do] |
|
||||
|
||||
---
|
||||
|
||||
## Development Plan
|
||||
|
||||
| Milestone | Duration | Deliverable |
|
||||
| ---- | ---- | ---- |
|
||||
| Concept & Pre-production | [X weeks] | Game concept, pillars, vertical slice plan |
|
||||
| Vertical Slice | [X weeks] | Playable slice demonstrating core loop |
|
||||
| Alpha | [X weeks] | All features in, content placeholder |
|
||||
| Beta | [X weeks] | Content complete, polish pass |
|
||||
| Launch | [Date] | Release build |
|
||||
|
||||
**Team Size**: [X people, roles]
|
||||
**Engine**: [Godot / Unity / Unreal]
|
||||
**Estimated Budget**: [Range if applicable]
|
||||
|
||||
---
|
||||
|
||||
## Risks and Mitigation
|
||||
|
||||
| Risk | Likelihood | Impact | Mitigation |
|
||||
| ---- | ---- | ---- | ---- |
|
||||
| [Risk 1] | [H/M/L] | [H/M/L] | [How we handle it] |
|
||||
| [Risk 2] | [H/M/L] | [H/M/L] | [Mitigation] |
|
||||
| [Risk 3] | [H/M/L] | [H/M/L] | [Mitigation] |
|
||||
|
||||
---
|
||||
|
||||
## The Ask
|
||||
|
||||
[What do you need? Funding, publishing deal, team members, feedback? Be
|
||||
specific about what you're looking for and what you're offering in return.]
|
||||
357
.claude/docs/templates/player-journey.md
vendored
Normal file
357
.claude/docs/templates/player-journey.md
vendored
Normal file
@@ -0,0 +1,357 @@
|
||||
# Player Journey Map: [Game Title]
|
||||
|
||||
> **Status**: Draft | In Review | Approved
|
||||
> **Author**: [game-designer / creative-director]
|
||||
> **Last Updated**: [Date]
|
||||
> **Links To**: `design/gdd/game-concept.md`, `design/gdd/game-pillars.md`
|
||||
|
||||
---
|
||||
|
||||
## Journey Overview
|
||||
|
||||
[One paragraph capturing the full emotional arc from first launch to long-term
|
||||
play. This is the player's story, not the game's feature list. Describe the
|
||||
journey in emotional terms: where do they start (curious, skeptical, cautious),
|
||||
how does the relationship with the game deepen, what is the peak emotional
|
||||
experience, and what sustains them afterward?
|
||||
|
||||
Example: "The player arrives skeptical and slightly overwhelmed, is quickly
|
||||
disarmed by an early moment of unexpected delight, spends the middle hours
|
||||
discovering that the systems run deeper than they first appeared, and eventually
|
||||
reaches a state of confident mastery where they generate their own challenges and
|
||||
share their discoveries with others."
|
||||
|
||||
If this arc cannot be described in one paragraph, the emotional design is not
|
||||
yet clear enough — resolve that ambiguity before filling in the phases below.]
|
||||
|
||||
---
|
||||
|
||||
## Target Player Archetype
|
||||
|
||||
[3-4 lines describing the player's MINDSET and gaming literacy, not their
|
||||
demographics. Demographics answer "who are they" — this answers "how do they
|
||||
approach games."
|
||||
|
||||
Describe: What expectations do they carry from other games? How patient are
|
||||
they with systems that don't explain themselves? Do they read tooltips or ignore
|
||||
them? Do they lean into challenge or route around it? Are they here for a story,
|
||||
a power trip, a creative outlet, or a test of skill?
|
||||
|
||||
Example: "A player who has finished at least one other game in this genre and
|
||||
arrived with a specific hypothesis about what to expect. They are willing to
|
||||
invest 30+ minutes before judging the game, they read item descriptions, and they
|
||||
find emergent mastery more satisfying than scripted victories. They feel respected
|
||||
when the game trusts them to figure things out."]
|
||||
|
||||
---
|
||||
|
||||
## Journey Phases
|
||||
|
||||
> **Guidance**: The six phases below are the standard template. Not all phases
|
||||
> apply to all games. A short narrative game may not have Habitual Play or
|
||||
> Long-Term Engagement. A puzzle game may compress Orientation into First Contact.
|
||||
> Delete or merge phases that genuinely do not apply — do not fill them with
|
||||
> placeholder values to make the template look complete.
|
||||
|
||||
---
|
||||
|
||||
### Phase 1: First Contact (0-5 minutes)
|
||||
|
||||
**Emotional state on arrival**: [What is the player feeling before they touch
|
||||
the game? They may be skeptical (purchased on impulse), curious (followed
|
||||
recommendations), or expectant (been waiting for it). This state is your
|
||||
starting condition — your design must meet them there.]
|
||||
|
||||
**Primary question the player is asking**: [e.g., "Is this worth my time?",
|
||||
"Will this be too hard?", "Do I understand what I'm supposed to do?"]
|
||||
|
||||
**Key experience the game must deliver**:
|
||||
[What MUST happen in these five minutes for the player to stay? Not a tutorial
|
||||
beat — an emotional beat. The first contact experience should answer the player's
|
||||
primary question with a confident "yes." It may be a moment of beauty, a
|
||||
satisfying mechanical click, a surprising twist on a familiar genre pattern, or
|
||||
an early win that feels earned.]
|
||||
|
||||
**Emotional state on exit**: [What does success look like? e.g., "Curious
|
||||
about the next layer", "Surprised that this feels different from similar games",
|
||||
"Already thinking about a decision they made and whether it was right."]
|
||||
|
||||
**Risk if this phase fails**: [What does the player do? e.g., "Refund within
|
||||
the 2-hour Steam window", "Put it down and never return", "Post a negative
|
||||
first impression", "Recommend it to no one."]
|
||||
|
||||
---
|
||||
|
||||
### Phase 2: Orientation (5-30 minutes)
|
||||
|
||||
**Emotional state on arrival**: [Player is intrigued but not yet committed.
|
||||
They are forming their first mental model of what this game is.]
|
||||
|
||||
**Primary question the player is asking**: [e.g., "How does this actually work?",
|
||||
"What am I building toward?", "Am I going to be good at this?"]
|
||||
|
||||
**Key experience the game must deliver**:
|
||||
[This is the window where the player builds their foundational mental model.
|
||||
Describe the one or two "aha" moments that crystallize the game's identity.
|
||||
The player should feel competence growing — their predictions about the game
|
||||
should start coming true. They should also catch their first glimpse of depth:
|
||||
a system or interaction that hints "this goes further than I thought."]
|
||||
|
||||
**Emotional state on exit**: [e.g., "Has a working model of the core loop",
|
||||
"Has made at least one meaningful decision they care about the outcome of",
|
||||
"Feels the skill ceiling is higher than it first appeared."]
|
||||
|
||||
**Risk if this phase fails**: [e.g., "Player concludes the game is shallow",
|
||||
"Player feels lost and stops trying", "Player never forms a goal."]
|
||||
|
||||
---
|
||||
|
||||
### Phase 3: First Mastery (30 minutes - 2 hours)
|
||||
|
||||
**Emotional state on arrival**: [Player understands the basics and is testing
|
||||
the edges. They are actively trying to get better rather than just trying to
|
||||
understand.]
|
||||
|
||||
**Primary question the player is asking**: [e.g., "What's the right strategy?",
|
||||
"What's possible if I get good at this?", "What am I missing?"]
|
||||
|
||||
**Key experience the game must deliver**:
|
||||
[This is the phase where the player earns their first genuine skill victory —
|
||||
a moment where something that was hard becomes easy through their own growth,
|
||||
not through the game getting easier. It should feel like crossing a threshold.
|
||||
They should also discover their first piece of emergent depth: a system
|
||||
interaction, a build synergy, or a hidden mechanic that rewards curiosity.
|
||||
According to Csikszentmihalyi's flow model, challenge must scale here — introduce
|
||||
the first real test of the skills they've been building.]
|
||||
|
||||
**Emotional state on exit**: [e.g., "Proud of a specific decision or victory",
|
||||
"Has an opinion about what the 'right' way to play is (even if wrong)",
|
||||
"Has questions they want to answer in their next session."]
|
||||
|
||||
**Risk if this phase fails**: [e.g., "Player never reaches flow state and stops
|
||||
before the game gets interesting", "Player forms wrong mental model and blames
|
||||
the game when it breaks."]
|
||||
|
||||
---
|
||||
|
||||
### Phase 4: Depth Discovery (2-10 hours)
|
||||
|
||||
**Emotional state on arrival**: [Player has a working strategy and is starting
|
||||
to see its limits. They are ready to discover that there is more.]
|
||||
|
||||
**Primary question the player is asking**: [e.g., "Is there a better way?",
|
||||
"What am I missing that other players know?", "How deep does this actually go?"]
|
||||
|
||||
**Key experience the game must deliver**:
|
||||
[This is where the game's true depth must reveal itself. Players who reach this
|
||||
phase are your core audience — they have cleared the onboarding and proven their
|
||||
commitment. They should discover systems, combinations, or strategies that
|
||||
recontextualize everything they have done so far. The world should feel larger
|
||||
than the tutorial implied. This is also the phase where Bartle's Explorers find
|
||||
their reward: content and knowledge that only the curious find.
|
||||
|
||||
Design note: Depth Discovery is where many indie games fail silently. Players
|
||||
exhaust the visible content without ever finding the hidden depth. Audit every
|
||||
layer of depth in this window and confirm it is discoverable without a guide.]
|
||||
|
||||
**Emotional state on exit**: [e.g., "Has rebuilt their strategy from scratch
|
||||
at least once", "Can imagine multiple viable approaches to the same problem",
|
||||
"Has discovered at least one thing that surprised them."]
|
||||
|
||||
**Risk if this phase fails**: [e.g., "Player concludes they have 'finished'
|
||||
the game and feels mild disappointment", "Player recommends the game but says
|
||||
'it's a bit short.'"]
|
||||
|
||||
---
|
||||
|
||||
### Phase 5: Habitual Play (10-50 hours)
|
||||
|
||||
> *Note: Not applicable to short-form games (visual novels, short narrative
|
||||
> games, puzzle games with fixed content). Delete this phase if the game's
|
||||
> intended experience concludes before this timeframe.*
|
||||
|
||||
**Emotional state on arrival**: [Player considers themselves competent. The
|
||||
game has become part of their routine. They have a playstyle identity.]
|
||||
|
||||
**Primary question the player is asking**: [e.g., "What's my next goal?",
|
||||
"Can I beat my previous record?", "What haven't I tried yet?"]
|
||||
|
||||
**Key experience the game must deliver**:
|
||||
[Habitual play requires the game to offer goals beyond the tutorial narrative.
|
||||
The player generates their own challenges, pursues optional content, or begins
|
||||
competing (against the game, other players, or their own records). This phase
|
||||
sustains through Bartle's Achiever motivations: collection completion, mastery
|
||||
benchmarks, visible milestones. It also requires natural session endings that
|
||||
leave forward tension — the player should always stop with something unfinished
|
||||
that they want to return to.]
|
||||
|
||||
**Emotional state on exit**: [e.g., "Has a specific goal they are working toward
|
||||
across multiple sessions", "Considers themselves part of a community of people
|
||||
who play this game."]
|
||||
|
||||
**Risk if this phase fails**: [e.g., "Player churns after completing main content
|
||||
and never returns", "Game fails word-of-mouth because players don't develop
|
||||
strong opinions about it."]
|
||||
|
||||
---
|
||||
|
||||
### Phase 6: Long-Term Engagement (50+ hours)
|
||||
|
||||
> *Note: Only applies to games designed for extended play — live service games,
|
||||
> deeply systemic games, competitive games, and games with community-driven
|
||||
> content. Delete this phase if it does not fit the game's design intent.*
|
||||
|
||||
**Emotional state on arrival**: [Player is a veteran. The game is part of their
|
||||
identity to some degree. They are invested in the community and the ecosystem.]
|
||||
|
||||
**Primary question the player is asking**: [e.g., "What's new?", "Can I reach
|
||||
the top?", "Can I find something no one has found before?"]
|
||||
|
||||
**Key experience the game must deliver**:
|
||||
[Long-term engagement is sustained by different mechanisms than initial fun:
|
||||
social status, creative expression, competitive standing, or the role of expert
|
||||
and guide. Design for this phase by asking what role a veteran player wants to
|
||||
play in the ecosystem — not just what content they want to consume. Systems
|
||||
that enable knowledge transfer (guides, community sharing, mentorship) dramatically
|
||||
extend this phase.]
|
||||
|
||||
**Emotional state on exit**: [e.g., "Part of a community", "Considered an
|
||||
expert by newer players", "Invested in the game's ongoing development and direction."]
|
||||
|
||||
**Risk if this phase fails**: [e.g., "Veteran players leave and take their
|
||||
social influence with them, accelerating churn in the broader player base."]
|
||||
|
||||
---
|
||||
|
||||
## Critical Moments
|
||||
|
||||
> **Guidance**: These are specific, individual events — not phases — that
|
||||
> must land with precision. A critical moment is a single interaction, scene,
|
||||
> or beat that carries outsized emotional weight. Missing it (through bad UX,
|
||||
> poor timing, or weak feedback) can derail the entire journey. Identify 8-15
|
||||
> such moments across the game.
|
||||
|
||||
| Moment | Phase | Emotional Target | If It Fails |
|
||||
|--------|-------|-----------------|-------------|
|
||||
| [The first death] | [First Contact] | [Surprise followed by understanding — "I see what I did wrong"] | [Player feels the death was unfair and loses trust in the game's fairness] |
|
||||
| [The first big win] | [Orientation] | [Earned pride — "I figured that out myself"] | [Player feels the win was handed to them and undervalues it] |
|
||||
| [The first system discovery] | [First Mastery] | [Delight — "I didn't know you could do that"] | [Player misses it entirely and never discovers the depth] |
|
||||
| [The moment the world opens up] | [Depth Discovery] | [Awe followed by hunger — "How much more is there?"] | [Player feels underwhelmed and concludes they have seen everything] |
|
||||
| [The first endgame goal] | [Habitual Play] | [Renewed purpose — "Now I have something to work toward"] | [Player completes the main content and feels finished] |
|
||||
| [Add moment] | [Phase] | [Emotional target] | [Failure consequence] |
|
||||
|
||||
---
|
||||
|
||||
## Retention Hooks
|
||||
|
||||
> **Guidance**: Retention hooks are the specific mechanisms that pull the player
|
||||
> back to the next session. They operate at different time scales. A game with
|
||||
> only one hook type has a fragile retention loop. Strong games layer multiple
|
||||
> hook types, so players with different motivations all have a reason to return.
|
||||
>
|
||||
> Map each hook to the systems that deliver it — if a hook has no system behind
|
||||
> it, it is an aspiration, not a design.
|
||||
|
||||
| Hook Type | Hook Description | Systems That Deliver It |
|
||||
|-----------|-----------------|------------------------|
|
||||
| **Session Start** | [What draws the player in when they launch? e.g., "Unresolved choices from last session", "World state changed while they were away", "Daily reward waiting"] | [System names, e.g., "Persistent world state, save system, daily login reward"] |
|
||||
| **Session End** | [What feeling do they have as they close the game? e.g., "A goal just out of reach", "A question unanswered", "An upgrade ready to use next time"] | [e.g., "Progress bar at 90%, next-session unlock notification"] |
|
||||
| **Daily Return** | [What reason exists to play today vs. skipping a day? e.g., "Daily challenge", "Time-gated resource replenishment", "Limited-time event"] | [e.g., "Daily quest system, resource regen timers, event calendar"] |
|
||||
| **Long-Term** | [What provides purpose across weeks? e.g., "Season pass milestones", "Competitive ranking reset", "Community challenge goals"] | [e.g., "Ranked system, seasonal content, community events"] |
|
||||
|
||||
---
|
||||
|
||||
## Player Progression Feel
|
||||
|
||||
[Describe HOW the player should experience their progression — not the mechanical
|
||||
system (that belongs in GDDs), but the FEELING of growing.
|
||||
|
||||
Choose the primary progression feeling and describe what it should feel like in
|
||||
concrete emotional terms. Examples of distinct progression feelings:
|
||||
|
||||
- **Power growth**: "The player should feel increasingly dangerous. Early game
|
||||
combat should feel tense and measured; late game combat should feel effortless
|
||||
against common enemies, reserving challenge for elite encounters."
|
||||
- **World expansion**: "The player's sense of the world should grow outward.
|
||||
Each new area should make the map feel larger, not just longer."
|
||||
- **Story revelation**: "The player should feel like they are slowly assembling
|
||||
a picture. Early revelations should recontextualize what they have already seen."
|
||||
- **Skill improvement**: "The player should feel themselves getting sharper.
|
||||
Encounters they struggled with early should feel controlled by mid-game,
|
||||
not because they got more powerful, but because their decisions improved."
|
||||
- **Community status**: "The player should feel a growing sense of belonging and
|
||||
recognition within the player community as their knowledge deepens."
|
||||
|
||||
Answer: what is the primary progression feeling in this game, and what does it
|
||||
concretely look and feel like at the beginning, middle, and end of the journey?]
|
||||
|
||||
---
|
||||
|
||||
## Anti-Patterns to Avoid
|
||||
|
||||
> **Guidance**: Anti-patterns are recurring design mistakes that reliably
|
||||
> break the player journey. List the ones most relevant to this specific game
|
||||
> and how the design actively guards against them. Be specific — "avoid bad UX"
|
||||
> is not an anti-pattern, it is a platitude.
|
||||
|
||||
- **[Player feels punished for experimenting]**: [e.g., "The crafting system
|
||||
should never consume irreplaceable resources. All experiment costs must be
|
||||
recoverable within one session."]
|
||||
- **[Player loses progress with no explanation]**: [e.g., "All save points are
|
||||
visible before risky encounters. Progress loss must always be preceded by a
|
||||
warning the player could have noticed."]
|
||||
- **[Difficulty spike creates a wall, not a gate]**: [e.g., "When a player
|
||||
fails an encounter three times, the game surfaces a contextual hint. A wall
|
||||
stops progress; a gate requires the right key — make sure players know what
|
||||
key they need."]
|
||||
- **[Player reaches the content ceiling before the emotional arc completes]**:
|
||||
[e.g., "The game should never run out of content while the player still has
|
||||
unanswered questions about the world or their build."]
|
||||
- **[Mandatory systems are introduced too late to feel meaningful]**: [e.g.,
|
||||
"Any system the player must engage with in the late game must be introduced
|
||||
in an optional or low-stakes context earlier."]
|
||||
- **[Add anti-pattern specific to this game's design risks]**: [Description]
|
||||
|
||||
---
|
||||
|
||||
## Validation Questions
|
||||
|
||||
> **Guidance**: These are questions a playtester session facilitator asks
|
||||
> during or after a session to verify the journey is working as intended.
|
||||
> They are not yes/no questions — they probe the player's emotional experience
|
||||
> and surface gaps between design intent and player reality.
|
||||
|
||||
**First Contact (0-5 min)**
|
||||
- [ ] "Without looking at any menus or tooltips, what do you think this game is about?"
|
||||
- [ ] "What's the first thing you want to do next?"
|
||||
|
||||
**Orientation (5-30 min)**
|
||||
- [ ] "What does winning or succeeding look like to you right now?"
|
||||
- [ ] "Is there anything you feel like you should understand but don't?"
|
||||
|
||||
**First Mastery (30 min - 2 hrs)**
|
||||
- [ ] "What's the best decision you've made so far? Why did you make it?"
|
||||
- [ ] "What would you do differently if you started over?"
|
||||
|
||||
**Depth Discovery (2-10 hrs)**
|
||||
- [ ] "Has the game surprised you? When? How did it feel?"
|
||||
- [ ] "What questions do you have about systems you haven't fully explored?"
|
||||
|
||||
**Habitual Play (10-50 hrs)**
|
||||
- [ ] "What's your current goal? How long have you been working toward it?"
|
||||
- [ ] "Have you told anyone about this game? What did you say?"
|
||||
|
||||
**General (any phase)**
|
||||
- [ ] "If you had to stop playing right now, what would you be most eager to
|
||||
come back for?"
|
||||
- [ ] "Is there anything you feel the game is not letting you do that you want to do?"
|
||||
|
||||
---
|
||||
|
||||
## Open Questions
|
||||
|
||||
| Question | Owner | Deadline | Resolution |
|
||||
|----------|-------|----------|-----------|
|
||||
| [Does the Phase 1 hook work for players without prior genre experience?] | [game-designer] | [Date] | [Unresolved] |
|
||||
| [Is Phase 4 depth discoverable without external guides?] | [game-designer, ux-designer] | [Date] | [Unresolved] |
|
||||
| [Add question] | [Owner] | [Date] | [Resolution] |
|
||||
69
.claude/docs/templates/post-mortem.md
vendored
Normal file
69
.claude/docs/templates/post-mortem.md
vendored
Normal file
@@ -0,0 +1,69 @@
|
||||
# Post-Mortem: [Milestone/Project Name]
|
||||
|
||||
## Document Status
|
||||
- **Date**: [Date]
|
||||
- **Facilitator**: producer
|
||||
- **Participants**: [List of agents/people involved]
|
||||
- **Period Covered**: [Start date] to [End date]
|
||||
|
||||
## Summary
|
||||
[2-3 sentence summary of what this milestone/project accomplished]
|
||||
|
||||
## Goals vs Results
|
||||
|
||||
| Goal | Target | Result | Status |
|
||||
| ---- | ------ | ------ | ------ |
|
||||
| [Goal 1] | [Metric] | [Actual] | [Met / Partially / Missed] |
|
||||
|
||||
## Timeline
|
||||
|
||||
| Date | Event | Impact |
|
||||
| ---- | ----- | ------ |
|
||||
| [Date] | [What happened] | [How it affected the project] |
|
||||
|
||||
## What Went Well
|
||||
|
||||
### [Category 1: e.g., Technical Execution]
|
||||
**What**: [Description]
|
||||
**Why it worked**: [Root cause of success]
|
||||
**How to repeat**: [What to keep doing]
|
||||
|
||||
### [Category 2: e.g., Team Coordination]
|
||||
**What**: [Description]
|
||||
**Why it worked**: [Root cause]
|
||||
**How to repeat**: [Action]
|
||||
|
||||
## What Went Poorly
|
||||
|
||||
### [Category 1: e.g., Scope Management]
|
||||
**What**: [Description]
|
||||
**Root cause**: [Why this happened]
|
||||
**Impact**: [Time/quality/morale cost]
|
||||
**Prevention**: [How to avoid next time]
|
||||
|
||||
### [Category 2]
|
||||
[Same structure]
|
||||
|
||||
## Key Metrics
|
||||
|
||||
| Metric | Target | Actual | Notes |
|
||||
| ------ | ------ | ------ | ----- |
|
||||
| Tasks completed | [N] | [N] | |
|
||||
| Bugs found | — | [N] | |
|
||||
| Bugs fixed | — | [N] | |
|
||||
| Estimation accuracy | 100% | [N%] | |
|
||||
| Scope changes | 0 | [N] | |
|
||||
|
||||
## Lessons Learned
|
||||
|
||||
1. **[Lesson]**: [Explanation and how it changes future work]
|
||||
2. **[Lesson]**: [Explanation]
|
||||
|
||||
## Action Items
|
||||
|
||||
| # | Action | Owner | Deadline | Status |
|
||||
| - | ------ | ----- | -------- | ------ |
|
||||
| 1 | [Action] | [Who] | [When] | [Open/Done] |
|
||||
|
||||
## Acknowledgments
|
||||
[Call out exceptional contributions]
|
||||
199
.claude/docs/templates/project-stage-report.md
vendored
Normal file
199
.claude/docs/templates/project-stage-report.md
vendored
Normal file
@@ -0,0 +1,199 @@
|
||||
# Project Stage Analysis Report
|
||||
|
||||
**Generated**: [DATE]
|
||||
**Stage**: [Concept | Systems Design | Technical Setup | Pre-Production | Production | Polish | Release]
|
||||
**Analysis Scope**: [Full project | Specific role: programmer/designer/producer]
|
||||
|
||||
---
|
||||
|
||||
## Executive Summary
|
||||
|
||||
[1-2 paragraph overview of project state, primary gaps, and recommended priority]
|
||||
|
||||
**Current Focus**: [What the project is actively working on]
|
||||
**Blocking Issues**: [Critical gaps preventing progress]
|
||||
**Estimated Time to Next Stage**: [If applicable]
|
||||
|
||||
---
|
||||
|
||||
## Completeness Overview
|
||||
|
||||
### Design Documentation
|
||||
- **Status**: [X%] complete
|
||||
- **Files Found**: [N] documents in `design/`
|
||||
- GDD sections: [N] files in `design/gdd/`
|
||||
- Narrative docs: [N] files in `design/narrative/`
|
||||
- Level designs: [N] files in `design/levels/`
|
||||
- **Key Gaps**:
|
||||
- [ ] [Missing doc 1 + why it matters]
|
||||
- [ ] [Missing doc 2 + why it matters]
|
||||
|
||||
### Source Code
|
||||
- **Status**: [X%] complete
|
||||
- **Files Found**: [N] source files in `src/`
|
||||
- **Major Systems Identified**:
|
||||
- ✅ [System 1] (`src/path/`) — [brief status]
|
||||
- ✅ [System 2] (`src/path/`) — [brief status]
|
||||
- ⚠️ [System 3] (`src/path/`) — [issue or incomplete]
|
||||
- **Key Gaps**:
|
||||
- [ ] [Missing system 1 + impact]
|
||||
- [ ] [Missing system 2 + impact]
|
||||
|
||||
### Architecture Documentation
|
||||
- **Status**: [X%] complete
|
||||
- **ADRs Found**: [N] decisions documented in `docs/architecture/`
|
||||
- **Coverage**:
|
||||
- ✅ [Decision area 1] — documented
|
||||
- ⚠️ [Decision area 2] — undocumented but implemented
|
||||
- ❌ [Decision area 3] — neither documented nor decided
|
||||
- **Key Gaps**:
|
||||
- [ ] [Missing ADR 1 + why it's needed]
|
||||
- [ ] [Missing ADR 2 + why it's needed]
|
||||
|
||||
### Production Management
|
||||
- **Status**: [X%] complete
|
||||
- **Found**:
|
||||
- Sprint plans: [N] in `production/sprints/`
|
||||
- Milestones: [N] in `production/milestones/`
|
||||
- Roadmap: [Exists | Missing]
|
||||
- **Key Gaps**:
|
||||
- [ ] [Missing production artifact + impact]
|
||||
|
||||
### Testing
|
||||
- **Status**: [X%] coverage (estimated)
|
||||
- **Test Files**: [N] in `tests/`
|
||||
- **Coverage by System**:
|
||||
- [System 1]: [X%] (estimated)
|
||||
- [System 2]: [X%] (estimated)
|
||||
- **Key Gaps**:
|
||||
- [ ] [Missing test area + risk]
|
||||
|
||||
### Prototypes
|
||||
- **Active Prototypes**: [N] in `prototypes/`
|
||||
- ✅ [Prototype 1] — documented with README
|
||||
- ⚠️ [Prototype 2] — no README, unclear status
|
||||
- **Archived**: [N] (experiments completed)
|
||||
- **Key Gaps**:
|
||||
- [ ] [Undocumented prototype + why it matters]
|
||||
|
||||
---
|
||||
|
||||
## Stage Classification Rationale
|
||||
|
||||
**Why [Stage]?**
|
||||
|
||||
[Explain why the project is classified at this stage based on indicators found]
|
||||
|
||||
**Indicators for this stage**:
|
||||
- [Indicator 1 that matches this stage]
|
||||
- [Indicator 2 that matches this stage]
|
||||
|
||||
**Next stage requirements**:
|
||||
- [ ] [Requirement 1 to reach next stage]
|
||||
- [ ] [Requirement 2 to reach next stage]
|
||||
- [ ] [Requirement 3 to reach next stage]
|
||||
|
||||
---
|
||||
|
||||
## Gaps Identified (with Clarifying Questions)
|
||||
|
||||
### Critical Gaps (block progress)
|
||||
|
||||
1. **[Gap Name]**
|
||||
- **Impact**: [Why this blocks progress]
|
||||
- **Question**: [Clarifying question before assuming solution]
|
||||
- **Suggested Action**: [What could be done, pending clarification]
|
||||
|
||||
### Important Gaps (affect quality/velocity)
|
||||
|
||||
2. **[Gap Name]**
|
||||
- **Impact**: [Why this matters]
|
||||
- **Question**: [Clarifying question]
|
||||
- **Suggested Action**: [Proposed solution]
|
||||
|
||||
### Nice-to-Have Gaps (polish/best practices)
|
||||
|
||||
3. **[Gap Name]**
|
||||
- **Impact**: [Minor but valuable]
|
||||
- **Question**: [Clarifying question]
|
||||
- **Suggested Action**: [Optional improvement]
|
||||
|
||||
---
|
||||
|
||||
## Recommended Next Steps
|
||||
|
||||
### Immediate Priority (Do First)
|
||||
1. **[Action 1]** — [Why it's priority 1]
|
||||
- Suggested skill: `/[skill-name]` or manual work
|
||||
- Estimated effort: [S/M/L]
|
||||
|
||||
2. **[Action 2]** — [Why it's priority 2]
|
||||
- Suggested skill: `/[skill-name]`
|
||||
- Estimated effort: [S/M/L]
|
||||
|
||||
### Short-Term (This Sprint/Week)
|
||||
3. **[Action 3]** — [Why it's important soon]
|
||||
4. **[Action 4]** — [Why it's important soon]
|
||||
|
||||
### Medium-Term (Next Milestone)
|
||||
5. **[Action 5]** — [Future need]
|
||||
6. **[Action 6]** — [Future need]
|
||||
|
||||
---
|
||||
|
||||
## Role-Specific Recommendations
|
||||
|
||||
[If role filter was used, provide role-specific guidance]
|
||||
|
||||
### For [Role]:
|
||||
- **Focus areas**: [What this role should prioritize]
|
||||
- **Blockers**: [What's blocking this role's work]
|
||||
- **Next tasks**:
|
||||
1. [Task 1]
|
||||
2. [Task 2]
|
||||
|
||||
---
|
||||
|
||||
## Follow-Up Skills to Run
|
||||
|
||||
Based on gaps identified, consider running:
|
||||
|
||||
- `/reverse-document [type] [path]` — [For which gap]
|
||||
- `/architecture-decision` — [For which gap]
|
||||
- `/sprint-plan` — [If production planning missing]
|
||||
- `/milestone-review` — [If approaching deadline]
|
||||
- `/onboard [role]` — [If new contributor joining]
|
||||
|
||||
---
|
||||
|
||||
## Appendix: File Counts by Directory
|
||||
|
||||
```
|
||||
design/
|
||||
gdd/ [N] files
|
||||
narrative/ [N] files
|
||||
levels/ [N] files
|
||||
|
||||
src/
|
||||
core/ [N] files
|
||||
gameplay/ [N] files
|
||||
ai/ [N] files
|
||||
networking/ [N] files
|
||||
ui/ [N] files
|
||||
|
||||
docs/
|
||||
architecture/ [N] ADRs
|
||||
|
||||
production/
|
||||
sprints/ [N] plans
|
||||
milestones/ [N] definitions
|
||||
|
||||
tests/ [N] test files
|
||||
prototypes/ [N] directories
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**End of Report**
|
||||
|
||||
*Generated by `/project-stage-detect` skill*
|
||||
114
.claude/docs/templates/prototype-report.md
vendored
Normal file
114
.claude/docs/templates/prototype-report.md
vendored
Normal file
@@ -0,0 +1,114 @@
|
||||
# Concept Prototype Report: [Concept Name]
|
||||
|
||||
> **Date**: [YYYY-MM-DD]
|
||||
> **Prototype Path**: [HTML / Engine / Paper]
|
||||
> **Concept File**: design/gdd/game-concept.md (if exists)
|
||||
|
||||
---
|
||||
|
||||
## Hypothesis
|
||||
|
||||
[The falsifiable hypothesis this prototype set out to test:
|
||||
"If the player [does X], they will feel [Y] — evidenced by [measurable signal Z]."]
|
||||
|
||||
---
|
||||
|
||||
## Riskiest Assumption Tested
|
||||
|
||||
[What was identified as the biggest risk in the concept, and whether it proved out.]
|
||||
|
||||
---
|
||||
|
||||
## Approach
|
||||
|
||||
[What was built, how long it took, what shortcuts were taken deliberately.]
|
||||
|
||||
**Path chosen:** [HTML / Engine / Paper]
|
||||
**Reason for path:** [Why this path was appropriate for this hypothesis]
|
||||
|
||||
**Shortcuts taken (intentional):**
|
||||
- [e.g., hardcoded values, placeholder art, no menus, etc.]
|
||||
|
||||
---
|
||||
|
||||
## Result
|
||||
|
||||
[What actually happened — specific observations, not opinions. Quote playtesters
|
||||
directly where possible.]
|
||||
|
||||
---
|
||||
|
||||
## Metrics
|
||||
|
||||
| Metric | Value |
|
||||
|--------|-------|
|
||||
| Path used | [HTML / Engine / Paper] |
|
||||
| Iterations to playable | [N — Engine path only; N/A otherwise] |
|
||||
| Prototype duration | [e.g., 4 hours] |
|
||||
| Playtesters | [N internal / N external] |
|
||||
| Feel assessment | [Specific — "response felt sluggish at 200ms" not "felt bad"] |
|
||||
| Hypothesis verdict | [CONFIRMED / PARTIALLY CONFIRMED / REFUTED] |
|
||||
|
||||
---
|
||||
|
||||
## Recommendation: [PROCEED / PIVOT / KILL]
|
||||
|
||||
[One paragraph explaining the recommendation with evidence from the result above.]
|
||||
|
||||
---
|
||||
|
||||
## If Proceeding
|
||||
|
||||
[What the prototype revealed that should directly inform GDD writing:]
|
||||
|
||||
- **Core tuning values discovered:** [e.g., "jump height of 3.5 units felt best"]
|
||||
- **Assumptions confirmed:** [What the concept doc assumed that proved true]
|
||||
- **Assumptions disproved:** [What the concept doc assumed that proved wrong]
|
||||
- **Emergent mechanics:** [Behaviors that appeared during testing worth formalizing]
|
||||
|
||||
> Note: If HTML path was used and feel is uncertain, consider an engine prototype
|
||||
> targeting feel specifically before committing to GDDs.
|
||||
|
||||
**Next steps:**
|
||||
1. `/design-review design/gdd/game-concept.md`
|
||||
2. `/gate-check`
|
||||
3. `/map-systems`
|
||||
4. `/design-system [mechanic]` (use learnings in Tuning Knobs and Formulas sections)
|
||||
|
||||
---
|
||||
|
||||
## If Pivoting
|
||||
|
||||
[What alternative direction the results suggest — what felt almost right and what
|
||||
to adjust. Be specific about what to change, not just that something needs changing.]
|
||||
|
||||
**Pivot direction:** [What to try differently]
|
||||
**What to keep:** [What worked and should be preserved]
|
||||
**Next step:** `/prototype [revised-concept]`
|
||||
|
||||
---
|
||||
|
||||
## If Killing
|
||||
|
||||
[Why this concept does not work — what specific signal led to this verdict.
|
||||
This report is the deliverable; no further action needed on this concept.]
|
||||
|
||||
**Next step:** `/brainstorm [new-direction]`
|
||||
|
||||
---
|
||||
|
||||
## Lessons Learned
|
||||
|
||||
- **What assumptions were broken by actually building this?**
|
||||
[...]
|
||||
|
||||
- **What surprised us that didn't show up in the brainstorm?**
|
||||
[...]
|
||||
|
||||
- **What would we test differently next time?**
|
||||
[...]
|
||||
|
||||
---
|
||||
|
||||
> *Prototype code location: `prototypes/[concept-name]-concept/`*
|
||||
> *This code is throwaway. Never refactor into production.*
|
||||
125
.claude/docs/templates/release-checklist-template.md
vendored
Normal file
125
.claude/docs/templates/release-checklist-template.md
vendored
Normal file
@@ -0,0 +1,125 @@
|
||||
# Release Checklist: [Version] -- [Platform]
|
||||
|
||||
**Release Date**: [Target Date]
|
||||
**Release Manager**: [Name]
|
||||
**Status**: [ ] GO / [ ] NO-GO
|
||||
|
||||
---
|
||||
|
||||
## Build Verification
|
||||
|
||||
- [ ] Clean build succeeds on all target platforms
|
||||
- [ ] No compiler warnings (zero-warning policy)
|
||||
- [ ] Build version number set correctly: `[version]`
|
||||
- [ ] Build is reproducible from tagged commit: `[commit hash]`
|
||||
- [ ] Build size within budget: [actual] / [budget]
|
||||
- [ ] All assets included and loading correctly
|
||||
- [ ] No debug/development features enabled in release build
|
||||
|
||||
---
|
||||
|
||||
## Quality Gates
|
||||
|
||||
### Critical Bugs
|
||||
- [ ] Zero S1 (Critical) bugs open
|
||||
- [ ] Zero S2 (Major) bugs -- or documented exceptions below:
|
||||
|
||||
| Bug ID | Description | Exception Rationale | Approved By |
|
||||
| ---- | ---- | ---- | ---- |
|
||||
| | | | |
|
||||
|
||||
### Test Coverage
|
||||
- [ ] All critical path features tested and signed off
|
||||
- [ ] Full regression suite passed: [pass rate]%
|
||||
- [ ] Soak test passed (4+ hours continuous play)
|
||||
- [ ] Edge case testing complete
|
||||
|
||||
### Performance
|
||||
- [ ] Target FPS met on minimum spec: [actual] / [target] FPS
|
||||
- [ ] Memory usage within budget: [actual] / [budget] MB
|
||||
- [ ] Load times within budget: [actual] / [target] seconds
|
||||
- [ ] No memory leaks over extended play (soak test)
|
||||
- [ ] No frame drops below [threshold] in normal gameplay
|
||||
|
||||
---
|
||||
|
||||
## Content Complete
|
||||
|
||||
- [ ] All placeholder assets replaced with final versions
|
||||
- [ ] All player-facing text proofread
|
||||
- [ ] All text localization-ready (no hardcoded strings)
|
||||
- [ ] Localization complete for: [list locales]
|
||||
- [ ] Audio mix finalized and approved
|
||||
- [ ] Credits complete and accurate
|
||||
- [ ] Legal notices and third-party attributions complete
|
||||
|
||||
---
|
||||
|
||||
## Platform: PC
|
||||
|
||||
- [ ] Minimum and recommended specs documented
|
||||
- [ ] Keyboard+mouse controls fully functional
|
||||
- [ ] Controller support tested (Xbox, PlayStation, generic)
|
||||
- [ ] Resolution scaling tested: 1080p, 1440p, 4K, ultrawide
|
||||
- [ ] Windowed, borderless, fullscreen modes working
|
||||
- [ ] Graphics settings save and load correctly
|
||||
- [ ] Store SDK integrated and tested: [Steam/Epic/GOG]
|
||||
- [ ] Achievements functional
|
||||
- [ ] Cloud saves functional
|
||||
|
||||
## Platform: Console (if applicable)
|
||||
|
||||
- [ ] TRC/TCR/Lotcheck requirements met
|
||||
- [ ] Platform controller prompts correct
|
||||
- [ ] Suspend/resume works
|
||||
- [ ] User switching handled
|
||||
- [ ] Network loss handled gracefully
|
||||
- [ ] Storage full scenario handled
|
||||
- [ ] Parental controls respected
|
||||
- [ ] Certification submission prepared
|
||||
|
||||
---
|
||||
|
||||
## Store and Distribution
|
||||
|
||||
- [ ] Store page metadata complete and proofread
|
||||
- [ ] Screenshots current and meet platform requirements
|
||||
- [ ] Trailer current
|
||||
- [ ] Key art and capsule images final
|
||||
- [ ] Age ratings obtained: [ ] ESRB [ ] PEGI [ ] Other
|
||||
- [ ] Legal: EULA, Privacy Policy, Terms of Service
|
||||
- [ ] Pricing configured for all regions
|
||||
|
||||
---
|
||||
|
||||
## Launch Readiness
|
||||
|
||||
- [ ] Analytics/telemetry verified and receiving data
|
||||
- [ ] Crash reporting configured: [service name]
|
||||
- [ ] Day-one patch prepared (if needed)
|
||||
- [ ] On-call team schedule set for first 72 hours
|
||||
- [ ] Community announcements drafted
|
||||
- [ ] Press/influencer keys prepared
|
||||
- [ ] Support team briefed on known issues
|
||||
- [ ] Rollback plan documented and tested
|
||||
|
||||
---
|
||||
|
||||
## Sign-offs
|
||||
|
||||
| Role | Name | Status | Date |
|
||||
| ---- | ---- | ---- | ---- |
|
||||
| QA Lead | | [ ] Approved | |
|
||||
| Technical Director | | [ ] Approved | |
|
||||
| Producer | | [ ] Approved | |
|
||||
| Creative Director | | [ ] Approved | |
|
||||
|
||||
---
|
||||
|
||||
## Final Decision
|
||||
|
||||
**GO / NO-GO**: ____________
|
||||
|
||||
**Rationale**: [Summary of readiness. If NO-GO, list specific blocking items and estimated time to resolve.]
|
||||
|
||||
**Notes**: [Any additional context, known risks accepted, or conditions on the release.]
|
||||
103
.claude/docs/templates/release-notes.md
vendored
Normal file
103
.claude/docs/templates/release-notes.md
vendored
Normal file
@@ -0,0 +1,103 @@
|
||||
# Release Notes: [Game Title] v[Version]
|
||||
|
||||
*Released: [Date]*
|
||||
|
||||
---
|
||||
|
||||
## Headline
|
||||
|
||||
> [One compelling sentence summarizing the most exciting part of this release.
|
||||
> This is what appears in store update notifications and social media.]
|
||||
|
||||
---
|
||||
|
||||
## What's New
|
||||
|
||||
### [Major Feature 1 Name]
|
||||
[2-4 sentences describing the feature. Focus on what players can DO, not
|
||||
how it works internally. Include a screenshot or GIF reference if applicable.]
|
||||
|
||||
### [Major Feature 2 Name]
|
||||
[Description]
|
||||
|
||||
---
|
||||
|
||||
## Gameplay Changes
|
||||
|
||||
### Balance Adjustments
|
||||
|
||||
| Target | Change | Before | After | Context |
|
||||
| ---- | ---- | ---- | ---- | ---- |
|
||||
| [Weapon/Ability/Item] | [What changed] | [Old value] | [New value] | [Why — 1 sentence] |
|
||||
| | | | | |
|
||||
|
||||
### Mechanic Changes
|
||||
- **[Change Name]**: [What changed and how it affects gameplay. Be specific
|
||||
about what players will experience differently.]
|
||||
|
||||
---
|
||||
|
||||
## Quality of Life
|
||||
|
||||
- [Improvement 1 — describe the player benefit, not the technical change]
|
||||
- [Improvement 2]
|
||||
- [Improvement 3]
|
||||
|
||||
---
|
||||
|
||||
## Bug Fixes
|
||||
|
||||
### Critical Fixes
|
||||
- Fixed [describe what players experienced, e.g., "a crash when loading
|
||||
saved games from version 1.0"]
|
||||
|
||||
### Gameplay Fixes
|
||||
- Fixed [describe the incorrect behavior and the correct behavior now]
|
||||
|
||||
### UI Fixes
|
||||
- Fixed [description]
|
||||
|
||||
### Audio Fixes
|
||||
- Fixed [description]
|
||||
|
||||
### Platform-Specific Fixes
|
||||
- **[Platform]**: Fixed [description]
|
||||
|
||||
---
|
||||
|
||||
## Performance Improvements
|
||||
|
||||
- [Improvement players will notice, e.g., "Reduced load times by approximately
|
||||
30% on all platforms"]
|
||||
- [Improvement]
|
||||
|
||||
---
|
||||
|
||||
## Known Issues
|
||||
|
||||
We are aware of the following issues and are working on fixes for a future update:
|
||||
|
||||
- **[Issue]**: [Brief description and workaround if available]
|
||||
- **[Issue]**: [Description]
|
||||
|
||||
---
|
||||
|
||||
## Coming Next
|
||||
|
||||
[Optional — tease upcoming content to build anticipation. Keep it vague enough
|
||||
to not create binding commitments.]
|
||||
|
||||
> [1-2 sentences about what the team is working on next]
|
||||
|
||||
---
|
||||
|
||||
## Thank You
|
||||
|
||||
[Brief message thanking the community. Reference specific community feedback
|
||||
that influenced changes in this release if applicable.]
|
||||
|
||||
---
|
||||
|
||||
*For the full changelog with technical details, see the [developer changelog](link).*
|
||||
*Report bugs: [link to bug report channel/form]*
|
||||
*Join the community: [link to Discord/forum]*
|
||||
58
.claude/docs/templates/risk-register-entry.md
vendored
Normal file
58
.claude/docs/templates/risk-register-entry.md
vendored
Normal file
@@ -0,0 +1,58 @@
|
||||
# Risk: [Short Title]
|
||||
|
||||
## Identification
|
||||
|
||||
- **ID**: RISK-[NNNN]
|
||||
- **Identified By**: [Agent or person]
|
||||
- **Date Identified**: [Date]
|
||||
- **Category**: [Technical | Design | Schedule | Resource | External | Quality]
|
||||
|
||||
## Assessment
|
||||
|
||||
- **Probability**: [Very Low | Low | Medium | High | Very High]
|
||||
- **Impact**: [Minimal | Minor | Moderate | Major | Critical]
|
||||
- **Risk Score**: [Probability x Impact = Low / Medium / High / Critical]
|
||||
|
||||
## Description
|
||||
|
||||
[Detailed description of the risk. What could go wrong? Under what conditions?]
|
||||
|
||||
## Trigger Conditions
|
||||
|
||||
[What observable conditions would indicate this risk is materializing?]
|
||||
|
||||
- [Condition 1]
|
||||
- [Condition 2]
|
||||
|
||||
## Impact Analysis
|
||||
|
||||
### If This Risk Materializes
|
||||
|
||||
- **Schedule Impact**: [How many days/weeks of delay]
|
||||
- **Quality Impact**: [What quality degradation]
|
||||
- **Scope Impact**: [What features affected]
|
||||
- **Cost Impact**: [Resource cost of dealing with it]
|
||||
|
||||
### Affected Systems/Features
|
||||
|
||||
- [System 1]
|
||||
- [System 2]
|
||||
|
||||
## Mitigation Strategy
|
||||
|
||||
### Prevention (reduce probability)
|
||||
|
||||
- [Action to prevent this risk from occurring]
|
||||
- [Owner and deadline for prevention action]
|
||||
|
||||
### Contingency (reduce impact if it occurs)
|
||||
|
||||
- [Action to take if this risk materializes]
|
||||
- [Owner responsible for contingency execution]
|
||||
|
||||
## Current Status
|
||||
|
||||
- **Status**: [Open | Mitigating | Occurred | Closed]
|
||||
- **Last Reviewed**: [Date]
|
||||
- **Trend**: [Increasing | Stable | Decreasing]
|
||||
- **Notes**: [Any updates]
|
||||
96
.claude/docs/templates/skill-test-spec.md
vendored
Normal file
96
.claude/docs/templates/skill-test-spec.md
vendored
Normal file
@@ -0,0 +1,96 @@
|
||||
# Skill Test Spec: /[skill-name]
|
||||
|
||||
## Skill Summary
|
||||
|
||||
[One paragraph: what this skill does, when to use it, what it produces. Include
|
||||
the primary output artifact, the verdict format it uses, and which pipeline stage
|
||||
it belongs to.]
|
||||
|
||||
---
|
||||
|
||||
## Static Assertions (Structural)
|
||||
|
||||
Verified automatically by `/skill-test static` — no fixture needed.
|
||||
|
||||
- [ ] Has required frontmatter fields: `name`, `description`, `argument-hint`, `user-invocable`, `allowed-tools`
|
||||
- [ ] Has ≥2 phase headings (## Phase N or numbered ## sections)
|
||||
- [ ] Contains verdict keywords: [list the ones expected, e.g., PASS, FAIL, CONCERNS]
|
||||
- [ ] Contains "May I write" collaborative protocol language (if skill writes files)
|
||||
- [ ] Has a next-step handoff at the end
|
||||
|
||||
---
|
||||
|
||||
## Test Cases
|
||||
|
||||
### Case 1: Happy Path — [short description]
|
||||
|
||||
**Fixture:** [Describe the assumed project state. Which files exist? What do they
|
||||
contain? E.g., "game-concept.md exists with all 8 required sections complete.
|
||||
systems-index.md exists. All MVP GDDs are present and individually reviewed."]
|
||||
|
||||
**Input:** `/[skill-name] [args]`
|
||||
|
||||
**Expected behavior:**
|
||||
1. [Phase 1 action — what the skill should read or check]
|
||||
2. [Phase 2 action — what the skill should evaluate]
|
||||
3. [Phase N action — what the skill should output]
|
||||
|
||||
**Assertions:**
|
||||
- [ ] Skill reads [specific file] before producing output
|
||||
- [ ] Output includes verdict keyword [PASS/FAIL/etc.]
|
||||
- [ ] Output lists [specific content] from the fixture
|
||||
- [ ] Skill asks for approval before writing any file
|
||||
|
||||
---
|
||||
|
||||
### Case 2: Failure Path — [short description, e.g., "Missing required artifact"]
|
||||
|
||||
**Fixture:** [Describe the failure state. E.g., "game-concept.md is missing.
|
||||
No files exist in design/gdd/."]
|
||||
|
||||
**Input:** `/[skill-name] [args]`
|
||||
|
||||
**Expected behavior:**
|
||||
1. [Phase 1: skill detects missing file]
|
||||
2. [Phase 2: skill surfaces the gap rather than assuming OK]
|
||||
3. [Output: FAIL or BLOCKED verdict with specific blocker named]
|
||||
|
||||
**Assertions:**
|
||||
- [ ] Skill does NOT output PASS when the fixture is incomplete
|
||||
- [ ] Skill names the specific missing artifact
|
||||
- [ ] Skill suggests a remediation action (e.g., "Run /[other-skill]")
|
||||
- [ ] Skill does not create files to fill in the gap without asking
|
||||
|
||||
---
|
||||
|
||||
### Case 3: Edge Case — [short description, e.g., "No argument provided"]
|
||||
|
||||
**Fixture:** [State of project files for this case]
|
||||
|
||||
**Input:** `/[skill-name]` (no argument)
|
||||
|
||||
**Expected behavior:**
|
||||
1. [What the skill should do when invoked without arguments]
|
||||
|
||||
**Assertions:**
|
||||
- [ ] [assertion]
|
||||
|
||||
---
|
||||
|
||||
## Protocol Compliance
|
||||
|
||||
- [ ] Uses "May I write" before all file writes
|
||||
- [ ] Presents findings or report before asking for write approval
|
||||
- [ ] Ends with a recommended next step or follow-up skill
|
||||
- [ ] Never auto-creates files without explicit user approval
|
||||
- [ ] Does not skip phases or jump straight to a verdict without checking
|
||||
|
||||
---
|
||||
|
||||
## Coverage Notes
|
||||
|
||||
[Document what is intentionally NOT tested in this spec and why. Examples:
|
||||
- "Case 3 (all-mode) is not covered because it runs too many checks to evaluate
|
||||
in a single spec — test each sub-mode individually."
|
||||
- "The database integration path is not covered as it requires a live environment."
|
||||
- "Edge cases involving corrupted YAML files are deferred to a future spec."]
|
||||
130
.claude/docs/templates/sound-bible.md
vendored
Normal file
130
.claude/docs/templates/sound-bible.md
vendored
Normal file
@@ -0,0 +1,130 @@
|
||||
# Sound Bible: [Project Name]
|
||||
|
||||
## Audio Vision
|
||||
|
||||
### Sonic Identity
|
||||
[Describe the overall audio personality of the game in 2-3 sentences. What does the game "sound like"? What emotions should the audio evoke?]
|
||||
|
||||
### Audio Pillars
|
||||
1. **[Pillar 1]**: [How this pillar manifests in audio]
|
||||
2. **[Pillar 2]**: [How this pillar manifests in audio]
|
||||
3. **[Pillar 3]**: [How this pillar manifests in audio]
|
||||
|
||||
### Reference Games / Media
|
||||
| Reference | What to Take From It | What to Avoid |
|
||||
| ---- | ---- | ---- |
|
||||
| [Game/Film 1] | [Specific audio quality to emulate] | [What doesn't fit our vision] |
|
||||
| [Game/Film 2] | [Specific audio quality to emulate] | [What doesn't fit our vision] |
|
||||
|
||||
---
|
||||
|
||||
## Music Direction
|
||||
|
||||
### Style and Genre
|
||||
[Primary musical style, instrumentation palette, tempo ranges]
|
||||
|
||||
### Instrumentation Palette
|
||||
- **Core instruments**: [List the primary instruments/synths that define the sound]
|
||||
- **Accent instruments**: [Used for emphasis, transitions, special moments]
|
||||
- **Avoid**: [Instruments or styles that do NOT fit the game]
|
||||
|
||||
### Adaptive Music System
|
||||
| Game State | Music Behavior | Transition |
|
||||
| ---- | ---- | ---- |
|
||||
| Exploration | [Tempo, energy, instrumentation] | [How it transitions to next state] |
|
||||
| Combat | [Tempo, energy, instrumentation] | [Trigger condition and crossfade time] |
|
||||
| Stealth/Tension | [Tempo, energy, instrumentation] | [Trigger and transition] |
|
||||
| Victory/Reward | [Stinger or transition behavior] | [Return to exploration] |
|
||||
| Menu/UI | [Style for menus] | [Fade on game start] |
|
||||
|
||||
### Music Rules
|
||||
- [Rule about looping, e.g., "All exploration tracks must loop seamlessly after 2-4 minutes"]
|
||||
- [Rule about silence, e.g., "Allow 10-15 seconds of silence between exploration loops"]
|
||||
- [Rule about intensity, e.g., "Combat music must reach full intensity within 3 seconds of combat start"]
|
||||
- [Rule about transitions, e.g., "All music transitions use 1.5 second crossfades"]
|
||||
|
||||
---
|
||||
|
||||
## Sound Effects
|
||||
|
||||
### SFX Palette
|
||||
| Category | Description | Style Notes |
|
||||
| ---- | ---- | ---- |
|
||||
| Player Actions | [Movement, attacks, abilities] | [Punchy, responsive, front-of-mix] |
|
||||
| Enemy Actions | [Attacks, abilities, death] | [Distinct from player, slightly recessed] |
|
||||
| UI | [Button clicks, menu transitions, notifications] | [Clean, subtle, never annoying on repeat] |
|
||||
| Environment | [Ambient loops, weather, objects] | [Immersive, layered, spatial] |
|
||||
| Feedback | [Damage taken, item pickup, level up] | [Clear, satisfying, non-fatiguing] |
|
||||
|
||||
### Audio Feedback Priority
|
||||
When multiple sounds compete, this priority determines what plays:
|
||||
1. Player damage / critical warnings (always audible)
|
||||
2. Player actions (attacks, abilities)
|
||||
3. Enemy actions (nearby enemies first)
|
||||
4. UI feedback
|
||||
5. Environment / ambient
|
||||
|
||||
### SFX Rules
|
||||
- [Rule about repetition, e.g., "Every SFX with >3 plays/minute needs 3+ variations"]
|
||||
- [Rule about spatial audio, e.g., "All gameplay SFX must be 3D positioned, UI SFX are 2D"]
|
||||
- [Rule about ducking, e.g., "Player hit SFX ducks all other SFX by 3dB for 200ms"]
|
||||
- [Rule about response time, e.g., "Action SFX must trigger within 1 frame of the action"]
|
||||
|
||||
---
|
||||
|
||||
## Mixing
|
||||
|
||||
### Mix Bus Structure
|
||||
| Bus | Content | Target Level |
|
||||
| ---- | ---- | ---- |
|
||||
| Master | Everything | 0 dB |
|
||||
| Music | All music tracks | [target dBFS] |
|
||||
| SFX | All sound effects | [target dBFS] |
|
||||
| Dialogue | All voice/narration | [target dBFS] |
|
||||
| UI | All interface sounds | [target dBFS] |
|
||||
| Ambient | Environment loops | [target dBFS] |
|
||||
|
||||
### Mixing Rules
|
||||
- Dialogue always takes priority — duck music and SFX during dialogue
|
||||
- Music should be felt, not dominate — if players can't hear SFX over music, music is too loud
|
||||
- Master output must never clip — use a limiter on the master bus
|
||||
- All volumes must be adjustable by the player (per bus)
|
||||
- Default mix should sound good on both speakers and headphones
|
||||
|
||||
### Dynamic Range
|
||||
- [Specify loudness targets, e.g., "Target -14 LUFS integrated, -1 dBTP true peak"]
|
||||
- [Specify compression policy, e.g., "Light compression on SFX bus, no compression on music"]
|
||||
|
||||
---
|
||||
|
||||
## Technical Specifications
|
||||
|
||||
### Format Requirements
|
||||
| Type | Format | Sample Rate | Bit Depth | Notes |
|
||||
| ---- | ---- | ---- | ---- | ---- |
|
||||
| Music | [OGG/WAV] | [44.1/48 kHz] | [16/24 bit] | [Streaming from disk] |
|
||||
| SFX | [WAV/OGG] | [44.1/48 kHz] | [16 bit] | [Loaded into memory] |
|
||||
| Ambient | [OGG] | [44.1 kHz] | [16 bit] | [Streaming, loopable] |
|
||||
| Dialogue | [OGG/WAV] | [44.1 kHz] | [16 bit] | [Streaming] |
|
||||
|
||||
### Naming Convention
|
||||
`[category]_[subcategory]_[name]_[variation].ext`
|
||||
- Example: `sfx_weapon_sword_swing_01.wav`
|
||||
- Example: `music_exploration_forest_loop.ogg`
|
||||
- Example: `amb_environment_cave_drip_loop.ogg`
|
||||
|
||||
### Memory Budget
|
||||
- Total audio memory: [target, e.g., 128 MB]
|
||||
- SFX pool: [target]
|
||||
- Music streaming buffer: [target]
|
||||
- Voice streaming buffer: [target]
|
||||
|
||||
---
|
||||
|
||||
## Accessibility
|
||||
|
||||
- All critical audio cues must have visual alternatives (subtitles, screen flash, icon)
|
||||
- Mono audio option for hearing-impaired players
|
||||
- Separate volume controls for all buses
|
||||
- Option to disable sudden loud sounds
|
||||
- Subtitle support for all dialogue with speaker identification
|
||||
66
.claude/docs/templates/sprint-plan.md
vendored
Normal file
66
.claude/docs/templates/sprint-plan.md
vendored
Normal file
@@ -0,0 +1,66 @@
|
||||
# Sprint [N] — [Start Date] to [End Date]
|
||||
|
||||
## Sprint Goal
|
||||
|
||||
[One sentence: what does this sprint achieve toward the current milestone?]
|
||||
|
||||
## Milestone Context
|
||||
|
||||
- **Current Milestone**: [Name]
|
||||
- **Milestone Deadline**: [Date]
|
||||
- **Sprints Remaining**: [N]
|
||||
|
||||
## Capacity
|
||||
|
||||
- **Total days**: [X]
|
||||
- **Buffer (20%)**: [Y days reserved for unplanned work]
|
||||
- **Available**: [Z days]
|
||||
|
||||
## Tasks
|
||||
|
||||
### Must Have (Critical Path)
|
||||
|
||||
| ID | Task | Agent/Owner | Est. Days | Dependencies | Acceptance Criteria | Status |
|
||||
|----|------|-------------|-----------|-------------|-------------------|--------|
|
||||
| S[N]-001 | | | | None | | Not Started |
|
||||
| S[N]-002 | | | | S[N]-001 | | Not Started |
|
||||
|
||||
### Should Have
|
||||
|
||||
| ID | Task | Agent/Owner | Est. Days | Dependencies | Acceptance Criteria | Status |
|
||||
|----|------|-------------|-----------|-------------|-------------------|--------|
|
||||
| S[N]-010 | | | | | | Not Started |
|
||||
|
||||
### Nice to Have (Cut First)
|
||||
|
||||
| ID | Task | Agent/Owner | Est. Days | Dependencies | Acceptance Criteria | Status |
|
||||
|----|------|-------------|-----------|-------------|-------------------|--------|
|
||||
| S[N]-020 | | | | | | Not Started |
|
||||
|
||||
## Carryover from Sprint [N-1]
|
||||
|
||||
| Original ID | Task | Reason for Carryover | New Estimate | Priority Change |
|
||||
|------------|------|---------------------|-------------|----------------|
|
||||
|
||||
## Risks to This Sprint
|
||||
|
||||
| Risk | Probability | Impact | Mitigation | Owner |
|
||||
|------|------------|--------|-----------|-------|
|
||||
|
||||
## External Dependencies
|
||||
|
||||
| Dependency | Status | Impact if Delayed | Contingency |
|
||||
|-----------|--------|------------------|-------------|
|
||||
|
||||
## Definition of Done
|
||||
|
||||
- [ ] All Must Have tasks completed
|
||||
- [ ] All tasks pass acceptance criteria
|
||||
- [ ] QA plan exists (`production/qa/qa-plan-sprint-[N].md`)
|
||||
- [ ] All Logic/Integration stories have passing unit/integration tests
|
||||
- [ ] Smoke check passed (`/smoke-check sprint`)
|
||||
- [ ] QA sign-off report: APPROVED or APPROVED WITH CONDITIONS (`/team-qa sprint`)
|
||||
- [ ] No S1 or S2 bugs in delivered features
|
||||
- [ ] Design documents updated for any deviations
|
||||
- [ ] Code reviewed and merged
|
||||
|
||||
146
.claude/docs/templates/systems-index.md
vendored
Normal file
146
.claude/docs/templates/systems-index.md
vendored
Normal file
@@ -0,0 +1,146 @@
|
||||
# Systems Index: [Game Title]
|
||||
|
||||
> **Status**: [Draft / Under Review / Approved]
|
||||
> **Created**: [Date]
|
||||
> **Last Updated**: [Date]
|
||||
> **Source Concept**: design/gdd/game-concept.md
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
[One paragraph explaining the game's mechanical scope. What kind of systems does
|
||||
this game need? Reference the core loop and game pillars. This should help any
|
||||
team member understand the "big picture" of what needs to be designed and built.]
|
||||
|
||||
---
|
||||
|
||||
## Systems Enumeration
|
||||
|
||||
| # | System Name | Category | Priority | Status | Design Doc | Depends On |
|
||||
|---|-------------|----------|----------|--------|------------|------------|
|
||||
| 1 | [e.g., Player Controller] | Core | MVP | [Not Started / In Design / In Review / Approved / Implemented] | [design/gdd/player-controller.md or "—"] | [e.g., Input System, Physics] |
|
||||
| 2 | [e.g., Camera System] | Core | MVP | Not Started | — | Player Controller |
|
||||
|
||||
[Add a row for every identified system. Use the categories and priority tiers
|
||||
defined below. Mark systems that were inferred (not explicitly in the concept doc)
|
||||
with "(inferred)" in the system name.]
|
||||
|
||||
---
|
||||
|
||||
## Categories
|
||||
|
||||
| Category | Description | Typical Systems |
|
||||
|----------|-------------|-----------------|
|
||||
| **Core** | Foundation systems everything depends on | Player controller, input, physics, camera, scene management, state machine |
|
||||
| **Gameplay** | The systems that make the game fun | Combat, AI, stealth, movement abilities, interaction |
|
||||
| **Progression** | How the player grows over time | XP/leveling, skill trees, unlocks, achievements, reputation |
|
||||
| **Economy** | Resource creation and consumption | Currency, loot, crafting, shops, item database, drop tables |
|
||||
| **Persistence** | Save state and continuity | Save/load, settings, cloud sync, profile management |
|
||||
| **UI** | Player-facing information displays | HUD, menus, inventory screen, dialogue UI, map, notifications |
|
||||
| **Audio** | Sound and music systems | Music manager, SFX bus, ambient audio, adaptive music, voice |
|
||||
| **Narrative** | Story and dialogue delivery | Dialogue system, quest tracking, cutscenes, journal, lore entries |
|
||||
| **Meta** | Systems outside the core game loop | Analytics, tutorials/onboarding, accessibility options, photo mode |
|
||||
|
||||
[Not every game needs every category. Remove categories that don't apply.
|
||||
Add custom categories if needed.]
|
||||
|
||||
---
|
||||
|
||||
## Priority Tiers
|
||||
|
||||
| Tier | Definition | Target Milestone | Design Urgency |
|
||||
|------|------------|------------------|----------------|
|
||||
| **MVP** | Required for the core loop to function. Without these, you can't test "is this fun?" | First playable prototype | Design FIRST |
|
||||
| **Vertical Slice** | Required for one complete, polished area. Demonstrates the full experience. | Vertical slice / demo | Design SECOND |
|
||||
| **Alpha** | All features present in rough form. Complete mechanical scope, placeholder content OK. | Alpha milestone | Design THIRD |
|
||||
| **Full Vision** | Polish, edge cases, nice-to-haves, and content-complete features. | Beta / Release | Design as needed |
|
||||
|
||||
---
|
||||
|
||||
## Dependency Map
|
||||
|
||||
[Systems sorted by dependency order — design and build from top to bottom.
|
||||
Systems at the top are foundations; systems at the bottom are wrappers.]
|
||||
|
||||
### Foundation Layer (no dependencies)
|
||||
|
||||
1. [System] — [one-line rationale for why this is foundational]
|
||||
|
||||
### Core Layer (depends on foundation)
|
||||
|
||||
1. [System] — depends on: [list]
|
||||
|
||||
### Feature Layer (depends on core)
|
||||
|
||||
1. [System] — depends on: [list]
|
||||
|
||||
### Presentation Layer (depends on features)
|
||||
|
||||
1. [System] — depends on: [list]
|
||||
|
||||
### Polish Layer (depends on everything)
|
||||
|
||||
1. [System] — depends on: [list]
|
||||
|
||||
---
|
||||
|
||||
## Recommended Design Order
|
||||
|
||||
[Combining dependency sort and priority tiers. Design these systems in this
|
||||
order. Each system's GDD should be completed and reviewed before starting the
|
||||
next, though independent systems at the same layer can be designed in parallel.]
|
||||
|
||||
| Order | System | Priority | Layer | Agent(s) | Est. Effort |
|
||||
|-------|--------|----------|-------|----------|-------------|
|
||||
| 1 | [First system to design] | MVP | Foundation | game-designer | [S/M/L] |
|
||||
| 2 | [Second system] | MVP | Foundation | game-designer | [S/M/L] |
|
||||
|
||||
[Effort estimates: S = 1 session, M = 2-3 sessions, L = 4+ sessions.
|
||||
A "session" is one focused design conversation producing a complete GDD.]
|
||||
|
||||
---
|
||||
|
||||
## Circular Dependencies
|
||||
|
||||
[List any circular dependency chains found during analysis. These require
|
||||
special architectural attention — either break the cycle with an interface,
|
||||
or design the systems simultaneously.]
|
||||
|
||||
- [None found] OR
|
||||
- [System A <-> System B: Description of the circular relationship and
|
||||
proposed resolution]
|
||||
|
||||
---
|
||||
|
||||
## High-Risk Systems
|
||||
|
||||
[Systems that are technically unproven, design-uncertain, or scope-dangerous.
|
||||
These should be prototyped early regardless of priority tier.]
|
||||
|
||||
| System | Risk Type | Risk Description | Mitigation |
|
||||
|--------|-----------|-----------------|------------|
|
||||
| [System] | [Technical / Design / Scope] | [What could go wrong] | [Prototype, research, or scope fallback] |
|
||||
|
||||
---
|
||||
|
||||
## Progress Tracker
|
||||
|
||||
| Metric | Count |
|
||||
|--------|-------|
|
||||
| Total systems identified | [N] |
|
||||
| Design docs started | [N] |
|
||||
| Design docs reviewed | [N] |
|
||||
| Design docs approved | [N] |
|
||||
| MVP systems designed | [N/total MVP] |
|
||||
| Vertical Slice systems designed | [N/total VS] |
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
- [ ] Review and approve this systems enumeration
|
||||
- [ ] Design MVP-tier systems first (use `/design-system [system-name]`)
|
||||
- [ ] Run `/design-review` on each completed GDD
|
||||
- [ ] Run `/gate-check pre-production` when MVP systems are designed
|
||||
- [ ] Validate the highest-risk systems with `/vertical-slice` before committing to Production
|
||||
96
.claude/docs/templates/technical-design-document.md
vendored
Normal file
96
.claude/docs/templates/technical-design-document.md
vendored
Normal file
@@ -0,0 +1,96 @@
|
||||
# Technical Design: [System Name]
|
||||
|
||||
## Document Status
|
||||
- **Version**: 1.0
|
||||
- **Last Updated**: [Date]
|
||||
- **Author**: [Agent/Person]
|
||||
- **Reviewer**: lead-programmer
|
||||
- **Related ADR**: [ADR-XXXX if applicable]
|
||||
- **Related Design Doc**: [Link to game design doc this implements]
|
||||
|
||||
## Engine API Surface
|
||||
|
||||
| Field | Value |
|
||||
|-------|-------|
|
||||
| **Engine** | [e.g. Godot 4.6 / Unity 6 / Unreal Engine 5.4] |
|
||||
| **APIs Depended On** | [Specific classes/methods/nodes used, version-pinned — e.g. `CharacterBody3D.move_and_slide() (Godot 4.x)`] |
|
||||
| **References Consulted** | [engine-reference docs read before writing this — e.g. `docs/engine-reference/godot/modules/physics.md`] |
|
||||
| **Post-Cutoff Features Used** | [Features from engine versions beyond LLM training cutoff, or "None"] |
|
||||
| **Unverified Assumptions** | [API behaviours assumed but not yet tested against the target version, or "None"] |
|
||||
| **Engine Upgrade Risk** | [LOW / MEDIUM / HIGH — how fragile is this design if the engine version changes?] |
|
||||
|
||||
> **Rule**: If any **Unverified Assumptions** are listed, this document cannot be marked
|
||||
> as Accepted until those assumptions are validated in the actual engine environment.
|
||||
|
||||
## Overview
|
||||
[2-3 sentence summary of what this system does and why it exists]
|
||||
|
||||
## Requirements
|
||||
### Functional Requirements
|
||||
- [FR-1]: [Description]
|
||||
- [FR-2]: [Description]
|
||||
|
||||
### Non-Functional Requirements
|
||||
- **Performance**: [Budget — e.g., "< 1ms per frame"]
|
||||
- **Memory**: [Budget — e.g., "< 50MB at peak"]
|
||||
- **Scalability**: [Limits — e.g., "Support up to 1000 entities"]
|
||||
- **Thread Safety**: [Requirements]
|
||||
|
||||
## Architecture
|
||||
|
||||
### System Diagram
|
||||
```
|
||||
[ASCII diagram showing components and data flow]
|
||||
```
|
||||
|
||||
### Component Breakdown
|
||||
| Component | Responsibility | Owns |
|
||||
| --------- | -------------- | ---- |
|
||||
| [Name] | [What it does] | [What data it owns] |
|
||||
|
||||
### Public API
|
||||
```
|
||||
[Interface/API definition in pseudocode or target language]
|
||||
```
|
||||
|
||||
### Data Structures
|
||||
```
|
||||
[Key data structures with field descriptions]
|
||||
```
|
||||
|
||||
### Data Flow
|
||||
[Step by step: how data moves through the system during a typical frame]
|
||||
|
||||
## Implementation Plan
|
||||
|
||||
### Phase 1: [Core Functionality]
|
||||
- [ ] [Task 1]
|
||||
- [ ] [Task 2]
|
||||
|
||||
### Phase 2: [Extended Features]
|
||||
- [ ] [Task 3]
|
||||
- [ ] [Task 4]
|
||||
|
||||
### Phase 3: [Optimization/Polish]
|
||||
- [ ] [Task 5]
|
||||
|
||||
## Dependencies
|
||||
| Depends On | For What |
|
||||
| ---------- | -------- |
|
||||
| [System] | [Reason] |
|
||||
|
||||
| Depended On By | For What |
|
||||
| -------------- | -------- |
|
||||
| [System] | [Reason] |
|
||||
|
||||
## Testing Strategy
|
||||
- **Unit Tests**: [What to test at unit level]
|
||||
- **Integration Tests**: [Cross-system tests needed]
|
||||
- **Performance Tests**: [Benchmarks to create]
|
||||
- **Edge Cases**: [Specific scenarios to test]
|
||||
|
||||
## Known Limitations
|
||||
[What this design intentionally does NOT support and why]
|
||||
|
||||
## Future Considerations
|
||||
[What might need to change if requirements evolve — but do NOT build for this now]
|
||||
90
.claude/docs/templates/test-evidence.md
vendored
Normal file
90
.claude/docs/templates/test-evidence.md
vendored
Normal file
@@ -0,0 +1,90 @@
|
||||
# Test Evidence: [Story Title]
|
||||
|
||||
> **Story**: `[path to story file]`
|
||||
> **Story Type**: [Visual/Feel | UI]
|
||||
> **Date**: [date]
|
||||
> **Tester**: [who performed the test]
|
||||
> **Build / Commit**: [version or git hash]
|
||||
|
||||
---
|
||||
|
||||
## What Was Tested
|
||||
|
||||
[One paragraph describing the feature or behaviour that was validated. Include
|
||||
the acceptance criteria numbers from the story that this evidence covers.]
|
||||
|
||||
**Acceptance criteria covered**: [AC-1, AC-2, AC-3]
|
||||
|
||||
---
|
||||
|
||||
## Acceptance Criteria Results
|
||||
|
||||
| # | Criterion (from story) | Result | Notes |
|
||||
|---|----------------------|--------|-------|
|
||||
| AC-1 | [exact criterion text] | PASS / FAIL | [any observations] |
|
||||
| AC-2 | [exact criterion text] | PASS / FAIL | |
|
||||
| AC-3 | [exact criterion text] | PASS / FAIL | |
|
||||
|
||||
---
|
||||
|
||||
## Screenshots / Video
|
||||
|
||||
List all captured evidence below. Store files in the same directory as this
|
||||
document or in `production/qa/evidence/[story-slug]/`.
|
||||
|
||||
| # | Filename | What It Shows | Acceptance Criterion |
|
||||
|---|----------|--------------|----------------------|
|
||||
| 1 | `[filename.png]` | [brief description of what is visible] | AC-1 |
|
||||
| 2 | `[filename.png]` | | AC-2 |
|
||||
|
||||
*If video: note the timestamp and what it demonstrates.*
|
||||
|
||||
---
|
||||
|
||||
## Test Conditions
|
||||
|
||||
- **Game state at start**: [e.g., "fresh save, player at level 1, no items"]
|
||||
- **Platform / hardware**: [e.g., "Windows 11, GTX 1080, 1080p"]
|
||||
- **Framerate during test**: [e.g., "stable 60fps" or "~45fps — within budget"]
|
||||
- **Any special setup required**: [e.g., "dev menu used to trigger specific state"]
|
||||
|
||||
---
|
||||
|
||||
## Observations
|
||||
|
||||
[Anything noteworthy that didn't cause a FAIL but should be recorded. Examples:
|
||||
minor visual jitter, frame dip under load, behaviour that technically passes
|
||||
but felt slightly off. These become candidates for polish work.]
|
||||
|
||||
- [Observation 1]
|
||||
- [Observation 2]
|
||||
|
||||
If nothing notable: *No significant observations.*
|
||||
|
||||
---
|
||||
|
||||
## Sign-Off
|
||||
|
||||
All roles must sign off before the story can be marked COMPLETE via `/story-done`.
|
||||
Visual/Feel stories require the designer or art-lead sign-off. UI stories require
|
||||
the UX lead or designer sign-off.
|
||||
|
||||
**Solo developers**: all sign-offs may be by the same person in each role. The
|
||||
intent is that someone deliberately reviews the evidence before marking complete —
|
||||
not that three separate people must participate.
|
||||
|
||||
| Role | Name | Date | Signature |
|
||||
|------|------|------|-----------|
|
||||
| Developer (implemented) | | | [ ] Approved |
|
||||
| Designer / Art Lead / UX Lead | | | [ ] Approved |
|
||||
| QA Lead | | | [ ] Approved |
|
||||
|
||||
**Any sign-off can be marked "Deferred — [reason]"** if the person is
|
||||
unavailable. Deferred sign-offs must be resolved before the story advances
|
||||
past the sprint review.
|
||||
|
||||
---
|
||||
|
||||
*Template: `.claude/docs/templates/test-evidence.md`*
|
||||
*Used for: Visual/Feel and UI story type evidence records*
|
||||
*Location: `production/qa/evidence/[story-slug]-evidence.md`*
|
||||
122
.claude/docs/templates/test-plan.md
vendored
Normal file
122
.claude/docs/templates/test-plan.md
vendored
Normal file
@@ -0,0 +1,122 @@
|
||||
# QA Plan: [Sprint/Feature Name]
|
||||
|
||||
> **Date**: [date]
|
||||
> **Generated by**: /qa-plan
|
||||
> **Scope**: [N stories across N systems]
|
||||
> **Engine**: [engine name and version]
|
||||
> **Sprint file**: [path to sprint plan]
|
||||
|
||||
---
|
||||
|
||||
## Story Coverage Summary
|
||||
|
||||
| Story | Type | Automated Test Required | Manual Verification Required |
|
||||
|-------|------|------------------------|------------------------------|
|
||||
| [story title] | Logic | Unit test — `tests/unit/[system]/` | None |
|
||||
| [story title] | Integration | Integration test — `tests/integration/[system]/` | Smoke check |
|
||||
| [story title] | Visual/Feel | None (not automatable) | Screenshot + lead sign-off |
|
||||
| [story title] | UI | None (not automatable) | Manual step-through |
|
||||
| [story title] | Config/Data | Data validation (optional) | Spot-check in-game values |
|
||||
|
||||
**Totals**: [N] Logic, [N] Integration, [N] Visual/Feel, [N] UI, [N] Config/Data
|
||||
|
||||
---
|
||||
|
||||
## Automated Tests Required
|
||||
|
||||
### [Story Title] — Logic
|
||||
|
||||
**Test file path**: `tests/unit/[system]/[story-slug]_test.[ext]`
|
||||
|
||||
**What to test**:
|
||||
- [Formula or rule from GDD Formulas section — e.g., "damage = base * multiplier where multiplier ∈ [0.5, 3.0]"]
|
||||
- [Each named state transition]
|
||||
- [Each side effect that should / should not occur]
|
||||
|
||||
**Edge cases to cover**:
|
||||
- Zero / minimum input values
|
||||
- Maximum / boundary input values
|
||||
- Invalid or null input
|
||||
- [GDD-specified edge cases]
|
||||
|
||||
**Estimated test count**: ~[N] unit tests
|
||||
|
||||
---
|
||||
|
||||
### [Story Title] — Integration
|
||||
|
||||
**Test file path**: `tests/integration/[system]/[story-slug]_test.[ext]`
|
||||
|
||||
**What to test**:
|
||||
- [Cross-system interaction — e.g., "applying buff updates CharacterStats and triggers UI refresh"]
|
||||
- [Round-trip — e.g., "save → load restores all fields"]
|
||||
|
||||
---
|
||||
|
||||
## Manual QA Checklist
|
||||
|
||||
### [Story Title] — Visual/Feel
|
||||
|
||||
**Verification method**: Screenshot + [designer / art-lead] sign-off
|
||||
**Evidence file**: `production/qa/evidence/[story-slug]-evidence.md`
|
||||
**Who must sign off**: [designer / lead-programmer / art-lead]
|
||||
|
||||
- [ ] [Specific observable condition — e.g., "hit flash appears on frame of impact, not the frame after"]
|
||||
- [ ] [Another falsifiable condition]
|
||||
|
||||
### [Story Title] — UI
|
||||
|
||||
**Verification method**: Manual step-through
|
||||
**Evidence file**: `production/qa/evidence/[story-slug]-evidence.md`
|
||||
|
||||
- [ ] [Every acceptance criterion translated into a manual check item]
|
||||
|
||||
---
|
||||
|
||||
## Smoke Test Scope
|
||||
|
||||
Critical paths to verify before QA hand-off (run via `/smoke-check`):
|
||||
|
||||
1. Game launches to main menu without crash
|
||||
2. New game / session can be started
|
||||
3. [Primary mechanic introduced or changed this sprint]
|
||||
4. [System with regression risk from this sprint's changes]
|
||||
5. Save / load cycle completes without data loss (if save system exists)
|
||||
6. Performance is within budget on target hardware
|
||||
|
||||
---
|
||||
|
||||
## Playtest Requirements
|
||||
|
||||
| Story | Playtest Goal | Min Sessions | Target Player Type |
|
||||
|-------|--------------|--------------|-------------------|
|
||||
| [story] | [What question must be answered?] | [N] | [new player / experienced / etc.] |
|
||||
|
||||
Sign-off requirement: Playtest notes → `production/session-logs/playtest-[sprint]-[story-slug].md`
|
||||
|
||||
If no playtest sessions required: *No playtest sessions required for this sprint.*
|
||||
|
||||
---
|
||||
|
||||
## Definition of Done — This Sprint
|
||||
|
||||
A story is DONE when ALL of the following are true:
|
||||
|
||||
- [ ] All acceptance criteria verified — automated test result OR documented manual evidence
|
||||
- [ ] Test file exists for all Logic and Integration stories and passes
|
||||
- [ ] Manual evidence document exists for all Visual/Feel and UI stories
|
||||
- [ ] Smoke check passes (run `/smoke-check sprint` before QA hand-off)
|
||||
- [ ] No regressions introduced — previous sprint's features still pass
|
||||
- [ ] Code reviewed (via `/code-review` or documented peer review)
|
||||
- [ ] Story file updated to `Status: Complete` via `/story-done`
|
||||
|
||||
**Stories requiring playtest sign-off before close**: [list, or "None"]
|
||||
|
||||
---
|
||||
|
||||
---
|
||||
|
||||
*Results and sign-off are tracked in the QA sign-off report generated by `/team-qa` — not in this plan file.*
|
||||
|
||||
*Template: `.claude/docs/templates/test-plan.md`*
|
||||
*Generated by: `/qa-plan` — do not edit this line*
|
||||
544
.claude/docs/templates/ux-spec.md
vendored
Normal file
544
.claude/docs/templates/ux-spec.md
vendored
Normal file
@@ -0,0 +1,544 @@
|
||||
# UX Specification: [Screen / Flow Name]
|
||||
|
||||
> **Status**: Draft | In Review | Approved | Implemented
|
||||
> **Author**: [Name or agent — e.g., ui-designer]
|
||||
> **Last Updated**: [Date]
|
||||
> **Screen / Flow Name**: [Short identifier used in code and tickets — e.g., `InventoryScreen`, `NewGameFlow`]
|
||||
> **Platform Target**: [PC | Console | Mobile | All — list all that this spec covers]
|
||||
> **Related GDDs**: [Links to the GDD sections that generated this UI requirement — e.g., `design/gdd/inventory.md § UI Requirements`]
|
||||
> **Related ADRs**: [Any architectural decisions that constrain this screen — e.g., `ADR-0012: UI Framework Selection`]
|
||||
> **Related UX Specs**: [Sibling and parent screens — e.g., `ux-spec-pause-menu.md`, `ux-spec-settings.md`]
|
||||
> **Accessibility Tier**: Basic | Standard | Comprehensive | Exemplary
|
||||
|
||||
> **Note — Scope boundary**: This template covers discrete screens and flows (menus,
|
||||
> dialogs, inventory, settings, cutscene UI, etc.). For persistent in-game overlays
|
||||
> that exist during active gameplay, use `hud-design.md` instead. If a screen is a
|
||||
> hybrid (e.g., a pause menu that overlays the game world), treat it as a screen spec
|
||||
> and note the overlay relationship in Navigation Position.
|
||||
|
||||
---
|
||||
|
||||
## 1. Purpose & Player Need
|
||||
|
||||
> **Why this section exists**: Every screen must justify its existence from the
|
||||
> player's perspective. Screens that are designed from a developer perspective ("display
|
||||
> the save data") produce cluttered, confusing interfaces. Screens designed from the
|
||||
> player's perspective ("let the player feel confident their progress is safe before they
|
||||
> put the controller down") produce purposeful, calm interfaces. Write this section before
|
||||
> touching any layout decisions — it is the filter through which every subsequent choice
|
||||
> is evaluated.
|
||||
|
||||
**What player need does this screen serve?**
|
||||
|
||||
[One paragraph. Name the real human need, not the system function. Consider: what would
|
||||
a player say they want when they open this screen? What would frustrate them if it did
|
||||
not work? That frustration describes the need.
|
||||
|
||||
Example — bad: "Displays the player's current items and equipment."
|
||||
Example — good: "Lets the player understand what they're carrying and quickly decide what
|
||||
to take into the next encounter, without breaking their mental model of the game world.
|
||||
The inventory is the player's planning tool between moments of action."]
|
||||
|
||||
**The player goal** (what the player wants to accomplish):
|
||||
|
||||
[One sentence. Specific enough that you could write an acceptance criterion for it.
|
||||
Example: "Find the item they are looking for within three button presses and equip it
|
||||
without navigating to a separate screen."]
|
||||
|
||||
**The game goal** (what the game needs to communicate or capture):
|
||||
|
||||
[One sentence. This is what the system needs from this interaction. Example: "Record the
|
||||
player's equipment choices and relay them to the combat system before the next encounter
|
||||
loads." This section prevents UI that looks good but fails to serve the system it is
|
||||
part of.]
|
||||
|
||||
---
|
||||
|
||||
## 2. Player Context on Arrival
|
||||
|
||||
> **Why this section exists**: Screens do not exist in isolation. A player opening the
|
||||
> inventory mid-combat is in a completely different cognitive and emotional state than
|
||||
> a player opening it after clearing a dungeon. The same information architecture can
|
||||
> feel oppressively complex in one context and trivially simple in another. Document the
|
||||
> context so that design decisions — what to show first, what to hide, what to animate,
|
||||
> what to simplify — are calibrated to the actual player arriving at this screen, not
|
||||
> an abstract user.
|
||||
|
||||
| Question | Answer |
|
||||
|----------|--------|
|
||||
| What was the player just doing? | [e.g., Completed a combat encounter / Pressed Esc from exploration / Triggered a story cutscene] |
|
||||
| What is their emotional state? | [e.g., High tension — just narrowly survived / Calm — exploring between objectives] |
|
||||
| What cognitive load are they carrying? | [e.g., High — actively tracking enemy positions / Low — no active threats] |
|
||||
| What information do they already have? | [e.g., They know they just picked up an item but haven't seen its stats yet] |
|
||||
| What are they most likely trying to do? | [e.g., Check if the new item is better than their current weapon — primary use case] |
|
||||
| What are they likely afraid of? | [e.g., Missing something, making an irreversible mistake, losing track of where they were] |
|
||||
|
||||
**Emotional design target for this screen**:
|
||||
|
||||
[One sentence describing the feeling the player should have while using this screen.
|
||||
Example: "Confident and in control — the player should feel like they have complete
|
||||
information and complete authority over their choices, with no ambiguity about outcomes."]
|
||||
|
||||
---
|
||||
|
||||
## 3. Navigation Position
|
||||
|
||||
> **Why this section exists**: A screen that does not know where it sits in the
|
||||
> navigation hierarchy cannot define its entry/exit transitions, its back-button
|
||||
> behavior, or its relationship to the game's pause state. Navigation position also
|
||||
> reveals architectural problems early — if this screen is reachable from eight
|
||||
> different places, that is a complexity flag that should be resolved in design, not
|
||||
> implementation.
|
||||
|
||||
**Screen hierarchy** (use indentation to show parent-child relationships):
|
||||
|
||||
```
|
||||
[Root — e.g., Main Menu]
|
||||
└── [Parent Screen — e.g., Settings]
|
||||
└── [This Screen — e.g., Audio Settings]
|
||||
├── [Child Screen — e.g., Advanced Audio Options]
|
||||
└── [Child Screen — e.g., Speaker Test Dialog]
|
||||
```
|
||||
|
||||
**Modal behavior**: [Modal (blocks everything behind it, requires explicit dismiss) | Non-modal (game continues behind it) | Overlay (renders over game world, game paused) | Overlay-live (renders over game world, game continues)]
|
||||
|
||||
> If this screen is modal: document the dismiss behavior. Can it be dismissed by pressing
|
||||
> Back/B? By pressing Escape? By clicking outside it? Can it be dismissed at all, or
|
||||
> must the player complete it? Undismissable modals are high-friction — justify them.
|
||||
|
||||
**Reachability — all entry points**:
|
||||
|
||||
| Entry Point | Triggered By | Notes |
|
||||
|-------------|-------------|-------|
|
||||
| [e.g., Main Menu → Play] | [Player selects "New Game"] | [Primary entry point] |
|
||||
| [e.g., Pause Menu → Resume] | [Player presses Start from any gameplay state] | [Secondary entry] |
|
||||
| [e.g., Game event] | [Tutorial system forces open first time only] | [Systemic entry — must not break if player dismisses] |
|
||||
|
||||
---
|
||||
|
||||
## 4. Entry & Exit Points
|
||||
|
||||
> **Why this section exists**: Entry and exit define the screen's contract with the
|
||||
> rest of the navigation system. Every entry point must have a corresponding exit point.
|
||||
> Transitions that are undefined become bugs — the player finds themselves stuck, or the
|
||||
> game state becomes inconsistent. Fill this table completely before implementation
|
||||
> begins. Empty cells are a sign that design work is unfinished.
|
||||
|
||||
**Entry table**:
|
||||
|
||||
| Trigger | Source Screen / State | Transition Type | Data Passed In | Notes |
|
||||
|---------|----------------------|-----------------|----------------|-------|
|
||||
| [e.g., Player presses Inventory button] | [Gameplay / Exploration state] | [Overlay push — game pauses] | [Current player loadout, inventory contents] | [Works from any non-combat state] |
|
||||
| [e.g., Item pickup prompt accepted] | [Gameplay / Item Pickup dialog] | [Replace dialog with full inventory] | [Newly acquired item pre-highlighted] | [The new item should be visually distinguished on open] |
|
||||
| [e.g., Quest system directs player to inventory] | [Gameplay / Quest Update notification] | [Overlay push] | [Quest-relevant item ID for highlight] | [Screen should deep-link to the relevant item] |
|
||||
|
||||
**Exit table**:
|
||||
|
||||
| Exit Action | Destination | Transition Type | Data Returned / Saved | Notes |
|
||||
|-------------|------------|-----------------|----------------------|-------|
|
||||
| [e.g., Player closes inventory (Back/B/Esc)] | [Previous state — Exploration] | [Overlay pop — game resumes] | [Updated equipment loadout committed] | [Changes must be committed before transition begins] |
|
||||
| [e.g., Player selects "Equip" on item] | [Same screen, updated state] | [In-place state change] | [Loadout change event fired] | [No navigation, just a state refresh] |
|
||||
| [e.g., Player navigates to Map from inventory shortcut] | [Map Screen] | [Replace] | [No data] | [Inventory state is preserved if player returns] |
|
||||
|
||||
---
|
||||
|
||||
## 5. Layout Specification
|
||||
|
||||
> **Why this section exists**: The layout specification is the handoff artifact between
|
||||
> UX design and UI programming. It does not need to be pixel-perfect — it needs to
|
||||
> communicate hierarchy (what is important), proximity (what belongs together), and
|
||||
> proportion (what is big vs. small). ASCII wireframes achieve this without requiring
|
||||
> design software. A programmer who reads this section should be able to build the
|
||||
> correct structure without guessing. An artist who reads it should know where
|
||||
> visual weight should be concentrated.
|
||||
>
|
||||
> Draw the layout at one standard resolution (e.g., 1920x1080). Note adaptations
|
||||
> for other resolutions separately.
|
||||
|
||||
### 5.1 Wireframe
|
||||
|
||||
```
|
||||
[Draw the screen layout using ASCII art. Suggested characters:
|
||||
┌ ┐ └ ┘ │ ─ for borders
|
||||
╔ ╗ ╚ ╝ ║ ═ for emphasized/modal borders
|
||||
[ ] for interactive elements (buttons, inputs)
|
||||
{ } for content areas (lists, grids, images)
|
||||
... for scrollable content
|
||||
● for the focused element on open
|
||||
|
||||
Example:
|
||||
┌──────────────────────────────────────────────┐
|
||||
│ [← Back] INVENTORY [Options] │ ← HEADER ZONE
|
||||
├──────────────────────────────────────────────┤
|
||||
│ ┌──────────────┐ ┌─────────────────────────┐│
|
||||
│ │ CATEGORY NAV │ │ ITEM DETAIL PANEL ││ ← CONTENT ZONE
|
||||
│ │ ● Weapons │ │ Item Name ││
|
||||
│ │ Armor │ │ {item icon} ││
|
||||
│ │ Consumable│ │ Stats comparison ││
|
||||
│ │ Key Items │ │ Description text... ││
|
||||
│ ├──────────────┤ └─────────────────────────┘│
|
||||
│ │ ITEM GRID │ │
|
||||
│ │ {□}{□}{□}{□} │ │
|
||||
│ │ {□}{□}{□}{□} │ │
|
||||
│ │ ... │ │
|
||||
│ └──────────────┘ │
|
||||
├──────────────────────────────────────────────┤
|
||||
│ [Equip] [Drop] [Compare] [Close] │ ← ACTION BAR
|
||||
└──────────────────────────────────────────────┘
|
||||
]
|
||||
```
|
||||
|
||||
### 5.2 Zone Definitions
|
||||
|
||||
| Zone Name | Description | Approximate Size | Scrollable? | Overflow Behavior |
|
||||
|-----------|-------------|-----------------|-------------|-------------------|
|
||||
| [e.g., Header Zone] | [Top bar: navigation, screen title, global actions] | [Full width, ~10% height] | [No] | [Truncate long screen names with ellipsis] |
|
||||
| [e.g., Category Nav] | [Left panel: item category tabs] | [~25% width, ~75% height] | [Yes — vertical if categories exceed panel] | [Scroll indicator appears at bottom of list] |
|
||||
| [e.g., Item Grid] | [Center: grid of item icons for selected category] | [~45% width, ~75% height] | [Yes — vertical] | [Page-based: 4x4 grid, next page on overflow] |
|
||||
| [e.g., Detail Panel] | [Right: stats and description for selected item] | [~30% width, ~75% height] | [Yes — vertical for long descriptions] | [Fade at bottom, scroll to reveal] |
|
||||
| [e.g., Action Bar] | [Bottom: context-sensitive actions for selected item] | [Full width, ~15% height] | [No] | [Actions collapse to icon-only below 4] |
|
||||
|
||||
### 5.3 Component Inventory
|
||||
|
||||
> List every discrete UI component on this screen. This table drives the implementation
|
||||
> task list — each row becomes a component to build or reuse.
|
||||
|
||||
| Component Name | Type | Zone | Purpose | Required? | Reuses Existing Component? |
|
||||
|----------------|------|------|---------|-----------|---------------------------|
|
||||
| [e.g., Back Button] | [Button] | [Header] | [Returns to previous screen] | [Yes] | [Yes — standard NavButton component] |
|
||||
| [e.g., Screen Title Label] | [Text] | [Header] | [Displays "INVENTORY" or context name] | [Yes] | [Yes — ScreenTitle component] |
|
||||
| [e.g., Category Tab] | [Toggle Button] | [Category Nav] | [Filters item grid by category] | [Yes] | [No — new component needed] |
|
||||
| [e.g., Item Slot] | [Icon + Frame] | [Item Grid] | [Represents one inventory slot, empty or filled] | [Yes] | [No — new component] |
|
||||
| [e.g., Item Name Label] | [Text] | [Detail Panel] | [Shows selected item's name] | [Yes] | [Yes — BodyText component] |
|
||||
| [e.g., Stat Comparison Row] | [Compound — label + value + delta] | [Detail Panel] | [Shows stat value vs. currently equipped] | [Yes] | [No — new component] |
|
||||
| [e.g., Equip Button] | [Primary Button] | [Action Bar] | [Equips selected item in appropriate slot] | [Yes] | [Yes — PrimaryAction component] |
|
||||
| [e.g., Empty State Message] | [Text + Icon] | [Item Grid] | [Shown when category has no items] | [Yes] | [Yes — EmptyState component] |
|
||||
|
||||
**Primary focus element on open**: [e.g., The first item in the Item Grid — or, if deep-linked, the highlighted item. If the grid is empty, focus lands on the first Category Tab.]
|
||||
|
||||
---
|
||||
|
||||
## 6. States & Variants
|
||||
|
||||
> **Why this section exists**: A screen is not a single picture — it is a set of
|
||||
> states, each of which must look correct and behave correctly. Screens that are
|
||||
> designed only in their "happy path" state ship with broken empty states, invisible
|
||||
> loading indicators, and crashes when data is missing. Document every state before
|
||||
> implementation. The states table is also the test matrix for QA.
|
||||
|
||||
| State Name | Trigger | What Changes Visually | What Changes Behaviorally | Notes |
|
||||
|------------|---------|----------------------|--------------------------|-------|
|
||||
| [Loading] | [Screen is opening, data not yet available] | [Item Grid shows skeleton/shimmer placeholders; Action Bar buttons disabled] | [No interactions possible except Close] | [Should not be visible >500ms under normal conditions; if it is, investigate data fetch performance] |
|
||||
| [Empty — no items in category] | [Player switches to a category with zero items] | [Item Grid replaced by EmptyState component: icon + "Nothing here yet."] | [Action Bar shows no item actions; Drop/Equip/Compare all hidden] | [Do not show disabled buttons — remove them. Disabled buttons with no tooltip are confusing.] |
|
||||
| [Populated — items present] | [Category has at least one item] | [Item Grid fills with item slots; first slot is auto-focused] | [All item actions available for selected item] | [Default and most common state] |
|
||||
| [Item Selected] | [Player navigates to an item slot] | [Detail Panel populates; selected slot has focus ring; Action Bar updates to item's valid actions] | [Equip/Drop/Compare enabled based on item type] | [Equip is disabled if item is already equipped — show a "Equipped" badge instead] |
|
||||
| [Confirmation Pending — Drop] | [Player selects Drop action] | [Confirmation dialog overlays the screen] | [All background interactions suspended until dialog resolves] | [Use a modal confirmation, not an inline toggle. Items cannot be recovered after dropping.] |
|
||||
| [Error — data load failed] | [Inventory data could not be retrieved] | [Item Grid shows error state: icon + "Couldn't load items." + Retry button] | [Only Retry and Close are available] | [Log the error; do not expose technical details to player] |
|
||||
| [Item Newly Acquired] | [Screen opened from item pickup deep-link] | [Newly acquired item has a visual "New" badge; Detail Panel pre-populated with that item] | [Same as Item Selected but with badge until player navigates away] | [Badge persists until the player manually navigates off that slot once] |
|
||||
|
||||
---
|
||||
|
||||
## 7. Interaction Map
|
||||
|
||||
> **Why this section exists**: This section is the source of truth for what every
|
||||
> input does on this screen. It forces the designer to think through every input
|
||||
> method (mouse, keyboard, gamepad, touch) and every interactive state (hover, focus,
|
||||
> pressed, disabled). Gaps in this table are bugs waiting to happen. The
|
||||
> interaction map is also the input for the accessibility audit — if an action is
|
||||
> only reachable by mouse, it will fail the keyboard and gamepad columns.
|
||||
|
||||
### 7.1 Navigation Inputs
|
||||
|
||||
| Input | Platform | Action | Visual Response | Audio Cue | Notes |
|
||||
|-------|----------|--------|-----------------|-----------|-------|
|
||||
| [Arrow keys / D-Pad] | [All] | [Move focus within active zone] | [Focus ring moves to adjacent element] | [Soft navigation tick] | [Wrap at edges within zone; do not cross zones with arrows alone] |
|
||||
| [Tab / R1] | [KB / Gamepad] | [Move focus to next zone (Category → Grid → Detail → Action Bar)] | [Focus ring jumps to first element in next zone] | [Distinct zone-change tone] | [Shift+Tab / L1 goes backward] |
|
||||
| [Mouse hover] | [PC] | [Show hover state on interactive elements] | [Highlight / underline / color shift] | [None] | [Hover does NOT move focus — only click does] |
|
||||
| [Mouse click] | [PC] | [Select and focus the clicked element] | [Pressed state flash, then selected/focused] | [Soft click] | [Right-click opens context menu if applicable; otherwise no-op] |
|
||||
| [Touch tap] | [Mobile] | [Select and activate in one gesture] | [Press ripple] | [Soft click] | [Treat tap as click + confirm for low-risk actions; require explicit confirm for destructive actions] |
|
||||
|
||||
### 7.2 Action Inputs
|
||||
|
||||
| Input | Platform | Context (What must be focused) | Action | Response | Animation | Audio Cue | Notes |
|
||||
|-------|----------|-------------------------------|--------|----------|-----------|-----------|-------|
|
||||
| [Enter / A button / Left click] | [All] | [Item slot focused] | [Select item → populate Detail Panel] | [Detail panel slides in or updates in place] | [Panel fade/slide in, 120ms] | [Soft select tone] | [If item already selected: no-op] |
|
||||
| [Enter / A button] | [All] | [Equip button focused] | [Equip selected item] | [Button animates press; item badge updates to "Equipped"; previously equipped item loses badge] | [Badge swap, 80ms] | [Equip success sound] | [Fires EquipItem event to Inventory system] |
|
||||
| [Triangle / Y button / Right-click] | [All] | [Item slot focused] | [Open item context menu] | [Context menu appears adjacent to item slot] | [Popover, 80ms] | [Menu open sound] | [Context menu contains: Equip, Drop, Inspect, Compare] |
|
||||
| [Square / X button] | [Gamepad] | [Item slot focused] | [Quick-equip without opening detail] | [Equip animation plays inline on slot] | [Slot flash, 80ms] | [Equip success sound] | [Convenience shortcut; does not change screen state] |
|
||||
| [Esc / B button / Back] | [All] | [Any, screen level] | [Close screen and return to previous state] | [Screen exit transition plays] | [Slide out, 200ms] | [Back/close tone] | [Commits all changes before closing. No discard — inventory is not a draft.] |
|
||||
| [F / L2] | [KB / Gamepad] | [Any] | [Toggle filter panel] | [Sort/filter overlay opens] | [Slide in from right, 200ms] | [Panel open tone] | [If no items in category, filter is disabled] |
|
||||
|
||||
### 7.3 State-Specific Behaviors
|
||||
|
||||
| State | Input Restriction | Reason |
|
||||
|-------|------------------|--------|
|
||||
| [Loading] | [All item and action inputs disabled] | [No data to act on; prevent race conditions] |
|
||||
| [Confirmation dialog open] | [Only Confirm and Cancel inputs active] | [Modal — background is locked] |
|
||||
| [Error state] | [Only Retry and Close active] | [No data available to navigate] |
|
||||
|
||||
---
|
||||
|
||||
## 8. Data Requirements
|
||||
|
||||
> **Why this section exists**: The separation between UI and game state is the most
|
||||
> important architectural boundary in a game's UI system. UI reads data; it does not
|
||||
> own it. UI fires events; it does not write state directly. This section defines
|
||||
> exactly what data this screen needs to display, where it comes from, and how
|
||||
> frequently it updates. Filling this table before implementation prevents two
|
||||
> common failure modes: (1) UI developers reaching into systems they should not touch,
|
||||
> and (2) systems not knowing they need to expose data until a UI is half-built.
|
||||
|
||||
| Data Element | Source System | Update Frequency | Who Owns It | Format | Null / Missing Handling |
|
||||
|--------------|--------------|-----------------|-------------|--------|------------------------|
|
||||
| [e.g., Item list] | [Inventory System] | [On screen open; on InventoryChanged event] | [InventorySystem] | [Array of ItemData structs: id, name, icon_path, category, stats, is_equipped] | [Empty array → show Empty State. Never null — system must return array.] |
|
||||
| [e.g., Equipped loadout] | [Equipment System] | [On screen open; on EquipmentChanged event] | [EquipmentSystem] | [Dict mapping slot_id → item_id] | [Unequipped slot has null value — UI shows empty slot icon] |
|
||||
| [e.g., Item stat comparisons] | [Stats System] | [On item selection change] | [StatsSystem] | [Dict mapping stat_name → {current, new, delta}] | [If no item selected, detail panel shows placeholder. Stats system must handle this gracefully.] |
|
||||
| [e.g., Player currency] | [Economy System] | [On screen open only — inventory does not show live currency] | [EconomySystem] | [Int — gold pieces] | [If currency system not active for this game mode, hide the currency row entirely] |
|
||||
| [e.g., Newly acquired item flag] | [Inventory System] | [On screen open] | [InventorySystem] | [Array of item_ids flagged as new] | [If empty array, no badges shown] |
|
||||
|
||||
> **Rule**: This screen must never write directly to any system listed above. All
|
||||
> player actions fire events (see Section 9). Systems update their own data and
|
||||
> notify the UI.
|
||||
|
||||
---
|
||||
|
||||
## 9. Events Fired
|
||||
|
||||
> **Why this section exists**: This is the other half of the UI/system boundary.
|
||||
> Where Section 8 defines what the UI reads, this section defines what the UI
|
||||
> communicates back to the game. Specifying events at design time prevents UI
|
||||
> programmers from writing game logic, and prevents game programmers from being
|
||||
> surprised by what the UI does. Every destructive or state-changing player action
|
||||
> must appear in this table.
|
||||
|
||||
| Player Action | Event Fired | Payload | Receiver System | Notes |
|
||||
|---------------|-------------|---------|-----------------|-------|
|
||||
| [Player equips an item] | [EquipItemRequested] | [{item_id: string, target_slot: string}] | [Equipment System] | [Equipment System validates the action and fires EquipmentChanged if successful; UI listens for EquipmentChanged to update its display] |
|
||||
| [Player drops an item] | [DropItemRequested] | [{item_id: string, quantity: int}] | [Inventory System] | [Fires only after player confirms the drop dialog. Inventory System removes the item and fires InventoryChanged.] |
|
||||
| [Player opens item compare] | [ItemCompareOpened] | [{item_a_id: string, item_b_id: string}] | [Analytics System] | [No game-state change — analytics event only. Compare view is purely local UI state.] |
|
||||
| [Player closes screen] | [InventoryScreenClosed] | [{session_duration_ms: int}] | [Analytics System] | [Fires on every close regardless of reason. Used for engagement metrics.] |
|
||||
| [Player navigates between categories] | [InventoryCategoryChanged] | [{category: string}] | [Analytics System] | [Analytics only. No game state change.] |
|
||||
|
||||
---
|
||||
|
||||
## 10. Transition & Animation
|
||||
|
||||
> **Why this section exists**: Transitions are not decoration — they communicate
|
||||
> hierarchy and causality. A screen that slides in from the right implies the
|
||||
> player has moved forward. A screen that fades implies a context break. Inconsistent
|
||||
> transitions make navigation feel broken even when it is technically correct.
|
||||
> This section ensures transitions are specified intentionally, not left to the
|
||||
> developer's discretion, and that accessibility settings (reduced motion) are
|
||||
> planned for from the start.
|
||||
|
||||
| Transition | Trigger | Direction / Type | Duration (ms) | Easing | Interruptible? | Skipped by Reduced Motion? |
|
||||
|------------|---------|-----------------|--------------|--------|----------------|---------------------------|
|
||||
| [Screen enter] | [Screen pushed onto stack] | [Slide in from right] | [250] | [Ease out cubic] | [No — must complete before interaction is enabled] | [Yes — instant appear at 0ms] |
|
||||
| [Screen exit — Back] | [Player presses Back] | [Slide out to right] | [200] | [Ease in cubic] | [No] | [Yes — instant disappear] |
|
||||
| [Screen exit — Forward] | [Player navigates to child screen] | [Slide out to left] | [200] | [Ease in cubic] | [No] | [Yes — instant] |
|
||||
| [Detail panel update] | [Player selects a new item] | [Cross-fade content] | [120] | [Linear] | [Yes — if player navigates quickly, previous animation cancels] | [Yes — instant swap] |
|
||||
| [Loading → Populated] | [Data arrives after load] | [Skeleton shimmer fades out, content fades in] | [180] | [Ease out] | [No] | [Yes — instant reveal] |
|
||||
| [Action Bar button press] | [Player activates a button] | [Scale down 95% on press, return on release] | [60 down / 60 up] | [Ease out / ease in] | [Yes — if released early, returns to normal] | [No — this is tactile feedback, not decorative motion] |
|
||||
| [Confirmation dialog open] | [Player initiates destructive action] | [Background dims 60% opacity; dialog scales up from 95%] | [150] | [Ease out] | [No] | [Yes — instant appear, no scale] |
|
||||
| [New item badge appear] | [Screen opens with newly acquired item] | [Badge pops from 0% to 110% to 100% scale] | [200 total] | [Ease out back] | [No] | [Yes — instant appear at 100% scale] |
|
||||
|
||||
---
|
||||
|
||||
## 11. Input Method Completeness Checklist
|
||||
|
||||
> **Why this section exists**: Input completeness is not optional — it is a
|
||||
> certification requirement for console platforms and a legal risk area for
|
||||
> accessibility laws in multiple markets. Fill this checklist before marking
|
||||
> the spec as Approved. Any unchecked item blocks implementation start.
|
||||
|
||||
**Keyboard**
|
||||
- [ ] All interactive elements are reachable using Tab and arrow keys alone
|
||||
- [ ] Tab order follows visual reading order (left-to-right, top-to-bottom within each zone)
|
||||
- [ ] Every action achievable by mouse is also achievable by keyboard
|
||||
- [ ] Focus is visible at all times (no element where focus ring disappears)
|
||||
- [ ] Focus does not escape the screen while it is open (focus trap for modals)
|
||||
- [ ] Esc key closes or cancels (and does not quit the game from within a screen)
|
||||
|
||||
**Gamepad**
|
||||
- [ ] All interactive elements reachable with D-Pad and left stick
|
||||
- [ ] Face button mapping documented and consistent with platform conventions (see Section 7.2)
|
||||
- [ ] No action requires analog stick precision that cannot be replicated with D-Pad
|
||||
- [ ] Trigger and bumper shortcuts documented if used
|
||||
- [ ] Controller disconnection while screen is open is handled gracefully
|
||||
|
||||
**Mouse**
|
||||
- [ ] Hover states defined for all interactive elements
|
||||
- [ ] Clickable hit targets are at minimum 32x32px (44x44px preferred)
|
||||
- [ ] Right-click behavior defined (context menu or no-op — not undefined)
|
||||
- [ ] Scroll wheel behavior defined in all scrollable zones
|
||||
|
||||
**Touch (if applicable)**
|
||||
- [ ] All touch targets are minimum 44x44px
|
||||
- [ ] Swipe gestures do not conflict with system-level swipe navigation
|
||||
- [ ] All actions achievable with one hand in portrait orientation
|
||||
- [ ] Long-press behavior defined if used
|
||||
|
||||
---
|
||||
|
||||
## 12. Screen-Level Accessibility Requirements
|
||||
|
||||
> **Why this section exists**: Accessibility requirements must be specified at design
|
||||
> time because retrofitting them is expensive and often architecturally impractical.
|
||||
> This section documents requirements specific to this screen. Project-wide standards
|
||||
> live in `docs/accessibility-requirements.md` — consult it before filling this
|
||||
> section so you do not duplicate or contradict project-level commitments.
|
||||
>
|
||||
> Accessibility Tiers in this project:
|
||||
> - Basic: WCAG 2.1 AA text contrast, keyboard navigable, no motion-only information
|
||||
> - Standard: Basic + screen reader support, colorblind-safe, focus management
|
||||
> - Comprehensive: Standard + reduced motion support, text scaling, high contrast mode
|
||||
> - Exemplary: Comprehensive + cognitive load management, AAA equivalent, certified
|
||||
|
||||
**Text contrast requirements for this screen**:
|
||||
|
||||
| Text Element | Background Context | Required Ratio | Current Ratio | Pass? |
|
||||
|--------------|-------------------|---------------|---------------|-------|
|
||||
| [e.g., Item name in Detail Panel] | [Dark panel background ~#1a1a1a] | [4.5:1 (WCAG AA normal text)] | [TBD — verify in implementation] | [ ] |
|
||||
| [e.g., Category tab label — inactive] | [Mid-grey tab background] | [4.5:1] | [TBD] | [ ] |
|
||||
| [e.g., Category tab label — active] | [Accent color background] | [4.5:1] | [TBD] | [ ] |
|
||||
| [e.g., Action button label] | [Button color (varies by state)] | [4.5:1] | [TBD] | [ ] |
|
||||
| [e.g., Stat comparison delta (positive)] | [Detail panel] | [4.5:1 — do NOT rely on green color alone] | [TBD] | [ ] |
|
||||
|
||||
**Colorblind-unsafe elements and mitigations**:
|
||||
|
||||
| Element | Colorblind Risk | Mitigation |
|
||||
|---------|----------------|------------|
|
||||
| [e.g., Stat delta indicators (red/green for worse/better)] | [Red-green colorblindness (Deuteranopia) — most common form] | [Add arrow icons (↑ / ↓) and +/- prefix in addition to color. Color is a redundant, not sole, indicator.] |
|
||||
| [e.g., Item rarity color coding (grey/green/blue/purple/orange)] | [Multiple types — rarity color is a common industry failure] | [Add rarity name text label below icon. Color is supplemental only.] |
|
||||
|
||||
**Focus order** (Tab key sequence, numbered):
|
||||
|
||||
[e.g.,
|
||||
1. Back button (Header)
|
||||
2. Options button (Header)
|
||||
3. Category Tab 1 — Weapons
|
||||
4. Category Tab 2 — Armor
|
||||
5. Category Tab 3 — Consumables
|
||||
6. Category Tab 4 — Key Items
|
||||
7. Item Slot [0,0]
|
||||
8. Item Slot [0,1] ... (grid traverses left-to-right, top-to-bottom)
|
||||
9. Last item slot
|
||||
10. Equip button (Action Bar)
|
||||
11. Drop button (Action Bar)
|
||||
12. Compare button (Action Bar)
|
||||
13. Close button (Action Bar)
|
||||
→ Cycles back to Back button
|
||||
|
||||
Focus does not enter the Detail Panel — it is a display panel driven by item focus, not independently navigable.]
|
||||
|
||||
**Screen reader announcements for key state changes**:
|
||||
|
||||
| State Change | Announcement Text | Announcement Timing |
|
||||
|--------------|------------------|---------------------|
|
||||
| [Screen opens] | ["Inventory screen. [N] items. [Active category] selected."] | [On screen focus settle] |
|
||||
| [Player focuses an item slot] | ["[Item name]. [Category]. [Rarity]. [Key stats summary]. [Equipped / Not equipped]."] | [On focus arrival] |
|
||||
| [Player equips an item] | ["[Item name] equipped to [slot name]."] | [After EquipmentChanged event confirmed] |
|
||||
| [Player drops an item] | ["[Item name] dropped."] | [After InventoryChanged event confirmed] |
|
||||
| [Category changes] | ["[Category name]. [N] items."] | [On category tab focus] |
|
||||
| [Empty state shown] | ["No items in [category name]."] | [When empty state renders] |
|
||||
|
||||
**Cognitive load assessment**:
|
||||
|
||||
[Estimate the number of information streams the player is simultaneously tracking while
|
||||
using this screen. For this screen: (1) item grid position, (2) item detail stats,
|
||||
(3) current equipment loadout for comparison, (4) available actions, (5) item category.
|
||||
That is 5 concurrent streams — within the standard 7±2 limit, but at the higher end.
|
||||
Mitigation: detail panel auto-updates on navigation so the player never needs to
|
||||
manually retrieve item info. Reduce active decisions by surfacing stat comparison
|
||||
automatically.]
|
||||
|
||||
---
|
||||
|
||||
## 13. Localization Considerations
|
||||
|
||||
> **Why this section exists**: UI built without localization in mind breaks on first
|
||||
> translation. German text is typically 30–40% longer than English. Arabic and Hebrew
|
||||
> require right-to-left layout mirroring. Japanese and Chinese text may be significantly
|
||||
> shorter than English, creating awkward whitespace. These issues are cheap to plan for
|
||||
> and expensive to fix after a layout is built and shipped. Every text element should
|
||||
> have an explicit max-character count and a plan for overflow.
|
||||
|
||||
**General rules for this screen**:
|
||||
- All text elements must tolerate a minimum of 40% expansion from English baseline
|
||||
- RTL layout (Arabic, Hebrew): mirrored layout required — document which elements mirror and which do not
|
||||
- CJK languages (Japanese, Korean, Chinese): text may be 20-30% shorter — verify layouts do not look broken with less text
|
||||
- Do not use text in images — all text must be from localization strings
|
||||
|
||||
| Text Element | English Baseline Length | Max Characters | Expansion Budget | RTL Behavior | Overflow Behavior | Risk |
|
||||
|--------------|------------------------|----------------|-----------------|--------------|-------------------|------|
|
||||
| [e.g., Screen title "INVENTORY"] | [9 chars] | [16 chars] | [78%] | [Mirror to right, or center — acceptable] | [Truncate with ellipsis — title is not critical content] | [Low] |
|
||||
| [e.g., Item name] | [~15 chars avg, max ~35 "Enchanted Dragon Scale Gauntlets"] | [50 chars] | [43%] | [Right-align in RTL layouts] | [Truncate with tooltip showing full name on hover/focus] | [Medium — long fantasy item names are common] |
|
||||
| [e.g., Item description] | [~80–120 chars] | [200 chars] | [67%] | [Right-align, wrap normally] | [Scroll within Detail Panel — no truncation] | [Low — panel is scrollable] |
|
||||
| [e.g., Action button "Equip"] | [5 chars] | [14 chars] | [180%] | [Button layout mirrors; text right-aligns] | [Shrink font to 90% minimum, then truncate] | [Medium — "Ausrüsten" in German is 9 chars] |
|
||||
| [e.g., Category tab "Consumables"] | [11 chars] | [18 chars] | [64%] | [Mirror tab position] | [Abbreviate: "Consum." — define abbreviations per language in loc file] | [High — long localized tab labels are a known problem] |
|
||||
|
||||
---
|
||||
|
||||
## 14. Acceptance Criteria
|
||||
|
||||
> **Why this section exists**: Acceptance criteria are the contractual definition of
|
||||
> "done." Without them, implementation is complete when the developer says it is.
|
||||
> With them, implementation is complete when a QA tester can verify every item on
|
||||
> this list. Write criteria that a tester can verify independently, without asking the
|
||||
> designer what they meant. Every criterion should be binary — pass or fail, not
|
||||
> subjective.
|
||||
|
||||
**Performance**
|
||||
- [ ] Screen opens (first frame visible) within 200ms of trigger on minimum-spec hardware
|
||||
- [ ] Screen is fully interactive (all data loaded) within 500ms of trigger on minimum-spec hardware
|
||||
- [ ] Navigation between items produces no perceptible frame drop (maintain target framerate ±5fps)
|
||||
|
||||
**Layout & Rendering**
|
||||
- [ ] Screen displays correctly (no overlap, no cutoff, no overflow) at minimum supported resolution [specify]
|
||||
- [ ] Screen displays correctly at maximum supported resolution [specify]
|
||||
- [ ] Screen displays correctly at 4:3, 16:9, 16:10, and 21:9 aspect ratios if targeting PC
|
||||
- [ ] No text overflow or truncation in English within defined max-character bounds
|
||||
- [ ] No text overflow or truncation in the longest-translation language [specify — typically German]
|
||||
- [ ] All states (Loading, Empty, Populated, Error, Confirmation) render correctly
|
||||
- [ ] Item grid scrolls smoothly without frame drops when all item slots are populated
|
||||
|
||||
**Input**
|
||||
- [ ] All interactive elements reachable by keyboard using Tab and arrow keys only
|
||||
- [ ] All interactive elements reachable by gamepad using D-Pad and face buttons only
|
||||
- [ ] All interactive elements reachable by mouse without keyboard
|
||||
- [ ] No action requires simultaneous input that is not documented in Section 7
|
||||
- [ ] Focus is visible at all times on keyboard and gamepad navigation
|
||||
- [ ] Focus does not escape the screen while it is open
|
||||
|
||||
**Events & Data**
|
||||
- [ ] All events in Section 9 fire with correct payloads on all exit paths (verify with debug logging)
|
||||
- [ ] Screen does not write directly to any game system (verify: no direct state mutation calls)
|
||||
- [ ] Inventory changes persist correctly after screen is closed and reopened
|
||||
- [ ] Screen handles InventoryChanged events fired by other systems while it is open without crashing
|
||||
|
||||
**Accessibility**
|
||||
- [ ] All text passes minimum contrast ratios specified in Section 12
|
||||
- [ ] Stat comparison does not rely on color alone as the sole differentiator
|
||||
- [ ] Screen reader announces item name and key stats on focus (verify with platform screen reader)
|
||||
- [ ] Reduced motion setting results in instant transitions (no animated transitions)
|
||||
- [ ] High contrast mode (if applicable to Accessibility Tier) renders without visual breakage
|
||||
|
||||
**Localization**
|
||||
- [ ] No text element overflows its container in any supported language
|
||||
- [ ] RTL layout renders correctly (if RTL is a target language)
|
||||
- [ ] All text elements are driven by localization strings — no hardcoded display text
|
||||
|
||||
---
|
||||
|
||||
## 15. Open Questions
|
||||
|
||||
> Track unresolved design questions here. Each question should have a clear owner
|
||||
> and a deadline. An Approved spec must have zero open questions — move to a decision
|
||||
> or explicitly document the deferral rationale.
|
||||
|
||||
| Question | Owner | Deadline | Resolution |
|
||||
|----------|-------|----------|-----------|
|
||||
| [e.g., Should item comparison be automatic (always showing equipped stats) or player-triggered (press Compare)?] | [ui-designer] | [Sprint 4, Day 3] | [Pending] |
|
||||
| [e.g., Do we support controller cursor (free aim) in the item grid, or d-pad-only grid navigation?] | [lead-programmer + ui-designer] | [Sprint 4, Day 3] | [Pending — depends on ADR-0015 input model decision] |
|
||||
| [e.g., What is the game's item drop policy — permanent loss or drop-to-world?] | [systems-designer] | [Requires GDD update] | [Blocked on inventory GDD Edge Cases section] |
|
||||
| [e.g., Maximum inventory size — does the grid have a hard cap or is it infinite-scroll?] | [economy-designer] | [Sprint 3, Day 5] | [Pending] |
|
||||
169
.claude/docs/templates/vertical-slice-report.md
vendored
Normal file
169
.claude/docs/templates/vertical-slice-report.md
vendored
Normal file
@@ -0,0 +1,169 @@
|
||||
# Vertical Slice Report: [Concept Name]
|
||||
|
||||
> **Date**: [YYYY-MM-DD]
|
||||
> **Slice Duration**: [N days]
|
||||
> **Target Scope**: 3–5 minutes of polished, continuous gameplay
|
||||
> **Source GDD**: design/gdd/game-concept.md
|
||||
|
||||
---
|
||||
|
||||
## Validation Question
|
||||
|
||||
[The full game loop question this build was proving — both experience AND feasibility:
|
||||
"Does a player, starting from nothing, experience [core fantasy] within [N] minutes,
|
||||
without developer guidance — and can we build one such loop in [X] days at
|
||||
representative quality?"]
|
||||
|
||||
---
|
||||
|
||||
## Scope Built
|
||||
|
||||
[Systems implemented, art quality level, what was intentionally omitted.]
|
||||
|
||||
**Systems included:**
|
||||
- [System 1]
|
||||
- [System 2]
|
||||
- [...]
|
||||
|
||||
**Art/audio quality level:** [Placeholder / Representative / Near-shipping]
|
||||
**Shortcuts taken deliberately:** [List]
|
||||
**What was cut from original scope:** [List]
|
||||
|
||||
---
|
||||
|
||||
## Build Velocity Log
|
||||
|
||||
[Day-by-day record of what was completed. This is your real production rate data —
|
||||
use it in sprint planning.]
|
||||
|
||||
| Day | Completed |
|
||||
|-----|-----------|
|
||||
| Day 1 | [What was built] |
|
||||
| Day 2 | [What was built] |
|
||||
| Day 3 | [What was built] |
|
||||
| ... | ... |
|
||||
|
||||
**Total elapsed:** [N days] for [scope summary]
|
||||
**Velocity estimate:** [N hours per equivalent scope unit — e.g., "1 day per combat
|
||||
encounter, 0.5 days per UI screen"]
|
||||
|
||||
---
|
||||
|
||||
## Playtest Results
|
||||
|
||||
| Attribute | Value |
|
||||
|-----------|-------|
|
||||
| Total sessions | [N] |
|
||||
| Internal testers | [N] |
|
||||
| External testers | [N — people who had not seen the game, if available] |
|
||||
| Avg session length | [N minutes (target: [N] minutes)] |
|
||||
| Time to first meaningful action | [N seconds (target: [N] seconds)] |
|
||||
|
||||
---
|
||||
|
||||
## Observations
|
||||
|
||||
[Specific, non-opinion observations from playtest sessions. Quote testers where useful.]
|
||||
|
||||
**Where testers succeeded without guidance:**
|
||||
- [...]
|
||||
|
||||
**Where testers were confused or stuck:**
|
||||
- [...]
|
||||
|
||||
**Emotional reactions observed:**
|
||||
- [...]
|
||||
|
||||
---
|
||||
|
||||
## Metrics
|
||||
|
||||
| Metric | Target | Actual |
|
||||
|--------|--------|--------|
|
||||
| Time to first meaningful action | [N sec] | [N sec] |
|
||||
| Session length | [N min] | [N min] |
|
||||
| Critical fun blockers found | 0 | [N] |
|
||||
| Pipeline blockers found | 0 | [N] |
|
||||
| Architecture surprises | 0 | [N] |
|
||||
|
||||
**Feel assessment:** [Specific — "combat feedback weak; no impact sound on hit" not "felt rough"]
|
||||
|
||||
---
|
||||
|
||||
## Recommendation: [PROCEED / PIVOT / KILL]
|
||||
|
||||
[One paragraph with evidence — reference the validation question directly. Did a
|
||||
player experience the core fantasy within the target time, without developer guidance?
|
||||
Can the team build at this quality on the projected schedule?]
|
||||
|
||||
---
|
||||
|
||||
## If Proceeding
|
||||
|
||||
**Production requirements** (what must change from slice to production):
|
||||
- [e.g., "Replace placeholder art with shipped assets"]
|
||||
- [e.g., "Combat system needs 2 more weapon types"]
|
||||
|
||||
**Architecture adjustments needed:**
|
||||
- [ADR to update or create]
|
||||
|
||||
**Sprint velocity estimate based on slice data:**
|
||||
- [e.g., "1 day per enemy type, 2 days per level section, 0.5 days per UI screen"]
|
||||
|
||||
**Scope adjustments from original design:**
|
||||
- [What the slice revealed about the true production scope]
|
||||
|
||||
**Performance targets:** [Confirmed / Revised — list changes if revised]
|
||||
|
||||
**Playtest note:** Run `/playtest-report` to structure additional session data
|
||||
before running `/gate-check pre-production`.
|
||||
|
||||
**Next steps:**
|
||||
1. `/gate-check pre-production` — formally advance to Production
|
||||
2. `/create-epics layer:foundation` — plan Foundation layer epics
|
||||
3. `/create-epics layer:core` — plan Core layer epics
|
||||
4. `/sprint-plan` — use velocity data from this report in the estimate
|
||||
|
||||
---
|
||||
|
||||
## If Pivoting
|
||||
|
||||
[Which GDDs need revision and why — be specific about the failure mode observed.]
|
||||
|
||||
**Systems requiring GDD revision:** [List]
|
||||
**Architecture decisions to revisit:** [List — use `/architecture-decision` to update]
|
||||
**Core loop change needed:** [What specifically to change]
|
||||
|
||||
**Next steps:**
|
||||
1. `/design-system [mechanic]` — revise affected GDDs
|
||||
2. `/architecture-decision [decision]` — address architecture issues
|
||||
3. `/vertical-slice` — re-validate after revisions
|
||||
|
||||
---
|
||||
|
||||
## If Killing
|
||||
|
||||
[Why the full game loop does not work at this quality level. What specifically
|
||||
prevented the player from experiencing the core fantasy. What to do instead.]
|
||||
|
||||
**Next step:** `/brainstorm` to explore a new direction, or `/prototype [new-concept]`
|
||||
to test a different concept cheaply before investing in another vertical slice.
|
||||
|
||||
---
|
||||
|
||||
## Lessons Learned
|
||||
|
||||
- **What assumptions were broken by building to near-production quality?**
|
||||
[...]
|
||||
|
||||
- **What surprised us about the pipeline or architecture?**
|
||||
[...]
|
||||
|
||||
- **What would we change about the slice scope if we ran this again?**
|
||||
[...]
|
||||
|
||||
---
|
||||
|
||||
> *Vertical slice code location: `prototypes/[concept-name]-vertical-slice/`*
|
||||
> *This code is reference material only. Production implementation is written from scratch.*
|
||||
> *Never import or refactor this code into production.*
|
||||
Reference in New Issue
Block a user