Godot Composition Apps

Godot Composition & Architecture (Apps & UI)

Decision Gate — App vs Gameplay Entity

App-only gate: If the node is a gameplay actor (Player/Enemy/Weapon/Hitbox), use godot-composition. This skill owns Control / EditorPlugin / tool composition.

The Core Philosophy

The Litmus Test (Rock Test)

Before writing a script, ask: "If I attached this script to a literal rock, would it still function?"

• Pass: An AuthComponent on a rock allows the rock to log in. (Context Agnostic)
• Fail: A LoginForm script on a rock tries to grab text fields the rock doesn't have. (Coupled)

MANDATORY: Validate new components with comp_rock_test_boilerplate.gd.

The Backpack Model (Has-A > Is-A)

Treat the Root Node as an empty Backpack.

• Wrong: SubmitButton extends AnimatedButton extends BaseButton.
• Right: Root HAS-A AnimationComponent and HAS-A NetworkRequestComponent.

The Hierarchy of Power (Communication Rules)

Sideways Fix: Component A signals the Orchestrator; Orchestrator calls Component B.

Available Scripts

MANDATORY: Read the matching script before implementing the pattern. Do not reinvent Orchestrator wiring inline.

comp_rock_test_boilerplate.gd

MANDATORY first read — Attach-candidate-to-literal-rock harness that fails hard-coupled components early.

comp_orchestrator_base.gd

MANDATORY when creating any App/UI root — Signal-up / call-down wiring skeleton (0% business math).

comp_logic_visual_syncer.gd

MANDATORY for VLS — Logic emits state_changed; visuals/animations react without logic knowing AnimationPlayer/Theme.

comp_base_component.gd

Shared component lifecycle + dependency validation for app workers.

comp_dependency_injector.gd

Typed export / registry injection so Orchestrators avoid brittle $ paths.

clipboard_copier.gd

Context-agnostic clipboard worker — pairs with orchestrator toast pattern (see references).

comp_data_driven_config.gd

Resource-backed config for tool settings and form defaults.

comp_persistence_component.gd

MANDATORY for saveable UI/tool state — Registers Saveable group + get_save_data() without putting I/O in visuals.

comp_ability_sequencer.gd

Ordered multi-step tool workflows (wizard pages, export pipelines) as child steps.

comp_health_component.gd / comp_hitbox_component.gd

Only when an app/tool simulates entities; prefer godot-composition for real games.

The Orchestrator Pattern

Root script (LoginScreen.gd, UserProfile.gd, EditorPlugin dock root) is an Orchestrator:

• Math/Logic: 0% · State wiring: 100%
• Job: listen to component signals → call other component methods

MANDATORY: Extend patterns from comp_orchestrator_base.gd.

Implementation Standards

1. Type Safety — class_name on components; no untyped core architecture.
2. Dependency Injection — @export var auth: AuthComponent (Inspector / %UniqueNames). NEVER get_node("Path/To/Child") for components.
3. Stateless workers — Orchestrator passes data into functions; components do not scrape sibling Controls.

NEVER Do (Expert Architectural Rules)

Hierarchy & Dependencies

• NEVER use get_parent() to fetch data — Inject via @export or function args.
• NEVER talk sideways — Signal up; Orchestrator calls down.
• NEVER use brittle Node Paths — Prefer @export / %.

Logic & State

• NEVER put business logic in the Orchestrator — Only _on_signal delegators.
• NEVER store global state in individual components — Shared Context Resource or Autoload.
• NEVER assume a component's parent is a specific type — Rock Test failure.

Polish & Orchestration

• NEVER skip signal cleanup — Disconnect on exit / use CONNECT_ONE_SHOT where appropriate.
• NEVER let Logic know about Visuals — Emit; VLS / Orchestrator plays animations and applies Theme.

Fragile App Workflow: Saveable + Theme Ownership

Do not put save I/O or Theme mutation inside form Controls. Route through components:

1. MANDATORY comp_persistence_component.gd on the Orchestrator (or a dedicated Saveable child) — add_to_group("Saveable") + get_save_data().
2. Theme / StyleBox changes belong in a theme component (theme_manager.gd) called down by the Orchestrator after logic signals success/failure.
3. Focus: Orchestrator owns grab_focus() after validation failures so logic stays Control-agnostic.

# settings_dock_orchestrator.gd (pattern — wire via @export, not $)
extends Control
@export var persistence: CompPersistenceComponent
@export var theme_mgr: Node  # theme_manager.gd API
@export var form_logic: Node

func _ready() -> void:
    form_logic.settings_valid.connect(_on_settings_valid)
    form_logic.settings_invalid.connect(_on_settings_invalid)

func _on_settings_valid(payload: Dictionary) -> void:
    theme_mgr.apply_user_theme(payload.get("theme_id"))
    # Save systems collect via Saveable group — persistence component stays dumb

func _on_settings_invalid(field: StringName) -> void:
    # Orchestrator owns focus; logic never touches sibling LineEdits
    var target := get_node_or_null("%" + String(field))
    if target is Control:
        target.grab_focus()

Expert Composition Patterns (Apps)

1. App-Level Service Locator

Prefer Engine.register_singleton() for lightweight non-Node services (Auth, Config) instead of dozens of Autoload Nodes [6].

2. Visual-Logic-Syncers (VLS)

MANDATORY comp_logic_visual_syncer.gd — logic never calls AnimationPlayer.play().