godot-autoload-architecture

Available Scripts

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

MANDATORY before trusting a multi-Autoload dependency graph — verifies boot sequence.

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

MANDATORY with the mermaid/order diagram — maps who may call whom at boot.

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

MANDATORY before a cross-system Autoload bus (Achievements, UI, Save events).

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

MANDATORY before Autoload-owned scene transitions (deferred free / root management).

[servicelocator.gd](scripts/servicelocator.gd) / [serviceregistry.gd](scripts/serviceregistry.gd)

MANDATORY before Engine.register_singleton DI for non-Node services.

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

Data that must survive changesceneto_file() (inventory, settings).

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

static var global state when you do not need a SceneTree Node.

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

On-demand instantiate instead of eager boot cost.

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

Safe cross-singleton calls after both are ready.

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

Mutex / call_deferred for background threads touching Autoload state.

[autoloadreferencechecker.gd](scripts/autoloadreferencechecker.gd) / [singletonhealthchecktest.gd](scripts/singletonhealthchecktest.gd)

Validate registration + defaults (debug / CI).

[autoloadbootstrapper.gd](scripts/autoloadbootstrapper.gd) / [autoloadinitializer.gd](scripts/autoloadinitializer.gd)

Ordered init helpers when _ready is too early for heavy work.

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

PROCESSMODEALWAYS CanvasLayer console.

[globalgamestate.gd](scripts/globalgamestate.gd) / [statelessbus.gd](scripts/statelessbus.gd)

State holder vs pure event bus split.

NEVER Do in AutoLoad Architecture

• NEVER access AutoLoads in init() — AutoLoads are initialized sequentially. Accessing one in init() may find a null reference.
• NEVER modify a Singleton's size or children in _ready() — If multiple Singletons refer to each other's trees during boot, it can cause layout/sorting errors.
• NEVER store highly localized, scene-specific data in AutoLoads — This creates "God Objects" and introduces global side effects that are hard to debug.
• NEVER use Parent.method() calls from an Autoload — Autoloads sit at the root. They are the ultimate "top". Use signals to talk to the active scene.
• NEVER use an Autoload for pure data containers — If you don't need process() or signals, use a static var in a classname script instead.
• NEVER create circular dependencies between Singletons — If A needs B and B needs A, Godot will hang during the splash screen.
• NEVER free an Autoload node manually — Removing a singleton from the root can leave dangling references that crash the engine.
• NEVER use AutoLoads for UI elements that aren't global — Popups that only exist in one level should be in that level, not a global singleton.
• NEVER assume gettree().currentscene is accurate in ready() — In Autoloads, the active scene might still be initializing. Access it via gettree().root.get_child(-1).
• NEVER skip processmode configuration — If your global console or music manager needs to work while the game is paused, set processmode = PROCESSMODEALWAYS.

When to Use AutoLoads

Good: Game/Audio/Save managers, SceneTransitioner, global score/inventory, cross-scene EventBus.

Avoid: Scene-specific logic, temporary state, pure data (prefer static / Resource), over-architecting tiny projects.

Expert Architecture Patterns

1. Boot order & dependency diagram

MANDATORY: Read [autoloadinitorderdiag.gd](scripts/autoloadinitorderdiag.gd) and [singletondependencydiagram.gd](scripts/singletondependencydiagram.gd) before drawing or trusting any Autoload order.

Autoloads initialize top → bottom in Project Settings. Upper singletons must not call lower ones in _ready(). Move dependents down the list.

graph TD
    subgraph Autoloads [Project Settings order]
        B[1. GlobalAudio] --> C[2. ServiceLocator]
        C --> D[3. QuestManager]
    end
    D --> E[Current Scene]
    E -->|Queries| C

2. Service locator (non-Node DI)

MANDATORY: [servicelocator.gd](scripts/servicelocator.gd) / [serviceregistry.gd](scripts/serviceregistry.gd) before Engine.register_singleton.

Use for lightweight RefCounted services; unregister in exittree to avoid dangling engine singletons.

3. Event bus vs state holder

MANDATORY: [globaleventbus.gd](scripts/globaleventbus.gd) for cross-system past-tense events. Keep mutable run state in [persistentdataholder.gd](scripts/persistentdataholder.gd) / [globalgamestate.gd](scripts/globalgamestate.gd) — not on the bus.

