| name | godot-autoload-architecture |
| description | Expert patterns for Godot AutoLoad (singleton) architecture including global state management, scene transitions, signal-based communication, dependency injection, autoload initialization order, and anti-patterns to avoid. Use for game managers, save systems, audio controllers, or cross-scene resources. Trigger keywords: AutoLoad, singleton, GameManager, SceneTransitioner, SaveManager, global_state, autoload_order, signal_bus, dependency_injection. |
Available Scripts
MANDATORY before trusting a multi-Autoload dependency graph — verifies boot sequence.
MANDATORY with the mermaid/order diagram — maps who may call whom at boot.
MANDATORY before a cross-system Autoload bus (Achievements, UI, Save events).
MANDATORY before Autoload-owned scene transitions (deferred free / root management).
MANDATORY before Engine.register_singleton DI for non-Node services.
Data that must survive change_scene_to_file() (inventory, settings).
static var global state when you do not need a SceneTree Node.
On-demand instantiate instead of eager boot cost.
Safe cross-singleton calls after both are ready.
Mutex / call_deferred for background threads touching Autoload state.
Validate registration + defaults (debug / CI).
Ordered init helpers when _ready is too early for heavy work.
PROCESS_MODE_ALWAYS CanvasLayer console.
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.
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
current_scene 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 —
process_mode / PROCESS_MODE_ALWAYS 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 —
register_singleton / 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
change_scene_to_file().
Master
- godot-master — Library router and mirrored module entry; open when discovering which Domain Skill owns a cross-cutting singleton concern.
