Godot Composition

Core Philosophy

This skill enforces Composition over Inheritance ("Has-a" vs "Is-a"). In Godot, Nodes are components. A complex entity (Player) is simply an Orchestrator managing specialized Worker Nodes (Components).

The Golden Rules

1. Single Responsibility: One script = One job.
2. Encapsulation: Components are "selfish." They handle their internal logic but don't know who owns them.
3. The Orchestrator: The root script (e.g., player.gd) does no logic. It only manages state and passes data between components.
4. Decoupling: Components communicate via Signals (up) and Methods (down).

Decision Tree — Composition vs Autoload vs Inheritance

Available Scripts

health_component.gd

Specialized Node for managing lifespan, damage logic, and death signals across any entity.

hit_box_component.gd

Area-based component for intercepting damage and delegating it to a HealthComponent.

hurt_box_component.gd

Area-based component for dealing damage specifically to HitBoxComponents.

velocity_component.gd

Encapsulated movement and acceleration logic for reuse across Players and Enemies.

interaction_component.gd

Decoupled interaction handler using injecting Callable logic for context-aware actions.

follower_component.gd

Decoupled tracking logic using NodePath injection for smooth entity following.

state_component_vsm.gd

Component-based state machine pattern using child nodes as individual states.

status_effect_component.gd

Managing temporary modifiers (buffs/debuffs) by stacking effect scenes as children.

visual_sync_component.gd

Separating logical state (velocity/direction) from visual representation (sprite flipping).

composition_root_init.gd

MANDATORY first read — Orchestrator wiring via typed @export (Inspector / %UniqueNames in the scene). Matches NEVER: no $ / get_node for components.

NEVER Do in Composition

• NEVER use deep inheritance chains (e.g., Player > Entity > LivingThing > Node) — Creates brittle "God Classes" that are hard to refactor [21].
• NEVER use get_node() or $ for components — This breaks if the scene tree is rearranged. Always use @export or %UniqueNames [22].
• NEVER let a component reference its parent script directly — This makes the component impossible to reuse. Use signals or dependency injection [23].
• NEVER mix Input, Physics, and Game Logic in one script — This violates Single Responsibility. Split them into specialized components [24, 13].
• NEVER create components that require a specific SceneTree structure — A component should be "selfish" and only care about its own properties and direct children.
• NEVER use inheritance to "add a feature" — If you want an enemy to shoot, add a ShootingComponent, don't make it inherit from ShooterEnemy.
• NEVER hardcode component dependencies — If CombatComponent needs HealthComponent, look it up in _ready() or inject it via the parent [11].
• NEVER treat Godot nodes as pure data — Nodes provide lifecycle (_process) and signals. If you only need data, use a Resource.
• NEVER ignore the Node lifecycle in components — Use _enter_tree() and _exit_tree() for setup/cleanup that must happen regardless of the parent's state.
• NEVER hide component points of access — Expose NodePath or Callable properties so the parent can wire the component in the Inspector [13].

Implementation Standards

1. Connection Strategy: Typed Exports

Do not rely on tree order. Use explicit dependency injection via @export with static typing.

The "Godot Way" for strict godot-composition:

# The Orchestrator (e.g., player.gd)
class_name Player extends CharacterBody3D

# Dependency Injection: Define the "slots" in the backpack
@export var health_component: HealthComponent
@export var movement_component: MovementComponent
@export var input_component: InputComponent

# Use Scene Unique Names (%) for auto-assignment in Editor
# or drag-and-drop in the Inspector.

2. Component Mindset

Components must define class_name to be recognized as types.

Standard Component Boilerplate:

class_name MyComponent extends Node 
# Use Node for logic, Node3D/2D if it needs position

@export var stats: Resource # Components can hold their own data
signal happened_something(value)

func _ready() -> void:
    _validate_dependencies()

func _validate_dependencies() -> void:
    # 2. Dependency-Validation: Fail early during development if setup is wrong [2]
    # NOTE: assert() is stripped in release builds [10].
    assert(stats != null, "Stats Resource missing on %s" % name)

func do_logic(delta: float) -> void:
    # Perform specific task
    pass

Standard Components — Use Scripts

Inline Input/Movement/Health recipes removed. MANDATORY: start from composition_root_init.gd, then load the matching script:

• Health / death: health_component.gd
• Damage areas: hit_box_component.gd, hurt_box_component.gd
• Motion: velocity_component.gd
• Interact / follow / VFX sync: interaction_component.gd, follower_component.gd, visual_sync_component.gd
• States / statuses: state_component_vsm.gd, status_effect_component.gd

Typed @export wiring stays under Implementation Standards above.

Expert Composition Patterns

1. State-Component Pattern (FSM)

Encapsulate complex behaviors into child nodes that act as states. The parent StateComponent delegates lifecycle calls to the active child [4, 6].

MANDATORY: Read state_component_vsm.gd — do not paste an inline StateMachine. For deeper VSM / hierarchical FSMs, open godot-state-machine-advanced.

2. Component-Registry (O(1) Lookup)

Avoid slow tree traversal for sibling communication. Catalog children in a Dictionary at ready (by name or group).

var _components: Dictionary = {}

func _ready() -> void:
    for child in get_children():
        _components[child.name] = child
        for group in child.get_groups():
            _components[group] = child

func get_comp(key: StringName) -> Node:
    return _components.get(key)

3. Dependency-Validation

Fail fast with @export asserts, not get_node_or_null paths (paths break when the tree is rearranged).

@export var health_component: HealthComponent
@export var input_component: InputComponent

func _ready() -> void:
    assert(health_component != null, "Missing HealthComponent export!")
    assert(input_component != null, "Missing InputComponent export!")

MANDATORY for Input/Movement/Health orchestrator recipes and registry depth: orchestrator-recipes.md. Do NOT Load when composition_root_init.gd + one component script suffice.