claude-code-arcane 1.0.0

package/templates/gamedev/game-design-document.md

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

package/templates/gamedev/game-pillars.md

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