feat: Finished extended architecture documentation needed for new game story tasks

expansion-packs/bmad-2d-unity-game-dev/checklists/game-architect-checklist.md

@@ -120,6 +120,23 @@ Ask the user if they want to work through the checklist:
 - [ ] Input system using Unity's new Input System is outlined
 - [ ] UI system using Unity's UI Toolkit or UGUI is determined
 - [ ] Scene management and loading architecture is clear
+- [ ] Gameplay systems architecture covers core game mechanics and player interactions
+- [ ] Component architecture details define MonoBehaviour and ScriptableObject patterns
+- [ ] Physics configuration for Unity 2D is comprehensively defined
+- [ ] State machine architecture covers game states, player states, and entity behaviors
+- [ ] UI component system and data binding patterns are established
+- [ ] UI state management across screens and game states is defined
+- [ ] Data persistence and save system architecture is fully specified
+- [ ] Analytics integration approach is defined (if applicable)
+- [ ] Multiplayer architecture is detailed (if applicable)
+- [ ] Rendering pipeline configuration and optimization strategies are clear
+- [ ] Shader guidelines and performance considerations are documented
+- [ ] Sprite management and optimization strategies are defined
+- [ ] Particle system architecture and performance budgets are established
+- [ ] Audio architecture includes system design and category management
+- [ ] Audio mixing configuration with Unity AudioMixer is detailed
+- [ ] Sound bank management and asset organization is specified
+- [ ] Unity development conventions and best practices are documented
 
 ### 3.3 Data Architecture & Game Balance
 

expansion-packs/bmad-2d-unity-game-dev/data/development-guidelines.md

@@ -9,15 +9,18 @@ This document establishes coding standards, architectural patterns, and developm
 ### Naming Conventions
 
 **Classes, Structs, Enums, and Interfaces:**
+
 - PascalCase for types: `PlayerController`, `GameData`, `IInteractable`
 - Prefix interfaces with 'I': `IDamageable`, `IControllable`
 - Descriptive names that indicate purpose: `GameStateManager` not `GSM`
 
 **Methods and Properties:**
+
 - PascalCase for methods and properties: `CalculateScore()`, `CurrentHealth`
 - Descriptive verb phrases for methods: `ActivateShield()` not `shield()`
 
 **Fields and Variables:**
+
 - `private` or `protected` fields: camelCase with an underscore prefix: `_playerHealth`, `_movementSpeed`
 - `public` fields (use sparingly, prefer properties): PascalCase: `PlayerName`
 - `static` fields: PascalCase: `Instance`, `GameVersion`
@@ -26,6 +29,7 @@ This document establishes coding standards, architectural patterns, and developm
 - Boolean variables with is/has/can prefix: `_isAlive`, `_hasKey`, `_canJump`
 
 **Files and Directories:**
+
 - PascalCase for C# script files, matching the primary class name: `PlayerController.cs`
 - PascalCase for Scene files: `MainMenu.unity`, `Level01.unity`
 
@@ -39,7 +43,9 @@ This document establishes coding standards, architectural patterns, and developm
 ## Unity Architecture Patterns
 
 ### Scene Lifecycle Management
+
 **Loading and Transitioning Between Scenes:**
+
 ```csharp
 // SceneLoader.cs - A singleton for managing scene transitions.
 using UnityEngine;
@@ -97,7 +103,9 @@ public class SceneLoader : MonoBehaviour
 ```
 
 ### MonoBehaviour Lifecycle
+
 **Understanding Core MonoBehaviour Events:**
+
 ```csharp
 // Example of a standard MonoBehaviour lifecycle
 using UnityEngine;
@@ -138,7 +146,7 @@ public class PlayerController : MonoBehaviour
     {
         // Handle input and non-physics movement here.
     }
-    
+
     // LATEUPDATE: Called every frame, after all Update functions have been called.
     // Good for camera logic that needs to track a target that moves in Update.
     private void LateUpdate()
@@ -165,6 +173,7 @@ public class PlayerController : MonoBehaviour
 ### Game Object Patterns
 
 **Component-Based Architecture:**
+
 ```csharp
 // Player.cs - The main GameObject class, acts as a container for components.
 using UnityEngine;
