From d3ae87154e43ea7ecac7df5474772e849ab98cc0 Mon Sep 17 00:00:00 2001 From: pbean Date: Mon, 21 Jul 2025 14:19:09 -0700 Subject: [PATCH] feat: Finished extended architecture documentation needed for new game story tasks --- .../checklists/game-architect-checklist.md | 17 + .../data/development-guidelines.md | 30 +- .../templates/game-architecture-tmpl.yaml | 480 ++++++++++++++++++ 3 files changed, 523 insertions(+), 4 deletions(-) diff --git a/expansion-packs/bmad-2d-unity-game-dev/checklists/game-architect-checklist.md b/expansion-packs/bmad-2d-unity-game-dev/checklists/game-architect-checklist.md index eb96be27..399477fd 100644 --- a/expansion-packs/bmad-2d-unity-game-dev/checklists/game-architect-checklist.md +++ b/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 diff --git a/expansion-packs/bmad-2d-unity-game-dev/data/development-guidelines.md b/expansion-packs/bmad-2d-unity-game-dev/data/development-guidelines.md index e87621f8..d5c28734 100644 --- a/expansion-packs/bmad-2d-unity-game-dev/data/development-guidelines.md +++ b/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().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("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(); // 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); diff --git a/expansion-packs/bmad-2d-unity-game-dev/templates/game-architecture-tmpl.yaml b/expansion-packs/bmad-2d-unity-game-dev/templates/game-architecture-tmpl.yaml index 3a4fd733..36e78012 100644 --- a/expansion-packs/bmad-2d-unity-game-dev/templates/game-architecture-tmpl.yaml +++ b/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