godot-architecture
Skill8 starsChanged 5 months agoMITView on GitHub
Game architecture patterns for Godot 4.x: ECS-like composition, scene organization, dependency injection via signals, service locator vs direct reference, and scalable project structure. Use when designing or refactoring a Godot game's overall architecture.
In this repository23 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- godot-47-migrationSkill
- godot-animationSkill
- godot-audioSkill
- godot-brainstormingSkill
- godot-code-reviewSkill
- godot-csharp-patternsSkill
- godot-debuggingSkill
- godot-dialog-systemsSkill
- godot-gdscript-patternsSkill
- godot-headless-workflowSkill
- godot-i18nSkill
- godot-inputSkill
- godot-inventory-economySkill
- godot-networkingSkill
- godot-performanceSkill
- godot-physicsSkill
- godot-project-setupSkill
- godot-save-systemsSkill
- godot-shaders-vfxSkill
- godot-state-managementSkill
- godot-uiSkill
The file
We split this skill into the rules it gives an agent
1 rule. About 0 are common, 1 is distinctive, and 0 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 207
When the MCP bridge is running (Phase 2), these tools can inspect and modify your project live:
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Godot Game Architecture Patterns
Architectural approaches for building scalable, maintainable Godot games.
Scene Composition Over Inheritance
Godot's scene system naturally supports composition. Build complex behavior by combining small, focused scenes rather than deep inheritance chains.
Component-Based Composition
# Player.tscn hierarchy:
# CharacterBody2D (root — movement logic)
# Sprite2D (visual)
# CollisionShape2D (physics body)
# HealthComponent (Node — health logic, emits signals)
# InventoryComponent (Node — item management)
# ExperienceComponent (Node — XP/leveling)
# Each component is a standalone .tscn with its own script.
# The player scene composes them without inheritance coupling.Component Script Pattern
class_name HealthComponent extends Node
signal health_changed(current: int, maximum: int)
signal died()
@export var max_health: int = 100
var current_health: int = 100:
set(value):
current_health = clampi(value, 0, max_health)
health_changed.emit(current_health, max_health)
if current_health <= 0:
died.emit()
func take_damage(amount: int) -> void:
current_health -= amount
func heal(amount: int) -> void:
current_health += amountDependency Management Patterns
Direct Reference (Simple Cases)
# Good for tightly-coupled parent-child relationships
@onready var health_component = $HealthComponent as HealthComponent
@onready var animation_player = $AnimationPlayer as AnimationPlayerSignal-Based Decoupling (Recommended)
# Components communicate via signals — no direct references needed
func _ready():
$HealthComponent.died.connect(_on_player_died)
$InventoryComponent.item_collected.connect(_on_item_collected)
func _on_player_died():
get_tree().reload_current_scene()Service Locator (Autoload Singletons)
# GameManager.gd — added as autoload in Project Settings
extends Node
var current_level: int = 0
var player_score: int = 0
var is_paused: bool = false
signal game_started()
signal game_paused(paused: bool)
signal level_completed(level_id: int, score: int)
# Access from anywhere: GameManager.current_levelWhen to Use Each Approach
| Pattern | Use When | Avoid When |
Direct reference ($Path) | Parent-child, same scene | Cross-scene communication |
| Signals | Decoupled components, event-driven flow | Simple data access |
| Autoload singleton | Global state (score, settings) | Per-instance data |
| Resource-based | Data that needs saving/loading | Runtime-only behavior |
ECS-Like Patterns in Godot
Godot isn't a true ECS engine, but you can approximate entity-component systems:
Entity Registry Pattern
class_name EntityRegistry extends Node
# Tracks all active entities by type
var _entities: Dictionary = {}
func register(entity_id: String, entity: Node) -> void:
if not _entities.has(entity_id):
_entities[entity_id] = []
_entities[entity_id].append(entity)
func unregister(entity_id: String, entity: Node) -> void:
if _entities.has(entity_id):
_entities[entity_id].erase(entity)
func get_all(entity_id: String) -> Array:
return _entities.get(entity_id, [])Data-Driven with Resources
# EntityData.tres — defines entity properties without code
class_name EntityData extends Resource
@export var entity_name: String = ""
@export var health: int = 100
@export var speed: float = 100.0
@export var components: Array[String] = [] # Component scene pathsProject Structure Patterns
Feature-Based Organization
res://
├── core/ # Engine-level systems (autoloads, event bus)
│ ├── GameManager.gd
│ └── EventBus.gd
├── features/ # Game features as self-contained modules
│ ├── combat/
│ │ ├── scripts/
│ │ ├── scenes/
│ │ └── resources/
│ ├── inventory/
│ │ ├── scripts/
│ │ ├── scenes/
│ │ └── resources/
│ └── dialogue/
├── levels/ # Level scenes and data
├── ui/ # UI components and screens
└── assets/ # Art, audio, fontsModule Pattern for Large Projects
# FeatureModule.gd — reusable feature registration pattern
class_name FeatureModule extends Node
func initialize() -> void:
pass # Override in subclasses
func cleanup() -> void:
pass # Override in subclasses
# Usage: CombatModule.gd extends FeatureModule
# - Registers signals with EventBus
# - Spawns combat-related autoloads if needed
# - Connects to game lifecycle eventsGodot 4.7 Architecture Notes
- tween_await() — Use for sequential animations without callback chains in component scripts
- DrawableTexture2D — Procedural rendering for debug visualization of entity bounds
- Perfetto tracing — Profile architecture decisions with CPU/GPU trace markers
MCP Bridge Tools (Optional — Live Editor Integration)
When the MCP bridge is running (Phase 2), these tools can inspect and modify your project live:
scene_tree— Inspect scene hierarchy to audit composition patternsscript_read/script_edit— Read and modify architecture scriptsclass_db_info— Query available methods on Godot classes for integration points
Note: MCP tools require the Godot editor to be running with the MCP plugin enabled. Skills work independently without the bridge.
References
- Composition Patterns
- Service Locator vs Signals
- ECS Approximation Guide
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