@@ -214,6 +223,7 @@ public class PlayerHealth : MonoBehaviour
 ### Data-Driven Design with ScriptableObjects
 
 **Define Data Containers:**
+
 ```csharp
 // EnemyData.cs - A ScriptableObject to hold data for an enemy type.
 using UnityEngine;
@@ -239,7 +249,7 @@ public class Enemy : MonoBehaviour
         _currentHealth = _enemyData.maxHealth;
         GetComponent<SpriteRenderer>().sprite = _enemyData.sprite;
     }
-    
+
     // ... other enemy logic
 }
 ```
@@ -247,6 +257,7 @@ public class Enemy : MonoBehaviour
 ### System Management
 
 **Singleton Managers:**
+
 ```csharp
 // GameManager.cs - A singleton to manage the overall game state.
 using UnityEngine;
@@ -280,6 +291,7 @@ public class GameManager : MonoBehaviour
 ### Object Pooling
 
 **Required for High-Frequency Objects (e.g., bullets, effects):**
+
 ```csharp
 // ObjectPool.cs - A generic object pooling system.
 using UnityEngine;
@@ -325,10 +337,12 @@ public class ObjectPool : MonoBehaviour
 ### Frame Rate Optimization
 
 **Update Loop Optimization:**
+
 - Avoid expensive calls like `GetComponent`, `FindObjectOfType`, or `Instantiate` inside `Update()` or `FixedUpdate()`. Cache references in `Awake()` or `Start()`.
 - Use Coroutines or simple timers for logic that doesn't need to run every single frame.
 
 **Physics Optimization:**
+
 - Adjust the "Physics 2D Settings" in Project Settings, especially the "Layer Collision Matrix", to prevent unnecessary collision checks.
 - Use `Rigidbody2D.Sleep()` for objects that are not moving to save CPU cycles.
 
@@ -339,6 +353,7 @@ public class ObjectPool : MonoBehaviour
 **Input Action Asset:** Create an Input Action Asset (`.inputactions`) to define controls.
 
 **PlayerInput Component:**
+
 - Add the `PlayerInput` component to the player GameObject.
 - Set its "Actions" to the created Input Action Asset.
 - Set "Behavior" to "Invoke Unity Events" to easily hook up methods in the Inspector, or "Send Messages" to use methods like `OnMove`, `OnFire`.
@@ -372,7 +387,9 @@ public class PlayerInputHandler : MonoBehaviour
 ### Graceful Degradation
 
 **Asset Loading Error Handling:**
+
 - When using Addressables or `Resources.Load`, always check if the loaded asset is null before using it.
+
 ```csharp
 // Load a sprite and use a fallback if it fails
 Sprite playerSprite = Resources.Load<Sprite>("Sprites/Player");
@@ -386,8 +403,10 @@ if (playerSprite == null)
 ### Runtime Error Recovery
 
 **Assertions and Logging:**
+
 - Use `Debug.Assert(condition, "Message")` to check for critical conditions that must be true.
 - Use `Debug.LogError("Message")` for fatal errors and `Debug.LogWarning("Message")` for non-critical issues.
+
 ```csharp
 // Example of using an assertion to ensure a component exists.
 private Rigidbody2D _rb;
@@ -404,6 +423,7 @@ void Awake()
 ### Unit Testing (Edit Mode)
 
 **Game Logic Testing:**
+
 ```csharp
 // HealthSystemTests.cs - Example test for a simple health system.
 using NUnit.Framework;
@@ -418,7 +438,7 @@ public class HealthSystemTests
         var gameObject = new GameObject();
         var healthSystem = gameObject.AddComponent<PlayerHealth>();
         // Note: This is a simplified example. You might need to mock dependencies.
-        
+
         // Act
         healthSystem.TakeDamage(20);
 
@@ -432,8 +452,10 @@ public class HealthSystemTests
 ### Integration Testing (Play Mode)
 
 **Scene Testing:**
+
 - Play Mode tests run in a live scene, allowing you to test interactions between multiple components and systems.
 - Use `yield return null;` to wait for the next frame.
+
 ```csharp
 // PlayerJumpTest.cs
 using System.Collections;
