agentleFS
vl4dtvl4dt/godot-skills/skills/godot-architecture/SKILL.md

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.

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
  1. Distinctive:

    When the MCP bridge is running (Phase 2), these tools can inspect and modify your project live:

    line 207

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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 += amount

Dependency 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 AnimationPlayer

Signal-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_level

When to Use Each Approach

PatternUse WhenAvoid When
Direct reference ($Path)Parent-child, same sceneCross-scene communication
SignalsDecoupled components, event-driven flowSimple data access
Autoload singletonGlobal state (score, settings)Per-instance data
Resource-basedData that needs saving/loadingRuntime-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 paths

Project 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, fonts

Module 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 events

Godot 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 patterns
  • script_read / script_edit — Read and modify architecture scripts
  • class_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

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.