Expert architectural standards for building scalable Godot GAMES (RPGs, Platformers, Shooters) using the Composition pattern (Entity-Component). Use when designing player controllers, NPCs, enemies, weapons, or complex gameplay systems. Enforces "Has-A" relationships for game entities. Trigger keywo

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 Situation Choose Gameplay entity behaviors (HP, hitbox, move, interact) Composition — child components + orchestrator ([composition root init.gd](scripts/composition root init.gd)) Cross scene services (audio bus, save, net, economy ledger) Autoload — not a component on the player True is a engine specialization (custom Control/Node with shared lifecycle) Inheritance exception — rare; never for "adds a gun" / "adds HP" Available Scripts [health component.gd](scripts/health component.gd) Specialized Node for managing lifespan, damage logic, and death signals across any entity. [hit box component.gd](scripts/hit box component.gd) Area based component for intercepting damage and delegating it to a HealthComponent. [hurt box component.gd](scripts/hurt box component.gd) Area based component for dealing damage specifically to HitBoxComponents. [velocity component.gd](scripts/velocity component.gd) Encapsulated movement and acceleration logic for reuse across Players and Enemies. [interaction component.gd](scripts/interaction component.gd) Decoupled interaction handler using injecting Callable logic for context aware actions. [follower component.gd](scripts/follower component.gd) Decoupled tracking logic using NodePath injection for smooth entity following. [state component vsm.gd](scripts/state component vsm.gd) Component based state machine pattern using child nodes as individual states. [status effect component.gd](scripts/status effect component.gd) Managing temporary modifiers (buffs/debuffs) by stacking effect scenes as children. [visual sync component.gd](scripts/visual sync component.gd) Separating logical state (velocity/direction) from visual representation (sprite flipping). [composition root init.gd](scripts/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: 2. Component Mindset Components must define class name to be recognized as types. Standard Component Boilerplate: Standard Components — Use Scripts Inline Input/Movement/Health recipes removed. MANDATORY : start from [composition root init.gd](scripts/composition root init.gd), then load the matching script: Health / death: [health component.gd](scripts/health component.gd) Damage areas: [hit box component.gd](scripts/hit box component.gd), [hurt box component.gd](scripts/hurt box component.gd) Motion: [velocity component.gd](scripts/velocity component.gd) Interact / follow / VFX sync: [interaction component.gd](scripts/interaction component.gd), [follower component.gd](scripts/follower component.gd), [visual sync component.gd](scripts/visual sync component.gd) States / statuses: [state component vsm.gd](scripts/state component vsm.gd), [status effect component.gd](scripts/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](scripts/state component vsm.gd) — do not paste an inline StateMachine. For deeper VSM / hierarchical FSMs, open [godot state machine advanced](https://github.com/thedivergentai/gd agentic skills/blob/main/skills/godot state machine advanced/SKILL.md). 2. Component Registry (O(1) Lookup) Avoid slow tree traversal for sibling communication. Catalog children in a Dictionary at ready (by name or group). 3. Dependency Validation Fail fast with @export asserts , not get node or null paths (paths break when the tree is rearranged). MANDATORY for Input/Movement/Health orchestrator recipes and registry depth: [orchestrator recipes.md](references/orchestrator recipes.md). Do NOT Load when [composition root init.gd](scripts/composition root init.gd) + one component script suffice. Performance Note Nodes are lightweight. Do not fear adding 10 20 nodes per entity. The organizational benefit of Composition vastly outweighs the negligible memory cost of Node instances. Reference Progressive disclosure: open Official Documentation links only when researching a specific API; load Related Skills when routing to a peer domain — do not preload the whole lattice. Official Documentation [Scene organization](https://docs.godotengine.org/en/stable/tutorials/best practices/scene organization.html) — Canonical signal up / call down ownership so orchestrators wire components without sibling hard coupling. [Nodes and Scenes](https://docs.godotengine.org/en/stable/getting started/step by step/nodes and scenes.html) — Why Godot treats nodes as reusable building blocks (components) assembled into entity scenes. [What are Godot classes](https://docs.godotengine.org/en/stable/tutorials/best practices/what are godot classes.html) — Prefer scene composition and class name components over deep inheritance trees for gameplay entities. [When and how to avoid using nodes for everything](https://docs.godotengine.org/en/stable/tutorials/best practices/node alternatives.html) — Keep pure data in Resources; reserve Nodes for lifecycle, signals, and process ticks. [Logic preferences](https://docs.godotengine.org/en/stable/tutorials/best practices/logic preferences.html) — Placement of game logic across scene trees so parents orchestrate and children stay single purpose. [Data preferences](https://docs.godotengine.org/en/stable/tutorials/best practices/data preferences.html) — Choose Node vs Resource vs plain data for stats and config that components consume. [Using signals](https://docs.godotengine.org/en/stable/getting started/step by step/signals.html) — Past tense component events ( health depleted , state changed ) parents connect without reverse dependencies. [GDScript exported properties](https://docs.godotengine.org/en/stable/tutorials/scripting/gdscript/gdscript exports.html) — Typed @export slots for Inspector dependency injection instead of brittle $ paths. [Scene Unique Nodes](https://docs.godotengine.org/en/stable/tutorials/scripting/scene unique nodes.html) — %Name lookups that survive scene tree reorders when wiring composition roots. [Groups](https://docs.godotengine.org/en/stable/tutorials/scripting/groups.html) — Tag components for O(1) style registry / interface like lookup without inheritance. [Godot notifications](https://docs.godotengine.org/en/stable/tutorials/best practices/godot notifications.html) — Safe ready / enter tree timing for validating and connecting component dependencies. [Resources](https://docs.godotengine.org/en/stable/tutorials/scripting/resources.html) — Share tunables (max health, speeds) as Resources so components stay reusable across entities. Related Skills Prerequisites [godot project foundations](https://github.com/thedivergentai/gd agentic skills/blob/main/skills/godot project foundations/SKILL.md) — Scene ownership, project layout, and Inspector wiring conventions every composition root assumes. [godot gdscript mastery](https://github.com/thedivergentai/gd agentic skills/blob/main/skills/godot gdscript mastery/SKILL.md) — class name , typed @export , Callables, and assert patterns required for typed component APIs. [godot signal architecture](https://github.com/thedivergentai/gd agentic skills/blob/main/skills/godot signal architecture/SKILL.md) — Signal up / call down connect hygiene so selfish components never grab parent scripts. Complements [godot resource data patterns](https://github.com/thedivergentai/gd agentic skills/blob/main/skills/godot resource data patterns/SKILL.md) — Stats and effect definitions as Resources; composition nodes own runtime mutation and emit change events. [godot state machine advanced](https://github.com/thedivergentai/gd agentic skills/blob/main/skills/godot state machine advanced/SKILL.md) — Child node FSM / VSM patterns that plug in as a StateComponent without bloating the orchestrator. [godot input handling](https://github.com/thedivergentai/gd agentic skills/blob/main/skills/godot input handling/SKILL.md) — Sense layer InputComponents that only sample actions; parents pass directions into movement components. [godot characterbody 2d](https://github.com/thedivergentai/gd agentic skills/blob/main/skills/godot characterbody 2d/SKILL.md) — Physics body movement APIs VelocityComponents and composition roots call via move and slide . [godot 2d physics](https://github.com/thedivergentai/gd agentic skills/blob/main/skills/godot 2d physics/SKILL.md) — Area2D layers/masks and overlap rules HitBox/HurtBox/Interaction components depend on. [godot scene management](https://github.com/thedivergentai/gd agentic skills/blob/main/skills/godot scene management/SKILL.md) — Spawn/despawn entities as composed scenes and re wire exports when instances are swapped. Downstream / consumers [godot combat system](https://github.com/thedivergentai/gd agentic skills/blob/main/skills/godot combat system/SKILL.md) — Damage pipelines assemble Health/HitBox/HurtBox components under combat orchestrators. [godot ability system](https://github.com/thedivergentai/gd agentic skills/blob/main/skills/godot ability system/SKILL.md) — Abilities attach as composed workers (cooldowns, targeting) rather than subclassing every caster. [godot rpg stats](https://github.com/thediverge

godot-composition