godot-autoload-architecture

可用脚本

autoload_init_order_diag.gd

在信任多 Autoload 依赖图之前必须使用——验证启动顺序。

singleton_dependency_diagram.gd

搭配 mermaid/顺序图时必须使用——映射启动时各对象可以调用谁。

global_event_bus.gd

在使用跨系统 Autoload 总线（成就、UI、存档事件）之前必须使用。

safe_scene_switcher.gd

在使用由 Autoload 管理的场景切换（延迟释放／根节点管理）之前必须使用。

service_locator.gd / service_registry.gd

在使用 Engine.register_singleton 为非 Node 服务进行 DI 之前必须使用。

persistent_data_holder.gd

用于必须在 change_scene_to_file() 后保留的数据（物品栏、设置）。

static_state_manager.gd

当你不需要 SceneTree Node 时，用 static var 管理全局状态。

lazy_loaded_singleton.gd

按需实例化，避免启动时的开销。

cross_autoload_comms.gd

在两个单例都就绪后安全地进行跨单例调用。

thread_safe_global_access.gd

使用 Mutex／call_deferred 处理后台线程对 Autoload 状态的访问。

autoload_reference_checker.gd / singleton_health_check_test.gd

验证注册状态和默认值（调试／CI）。

autoload_bootstrapper.gd / autoload_initializer.gd

当 _ready 不适合执行繁重任务时，使用有序初始化辅助工具。

debug_console_autoload.gd

PROCESS_MODE_ALWAYS CanvasLayer 控制台。

global_game_state.gd / stateless_bus.gd

区分状态持有器与纯事件总线。

AutoLoad 架构中绝对不要这样做

• 绝不要在 _init() 中访问 AutoLoads——AutoLoads 按顺序初始化。在 _init() 中访问可能会得到空引用。
• 绝不要在 _ready() 中修改单例的大小或子节点——如果多个单例在启动期间相互引用对方的场景树，可能导致布局／排序错误。
• 绝不要在 AutoLoads 中存储高度局部化、特定于场景的数据——这会形成“上帝对象”，并引入难以调试的全局副作用。
• 绝不要从 Autoload 调用 Parent.method()——Autoload 位于根节点，是最顶层。使用信号与当前场景通信。
• 绝不要将 Autoload 用作纯数据容器——如果不需要 _process() 或信号，请改用 class_name 脚本中的 static var。
• 绝不要在单例之间创建循环依赖——如果 A 需要 B，而 B 又需要 A，Godot 会在启动画面期间卡死。
• 绝不要手动释放 Autoload 节点——从根节点移除单例可能留下悬空引用，导致引擎崩溃。
• 绝不要将 AutoLoads 用于非全局 UI 元素——只存在于一个关卡中的弹窗应属于该关卡，而不是全局单例。
• 绝不要假设 get_tree().current_scene 在 _ready() 中准确无误——在 Autoload 中，当前场景可能仍在初始化。通过 get_tree().root.get_child(-1) 访问。
• 绝不要跳过 process_mode 配置——如果全局控制台或音乐管理器需要在游戏暂停时继续运行，请设置 process_mode = PROCESS_MODE_ALWAYS。

---

何时使用 AutoLoads

适用： 游戏／音频／存档管理器、SceneTransitioner、全局分数／物品栏、跨场景 EventBus。

避免： 特定于场景的逻辑、临时状态、纯数据（优先使用 static／Resource）、为小型项目过度设计。

---

专家级架构模式

1. 启动顺序与依赖关系图

MANDATORY：在绘制或信任任何 Autoload 顺序前，请阅读 autoload_init_order_diag.gd 和 singleton_dependency_diagram.gd。

在 Project Settings 中，Autoload 按照从上到下的顺序初始化。上方的单例不得在 _ready() 中调用下方的单例。请将依赖项移到列表下方。

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. 服务定位器（非 Node DI）

MANDATORY：在调用 Engine.register_singleton 前，请阅读 service_locator.gd / service_registry.gd。

用于轻量级 RefCounted 服务；请在 _exit_tree 中取消注册，以避免引擎单例失效。

3. 事件总线与状态持有器

MANDATORY：使用 global_event_bus.gd 传递跨系统的过去时事件。将可变的运行状态保存在 persistent_data_holder.gd / global_game_state.gd 中，而不是事件总线上。

4. 从 Autoload 安全切换场景

MANDATORY：safe_scene_switcher.gd — 延迟释放 + 根节点所有权。对于线程化加载，请与 godot-scene-management 配合使用。

5. 健康检查

在调试/CI 中 MANDATORY：singleton_health_check_test.gd / autoload_reference_checker.gd — 使用 assert 检查存在性，并使用 Engine.has_singleton 检查已注册的服务。

专家见解（原因 — 保留在正文中）