@@ -453,7 +475,7 @@ public class PlayerJumpTest
         // Act
         // Simulate pressing the jump button (requires setting up the input system for tests)
         // For simplicity, we'll call a public method here.
-        // player.Jump(); 
+        // player.Jump();
 
         // Wait for a few physics frames
         yield return new WaitForSeconds(0.5f);

expansion-packs/bmad-2d-unity-game-dev/templates/game-architecture-tmpl.yaml

@@ -244,6 +244,486 @@ sections:
           - Sequence diagrams for complex game loops (Update, FixedUpdate flows)
           Choose the most appropriate for clarity and Unity-specific understanding
 
+  - id: gameplay-systems
+    title: Gameplay Systems Architecture
+    instruction: |
+      Define the core gameplay systems that drive the player experience. Focus on game-specific logic and mechanics.
+    elicit: true
+    sections:
+      - id: gameplay-overview
+        title: Gameplay Systems Overview
+        template: |
+          **Core Game Loop:** {{core_game_loop_description}}
+
+          **Player Actions:** {{primary_player_actions}}
+
+          **Game State Flow:** {{game_state_transitions}}
+      - id: gameplay-components
+        title: Gameplay Component Architecture
+        template: |
+          **Player Controller Components:**
+          - {{player_controller_components}}
+
+          **Game Logic Components:**
+          - {{game_logic_components}}
+
+          **Interaction Systems:**
+          - {{interaction_system_components}}
+
+  - id: component-architecture
+    title: Component Architecture Details
+    instruction: |
+      Define detailed Unity component architecture patterns and conventions for the game.
+    elicit: true
+    sections:
+      - id: monobehaviour-patterns
+        title: MonoBehaviour Patterns
+        template: |
+          **Component Composition:** {{component_composition_approach}}
+
+          **Lifecycle Management:** {{lifecycle_management_patterns}}
+
+          **Component Communication:** {{component_communication_methods}}
+      - id: scriptableobject-usage
+        title: ScriptableObject Architecture
+        template: |
+          **Data Architecture:** {{scriptableobject_data_patterns}}
+
+          **Configuration Management:** {{config_scriptableobject_usage}}
+
+          **Runtime Data:** {{runtime_scriptableobject_patterns}}
+
+  - id: physics-config
+    title: Physics Configuration
+    instruction: |
+      Define Unity 2D physics setup and configuration for the game.
+    elicit: true
+    sections:
+      - id: physics-settings
+        title: Physics Settings
+        template: |
+          **Physics 2D Settings:** {{physics_2d_configuration}}
+
+          **Collision Layers:** {{collision_layer_matrix}}
+
+          **Physics Materials:** {{physics_materials_setup}}
+      - id: rigidbody-patterns
+        title: Rigidbody Patterns
+        template: |
+          **Player Physics:** {{player_rigidbody_setup}}
+
+          **Object Physics:** {{object_physics_patterns}}
+
+          **Performance Optimization:** {{physics_optimization_strategies}}
+
+  - id: input-system
+    title: Input System Architecture
+    instruction: |
+      Define input handling using Unity's Input System package.
+    elicit: true
+    sections:
+      - id: input-actions
+        title: Input Actions Configuration
+        template: |
+          **Input Action Assets:** {{input_action_asset_structure}}
+
+          **Action Maps:** {{input_action_maps}}
+
+          **Control Schemes:** {{control_schemes_definition}}
+      - id: input-handling
+        title: Input Handling Patterns
+        template: |
+          **Player Input:** {{player_input_component_usage}}
+
+          **UI Input:** {{ui_input_handling_patterns}}
+
+          **Input Validation:** {{input_validation_strategies}}
+
+  - id: state-machines
+    title: State Machine Architecture
+    instruction: |
+      Define state machine patterns for game states, player states, and AI behavior.
+    elicit: true
+    sections:
+      - id: game-state-machine
+        title: Game State Machine
+        template: |
+          **Game States:** {{game_state_definitions}}
+
+          **State Transitions:** {{game_state_transition_rules}}
+
+          **State Management:** {{game_state_manager_implementation}}
+      - id: entity-state-machines
+        title: Entity State Machines
+        template: |
+          **Player States:** {{player_state_machine_design}}
+
+          **AI Behavior States:** {{ai_state_machine_patterns}}
+
+          **Object States:** {{object_state_management}}
+
+  - id: ui-architecture
+    title: UI Architecture
+    instruction: |
+      Define Unity UI system architecture using UGUI or UI Toolkit.
+    elicit: true
+    sections:
+      - id: ui-system-choice
+        title: UI System Selection
+        template: |
+          **UI Framework:** {{ui_framework_choice}} (UGUI/UI Toolkit)
+
+          **UI Scaling:** {{ui_scaling_strategy}}
+
+          **Canvas Setup:** {{canvas_configuration}}
+      - id: ui-navigation
+        title: UI Navigation System
+        template: |
+          **Screen Management:** {{screen_management_system}}
+
+          **Navigation Flow:** {{ui_navigation_patterns}}
+
+          **Back Button Handling:** {{back_button_implementation}}
+
+  - id: ui-components
+    title: UI Component System
+    instruction: |
+      Define reusable UI components and their implementation patterns.
+    elicit: true
+    sections:
+      - id: ui-component-library
+        title: UI Component Library
+        template: |
+          **Base Components:** {{base_ui_components}}
+
+          **Custom Components:** {{custom_ui_components}}
+
+          **Component Prefabs:** {{ui_prefab_organization}}
+      - id: ui-data-binding
+        title: UI Data Binding
+        template: |
+          **Data Binding Patterns:** {{ui_data_binding_approach}}
+
+          **UI Events:** {{ui_event_system}}
+
+          **View Model Patterns:** {{ui_viewmodel_implementation}}
+
+  - id: ui-state-management
+    title: UI State Management
+    instruction: |
+      Define how UI state is managed across the game.
+    elicit: true
+    sections:
+      - id: ui-state-patterns
+        title: UI State Patterns
+        template: |
+          **State Persistence:** {{ui_state_persistence}}
+
+          **Screen State:** {{screen_state_management}}
+
+          **UI Configuration:** {{ui_configuration_management}}
+
+  - id: scene-management
+    title: Scene Management Architecture
+    instruction: |
+      Define scene loading, unloading, and transition strategies.
+    elicit: true
+    sections:
+      - id: scene-structure
+        title: Scene Structure
+        template: |
+          **Scene Organization:** {{scene_organization_strategy}}
+
+          **Scene Hierarchy:** {{scene_hierarchy_patterns}}
+
+          **Persistent Scenes:** {{persistent_scene_usage}}
+      - id: scene-loading
+        title: Scene Loading System
+        template: |
+          **Loading Strategies:** {{scene_loading_patterns}}
+
+          **Async Loading:** {{async_scene_loading_implementation}}
+
+          **Loading Screens:** {{loading_screen_management}}
+
+  - id: data-persistence
+    title: Data Persistence Architecture
+    instruction: |
+      Define save system and data persistence strategies.
+    elicit: true
+    sections:
+      - id: save-data-structure
+        title: Save Data Structure
+        template: |
+          **Save Data Models:** {{save_data_model_design}}
+
+          **Serialization Format:** {{serialization_format_choice}}
+
+          **Data Validation:** {{save_data_validation}}
+      - id: persistence-strategy
+        title: Persistence Strategy
+        template: |
+          **Save Triggers:** {{save_trigger_events}}
+
+          **Auto-Save:** {{auto_save_implementation}}
+
+          **Cloud Save:** {{cloud_save_integration}}
+
+  - id: save-system
+    title: Save System Implementation
+    instruction: |
+      Define detailed save system implementation patterns.
+    elicit: true
+    sections:
+      - id: save-load-api
+        title: Save/Load API
+        template: |
+          **Save Interface:** {{save_interface_design}}
+
+          **Load Interface:** {{load_interface_design}}
+
+          **Error Handling:** {{save_load_error_handling}}
+      - id: save-file-management
+        title: Save File Management
+        template: |
+          **File Structure:** {{save_file_structure}}
+
+          **Backup Strategy:** {{save_backup_strategy}}
+
+          **Migration:** {{save_data_migration_strategy}}
+
+  - id: analytics-integration
+    title: Analytics Integration
+    instruction: |
+      Define analytics tracking and integration patterns.
+    condition: Game requires analytics tracking
+    elicit: true
+    sections:
+      - id: analytics-events
+        title: Analytics Event Design
+        template: |
+          **Event Categories:** {{analytics_event_categories}}
+
+          **Custom Events:** {{custom_analytics_events}}
+
+          **Player Progression:** {{progression_analytics}}
+      - id: analytics-implementation
+        title: Analytics Implementation
+        template: |
+          **Analytics SDK:** {{analytics_sdk_choice}}
+
+          **Event Tracking:** {{event_tracking_patterns}}
+
+          **Privacy Compliance:** {{analytics_privacy_considerations}}
+
+  - id: multiplayer-architecture
+    title: Multiplayer Architecture
+    instruction: |
+      Define multiplayer system architecture if applicable.
+    condition: Game includes multiplayer features
+    elicit: true
+    sections:
+      - id: networking-approach
+        title: Networking Approach
+        template: |
+          **Networking Solution:** {{networking_solution_choice}}
+
+          **Architecture Pattern:** {{multiplayer_architecture_pattern}}
+
+          **Synchronization:** {{state_synchronization_strategy}}
+      - id: multiplayer-systems
+        title: Multiplayer System Components
+        template: |
+          **Client Components:** {{multiplayer_client_components}}
+
+          **Server Components:** {{multiplayer_server_components}}
+
+          **Network Messages:** {{network_message_design}}
+
+  - id: rendering-pipeline
+    title: Rendering Pipeline Configuration
+    instruction: |
+      Define Unity rendering pipeline setup and optimization.
+    elicit: true
+    sections:
+      - id: render-pipeline-setup
+        title: Render Pipeline Setup
+        template: |
+          **Pipeline Choice:** {{render_pipeline_choice}} (URP/Built-in)
+
+          **Pipeline Asset:** {{render_pipeline_asset_config}}
+
+          **Quality Settings:** {{quality_settings_configuration}}
+      - id: rendering-optimization
+        title: Rendering Optimization
+        template: |
+          **Batching Strategies:** {{sprite_batching_optimization}}
+
+          **Draw Call Optimization:** {{draw_call_reduction_strategies}}
+
+          **Texture Optimization:** {{texture_optimization_settings}}
+
+  - id: shader-guidelines
+    title: Shader Guidelines
+    instruction: |
+      Define shader usage and custom shader guidelines.
+    elicit: true
+    sections:
+      - id: shader-usage
+        title: Shader Usage Patterns
+        template: |
+          **Built-in Shaders:** {{builtin_shader_usage}}
+
+          **Custom Shaders:** {{custom_shader_requirements}}
+
+          **Shader Variants:** {{shader_variant_management}}
+      - id: shader-performance
+        title: Shader Performance Guidelines
+        template: |
+          **Mobile Optimization:** {{mobile_shader_optimization}}
+
+          **Performance Budgets:** {{shader_performance_budgets}}
+
+          **Profiling Guidelines:** {{shader_profiling_approach}}
+
+  - id: sprite-management
+    title: Sprite Management
+    instruction: |
+      Define sprite asset management and optimization strategies.
+    elicit: true
+    sections:
+      - id: sprite-organization
+        title: Sprite Organization
+        template: |
+          **Atlas Strategy:** {{sprite_atlas_organization}}
+
+          **Sprite Naming:** {{sprite_naming_conventions}}
+
+          **Import Settings:** {{sprite_import_settings}}
+      - id: sprite-optimization
+        title: Sprite Optimization
+        template: |
+          **Compression Settings:** {{sprite_compression_settings}}
+
+          **Resolution Strategy:** {{sprite_resolution_strategy}}
+
+          **Memory Optimization:** {{sprite_memory_optimization}}
+
+  - id: particle-systems
+    title: Particle System Architecture
+    instruction: |
+      Define particle system usage and optimization.
+    elicit: true
+    sections:
+      - id: particle-design
+        title: Particle System Design
+        template: |
+          **Effect Categories:** {{particle_effect_categories}}
+
+          **Prefab Organization:** {{particle_prefab_organization}}
+
+          **Pooling Strategy:** {{particle_pooling_implementation}}
+      - id: particle-performance
+        title: Particle Performance
+        template: |
+          **Performance Budgets:** {{particle_performance_budgets}}
+
+          **Mobile Optimization:** {{particle_mobile_optimization}}
+
+          **LOD Strategy:** {{particle_lod_implementation}}
+
+  - id: audio-architecture
+    title: Audio Architecture
+    instruction: |
+      Define audio system architecture and implementation.
+    elicit: true
+    sections:
+      - id: audio-system-design
+        title: Audio System Design
+        template: |
+          **Audio Manager:** {{audio_manager_implementation}}
+
+          **Audio Sources:** {{audio_source_management}}
+
+          **3D Audio:** {{spatial_audio_implementation}}
+      - id: audio-categories
+        title: Audio Categories
+        template: |
+          **Music System:** {{music_system_architecture}}
+
+          **Sound Effects:** {{sfx_system_design}}
+
+          **Voice/Dialog:** {{dialog_system_implementation}}
+
+  - id: audio-mixing
+    title: Audio Mixing Configuration
+    instruction: |
+      Define Unity Audio Mixer setup and configuration.
+    elicit: true
+    sections:
+      - id: mixer-setup
+        title: Audio Mixer Setup
+        template: |
+          **Mixer Groups:** {{audio_mixer_group_structure}}
+
+          **Effects Chain:** {{audio_effects_configuration}}
+
+          **Snapshot System:** {{audio_snapshot_usage}}
+      - id: dynamic-mixing
+        title: Dynamic Audio Mixing
+        template: |
+          **Volume Control:** {{volume_control_implementation}}
+
+          **Dynamic Range:** {{dynamic_range_management}}
+
+          **Platform Optimization:** {{platform_audio_optimization}}
+
+  - id: sound-banks
+    title: Sound Bank Management
+    instruction: |
+      Define sound asset organization and loading strategies.
+    elicit: true
+    sections:
+      - id: sound-organization
+        title: Sound Asset Organization
+        template: |
+          **Bank Structure:** {{sound_bank_organization}}
+
+          **Loading Strategy:** {{audio_loading_patterns}}
+
+          **Memory Management:** {{audio_memory_management}}
+      - id: sound-streaming
+        title: Audio Streaming
+        template: |
+          **Streaming Strategy:** {{audio_streaming_implementation}}
+
+          **Compression Settings:** {{audio_compression_settings}}
+
+          **Platform Considerations:** {{platform_audio_considerations}}
+
+  - id: unity-conventions
+    title: Unity Development Conventions
+    instruction: |
+      Define Unity-specific development conventions and best practices.
+    elicit: true
+    sections:
+      - id: unity-best-practices
+        title: Unity Best Practices
+        template: |
+          **Component Design:** {{unity_component_best_practices}}
+
+          **Performance Guidelines:** {{unity_performance_guidelines}}
+
+          **Memory Management:** {{unity_memory_best_practices}}
+      - id: unity-workflow
+        title: Unity Workflow Conventions
+        template: |
+          **Scene Workflow:** {{scene_workflow_conventions}}
+
+          **Prefab Workflow:** {{prefab_workflow_conventions}}
+
+          **Asset Workflow:** {{asset_workflow_conventions}}
+
   - id: external-integrations
     title: External Integrations
     condition: Game requires external service integrations