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 [comprocktestboilerplate.gd](scripts/comprocktestboilerplate.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.

[comprocktestboilerplate.gd](scripts/comprocktestboilerplate.gd)

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

[comporchestratorbase.gd](scripts/comporchestratorbase.gd)

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

[complogicvisualsyncer.gd](scripts/complogicvisualsyncer.gd)

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

[compbasecomponent.gd](scripts/compbasecomponent.gd)

Shared component lifecycle + dependency validation for app workers.

[compdependencyinjector.gd](scripts/compdependencyinjector.gd)

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

[clipboardcopier.gd](scripts/clipboardcopier.gd)

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

[compdatadrivenconfig.gd](scripts/compdatadrivenconfig.gd)

Resource-backed config for tool settings and form defaults.

[comppersistencecomponent.gd](scripts/comppersistencecomponent.gd)

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

[compabilitysequencer.gd](scripts/compabilitysequencer.gd)

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

[comphealthcomponent.gd](scripts/comphealthcomponent.gd) / [comphitboxcomponent.gd](scripts/comphitboxcomponent.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 [comporchestratorbase.gd](scripts/comporchestratorbase.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 onsignal 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 CONNECTONESHOT 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 [comppersistencecomponent.gd](scripts/comppersistencecomponent.gd) on the Orchestrator (or a dedicated Saveable child) — addtogroup("Saveable") + getsavedata().
2. Theme / StyleBox changes belong in a theme component (thememanager.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()

• 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 getnode 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.