Godot Architecture — Systems Design

1. Thinking Framework

Before writing any system, answer these three questions for every piece of state:

Who owns the data? (StatsComponent owns health, NOT CombatSystem)
Who is allowed to change it? (Only the owner via a public method like apply_damage())
Who needs to know it changed? (Anyone listening to the health_changed signal)

If you can't answer all three, you have a coupling problem.

The Layer Cake — signals travel UP, never down:

┌──────────────────────────────┐
│  PRESENTATION (UI / VFX)     │  ← Listens to signals, never owns data
├──────────────────────────────┤
│  LOGIC (State Machines)      │  ← Orchestrates transitions, queries data
├──────────────────────────────┤
│  DATA (Resources / .tres)    │  ← Single source of truth, serializable
├──────────────────────────────┤
│  INFRASTRUCTURE (Autoloads)  │  ← Signal Bus, SaveManager, AudioBus
└──────────────────────────────┘

Signal Bus tiers:

Global Bus (Autoload): lifecycle-only events (match_started, player_died). Keep < 15 events.
Scoped Feature Bus: one per feature folder (e.g., CombatBus). Scales better than a single global bus.
Direct Signals: parent→child within a single scene only. Never cross scene boundaries with direct signals.

2. Decision Matrix

| Scenario | Strategy | Key References | Trade-off | |----------|----------|---------------|-----------| | Rapid prototype | Event-Driven Mono | Foundations → Autoloads | Fast start, spaghetti risk | | Complex RPG | Component-Driven | Composition → States → RPG Stats | Heavy setup, infinite scaling | | Massive open world | Resource-Streaming | Open World → Save/Load → Performance | Complex I/O, float jitter past 10K units | | Server-auth multiplayer | Deterministic | Server Arch → Multiplayer | High latency cost, anti-cheat secure | | Mobile/Web port | Adaptive-Responsive | UI Containers → Adapt Desktop→Mobile | UI complexity, broad reach | | Application/tool | App-Composition | App Composition → Theming | Different paradigm from games | | Complex RPG with combat | Component-Driven | Composition → States → Combat → Inventory | Heavy setup, infinite scaling |

Node vs lighter types — don't default to Node for everything:

| Type | Use When | Cost | |------|----------|------| | Node | Needs _process, spatial transform, or scene tree lifetime | Heaviest — SceneTree overhead | | Resource | Designer-editable data, serializable to .tres | Medium — Inspector support | | RefCounted | Transient logic packets (DamageRequest, PathQuery) | Light — auto-freed when no refs remain | | Object | Custom data structures, manual memory management | Lightest — must call .free() |

Use RefCounted for logic packets. Reserve Node for entities that must exist spatially or need per-frame updates.

3. NEVER Rules

NEVER use get_tree().root.get_node("...") — absolute paths break when ANY ancestor is renamed or reparented. Use %UniqueNames, @export NodePath, or signal-based discovery.
NEVER mutate external state from a component — if HealthComponent calls $HUD.update_bar(), deleting the HUD crashes the game. Components emit signals; listeners decide how to respond.
NEVER use Area2D for 1000+ overlapping objects — O(n²) broadphase cost. Use ShapeCast2D, PhysicsDirectSpaceState2D.intersect_shape(), or Server APIs for bullet-hell patterns.
NEVER use _process for 1000+ entities — per-node SceneTree overhead kills perf. Use a single Manager._process iterating an array of data structs, or Server APIs directly.
NEVER create circular signal connections — A connects to B, B connects to A → infinite loop on first emit. Use a Signal Bus mediator to break cycles.

4. Performance Budgets

| Metric | Mobile Target | Desktop Target | Notes | |--------|--------------|----------------|-------| | Draw calls | < 100 (2D), < 200 (3D) | < 500 | MultiMeshInstance for foliage/debris | | Triangle count | < 100K visible | < 1M visible | LOD mandatory above 500K | | Texture VRAM | < 512MB | < 2GB | ETC2 (mobile), BPTC (desktop) | | Script time | < 4ms/frame | < 8ms/frame | Move hot loops to Server APIs | | Physics bodies | < 200 active | < 1000 active | Use PhysicsServer direct API for mass sim | | Particles | < 2000 total | < 10000 total | GPU particles; set visibility_aabb manually | | Scene load time | < 500ms | < 2s | Use load_threaded_request() |

Diagnosis-first approach — never optimize blindly:

High script time → profile with built-in Profiler; check for hundreds of _process calls
High draw calls → MultiMeshInstance for repeated geometry
Physics stutter → simplify collision shapes to primitives; verify _physics_process not _process is used for movement
Frame spikes → usually GC pass, synchronous load(), or NavigationServer rebaking

