@zeyue0329/xiaoma-cli 1.0.8 → 1.0.10

package/expansion-packs/bmad-2d-unity-game-dev/templates/level-design-doc-tmpl.yaml

@@ -0,0 +1,485 @@
+# <!-- Powered by BMAD™ Core -->
+template:
+  id: level-design-doc-template-v2
+  name: Level Design Document
+  version: 2.1
+  output:
+    format: markdown
+    filename: docs/level-design-document.md
+    title: "{{game_title}} Level Design Document"
+
+workflow:
+  mode: interactive
+
+sections:
+  - id: initial-setup
+    instruction: |
+      This template creates comprehensive level design documentation that guides both content creation and technical implementation. This document should provide enough detail for developers to create level loading systems and for designers to create specific levels.
+
+      If available, review: Game Design Document (GDD), Game Architecture Document. This document should align with the game mechanics and technical systems defined in those documents.
+
+  - id: introduction
+    title: Introduction
+    instruction: Establish the purpose and scope of level design for this game
+    content: |
+      This document defines the level design framework for {{game_title}}, providing guidelines for creating engaging, balanced levels that support the core gameplay mechanics defined in the Game Design Document.
+
+      This framework ensures consistency across all levels while providing flexibility for creative level design within established technical and design constraints.
+    sections:
+      - id: change-log
+        title: Change Log
+        instruction: Track document versions and changes
+        type: table
+        template: |
+          | Date | Version | Description | Author |
+          | :--- | :------ | :---------- | :----- |
+
+  - id: level-design-philosophy
+    title: Level Design Philosophy
+    instruction: Establish the overall approach to level design based on the game's core pillars and mechanics. Apply `tasks#advanced-elicitation` after presenting this section.
+    sections:
+      - id: design-principles
+        title: Design Principles
+        instruction: Define 3-5 core principles that guide all level design decisions
+        type: numbered-list
+        template: |
+          **{{principle_name}}** - {{description}}
+      - id: player-experience-goals
+        title: Player Experience Goals
+        instruction: Define what players should feel and learn in each level category
+        template: |
+          **Tutorial Levels:** {{experience_description}}
+          **Standard Levels:** {{experience_description}}
+          **Challenge Levels:** {{experience_description}}
+          **Boss Levels:** {{experience_description}}
+      - id: level-flow-framework
+        title: Level Flow Framework
+        instruction: Define the standard structure for level progression
+        template: |
+          **Introduction Phase:** {{duration}} - {{purpose}}
+          **Development Phase:** {{duration}} - {{purpose}}
+          **Climax Phase:** {{duration}} - {{purpose}}
+          **Resolution Phase:** {{duration}} - {{purpose}}
+
+  - id: level-categories
+    title: Level Categories
+    instruction: Define different types of levels based on the GDD requirements. Each category should be specific enough for implementation.
+    repeatable: true
+    sections:
+      - id: level-category
+        title: "{{category_name}} Levels"
+        template: |
+          **Purpose:** {{gameplay_purpose}}
+
+          **Target Duration:** {{min_time}} - {{max_time}} minutes
+
+          **Difficulty Range:** {{difficulty_scale}}
+
+          **Key Mechanics Featured:**
+
+          - {{mechanic_1}} - {{usage_description}}
+          - {{mechanic_2}} - {{usage_description}}
+
+          **Player Objectives:**
+
+          - Primary: {{primary_objective}}
+          - Secondary: {{secondary_objective}}
+          - Hidden: {{secret_objective}}
+
+          **Success Criteria:**
+
+          - {{completion_requirement_1}}
+          - {{completion_requirement_2}}
+
+          **Technical Requirements:**
+
+          - Maximum entities: {{entity_limit}}
+          - Performance target: {{fps_target}} FPS
+          - Memory budget: {{memory_limit}}MB
+          - Asset requirements: {{asset_needs}}
+
+  - id: level-progression-system
+    title: Level Progression System
+    instruction: Define how players move through levels and how difficulty scales
+    sections:
+      - id: world-structure
+        title: World Structure
+        instruction: Based on GDD requirements, define the overall level organization
+        template: |
+          **Organization Type:** {{linear|hub_world|open_world}}
+
+          **Total Level Count:** {{number}}
+
+          **World Breakdown:**
+
+          - World 1: {{level_count}} levels - {{theme}} - {{difficulty_range}}
+          - World 2: {{level_count}} levels - {{theme}} - {{difficulty_range}}
+          - World 3: {{level_count}} levels - {{theme}} - {{difficulty_range}}
+      - id: difficulty-progression
+        title: Difficulty Progression
+        instruction: Define how challenge increases across the game
+        sections:
+          - id: progression-curve
+            title: Progression Curve
+            type: code
+            language: text
+            template: |
+              Difficulty
+                  ^     ___/```
+                  |    /
+                  |   /     ___/```
+                  |  /     /
+                  | /     /
+                  |/     /
+                  +-----------> Level Number
+                 Tutorial  Early  Mid  Late
+          - id: scaling-parameters
+            title: Scaling Parameters
+            type: bullet-list
+            template: |
+              - Enemy count: {{start_count}} → {{end_count}}
+              - Enemy difficulty: {{start_diff}} → {{end_diff}}
+              - Level complexity: {{start_complex}} → {{end_complex}}
+              - Time pressure: {{start_time}} → {{end_time}}
+      - id: unlock-requirements
+        title: Unlock Requirements
+        instruction: Define how players access new levels
+        template: |
+          **Progression Gates:**
+
+          - Linear progression: Complete previous level
+          - Star requirements: {{star_count}} stars to unlock
+          - Skill gates: Demonstrate {{skill_requirement}}
+          - Optional content: {{unlock_condition}}
+
+  - id: level-design-components
+    title: Level Design Components
+    instruction: Define the building blocks used to create levels
+    sections:
+      - id: environmental-elements
+        title: Environmental Elements
+        instruction: Define all environmental components that can be used in levels
+        template: |
+          **Terrain Types:**
+
+          - {{terrain_1}}: {{properties_and_usage}}
+          - {{terrain_2}}: {{properties_and_usage}}
+
+          **Interactive Objects:**
+
+          - {{object_1}}: {{behavior_and_purpose}}
+          - {{object_2}}: {{behavior_and_purpose}}
+
+          **Hazards and Obstacles:**
+
+          - {{hazard_1}}: {{damage_and_behavior}}
+          - {{hazard_2}}: {{damage_and_behavior}}
+      - id: collectibles-rewards
+        title: Collectibles and Rewards
+        instruction: Define all collectible items and their placement rules
+        template: |
+          **Collectible Types:**
+
+          - {{collectible_1}}: {{value_and_purpose}}
+          - {{collectible_2}}: {{value_and_purpose}}
+
+          **Placement Guidelines:**
+
+          - Mandatory collectibles: {{placement_rules}}
+          - Optional collectibles: {{placement_rules}}
+          - Secret collectibles: {{placement_rules}}
+
+          **Reward Distribution:**
+
+          - Easy to find: {{percentage}}%
+          - Moderate challenge: {{percentage}}%
+          - High skill required: {{percentage}}%
+      - id: enemy-placement-framework
+        title: Enemy Placement Framework
+        instruction: Define how enemies should be placed and balanced in levels
+        template: |
+          **Enemy Categories:**
+
+          - {{enemy_type_1}}: {{behavior_and_usage}}
+          - {{enemy_type_2}}: {{behavior_and_usage}}
+
+          **Placement Principles:**
+
+          - Introduction encounters: {{guideline}}
+          - Standard encounters: {{guideline}}
+          - Challenge encounters: {{guideline}}
+
+          **Difficulty Scaling:**
+
+          - Enemy count progression: {{scaling_rule}}
+          - Enemy type introduction: {{pacing_rule}}
+          - Encounter complexity: {{complexity_rule}}
+
+  - id: level-creation-guidelines
+    title: Level Creation Guidelines
+    instruction: Provide specific guidelines for creating individual levels
+    sections:
+      - id: level-layout-principles
+        title: Level Layout Principles
+        template: |
+          **Spatial Design:**
+
+          - Grid size: {{grid_dimensions}}
+          - Minimum path width: {{width_units}}
+          - Maximum vertical distance: {{height_units}}
+          - Safe zones placement: {{safety_guidelines}}
+
+          **Navigation Design:**
+
+          - Clear path indication: {{visual_cues}}
+          - Landmark placement: {{landmark_rules}}
+          - Dead end avoidance: {{dead_end_policy}}
+          - Multiple path options: {{branching_rules}}
+      - id: pacing-and-flow
+        title: Pacing and Flow
+        instruction: Define how to control the rhythm and pace of gameplay within levels
+        template: |
+          **Action Sequences:**
+
+          - High intensity duration: {{max_duration}}
+          - Rest period requirement: {{min_rest_time}}
+          - Intensity variation: {{pacing_pattern}}
+
+          **Learning Sequences:**
+
+          - New mechanic introduction: {{teaching_method}}
+          - Practice opportunity: {{practice_duration}}
+          - Skill application: {{application_context}}
+      - id: challenge-design
+        title: Challenge Design
+        instruction: Define how to create appropriate challenges for each level type
+        template: |
+          **Challenge Types:**
+
+          - Execution challenges: {{skill_requirements}}
+          - Puzzle challenges: {{complexity_guidelines}}
+          - Time challenges: {{time_pressure_rules}}
+          - Resource challenges: {{resource_management}}
+
+          **Difficulty Calibration:**
+
+          - Skill check frequency: {{frequency_guidelines}}
+          - Failure recovery: {{retry_mechanics}}
+          - Hint system integration: {{help_system}}
+
+  - id: technical-implementation
+    title: Technical Implementation
+    instruction: Define technical requirements for level implementation
+    sections:
+      - id: level-data-structure
+        title: Level Data Structure
+        instruction: Define how level data should be structured for implementation
+        template: |
+          **Level File Format:**
+
+          - Data format: {{json|yaml|custom}}
+          - File naming: `level_{{world}}_{{number}}.{{extension}}`
+          - Data organization: {{structure_description}}
+        sections:
+          - id: required-data-fields
+            title: Required Data Fields
+            type: code
+            language: json
+            template: |
+              {
+                "levelId": "{{unique_identifier}}",
+                "worldId": "{{world_identifier}}",
+                "difficulty": {{difficulty_value}},
+                "targetTime": {{completion_time_seconds}},
+                "objectives": {
+                  "primary": "{{primary_objective}}",
+                  "secondary": ["{{secondary_objectives}}"],
+                  "hidden": ["{{secret_objectives}}"]
+                },
+                "layout": {
+                  "width": {{grid_width}},
+                  "height": {{grid_height}},
+                  "tilemap": "{{tilemap_reference}}"
+                },
+                "entities": [
+                  {
+                    "type": "{{entity_type}}",
+                    "position": {"x": {{x}}, "y": {{y}}},
+                    "properties": {{entity_properties}}
+                  }
+                ]
+              }
+      - id: asset-integration
+        title: Asset Integration
+        instruction: Define how level assets are organized and loaded
+        template: |
+          **Tilemap Requirements:**
+
+          - Tile size: {{tile_dimensions}}px
+          - Tileset organization: {{tileset_structure}}
+          - Layer organization: {{layer_system}}
+          - Collision data: {{collision_format}}
+
+          **Audio Integration:**
+
+          - Background music: {{music_requirements}}
+          - Ambient sounds: {{ambient_system}}
+          - Dynamic audio: {{dynamic_audio_rules}}
+      - id: performance-optimization
+        title: Performance Optimization
+        instruction: Define performance requirements for level systems
+        template: |
+          **Entity Limits:**
+
+          - Maximum active entities: {{entity_limit}}
+          - Maximum particles: {{particle_limit}}
+          - Maximum audio sources: {{audio_limit}}
+
+          **Memory Management:**
+
+          - Texture memory budget: {{texture_memory}}MB
+          - Audio memory budget: {{audio_memory}}MB
+          - Level loading time: <{{load_time}}s
+
+          **Culling and LOD:**
+
+          - Off-screen culling: {{culling_distance}}
+          - Level-of-detail rules: {{lod_system}}
+          - Asset streaming: {{streaming_requirements}}
+
+  - id: level-testing-framework
+    title: Level Testing Framework
+    instruction: Define how levels should be tested and validated
+    sections:
+      - id: automated-testing
+        title: Automated Testing
+        template: |
+          **Performance Testing:**
+
+          - Frame rate validation: Maintain {{fps_target}} FPS
+          - Memory usage monitoring: Stay under {{memory_limit}}MB
+          - Loading time verification: Complete in <{{load_time}}s
+
+          **Gameplay Testing:**
+
+          - Completion path validation: All objectives achievable
+          - Collectible accessibility: All items reachable
+          - Softlock prevention: No unwinnable states
+      - id: manual-testing-protocol
+        title: Manual Testing Protocol
+        sections:
+          - id: playtesting-checklist
+            title: Playtesting Checklist
+            type: checklist
+            items:
+              - Level completes within target time range
+              - All mechanics function correctly
+              - Difficulty feels appropriate for level category
+              - Player guidance is clear and effective
+              - No exploits or sequence breaks (unless intended)
+          - id: player-experience-testing
+            title: Player Experience Testing
+            type: checklist
+            items:
+              - Tutorial levels teach effectively
+              - Challenge feels fair and rewarding
+              - Flow and pacing maintain engagement
+              - Audio and visual feedback support gameplay
+      - id: balance-validation
+        title: Balance Validation
+        template: |
+          **Metrics Collection:**
+
+          - Completion rate: Target {{completion_percentage}}%
+          - Average completion time: {{target_time}} ± {{variance}}
+          - Death count per level: <{{max_deaths}}
+          - Collectible discovery rate: {{discovery_percentage}}%
+
+          **Iteration Guidelines:**
+
+          - Adjustment criteria: {{criteria_for_changes}}
+          - Testing sample size: {{minimum_testers}}
+          - Validation period: {{testing_duration}}
+
+  - id: content-creation-pipeline
+    title: Content Creation Pipeline
+    instruction: Define the workflow for creating new levels
+    sections:
+      - id: design-phase
+        title: Design Phase
+        template: |
+          **Concept Development:**
+
+          1. Define level purpose and goals
+          2. Create rough layout sketch
+          3. Identify key mechanics and challenges
+          4. Estimate difficulty and duration
+
+          **Documentation Requirements:**
+
+          - Level design brief
+          - Layout diagrams
+          - Mechanic integration notes
+          - Asset requirement list
+      - id: implementation-phase
+        title: Implementation Phase
+        template: |
+          **Technical Implementation:**
+
+          1. Create level data file
+          2. Build tilemap and layout
+          3. Place entities and objects
+          4. Configure level logic and triggers
+          5. Integrate audio and visual effects
+
+          **Quality Assurance:**
+
+          1. Automated testing execution
+          2. Internal playtesting
+          3. Performance validation
+          4. Bug fixing and polish
+      - id: integration-phase
+        title: Integration Phase
+        template: |
+          **Game Integration:**
+
+          1. Level progression integration
+          2. Save system compatibility
+          3. Analytics integration
+          4. Achievement system integration
+
+          **Final Validation:**
+
+          1. Full game context testing
+          2. Performance regression testing
+          3. Platform compatibility verification
+          4. Final approval and release
+
+  - id: success-metrics
+    title: Success Metrics
+    instruction: Define how to measure level design success
+    sections:
+      - id: player-engagement
+        title: Player Engagement
+        type: bullet-list
+        template: |
+          - Level completion rate: {{target_rate}}%
+          - Replay rate: {{replay_target}}%
+          - Time spent per level: {{engagement_time}}
+          - Player satisfaction scores: {{satisfaction_target}}/10
+      - id: technical-performance
+        title: Technical Performance
+        type: bullet-list
+        template: |
+          - Frame rate consistency: {{fps_consistency}}%
+          - Loading time compliance: {{load_compliance}}%
+          - Memory usage efficiency: {{memory_efficiency}}%
+          - Crash rate: <{{crash_threshold}}%
+      - id: design-quality
+        title: Design Quality
+        type: bullet-list
+        template: |
+          - Difficulty curve adherence: {{curve_accuracy}}
+          - Mechanic integration effectiveness: {{integration_score}}
+          - Player guidance clarity: {{guidance_score}}
+          - Content accessibility: {{accessibility_rate}}%

