BMAD-METHOD/expansion-packs/bmad-godot-game-dev/templates/level-design-doc-tmpl.yaml

template:
  id: godot-level-design-doc-template-v3
  name: Godot Level Design Document
  version: 3.0
  output:
    format: markdown
    filename: docs/godot-level-design-document.md
    title: "{{game_title}} Godot Level Design Document"

workflow:
  mode: interactive

sections:
  - id: initial-setup
    instruction: |
      This template creates comprehensive Godot level design documentation focusing on scene structure, TileMap implementation, and performance optimization (60+ FPS). This document provides detail for creating Godot scenes (.tscn), implementing node hierarchies, and optimizing with object pooling.

      If available, review: Game Design Document (GDD), Game Architecture Document, Language Strategy (GDScript vs C#). This document must align with 60+ FPS performance requirements and TDD practices (GUT/GoDotTest).

  - id: introduction
    title: Introduction
    instruction: Establish the purpose and scope of level design for this game
    content: |
      This document defines the Godot level design framework for {{game_title}}, providing guidelines for creating performant, engaging levels using Godot's scene system, TileMap nodes, and Area2D/3D collision systems while maintaining 60+ FPS.

      This framework ensures consistency across all level scenes (.tscn) while leveraging Godot's node inheritance, scene instancing, and object pooling for optimal performance.
    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 with performance targets
        template: |
          **Introduction Phase:** {{duration}} - {{purpose}} - Target: 60+ FPS
          **Development Phase:** {{duration}} - {{purpose}} - Object pooling active
          **Climax Phase:** {{duration}} - {{purpose}} - Peak performance critical
          **Resolution Phase:** {{duration}} - {{purpose}} - Scene cleanup required

  - 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}}

          **Godot Technical Requirements:**

          - Maximum nodes: {{node_limit}} active nodes
          - Performance target: 60+ FPS mandatory (frame time <16.67ms)
          - Memory budget: {{memory_limit}}MB scene memory
          - Draw calls: <{{draw_call_limit}} for level geometry
          - Object pools: Required for {{spawned_entities}}
          - Language: {{GDScript|C#}} for level logic - {{reason}}

  - 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: Define the Godot scene organization and resource structure
        template: |
          **Scene Organization:** {{linear|hub_world|open_world}}

          **Total Level Scenes:** {{number}} .tscn files

          **World Scene Breakdown:**

          - World 1: {{level_count}} scenes - res://levels/world1/ - {{difficulty_range}}
          - World 2: {{level_count}} scenes - res://levels/world2/ - {{difficulty_range}}
          - World 3: {{level_count}} scenes - res://levels/world3/ - {{difficulty_range}}

          **Scene Loading:** < 3 seconds with loading screen if needed
          **Scene Instancing:** Use PackedScene for repeated elements
      - 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}} (pooled)
              - Enemy difficulty: {{start_diff}} → {{end_diff}}
              - Level complexity: {{start_complex}} → {{end_complex}}
              - Time pressure: {{start_time}} → {{end_time}}
              - Performance impact: Must maintain 60+ FPS at peak
      - 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 Godot nodes and resources for level components
        template: |
          **TileMap Layers:**

          - Background: TileMap node - {{tile_size}}px tiles
          - Collision: TileMap with physics layers
          - Foreground: TileMap for overlays

          **Interactive Nodes:**

          - {{node_1}}: Area2D/3D - {{signals_emitted}}
          - {{node_2}}: RigidBody2D/3D - {{physics_properties}}

          **Hazard Nodes:**

          - {{hazard_1}}: Area2D with damage signal
          - {{hazard_2}}: AnimationPlayer for moving hazards

          **Performance:** All interactive elements use object pooling
      - 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 enemy node placement and pooling strategies
        template: |
          **Enemy Scene Types:**

          - {{enemy_scene_1}}.tscn: {{node_type}} - {{ai_behavior}}
          - {{enemy_scene_2}}.tscn: {{node_type}} - {{ai_behavior}}

          **Godot Placement Methods:**

          - Spawn Points: Position2D/3D markers in scene
          - Dynamic Spawning: Object pool with max {{pool_size}}
          - Wave System: Timer-based with performance monitoring

          **Performance Scaling:**

          - Max active enemies: {{max_count}} to maintain 60+ FPS
          - LOD system: Disable AI beyond {{distance}} units
          - Pooling strategy: Reuse instances, never instantiate in gameplay

  - id: level-creation-guidelines
    title: Level Creation Guidelines
    instruction: Provide specific guidelines for creating individual levels
    sections:
      - id: level-layout-principles
        title: Godot Level Layout Principles
        template: |
          **TileMap Design:**

          - Tile size: {{tile_size}}x{{tile_size}} pixels
          - Grid dimensions: {{grid_width}}x{{grid_height}} tiles
          - Collision layers: {{collision_layer_count}}
          - Autotiling: {{autotile_enabled}} for efficiency

          **Node-Based Navigation:**

          - Navigation2D/3D setup: {{nav_mesh_config}}
          - Path2D for guided movement
          - Area2D triggers for zone transitions
          - Position2D markers for spawn points

          **Performance Layout:**
          - Chunk size for streaming: {{chunk_size}}
          - Occlusion culling setup: {{occlusion_config}}
          - Draw call optimization: Batch similar tiles
      - 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: Godot Technical Implementation
    instruction: Define Godot-specific technical requirements for level scenes
    sections:
      - id: level-scene-structure
        title: Level Scene Structure
        instruction: Define Godot scene hierarchy and resource organization
        template: |
          **Scene File Format:**

          - File type: .tscn (Godot scene)
          - Naming: `level_{{world}}_{{number}}.tscn`
          - Location: res://levels/{{world}}/
          - Resource format: .tres for level data

          **Scene Hierarchy:**
          ```
          Level (Node2D/Spatial)
          ├── TileMap (background)
          ├── TileMap (collision)
          ├── TileMap (foreground)
          ├── Entities (Node2D)
          │   ├── Enemies (pooled)
          │   └── Pickups (pooled)
          ├── Triggers (Node2D)
          └── LevelLogic (Node with script)
          ```
        sections:
          - id: level-resource-data
            title: Level Resource Data (.tres)
            type: code
            language: gdscript
            template: |
              # LevelData.gd - extends Resource
              class_name LevelData
              extends Resource

              @export var level_id: String = "{{unique_identifier}}"
              @export var world_id: String = "{{world_identifier}}"
              @export var difficulty: float = {{difficulty_value}}
              @export var target_time: float = {{completion_time_seconds}}
              @export var target_fps: int = 60  # Mandatory

              @export var objectives: Dictionary = {
                  "primary": "{{primary_objective}}",
                  "secondary": ["{{secondary_objectives}}"],
                  "hidden": ["{{secret_objectives}}"]
              }

              @export var performance_limits: Dictionary = {
                  "max_enemies": {{enemy_pool_size}},
                  "max_particles": {{particle_limit}},
                  "max_draw_calls": {{draw_call_limit}}
              }

              # Entity spawn data
              @export var spawn_points: Array[Vector2] = []
              @export var enemy_waves: Array[Resource] = []
      - id: godot-asset-integration
        title: Godot Asset Integration
        instruction: Define how Godot resources and assets are organized
        template: |
          **TileSet Resource:**

          - Resource path: res://tilesets/{{tileset_name}}.tres
          - Tile size: {{tile_dimensions}}x{{tile_dimensions}}px
          - Physics layers: {{collision_layers}}
          - Autotile setup: {{autotile_config}}
          - Custom data layers: {{custom_properties}}

          **Audio Integration:**

          - AudioStreamPlayer2D for positional audio
          - Audio bus: "Level" for volume control
          - Stream format: .ogg for music, .wav for SFX
          - Preload critical sounds to avoid frame drops

          **Texture Import Settings:**
          - Filter: Nearest (for pixel art) or Linear
          - Mipmaps: Disabled for 2D, Enabled for 3D
          - Compression: Lossless for important visuals
      - id: godot-performance-optimization
        title: Godot Performance Optimization
        instruction: Define Godot-specific optimization for 60+ FPS
        template: |
          **Node Limits (for 60+ FPS):**

          - Maximum active nodes: {{node_limit}}
          - Maximum physics bodies: {{physics_limit}}
          - Maximum particles: {{particle_limit}} (use GPUParticles2D/3D)
          - Maximum lights: {{light_limit}}

          **Memory Management:**

          - Scene memory budget: {{scene_memory}}MB
          - Texture memory: {{texture_memory}}MB
          - Object pooling: Mandatory for all spawned entities
          - Scene loading: <3 seconds (show loading screen if longer)

          **Godot Optimization Techniques:**

          - VisibilityEnabler2D/3D for automatic culling
          - LOD using visibility ranges
          - Static body optimization for non-moving collision
          - YSort for efficient 2D depth sorting
          - Multimesh for repeated elements

          **Language Strategy:**
          - Level logic: GDScript with static typing
          - Performance-critical systems: C# (no LINQ)

  - id: godot-level-patterns
    title: Godot Level Design Patterns
    instruction: Document common Godot patterns for level implementation
    sections:
      - id: scene-inheritance
        title: Scene Inheritance Pattern
        template: |
          **Base Level Scene:**
          - res://levels/base_level.tscn
          - Contains common nodes (UI, pause, music)
          - Child scenes inherit and override

          **Inherited Scenes:**
          - Each level extends base_level.tscn
          - Override specific properties
          - Maintain 60+ FPS through shared resources
      - id: tilemap-patterns
        title: TileMap Best Practices
        template: |
          **Layer Organization:**
          - Background: Decorative, no collision
          - Collision: Physics bodies, one-way platforms
          - Foreground: Overlay effects

          **Autotiling Setup:**
          - 3x3 minimal or 16-tile for complex terrain
          - Custom data for gameplay properties
          - Collision shapes optimized per tile
      - id: spawning-patterns
        title: Entity Spawning Patterns
        template: |
          **Object Pooling (Mandatory):**
          ```gdscript
          # Enemy pool manager
          var enemy_pool: Array = []
          var max_enemies: int = {{max_count}}

          func _ready() -> void:
              # Pre-instantiate enemies
              for i in max_enemies:
                  var enemy = enemy_scene.instantiate()
                  enemy.set_process(false)
                  enemy_pool.append(enemy)
          ```

          **Spawn Points:**
          - Use Position2D/3D markers
          - Group spawn points for wave management
          - Signal when spawn completes
      - id: performance-patterns
        title: Performance Optimization Patterns
        template: |
          **Visibility Management:**
          - VisibilityEnabler2D for off-screen culling
          - LOD groups for distance-based quality
          - Disable process for inactive entities

          **Memory Management:**
          - Preload frequently used resources
          - Queue_free() with object pool return
          - Signal cleanup in _exit_tree()

          **Draw Call Batching:**
          - Use same material/shader where possible
          - Batch static geometry
          - Minimize transparent overdraw

  - 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 (GUT/GoDotTest):**

          - Frame rate validation: Must maintain 60+ FPS
          - Frame time monitoring: <16.67ms average
          - Memory leak detection: Check signal cleanup
          - Object pool verification: Ensure recycling works
          - Loading time: <3 seconds per scene

          **Gameplay Testing (TDD Approach):**

          - Write GUT tests for level completion paths
          - Test all Area2D triggers fire correctly
          - Verify collectible spawn points accessible
          - Test enemy AI with performance monitoring
          - Validate all signals connect/disconnect properly
      - id: manual-testing-protocol
        title: Manual Testing Protocol
        sections:
          - id: playtesting-checklist
            title: Godot Playtesting Checklist
            type: checklist
            items:
              - Level maintains 60+ FPS throughout gameplay
              - TileMap collision works correctly
              - All Area2D triggers activate properly
              - Object pooling functions without hiccups
              - Scene transitions take <3 seconds
              - Input responsiveness <50ms (3 frames)
              - No memory leaks from signals
              - Navigation mesh pathfinding works
          - 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: |
          **Godot Metrics Collection:**

          - FPS consistency: >95% of time at 60+ FPS
          - Completion rate: Target {{completion_percentage}}%
          - Average completion time: {{target_time}} ± {{variance}}
          - Object pool efficiency: >90% reuse rate
          - Draw calls per level: <{{draw_call_target}}

          **Performance-Based Iteration:**

          - If FPS drops: Reduce active enemies/particles
          - If loading slow: Optimize texture imports
          - If memory high: Check for signal leaks
          - Testing with Godot profiler mandatory

  - id: content-creation-pipeline
    title: Godot Level Creation Pipeline
    instruction: Define the workflow for creating new Godot level scenes
    sections:
      - id: design-phase
        title: Design Phase
        template: |
          **Concept Development:**

          1. Define level goals and performance targets (60+ FPS)
          2. Sketch TileMap layout and node placement
          3. Plan object pooling for spawned entities
          4. Choose language (GDScript vs C#) for level logic
          5. Estimate memory and draw call budget

          **Godot Documentation Requirements:**

          - Level scene hierarchy diagram
          - TileSet resource requirements
          - Signal flow documentation
          - Performance budget allocation
          - TDD test plan (GUT/GoDotTest)
      - id: implementation-phase
        title: Godot Implementation Phase
        template: |
          **Scene Creation (TDD Approach):**

          1. Write GUT tests for level mechanics (RED phase)
          2. Create level scene (.tscn) structure
          3. Build TileMap layers (collision, visual, background)
          4. Implement object pools for enemies/pickups
          5. Add Area2D triggers and signals (GREEN phase)
          6. Configure Navigation2D mesh
          7. Optimize with static typing (REFACTOR phase)

          **Godot Quality Assurance:**

          1. Run GUT/GoDotTest suites
          2. Profile with Godot debugger (60+ FPS check)
          3. Verify object pooling efficiency
          4. Check memory usage and draw calls
          5. Test on minimum spec hardware
      - id: integration-phase
        title: Godot Integration Phase
        template: |
          **Scene Integration:**

          1. Add to level scene autoload manager
          2. Connect to game state signals
          3. Integrate with save system (user:// path)
          4. Link achievements via signal system
          5. Set up scene transitions (<3 seconds)

          **Final Godot Validation:**

          1. Test scene in full game context
          2. Verify 60+ FPS with all systems active
          3. Export template testing (all platforms)
          4. Check InputMap works for all devices
          5. Validate object pools don't leak memory

  - id: success-metrics
    title: Godot Level Success Metrics
    instruction: Define metrics for level design success with performance focus
    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: {{satisfaction_target}}/10
          - Input responsiveness: <50ms feedback
      - id: godot-performance
        title: Godot Technical Performance
        type: bullet-list
        template: |
          - Frame rate: 60+ FPS maintained {{fps_consistency}}%
          - Frame time: <16.67ms average
          - Scene loading: <3 seconds {{load_compliance}}%
          - Memory efficiency: {{memory_efficiency}}%
          - Object pool reuse: >90% efficiency
          - Draw calls: Within budget {{draw_compliance}}%
          - Signal leaks: 0 tolerance
          - Crash rate: <{{crash_threshold}}%
      - id: design-quality
        title: Design Quality
        type: bullet-list
        template: |
          - Difficulty curve adherence: {{curve_accuracy}}
          - Node architecture efficiency: {{node_score}}
          - TileMap optimization: {{tilemap_score}}
          - Signal flow clarity: {{signal_score}}
          - TDD coverage: >80% (GUT/GoDotTest)
          - Language strategy appropriateness: {{language_score}}
          - Content accessibility: {{accessibility_rate}}%