Godot Composition & Architecture (Apps & UI)

Decision Gate — App vs Gameplay Entity

Root node / task	Route
Control, EditorPlugin, tool window, settings dock, form UI	Stay here — Orchestrator + components
Player, Enemy, Weapon, Hitbox, gameplay CharacterBody	godot-composition — not this skill

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)

Direction	Source → Target	Method	Reason
Downward	Orchestrator → Component	Function Call	Manager owns the workers.
Upward	Component → Orchestrator	Signals	Workers are blind.
Sideways	Component A ↔ Component B	FORBIDDEN	Siblings never talk directly.

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.

Concept	App/UI Example
Orchestrator	UserProfile.gd / Editor dock root
Logic component	AuthValidator
VLS	AuthVisualSyncer via comp_logic_visual_syncer.gd
Theme ownership	Separate theme component — never mutated inside form logic
Focus ownership	Orchestrator grants/releases Control focus; components never steal siblings' focus

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().

3. O(1) Component Registry

Orchestrator Dictionary registry for dashboard modules — still no sideways calls; registry is Orchestrator-private lookup.

MANDATORY for clipboard/share orchestrator examples and service-locator depth: app-orchestrator-examples.md. Do NOT Load when comp_orchestrator_base.gd covers your screen.

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 — Canonical signal-up / call-down ownership so Orchestrators wire components without sibling coupling.
• When and how to avoid using nodes for everything — Prefer Resources/RefCounted for pure data and logic services so components stay lean and rock-testable.
• Godot interfaces — Duck-typed method contracts (has_method) that let composition work without deep inheritance trees.
• What are Godot classes? — Why Godot favors scene composition (Has-A) over classical Is-A hierarchies for reusable behaviors.
• Using signals — Upward component→Orchestrator events that keep workers blind to parents and siblings.
• GDScript exports — Typed @export dependency injection that replaces brittle get_node paths in the Inspector.
• Scene Unique Nodes — %UniqueName for Orchestrator-local Control/Button wiring without string path fragility.
• Resources — Data-driven .tres configs so values stay outside logic components.
• Groups — Mass registration (e.g. Saveable/Components) for Orchestrator registries without hard sibling refs.
• Autoloads versus regular nodes — When a scene-local Orchestrator beats a global Autoload for app/UI composition.
• Singletons (Autoload) — Safe registration of cross-scene services when a true app-level locator is justified.
• Saving games — Persistence patterns that map cleanly onto modular saveable components.

Related Skills

Prerequisites

• godot-project-foundations — Project layout, Autoload registration, and scene ownership that Orchestrators and components plug into.
• godot-gdscript-mastery — Typed exports, signals, and class_name fluency required before dependency injection and rock-testable components.
• godot-composition — Core Has-A component model (game-focused sibling); this skill specializes the same rules for Apps/Tools/UI.

Complements

• godot-signal-architecture — Connect flags, ghost cleanup, and EventBus patterns Orchestrators use for upward wiring.
• godot-autoload-architecture — Boot order and ownership when composition needs a thin global service instead of scene-local state.
• godot-resource-data-patterns — Custom Resources and hot-swap .tres configs that feed data-driven components.
• godot-ui-containers — Control trees that should signal intent upward while Orchestrators call down into layout.
• godot-ui-theming — Theme/visual syncers stay separate from auth/form logic under the VLS pattern.
• godot-scene-management — Scene swaps must re-inject exports and reconnect Orchestrator wiring without sideways sibling links.
• godot-testing-patterns — Rock-test and signal spies that prove components stay context-agnostic.

Downstream / consumers

• godot-save-load-systems — Consumes Saveable-group persistence components for modular app state.
• godot-ability-system — Ability nodes as child components sequenced by an Orchestrator without inheritance trees.
• godot-state-machine-advanced — State nodes compose beside logic/visual syncers; FSM owns transitions, not sibling chatter.

Master

• godot-master — Library router and mirrored module entry; open when discovering which Domain Skill owns a cross-cutting architecture concern.