bmad-method 5.1.2 → 6.0.0-alpha.0

package/src/modules/bmm/workflows/3-solutioning/templates/game-engine-unity-guide.md

@@ -0,0 +1,333 @@
+# Unity Game Engine Architecture Guide
+
+This guide provides Unity-specific guidance for solution architecture generation.
+
+---
+
+## Unity-Specific Questions
+
+### 1. Unity Version & Render Pipeline
+
+**Ask:**
+
+- Which Unity version are you targeting? (2021 LTS, 2022 LTS, 2023+, 6000+)
+- Which render pipeline? (Built-in, URP Universal Render Pipeline, HDRP High Definition)
+- Target platform(s)? (PC, Mobile, Console, WebGL)
+
+**Guidance:**
+
+- **2021/2022 LTS**: Stable, well-supported, good for production
+- **URP**: Best for mobile and cross-platform (lower overhead)
+- **HDRP**: High-fidelity graphics for PC/console only
+- **Built-in**: Legacy, avoid for new projects
+
+**Record ADR:** Unity version and render pipeline choice
+
+---
+
+### 2. Architecture Pattern
+
+**Ask:**
+
+- Component-based MonoBehaviour architecture? (Unity standard)
+- ECS (Entity Component System) for performance-critical systems?
+- Hybrid (MonoBehaviour + ECS where needed)?
+
+**Guidance:**
+
+- **MonoBehaviour**: Standard, easy to use, good for most games
+- **ECS/DOTS**: High performance, steep learning curve, use for massive scale (1000s of entities)
+- **Hybrid**: MonoBehaviour for gameplay, ECS for particles/crowds
+
+**Record ADR:** Architecture pattern choice and justification
+
+---
+
+### 3. Data Management Strategy
+
+**Ask:**
+
+- ScriptableObjects for data-driven design?
+- JSON/XML config files?
+- Addressables for asset management?
+
+**Guidance:**
+
+- **ScriptableObjects**: Unity-native, inspector-friendly, good for game data (enemies, items, levels)
+- **Addressables**: Essential for large games, enables asset streaming and DLC
+- Avoid Resources folder (deprecated pattern)
+
+**Record ADR:** Data management approach
+
+---
+
+## Unity-Specific Architecture Sections
+
+### Game Systems Architecture
+
+**Components to define:**
+
+- **Player Controller**: Character movement, input handling
+- **Camera System**: Follow camera, cinemachine usage
+- **Game State Manager**: Scene transitions, game modes, pause/resume
+- **Save System**: PlayerPrefs vs JSON vs Cloud Save
+- **Input System**: New Input System vs Legacy
+
+**Unity-specific patterns:**
+
+```csharp
+// Singleton GameManager pattern
+public class GameManager : MonoBehaviour
+{
+    public static GameManager Instance { get; private set; }
+
+    void Awake()
+    {
+        if (Instance == null) Instance = this;
+        else Destroy(gameObject);
+        DontDestroyOnLoad(gameObject);
+    }
+}
+
+// ScriptableObject data pattern
+[CreateAssetMenu(fileName = "EnemyData", menuName = "Game/Enemy")]
+public class EnemyData : ScriptableObject
+{
+    public string enemyName;
+    public int health;
+    public float speed;
+    public GameObject prefab;
+}
+```
+
+---
+
+### Unity Events & Communication
+
+**Ask:**
+
+- UnityEvents for inspector-wired connections?
+- C# Events for code-based pub/sub?
+- Message system for decoupled communication?
+
+**Guidance:**
+
+- **UnityEvents**: Good for designer-configurable connections
+- **C# Events**: Better performance, type-safe
+- **Avoid** FindObjectOfType and GetComponent in Update()
+
+**Pattern:**
+
+```csharp
+// Event-driven damage system
+public class HealthSystem : MonoBehaviour
+{
+    public UnityEvent<int> OnDamaged;
+    public UnityEvent OnDeath;
+
+    public void TakeDamage(int amount)
+    {
+        health -= amount;
+        OnDamaged?.Invoke(amount);
+        if (health <= 0) OnDeath?.Invoke();
+    }
+}
+```
+
+---
+
+### Performance Optimization
+
+**Unity-specific considerations:**
+
+- **Object Pooling**: Essential for bullets, particles, enemies
+- **Sprite Batching**: Use sprite atlases, minimize draw calls
+- **Physics Optimization**: Layer-based collision matrix
+- **Profiler Usage**: CPU, GPU, Memory, Physics profilers
+- **IL2CPP vs Mono**: Build performance differences
+
+**Target Performance:**
+
+- Mobile: 60 FPS minimum (30 FPS for complex 3D)
+- PC: 60 FPS minimum
+- Monitor with Unity Profiler
+
+---
+
+### Testing Strategy
+
+**Unity Test Framework:**
+
+- **Edit Mode Tests**: Test pure C# logic, no Unity lifecycle
+- **Play Mode Tests**: Test MonoBehaviour components in play mode
+- Use `[UnityTest]` attribute for coroutine tests
+- Mock Unity APIs with interfaces
+
+**Example:**
+
+```csharp
+[UnityTest]
+public IEnumerator Player_TakesDamage_DecreasesHealth()
+{
+    var player = new GameObject().AddComponent<Player>();
+    player.health = 100;
+
+    player.TakeDamage(20);
+
+    yield return null; // Wait one frame
+
+    Assert.AreEqual(80, player.health);
+}
+```
+
+---
+
+### Source Tree Structure
+
+**Unity-specific folders:**
+
+```
+Assets/
+├── Scenes/              # All .unity scene files
+│   ├── MainMenu.unity
+│   ├── Level1.unity
+│   └── Level2.unity
+├── Scripts/             # All C# code
+│   ├── Player/
+│   ├── Enemies/
+│   ├── Managers/
+│   ├── UI/
+│   └── Utilities/
+├── Prefabs/             # Reusable game objects
+├── ScriptableObjects/   # Game data assets
+│   ├── Enemies/
+│   ├── Items/
+│   └── Levels/
+├── Materials/
+├── Textures/
+├── Audio/
+│   ├── Music/
+│   └── SFX/
+├── Fonts/
+├── Animations/
+├── Resources/           # Avoid - use Addressables instead
+└── Plugins/             # Third-party SDKs
+```
+
+---
+
+### Deployment & Build
+
+**Platform-specific:**
+
+- **PC**: Standalone builds (Windows/Mac/Linux)
+- **Mobile**: IL2CPP mandatory for iOS, recommended for Android
+- **WebGL**: Compression, memory limitations
+- **Console**: Platform-specific SDKs and certification
+
+**Build pipeline:**
+
+- Unity Cloud Build OR
+- CI/CD with command-line builds: `Unity -batchmode -buildTarget ...`
+
+---
+
+## Specialist Recommendations
+
+### Audio Designer
+
+**When needed:** Games with music, sound effects, ambience
+**Responsibilities:**
+
+- Audio system architecture (2D vs 3D audio)
+- Audio mixer setup
+- Music transitions and adaptive audio
+- Sound effect implementation
+- Audio performance optimization
+
+### Performance Optimizer
+
+**When needed:** Mobile games, large-scale games, VR
+**Responsibilities:**
+
+- Profiling and optimization
+- Memory management
+- Draw call reduction
+- Physics optimization
+- Asset optimization (textures, meshes, audio)
+
+### Multiplayer Architect
+
+**When needed:** Multiplayer/co-op games
+**Responsibilities:**
+
+- Netcode architecture (Netcode for GameObjects, Mirror, Photon)
+- Client-server vs peer-to-peer
+- State synchronization
+- Anti-cheat considerations
+- Latency compensation
+
+### Monetization Specialist
+
+**When needed:** F2P, mobile games with IAP
+**Responsibilities:**
+
+- Unity IAP integration
+- Ad network integration (AdMob, Unity Ads)
+- Analytics integration
+- Economy design (virtual currency, shop)
+
+---
+
+## Common Pitfalls
+
+1. **Over-using GetComponent** - Cache references in Awake/Start
+2. **Empty Update methods** - Remove them, they have overhead
+3. **String comparisons for tags** - Use CompareTag() instead
+4. **Resources folder abuse** - Migrate to Addressables
+5. **Not using object pooling** - Instantiate/Destroy is expensive
+6. **Ignoring the Profiler** - Profile early, profile often
+7. **Not testing on target hardware** - Mobile performance differs vastly
+
+---
+
+## Key Architecture Decision Records
+
+### ADR Template for Unity Projects
+
+**ADR-XXX: [Title]**
+
+**Context:**
+What Unity-specific issue are we solving?
+
+**Options:**
+
+1. Unity Built-in Solution (e.g., Built-in Input System)
+2. Unity Package (e.g., New Input System)
+3. Third-party Asset (e.g., Rewired)
+4. Custom Implementation
+
+**Decision:**
+We chose [Option X]
+
+**Unity-specific Rationale:**
+
+- Version compatibility
+- Performance characteristics
+- Community support
+- Asset Store availability
+- License considerations
+
+**Consequences:**
+
+- Impact on build size
+- Platform compatibility
+- Learning curve for team
+
+---
+
+_This guide is specific to Unity Engine. For other engines, see:_
+
+- game-engine-godot-guide.md
+- game-engine-unreal-guide.md
+- game-engine-web-guide.md