doc status updates
This commit is contained in:
Brian Madison
@@ -1,428 +0,0 @@
|
||||
# Godot Game Engine Architecture Guide
|
||||
|
||||
This guide provides Godot-specific guidance for solution architecture generation.
|
||||
|
||||
---
|
||||
|
||||
## Godot-Specific Questions
|
||||
|
||||
### 1. Godot Version and 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 and 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
|
||||
Reference in New Issue
Block a user