godot-autoload-architecture
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.
thedivergentai · 已有 AI 审核记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add thedivergentai/GD-Agentic-Skills --skill godot-autoload-architecture技能说明
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
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 astatic varin aclass_namescript 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_sceneis accurate in_ready()— In Autoloads, the active scene might still be initializing. Access it viaget_tree().root.get_child(-1). - NEVER skip
process_modeconfiguration — If your global console or music manager needs to work while the game is paused, setprocess_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-managementfor threaded loads.
5. Health checks
阅读完整来源 ↗MANDATORY in debug/CI: [singleton_health_check_test.gd](scripts/singl