5. Godot 4.x Gotchas

@export Resources are shared: all instances share the same object. Use resource.duplicate() in _ready() or "Local to Scene" checkbox.
Signal syntax silently fails: Godot 3 connect("name", target, "method") compiles but does nothing. Use signal_name.connect(callable).
Tween is not a Node: bound to creating node's lifetime. Use get_tree().create_tween() for persistent tweens.
Physics layer vs mask: collision_layer = "what I am"; collision_mask = "what I detect". Same value on both → self-collision or misses.
@onready timing: runs during _ready(), after _init(). Never mix tree-access code in _init().
Server query stalls: calling RenderingServer/PhysicsServer getter functions in _process forces a synchronous pipeline flush — these servers are async.
move_and_slide() API change: velocity is now a property, not a parameter. Set velocity before calling.
Infinite world float jitter: past ~10K world units, float precision causes visible jitter. Use origin-shifting or large-world coordinates plugin.

6. Expert Code Patterns

State Machine Transition Guard

func can_transition_to(new_state: StringName) -> bool:
    match name:
        &"Dead": return false          # terminal — no exit
        &"Stunned": return new_state == &"Idle"   # can only recover to Idle
        _: return true

Component Registry (Entity Root)

class_name Entity extends CharacterBody2D

var _components: Dictionary = {}

func _ready() -> void:
    for child in get_children():
        if child.has_method("get_component_name"):
            _components[child.get_component_name()] = child

func get_component(name: StringName) -> Node:
    return _components.get(name)

Dead-Instance Safe Signal Handler

func _on_damage_dealt(target: Node, amount: int) -> void:
    if not is_instance_valid(target): return
    if target.is_queued_for_deletion(): return
    target.get_component(&"health").apply_damage(amount)

Async Level Loader

func _load_level_async(path: String) -> void:
    ResourceLoader.load_threaded_request(path)
    while ResourceLoader.load_threaded_get_status(path) == ResourceLoader.THREAD_LOAD_IN_PROGRESS:
        await get_tree().process_frame
    var scene: PackedScene = ResourceLoader.load_threaded_get(path)
    add_child(scene.instantiate())

Thread-Safe Chunk Attach

func _load_chunk_threaded(chunk_pos: Vector2i) -> void:
    # Generate OFF the active tree (thread-safe)
    var chunk := _generate_chunk(chunk_pos)
    # Attach on main thread only
    _world_root.add_child.call_deferred(chunk)

⚠️ Threading rule: the scene tree is NOT thread-safe. Server APIs (RenderingServer, PhysicsServer) ARE thread-safe when enabled in Project Settings. Always call_deferred() when attaching to the live tree from a worker thread.

Godot Architecture — Systems Design

1. Thinking Framework

Before writing any system, answer these three questions for every piece of state:

Who owns the data? (StatsComponent owns health, NOT CombatSystem)
Who is allowed to change it? (Only the owner via a public method like apply_damage())
Who needs to know it changed? (Anyone listening to the health_changed signal)

If you can't answer all three, you have a coupling problem.

The Layer Cake — signals travel UP, never down:

┌──────────────────────────────┐
│  PRESENTATION (UI / VFX)     │  ← Listens to signals, never owns data
├──────────────────────────────┤
│  LOGIC (State Machines)      │  ← Orchestrates transitions, queries data
├──────────────────────────────┤
│  DATA (Resources / .tres)    │  ← Single source of truth, serializable
├──────────────────────────────┤
│  INFRASTRUCTURE (Autoloads)  │  ← Signal Bus, SaveManager, AudioBus
└──────────────────────────────┘

Signal Bus tiers:

Global Bus (Autoload): lifecycle-only events (match_started, player_died). Keep < 15 events.
Scoped Feature Bus: one per feature folder (e.g., CombatBus). Scales better than a single global bus.
Direct Signals: parent→child within a single scene only. Never cross scene boundaries with direct signals.

2. Decision Matrix

Node vs lighter types — don't default to Node for everything:

Use RefCounted for logic packets. Reserve Node for entities that must exist spatially or need per-frame updates.

3. NEVER Rules