package/expansion-packs/bmad-2d-unity-game-dev/workflows/game-dev-greenfield.yaml

@@ -0,0 +1,184 @@
+# <!-- Powered by BMAD™ Core -->
+workflow:
+  id: unity-game-dev-greenfield
+  name: Game Development - Greenfield Project (Unity)
+  description: Specialized workflow for creating 2D games from concept to implementation using Unity and C#. Guides teams through game concept development, design documentation, technical architecture, and story-driven development for professional game development.
+  type: greenfield
+  project_types:
+    - indie-game
+    - mobile-game
+    - web-game
+    - educational-game
+    - prototype-game
+    - game-jam
+  full_game_sequence:
+    - agent: game-designer
+      creates: game-brief.md
+      optional_steps:
+        - brainstorming_session
+        - game_research_prompt
+        - player_research
+      notes: "Start with brainstorming game concepts, then create comprehensive game brief. SAVE OUTPUT: Copy final game-brief.md to your project's docs/design/ folder."
+    - agent: game-designer
+      creates: game-design-doc.md
+      requires: game-brief.md
+      optional_steps:
+        - competitive_analysis
+        - technical_research
+      notes: "Create detailed Game Design Document using game-design-doc-tmpl. Defines all gameplay mechanics, progression, and technical requirements. SAVE OUTPUT: Copy final game-design-doc.md to your project's docs/design/ folder."
+    - agent: game-designer
+      creates: level-design-doc.md
+      requires: game-design-doc.md
+      optional_steps:
+        - level_prototyping
+        - difficulty_analysis
+      notes: "Create level design framework using level-design-doc-tmpl. Establishes content creation guidelines and performance requirements. SAVE OUTPUT: Copy final level-design-doc.md to your project's docs/design/ folder."
+    - agent: solution-architect
+      creates: game-architecture.md
+      requires:
+        - game-design-doc.md
+        - level-design-doc.md
+      optional_steps:
+        - technical_research_prompt
+        - performance_analysis
+        - platform_research
+      notes: "Create comprehensive technical architecture using game-architecture-tmpl. Defines Unity systems, performance optimization, and code structure. SAVE OUTPUT: Copy final game-architecture.md to your project's docs/architecture/ folder."
+    - agent: game-designer
+      validates: design_consistency
+      requires: all_design_documents
+      uses: game-design-checklist
+      notes: Validate all design documents for consistency, completeness, and implementability. May require updates to any design document.
+    - agent: various
+      updates: flagged_design_documents
+      condition: design_validation_issues
+      notes: If design validation finds issues, return to relevant agent to fix and re-export updated documents to docs/ folder.
+  project_setup_guidance:
+    action: guide_game_project_structure
+    notes: Set up Unity project structure following game architecture document. Create Assets/ with subdirectories for Scenes, Scripts, Prefabs, etc.
+  workflow_end:
+    action: move_to_story_development
+    notes: All design artifacts complete. Begin story-driven development phase. Use Game Scrum Master to create implementation stories from design documents.
+  prototype_sequence:
+    - step: prototype_scope
+      action: assess_prototype_complexity
+      notes: First, assess if this needs full game design (use full_game_sequence) or can be a rapid prototype.
+    - agent: game-designer
+      creates: game-brief.md
+      optional_steps:
+        - quick_brainstorming
+        - concept_validation
+      notes: "Create focused game brief for prototype. Emphasize core mechanics and immediate playability. SAVE OUTPUT: Copy final game-brief.md to your project's docs/ folder."
+    - agent: game-designer
+      creates: prototype-design.md
+      uses: create-doc prototype-design OR create-game-story
+      requires: game-brief.md
+      notes: Create minimal design document or jump directly to implementation stories for rapid prototyping. Choose based on prototype complexity.
+  prototype_workflow_end:
+    action: move_to_rapid_implementation
+    notes: Prototype defined. Begin immediate implementation with Game Developer. Focus on core mechanics first, then iterate based on playtesting.
+  flow_diagram: |
+    ```mermaid
+    graph TD
+        A[Start: Game Development Project] --> B{Project Scope?}
+        B -->|Full Game/Production| C[game-designer: game-brief.md]
+        B -->|Prototype/Game Jam| D[game-designer: focused game-brief.md]
+
+        C --> E[game-designer: game-design-doc.md]
+        E --> F[game-designer: level-design-doc.md]
+        F --> G[solution-architect: game-architecture.md]
+        G --> H[game-designer: validate design consistency]
+        H --> I{Design validation issues?}
+        I -->|Yes| J[Return to relevant agent for fixes]
+        I -->|No| K[Set up game project structure]
+        J --> H
+        K --> L[Move to Story Development Phase]
+
+        D --> M[game-designer: prototype-design.md]
+        M --> N[Move to Rapid Implementation]
+
+        C -.-> C1[Optional: brainstorming]
+        C -.-> C2[Optional: game research]
+        E -.-> E1[Optional: competitive analysis]
+        F -.-> F1[Optional: level prototyping]
+        G -.-> G1[Optional: technical research]
+        D -.-> D1[Optional: quick brainstorming]
+
+        style L fill:#90EE90
+        style N fill:#90EE90
+        style C fill:#FFE4B5
+        style E fill:#FFE4B5
+        style F fill:#FFE4B5
+        style G fill:#FFE4B5
+        style D fill:#FFB6C1
+        style M fill:#FFB6C1
+    ```
+  decision_guidance:
+    use_full_sequence_when:
+      - Building commercial or production games
+      - Multiple team members involved
+      - Complex gameplay systems (3+ core mechanics)
+      - Long-term development timeline (2+ months)
+      - Need comprehensive documentation for team coordination
+      - Targeting multiple platforms
+      - Educational or enterprise game projects
+    use_prototype_sequence_when:
+      - Game jams or time-constrained development
+      - Solo developer or very small team
+      - Experimental or proof-of-concept games
+      - Simple mechanics (1-2 core systems)
+      - Quick validation of game concepts
+      - Learning projects or technical demos
+  handoff_prompts:
+    designer_to_gdd: Game brief is complete. Save it as docs/design/game-brief.md in your project, then create the comprehensive Game Design Document.
+    gdd_to_level: Game Design Document ready. Save it as docs/design/game-design-doc.md, then create the level design framework.
+    level_to_architect: Level design complete. Save it as docs/design/level-design-doc.md, then create the technical architecture.
+    architect_review: Architecture complete. Save it as docs/architecture/game-architecture.md. Please validate all design documents for consistency.
+    validation_issues: Design validation found issues with [document]. Please return to [agent] to fix and re-save the updated document.
+    full_complete: All design artifacts validated and saved. Set up game project structure and move to story development phase.
+    prototype_designer_to_dev: Prototype brief complete. Save it as docs/game-brief.md, then create minimal design or jump directly to implementation stories.
+    prototype_complete: Prototype defined. Begin rapid implementation focusing on core mechanics and immediate playability.
+  story_development_guidance:
+    epic_breakdown:
+      - Core Game Systems" - Fundamental gameplay mechanics and player controls
+      - Level Content" - Individual levels, progression, and content implementation
+      - User Interface" - Menus, HUD, settings, and player feedback systems
+      - Audio Integration" - Music, sound effects, and audio systems
+      - Performance Optimization" - Platform optimization and technical polish
+      - Game Polish" - Visual effects, animations, and final user experience
+    story_creation_process:
+      - Use Game Scrum Master to create detailed implementation stories
+      - Each story should reference specific GDD sections
+      - Include performance requirements (stable frame rate)
+      - Specify Unity implementation details (components, prefabs, scenes)
+      - Apply game-story-dod-checklist for quality validation
+      - Ensure stories are immediately actionable by Game Developer
+  game_development_best_practices:
+    performance_targets:
+      - Maintain stable frame rate on target devices throughout development
+      - Memory usage under specified limits per game system
+      - Loading times under 3 seconds for levels
+      - Smooth animation and responsive player controls
+    technical_standards:
+      - C# best practices compliance
+      - Component-based game architecture
+      - Object pooling for performance-critical objects
+      - Cross-platform input handling with the new Input System
+      - Comprehensive error handling and graceful degradation
+    playtesting_integration:
+      - Test core mechanics early and frequently
+      - Validate game balance through metrics and player feedback
+      - Iterate on design based on implementation discoveries
+      - Document design changes and rationale
+  success_criteria:
+    design_phase_complete:
+      - All design documents created and validated
+      - Technical architecture aligns with game design requirements
+      - Performance targets defined and achievable
+      - Story breakdown ready for implementation
+      - Project structure established
+    implementation_readiness:
+      - Development environment configured for Unity + C#
+      - Asset pipeline and build system established
+      - Testing framework in place
+      - Team roles and responsibilities defined
+      - First implementation stories created and ready