4. Safe scene switching from Autoload

MANDATORY: [safesceneswitcher.gd](scripts/safesceneswitcher.gd) — deferred free + root ownership. Pair with godot-scene-management for threaded loads.

5. Health checks

MANDATORY in debug/CI: [singletonhealthchecktest.gd](scripts/singletonhealthchecktest.gd) / [autoloadreferencechecker.gd](scripts/autoloadreferencechecker.gd) — assert presence + Engine.has_singleton for registered services.

Expert insights (WHY — keep in body)

• Boot order — WHY: Autoloads init top→bottom in Project Settings. Upper singletons must not call lower ones in ready() ([autoloadinitorderdiag.gd](scripts/autoloadinitorder_diag.gd)).
• Service locator vs Node Autoload — WHY: RefCounted services avoid SceneTree overhead; register via Engine.registersingleton and unregister in exittree ([servicelocator.gd](scripts/service_locator.gd)).
• Event bus vs state — WHY: buses emit past-tense events; mutable run state belongs in [persistentdataholder.gd](scripts/persistentdataholder.gd), not on the bus.
• currentscene in ready() — WHY: active scene may still be mounting; use gettree().root.getchild(-1) or defer until scene ready.

Deep recipes (on demand)

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

• Singletons (AutoLoad) — How AutoLoads register under /root, become global names, and why boot order matches Project Settings list order.
• Autoloads versus regular nodes — Decision guide for when a global singleton is justified versus a scene-owned node or static helper.
• Scene organization — Keep scene-local data out of AutoLoads so managers do not become God Objects.
• Logic preferences — Prefer signals and ownership edges over reaching into Autoload trees for gameplay orchestration.
• Using SceneTree — Why currentscene can be unreliable during Autoload _ready() and how root children relate to the active scene.
• Change scenes manually — Deferred free + root reparent patterns behind safe global scene switchers.
• Pausing games — processmode / PROCESSMODEALWAYS for consoles, music, and managers that must run while get_tree().paused.
• Overridable functions — init vs _ready timing so cross-Autoload access does not hit nulls during sequential boot.
• Using signals — Emit/connect model for Autoload event buses that decouple scenes without hard node paths.
• Engine — registersingleton / get_singleton for lightweight service locators that are not SceneTree Nodes.
• Thread-safe APIs — Which engine APIs need Mutex/call_deferred when background threads touch global Autoload state.
• Saving games — Persistence patterns for inventory/settings held in long-lived Autoload data holders.

Related Skills

Prerequisites

• godot-project-foundations — AutoLoad entries live in Project Settings / project.godot; get registration and naming right before wiring managers.
• godot-gdscript-mastery — Typed signals, static var / class_name, and deferred calls are the language tools this skill’s patterns assume.
• godot-signal-architecture — Event-bus and Signal-Up contracts for Autoload mediators without circular emit chains.

Complements

• godot-scene-management — Pair with safe scene switchers so transitions own loading/unload while AutoLoads keep cross-scene state.
• godot-save-load-systems — Serialize what persistent Autoload holders store; do not invent a second save path inside GameManager.
• godot-resource-data-patterns — Prefer Resources for shared config; reserve AutoLoads for lifecycle + signals, not duplicated data blobs.
• godot-composition — Component ownership alternative when a “manager Autoload” is really scene-scoped behavior in disguise.
• godot-audio-systems — Music/SFX pools are classic Autoload homes; use this skill for ownership and boot order around those managers.
• godot-state-machine-advanced — Global MENU/PLAYING/PAUSED FSMs belong here when the Autoload is only the owner, not the whole game logic dump.
• godot-debugging-profiling — Init-order diagnostics and singleton health checks escalate into debugger/profiler workflows when boot hangs.

Downstream / consumers

• godot-performance-optimization — Escalate when too many Node Autoloads, eager preloads, or per-frame manager work show up in profilers.
• godot-testing-patterns — GUT/CI health checks for registered singletons and reset of global state between tests.
• godot-multiplayer-networking — Global state Autoloads become authority/replication hazards; consume this skill’s DI patterns carefully online.
• godot-inventory-system — Typical consumer of persistent Autoload holders for inventory that must survive changesceneto_file().

Master

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