NEVER use get_tree().root.get_node("...") — absolute paths break when ANY ancestor is renamed or reparented. Use %UniqueNames, @export NodePath, or signal-based discovery.
NEVER mutate external state from a component — if HealthComponent calls $HUD.update_bar(), deleting the HUD crashes the game. Components emit signals; listeners decide how to respond.
NEVER use Area2D for 1000+ overlapping objects — O(n²) broadphase cost. Use ShapeCast2D, PhysicsDirectSpaceState2D.intersect_shape(), or Server APIs for bullet-hell patterns.
NEVER use _process for 1000+ entities — per-node SceneTree overhead kills perf. Use a single Manager._process iterating an array of data structs, or Server APIs directly.
NEVER create circular signal connections — A connects to B, B connects to A → infinite loop on first emit. Use a Signal Bus mediator to break cycles.

4. Performance Budgets

Diagnosis-first approach — never optimize blindly:

High script time → profile with built-in Profiler; check for hundreds of _process calls
High draw calls → MultiMeshInstance for repeated geometry
Physics stutter → simplify collision shapes to primitives; verify _physics_process not _process is used for movement
Frame spikes → usually GC pass, synchronous load(), or NavigationServer rebaking

5. Godot 4.x Gotchas

@export Resources are shared: all instances share the same object. Use resource.duplicate() in _ready() or "Local to Scene" checkbox.
Signal syntax silently fails: Godot 3 connect("name", target, "method") compiles but does nothing. Use signal_name.connect(callable).
Tween is not a Node: bound to creating node's lifetime. Use get_tree().create_tween() for persistent tweens.
Physics layer vs mask: collision_layer = "what I am"; collision_mask = "what I detect". Same value on both → self-collision or misses.
@onready timing: runs during _ready(), after _init(). Never mix tree-access code in _init().
Server query stalls: calling RenderingServer/PhysicsServer getter functions in _process forces a synchronous pipeline flush — these servers are async.
move_and_slide() API change: velocity is now a property, not a parameter. Set velocity before calling.
Infinite world float jitter: past ~10K world units, float precision causes visible jitter. Use origin-shifting or large-world coordinates plugin.

6. Expert Code Patterns

State Machine Transition Guard

func can_transition_to(new_state: StringName) -> bool:
    match name:
        &"Dead": return false          # terminal — no exit
        &"Stunned": return new_state == &"Idle"   # can only recover to Idle
        _: return true

Component Registry (Entity Root)

class_name Entity extends CharacterBody2D

var _components: Dictionary = {}

func _ready() -> void:
    for child in get_children():
        if child.has_method("get_component_name"):
            _components[child.get_component_name()] = child

func get_component(name: StringName) -> Node:
    return _components.get(name)

Dead-Instance Safe Signal Handler

func _on_damage_dealt(target: Node, amount: int) -> void:
    if not is_instance_valid(target): return
    if target.is_queued_for_deletion(): return
    target.get_component(&"health").apply_damage(amount)

Async Level Loader

func _load_level_async(path: String) -> void:
    ResourceLoader.load_threaded_request(path)
    while ResourceLoader.load_threaded_get_status(path) == ResourceLoader.THREAD_LOAD_IN_PROGRESS:
        await get_tree().process_frame
    var scene: PackedScene = ResourceLoader.load_threaded_get(path)
    add_child(scene.instantiate())

Thread-Safe Chunk Attach

func _load_chunk_threaded(chunk_pos: Vector2i) -> void:
    # Generate OFF the active tree (thread-safe)
    var chunk := _generate_chunk(chunk_pos)
    # Attach on main thread only
    _world_root.add_child.call_deferred(chunk)

Adoption

erikstmartin/godot-architecture

$ install --global

Security Scan Results

SKILL.md

Godot Architecture — Systems Design

1. Thinking Framework

2. Decision Matrix

3. NEVER Rules

4. Performance Budgets

5. Godot 4.x Gotchas

6. Expert Code Patterns

State Machine Transition Guard

Component Registry (Entity Root)

Dead-Instance Safe Signal Handler

Async Level Loader

Thread-Safe Chunk Attach

Related Skills

erikstmartin/writing-skills

erikstmartin/writing-plans

erikstmartin/verification-before-completion

erikstmartin/using-superpowers

erikstmartin/godot-architecture

$ install --global

Security Scan Results

SKILL.md

Godot Architecture — Systems Design

1. Thinking Framework

2. Decision Matrix

3. NEVER Rules

4. Performance Budgets

5. Godot 4.x Gotchas

6. Expert Code Patterns

State Machine Transition Guard

Component Registry (Entity Root)

Dead-Instance Safe Signal Handler

Async Level Loader

Thread-Safe Chunk Attach

Related Skills

erikstmartin/writing-skills

erikstmartin/writing-plans

erikstmartin/verification-before-completion

erikstmartin/using-superpowers