Game Systems Documentation

Create professional AAA-quality game design documents with consistent structure, cross-referencing, and implementation-ready specifications.

Document Hierarchy

Required Sections by Document Type

System Design Document (Minigames, Core Loops)

1. OVERVIEW
   - System Name & Codename
   - Design Pillars (3-5 guiding principles)
   - Player Fantasy (what experience this delivers)
   - Dependencies (other systems this touches)

2. CORE LOOP
   - Primary loop diagram (Mermaid or ASCII)
   - Session flow with timing
   - Win/loss states and triggers

3. MECHANICS SPECIFICATION
   - Input mechanics (player actions)
   - Processing mechanics (game calculations)
   - Output mechanics (feedback/rewards)
   - Edge cases and failure states

4. ECONOMY INTEGRATION
   - Currency inputs (what players spend)
   - Currency outputs (what players earn)
   - Sink/faucet balance
   - Cross-system influence maps

5. PROGRESSION
   - Unlock conditions
   - Difficulty scaling
   - Mastery indicators

6. UI/UX REQUIREMENTS
   - Screen inventory
   - Key interactions
   - Animation requirements
   - Audio cues

7. TECHNICAL NOTES
   - Data structures
   - State management
   - API endpoints needed
   - Performance considerations

8. METRICS & ANALYTICS
   - KPIs to track
   - A/B test opportunities
   - Balancing levers

9. APPENDICES
   - Probability tables
   - Payout matrices
   - Reference materials

Feature Brief Template

FEATURE: [Name]
STATUS: [Concept | In Design | Ready for Dev | In Development]
OWNER: [Designer name]
VERSION: [X.X]

PROBLEM STATEMENT
What player need does this address?

SOLUTION OVERVIEW
High-level description (2-3 sentences)

SUCCESS CRITERIA
- Metric 1: [target]
- Metric 2: [target]

SCOPE
In Scope:
- Item 1
- Item 2

Out of Scope:
- Item 1

DEPENDENCIES
- System/Feature it requires
- System/Feature it affects

DETAILED SPECIFICATION
[Body of the feature design]

OPEN QUESTIONS
- [ ] Question 1
- [ ] Question 2

Cross-Reference Standards

Use consistent ID formatting for traceability:

• Systems: SYS-[ABBREV]-[NUM] (e.g., SYS-TULIP-001)
• Features: FEAT-[ABBREV]-[NUM] (e.g., FEAT-WAGER-012)
• Mechanics: MECH-[ABBREV]-[NUM] (e.g., MECH-CARD-003)
• UI Screens: UI-[ABBREV]-[NUM] (e.g., UI-HUD-007)

Reference format in documents: [See SYS-TULIP-001] or [Ref: FEAT-WAGER-012]

Diagram Standards

Use Mermaid for:

• Flow diagrams (game loops, player journeys)
• State machines (game states, UI states)
• Sequence diagrams (multiplayer interactions, API calls)
• Entity relationship diagrams (data models)

Example loop diagram:

graph TD
    A[Session Start] --> B[Place Wager]
    B --> C[Deal Cards]
    C --> D{Player Decision}
    D -->|Hit| C
    D -->|Stand| E[Dealer Plays]
    E --> F{Outcome}
    F -->|Win| G[Payout + Farm Bonus]
    F -->|Lose| H[Consolation Mechanic]
    G --> I[Session End]
    H --> I

Probability & Payout Tables

Format all gambling mechanics with:

Always include:

• Theoretical RTP (Return to Player)
• House edge calculation
• Variance classification (Low/Medium/High)
• Hit frequency

Writing Standards

• Use active voice and imperative mood
• Present tense for mechanics ("Player taps to confirm")
• Future tense for implementation notes ("System will validate...")
• Specific numbers over vague terms ("3 seconds" not "a few seconds")
• Define all jargon on first use

Farming in Purria Conventions

Project-specific standards:

• Seasons: 42-day cycles, reference as Day X of [Season]
• Currency tiers: Petals (soft) → Seeds (premium) → Bulbs (ultra-rare)
• Simulin naming: [Function]-[Generation] (e.g., Harvester-Mk3)
• Card sessions: Always specify table (Tulip Hold'em, Hexfield Fortune, etc.)
• Influence mapping: Document card→farm effects with INFLUENCE-[ID]

Quality Checklist

Before finalizing any document:

• All sections have content (no TBDs in shipped docs)
• Cross-references resolve to existing documents
• Numbers are specific and justified
• Diagrams render correctly
• Economy math is validated
• Edge cases are addressed
• Implementation notes are actionable
• Version number is updated

For detailed templates, see references/templates.md