bmad-method 5.1.2 → 6.0.0-alpha.0

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

@@ -0,0 +1,428 @@
+# Godot Game Engine Architecture Guide
+
+This guide provides Godot-specific guidance for solution architecture generation.
+
+---
+
+## Godot-Specific Questions
+
+### 1. Godot Version & Language Strategy
+
+**Ask:**
+
+- Which Godot version? (3.x, 4.x)
+- Language preference? (GDScript only, C# only, or Mixed GDScript+C#)
+- Target platform(s)? (PC, Mobile, Web, Console)
+
+**Guidance:**
+
+- **Godot 4.x**: Modern, Vulkan renderer, better 3D, C# improving
+- **Godot 3.x**: Stable, mature ecosystem, OpenGL
+- **GDScript**: Python-like, fast iteration, integrated with editor
+- **C#**: Better performance for complex systems, familiar to Unity devs
+- **Mixed**: GDScript for game logic, C# for performance-critical (physics, AI)
+
+**Record ADR:** Godot version and language strategy
+
+---
+
+### 2. Node-Based Architecture
+
+**Ask:**
+
+- Scene composition strategy? (Nested scenes, scene inheritance, or flat hierarchy)
+- Node organization patterns? (By feature, by type, or hybrid)
+
+**Guidance:**
+
+- **Scenes as Prefabs**: Each reusable entity is a scene (Player.tscn, Enemy.tscn)
+- **Scene Inheritance**: Extend base scenes for variations (BaseEnemy → FlyingEnemy)
+- **Node Signals**: Use built-in signal system for decoupled communication
+- **Autoload Singletons**: For global managers (GameManager, AudioManager)
+
+**Godot Pattern:**
+
+```gdscript
+# Player.gd
+extends CharacterBody2D
+
+signal health_changed(new_health)
+signal died
+
+@export var max_health: int = 100
+var health: int = max_health
+
+func take_damage(amount: int) -> void:
+    health -= amount
+    health_changed.emit(health)
+    if health <= 0:
+        died.emit()
+        queue_free()
+```
+
+**Record ADR:** Scene architecture and node organization
+
+---
+
+### 3. Resource Management
+
+**Ask:**
+
+- Use Godot Resources for data? (Custom Resource types for game data)
+- Asset loading strategy? (preload vs load vs ResourceLoader)
+
+**Guidance:**
+
+- **Resources**: Like Unity ScriptableObjects, serializable data containers
+- **preload()**: Load at compile time (fast, but increases binary size)
+- **load()**: Load at runtime (slower, but smaller binary)
+- **ResourceLoader.load_threaded_request()**: Async loading for large assets
+
+**Pattern:**
+
+```gdscript
+# EnemyData.gd
+class_name EnemyData
+extends Resource
+
+@export var enemy_name: String
+@export var health: int
+@export var speed: float
+@export var prefab_scene: PackedScene
+```
+
+**Record ADR:** Resource and asset loading strategy
+
+---
+
+## Godot-Specific Architecture Sections
+
+### Signal-Driven Communication
+
+**Godot's built-in Observer pattern:**
+
+```gdscript
+# GameManager.gd (Autoload singleton)
+extends Node
+
+signal game_started
+signal game_paused
+signal game_over(final_score: int)
+
+func start_game() -> void:
+    game_started.emit()
+
+func pause_game() -> void:
+    get_tree().paused = true
+    game_paused.emit()
+
+# In Player.gd
+func _ready() -> void:
+    GameManager.game_started.connect(_on_game_started)
+    GameManager.game_over.connect(_on_game_over)
+
+func _on_game_started() -> void:
+    position = Vector2.ZERO
+    health = max_health
+```
+
+**Benefits:**
+
+- Decoupled systems
+- No FindNode or get_node everywhere
+- Type-safe with typed signals (Godot 4)
+
+---
+
+### Godot Scene Architecture
+
+**Scene organization patterns:**
+
+**1. Composition Pattern:**
+
+```
+Player (CharacterBody2D)
+├── Sprite2D
+├── CollisionShape2D
+├── AnimationPlayer
+├── HealthComponent (Node - custom script)
+├── InputComponent (Node - custom script)
+└── WeaponMount (Node2D)
+    └── Weapon (instanced scene)
+```
+
+**2. Scene Inheritance:**
+
+```
+BaseEnemy.tscn
+├── Inherits → FlyingEnemy.tscn (adds wings, aerial movement)
+└── Inherits → GroundEnemy.tscn (adds ground collision)
+```
+
+**3. Autoload Singletons:**
+
+```
+# In Project Settings > Autoload:
+GameManager → res://scripts/managers/game_manager.gd
+AudioManager → res://scripts/managers/audio_manager.gd
+SaveManager → res://scripts/managers/save_manager.gd
+```
+
+---
+
+### Performance Optimization
+
+**Godot-specific considerations:**
+
+- **Static Typing**: Use type hints for GDScript performance (`var health: int = 100`)
+- **Object Pooling**: Implement manually or use addons
+- **CanvasItem batching**: Reduce draw calls with texture atlases
+- **Viewport rendering**: Offload effects to separate viewports
+- **GDScript vs C#**: C# faster for heavy computation, GDScript faster for simple logic
+
+**Target Performance:**
+
+- **PC**: 60 FPS minimum
+- **Mobile**: 60 FPS (high-end), 30 FPS (low-end)
+- **Web**: 30-60 FPS depending on complexity
+
+**Profiler:**
+
+- Use Godot's built-in profiler (Debug > Profiler)
+- Monitor FPS, draw calls, physics time
+
+---
+
+### Testing Strategy
+
+**GUT (Godot Unit Test):**
+
+```gdscript
+# test_player.gd
+extends GutTest
+
+func test_player_takes_damage():
+    var player = Player.new()
+    add_child(player)
+    player.health = 100
+
+    player.take_damage(20)
+
+    assert_eq(player.health, 80, "Player health should decrease")
+```
+
+**GoDotTest for C#:**
+
+```csharp
+[Test]
+public void PlayerTakesDamage_DecreasesHealth()
+{
+    var player = new Player();
+    player.Health = 100;
+
+    player.TakeDamage(20);
+
+    Assert.That(player.Health, Is.EqualTo(80));
+}
+```
+
+**Recommended Coverage:**
+
+- 80% minimum test coverage (from expansion pack)
+- Test game systems, not rendering
+- Use GUT for GDScript, GoDotTest for C#
+
+---
+
+### Source Tree Structure
+
+**Godot-specific folders:**
+
+```
+project/
+├── scenes/              # All .tscn scene files
+│   ├── main_menu.tscn
+│   ├── levels/
+│   │   ├── level_1.tscn
+│   │   └── level_2.tscn
+│   ├── player/
+│   │   └── player.tscn
+│   └── enemies/
+│       ├── base_enemy.tscn
+│       └── flying_enemy.tscn
+├── scripts/             # GDScript and C# files
+│   ├── player/
+│   │   ├── player.gd
+│   │   └── player_input.gd
+│   ├── enemies/
+│   ├── managers/
+│   │   ├── game_manager.gd  (Autoload)
+│   │   └── audio_manager.gd (Autoload)
+│   └── ui/
+├── resources/           # Custom Resource types
+│   ├── enemy_data.gd
+│   └── level_data.gd
+├── assets/
+│   ├── sprites/
+│   ├── textures/
+│   ├── audio/
+│   │   ├── music/
+│   │   └── sfx/
+│   ├── fonts/
+│   └── shaders/
+├── addons/              # Godot plugins
+└── project.godot        # Project settings
+```
+
+---
+
+### Deployment & Build
+
+**Platform-specific:**
+
+- **PC**: Export presets for Windows, Linux, macOS
+- **Mobile**: Android (APK/AAB), iOS (Xcode project)
+- **Web**: HTML5 export (SharedArrayBuffer requirements)
+- **Console**: Partner programs for Switch, Xbox, PlayStation
+
+**Export templates:**
+
+- Download from Godot website for each platform
+- Configure export presets in Project > Export
+
+**Build automation:**
+
+- Use `godot --export` command-line for CI/CD
+- Example: `godot --export-release "Windows Desktop" output/game.exe`
+
+---
+
+## Specialist Recommendations
+
+### Audio Designer
+
+**When needed:** Games with music, sound effects, ambience
+**Responsibilities:**
+
+- AudioStreamPlayer node architecture (2D vs 3D audio)
+- Audio bus setup in Godot's audio mixer
+- Music transitions with AudioStreamPlayer.finished signal
+- Sound effect implementation
+- Audio performance optimization
+
+### Performance Optimizer
+
+**When needed:** Mobile games, large-scale games, complex 3D
+**Responsibilities:**
+
+- Godot profiler analysis
+- Static typing optimization
+- Draw call reduction
+- Physics optimization (collision layers/masks)
+- Memory management
+- C# performance optimization for heavy systems
+
+### Multiplayer Architect
+
+**When needed:** Multiplayer/co-op games
+**Responsibilities:**
+
+- High-level multiplayer API or ENet
+- RPC architecture (remote procedure calls)
+- State synchronization patterns
+- Client-server vs peer-to-peer
+- Anti-cheat considerations
+- Latency compensation
+
+### Monetization Specialist
+
+**When needed:** F2P, mobile games with IAP
+**Responsibilities:**
+
+- In-app purchase integration (via plugins)
+- Ad network integration
+- Analytics integration
+- Economy design
+- Godot-specific monetization patterns
+
+---
+
+## Common Pitfalls
+
+1. **Over-using get_node()** - Cache node references in `@onready` variables
+2. **Not using type hints** - Static typing improves GDScript performance
+3. **Deep node hierarchies** - Keep scene trees shallow for performance
+4. **Ignoring signals** - Use signals instead of polling or direct coupling
+5. **Not leveraging autoload** - Use autoload singletons for global state
+6. **Poor scene organization** - Plan scene structure before building
+7. **Forgetting to queue_free()** - Memory leaks from unreleased nodes
+
+---
+
+## Godot vs Unity Differences
+
+### Architecture Differences:
+
+| Unity                  | Godot          | Notes                                   |
+| ---------------------- | -------------- | --------------------------------------- |
+| GameObject + Component | Node hierarchy | Godot nodes have built-in functionality |
+| MonoBehaviour          | Node + Script  | Attach scripts to nodes                 |
+| ScriptableObject       | Resource       | Custom data containers                  |
+| UnityEvent             | Signal         | Godot signals are built-in              |
+| Prefab                 | Scene (.tscn)  | Scenes are reusable like prefabs        |
+| Singleton pattern      | Autoload       | Built-in singleton system               |
+
+### Language Differences:
+
+| Unity C#                              | GDScript                                    | Notes                       |
+| ------------------------------------- | ------------------------------------------- | --------------------------- |
+| `public class Player : MonoBehaviour` | `class_name Player extends CharacterBody2D` | GDScript more concise       |
+| `void Start()`                        | `func _ready():`                            | Initialization              |
+| `void Update()`                       | `func _process(delta):`                     | Per-frame update            |
+| `void FixedUpdate()`                  | `func _physics_process(delta):`             | Physics update              |
+| `[SerializeField]`                    | `@export`                                   | Inspector-visible variables |
+| `GetComponent<T>()`                   | `get_node("NodeName")` or `$NodeName`       | Node access                 |
+
+---
+
+## Key Architecture Decision Records
+
+### ADR Template for Godot Projects
+
+**ADR-XXX: [Title]**
+
+**Context:**
+What Godot-specific issue are we solving?
+
+**Options:**
+
+1. GDScript solution
+2. C# solution
+3. GDScript + C# hybrid
+4. Third-party addon (Godot Asset Library)
+
+**Decision:**
+We chose [Option X]
+
+**Godot-specific Rationale:**
+
+- GDScript vs C# performance tradeoffs
+- Engine integration (signals, nodes, resources)
+- Community support and addons
+- Team expertise
+- Platform compatibility
+
+**Consequences:**
+
+- Impact on performance
+- Learning curve
+- Maintenance considerations
+- Platform limitations (Web export with C#)
+
+---
+
+_This guide is specific to Godot Engine. For other engines, see:_
+
+- game-engine-unity-guide.md
+- game-engine-unreal-guide.md
+- game-engine-web-guide.md