Godot Autoload Architecture

Available Scripts

autoload_init_order_diag.gd

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

singleton_dependency_diagram.gd

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

global_event_bus.gd

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

safe_scene_switcher.gd

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

service_locator.gd / service_registry.gd

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

persistent_data_holder.gd

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

static_state_manager.gd

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

lazy_loaded_singleton.gd

On-demand instantiate instead of eager boot cost.

cross_autoload_comms.gd

Safe cross-singleton calls after both are ready.

thread_safe_global_access.gd

Mutex / call_deferred for background threads touching Autoload state.

autoload_reference_checker.gd / singleton_health_check_test.gd

Validate registration + defaults (debug / CI).

autoload_bootstrapper.gd / autoload_initializer.gd

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

debug_console_autoload.gd

PROCESS_MODE_ALWAYS CanvasLayer console.

global_game_state.gd / stateless_bus.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 class_name 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 get_tree().current_scene is accurate in _ready() — In Autoloads, the active scene might still be initializing. Access it via get_tree().root.get_child(-1).
• NEVER skip process_mode configuration — If your global console or music manager needs to work while the game is paused, set process_mode = PROCESS_MODE_ALWAYS.

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 autoload_init_order_diag.gd and singleton_dependency_diagram.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: service_locator.gd / service_registry.gd before Engine.register_singleton.

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

3. Event bus vs state holder

MANDATORY: global_event_bus.gd for cross-system past-tense events. Keep mutable run state in persistent_data_holder.gd / global_game_state.gd — not on the bus.

4. Safe scene switching from Autoload

MANDATORY: safe_scene_switcher.gd — deferred free + root ownership. Pair with godot-scene-management for threaded loads.

5. Health checks

MANDATORY in debug/CI: singleton_health_check_test.gd / autoload_reference_checker.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() (autoload_init_order_diag.gd).
• Service locator vs Node Autoload — WHY: RefCounted services avoid SceneTree overhead; register via Engine.register_singleton and unregister in _exit_tree (service_locator.gd).
• Event bus vs state — WHY: buses emit past-tense events; mutable run state belongs in persistent_data_holder.gd, not on the bus.
• current_scene in _ready() — WHY: active scene may still be mounting; use get_tree().root.get_child(-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.