• 启动顺序 — 原因：Autoload 在 Project Settings 中按从上到下的顺序初始化。上方的单例不得在 _ready() 中调用下方的单例（autoload_init_order_diag.gd）。
• 服务定位器与 Node Autoload — 原因：RefCounted 服务可避免 SceneTree 开销；通过 Engine.register_singleton 注册，并在 _exit_tree 中取消注册（service_locator.gd）。
• 事件总线与状态 — 原因：事件总线发送过去时事件；可变的运行状态应保存在 persistent_data_holder.gd 中，而不是事件总线上。
• _ready() 中的 current_scene — 原因：活动场景可能仍在挂载；请使用 get_tree().root.get_child(-1)，或延迟到场景就绪后再操作。

深入用法（按需查阅）

主题	参考资料 / 脚本
服务定位器 / 启动关系图 / 健康检查	expert-patterns.md
仅介绍初学者注册方式	autoload-patterns.md

参考资料

渐进式披露：仅在研究特定 API 时打开官方文档链接；在转向同级领域时加载相关技能 — 不要预加载整个技能网络。

官方文档

• 单例（自动加载） — 介绍 AutoLoad 如何注册到 /root 下、如何成为全局名称，以及启动顺序为何与 Project Settings 列表顺序一致。
• 自动加载与常规节点的区别 — 帮助判断何时适合使用全局单例，而非由场景拥有的节点或静态辅助类。
• 场景组织 — 将场景局部数据留在 AutoLoad 之外，避免管理器变成上帝对象。
• 逻辑设计偏好 — 优先使用信号和所有权关系来编排游戏逻辑，而不是访问 Autoload 树。
• 使用 SceneTree — 说明为什么在 Autoload 的 _ready() 期间 current_scene 可能不可靠，以及根节点的子节点与活动场景之间的关系。
• 手动切换场景 — 安全的全局场景切换器背后的延迟释放与根节点重设父级模式。
• 暂停游戏 — 为控制台、音乐和必须在 get_tree().paused 时继续运行的管理器介绍 process_mode / PROCESS_MODE_ALWAYS。
• 可重写函数 — 介绍 _init 与 _ready 的时机，避免跨 Autoload 访问在顺序启动期间遇到空值。
• 使用信号 — 介绍 Autoload 事件总线的发出 / 连接模式，如何在不使用硬编码节点路径的情况下解耦场景。
• Engine — 介绍 register_singleton / get_singleton，用于实现不属于 SceneTree 节点的轻量级服务定位器。
• 线程安全 API — 说明后台线程访问全局 Autoload 状态时，哪些引擎 API 需要 Mutex / call_deferred。
• 保存游戏 — 介绍由长期存在的 Autoload 数据持有器保存库存 / 设置的持久化模式。

相关技能

前置条件

• godot-project-foundations — AutoLoad 条目位于 Project Settings / project.godot 中；在连接管理器前，先正确设置注册和命名。
• godot-gdscript-mastery — 类型化信号、static var / class_name 和延迟调用是本技能所用模式依赖的语言工具。
• godot-signal-architecture — 介绍 Autoload 中介器的事件总线与 Signal-Up 契约，避免形成循环发射链。

补充内容

• godot-scene-management — 配合安全的场景切换器使用，让转换流程负责加载/卸载，而 AutoLoad 负责保留跨场景状态。
• godot-save-load-systems — 序列化持久化 AutoLoad 持有者存储的内容；不要在 GameManager 内另造一套保存路径。
• godot-resource-data-patterns — 共享配置优先使用 Resources；AutoLoad 应用于生命周期管理和信号，而不是存放重复的数据块。
• godot-composition — 当所谓的“管理器 AutoLoad”实质上是伪装成全局对象的场景级行为时，可采用组件所有权作为替代方案。
• godot-audio-systems — 音乐/音效池是典型的 AutoLoad 用例；使用此技能管理这些管理器的所有权和启动顺序。
• godot-state-machine-advanced — 全局 MENU/PLAYING/PAUSED FSM 适合放在这里，前提是 AutoLoad 只负责所有权，而不是承载所有游戏逻辑。
• godot-debugging-profiling — 启动卡住时，初始化顺序诊断和单例健康检查可进一步转入调试器/分析器工作流。

下游 / 使用者

• godot-performance-optimization — 当分析器发现 Node AutoLoad 过多、过早预加载或管理器每帧执行过多工作时，应进一步排查。
• godot-testing-patterns — 使用 GUT/CI 检查已注册单例的健康状况，并在测试之间重置全局状态。
• godot-multiplayer-networking — 全局状态 AutoLoad 会带来权限和复制方面的风险；在线使用此技能的 DI 模式时务必谨慎。
• godot-inventory-system — 物品栏通常会使用持久化 AutoLoad 持有者，以便在 change_scene_to_file() 后保留数据。

主入口

• godot-master — 知识库路由器和镜像模块入口；需要确定哪个领域技能负责跨领域单例问题时，请打开此项。