godot-scene-management

可用脚本

以下触发条件为强制要求——请阅读匹配的脚本；不要粘贴不完整的 Autoload 加载器。

• async_scene_manager.gd — 在加载画面／线程化关卡切换之前 必须使用（包括 THREAD_LOAD_FAILED）。
• background_resource_loader.gd — 在游戏过程中预加载下一个关卡时 必须使用（避免卡顿）。
• scene_transition_manager.gd — 使用淡入淡出／擦除 Tweens 包装安全切换。
• scene_pool.gd — 在频繁生成／销毁对象（子弹、敌人、VFX）之前 必须使用。
• scene_instancing_pooling.gd — 对象池填充／回收模式。
• additive_ui_layering.gd — 无需销毁世界场景即可显示菜单／叠加层。
• subviewport_scene_layering.gd — 并行世界／小地图（必须规划 SubViewport 输入）。
• persistent_data_preservation.gd — 在场景切换期间保留 Autoload／根节点持有者。
• scene_state_manager.gd — 在场景切换期间保存／恢复持久化组。
• node_unparent_reparent.gd — 保留变换的重新挂载（切勿不加考虑地在物理过程中操作）。
• node_path_safe_retrieval.gd — %UniqueName／受保护的 @onready。
• dynamic_script_attachment.gd — 为模组／动态实体运行时附加脚本。

场景管理中绝对不要做的事

• 绝不要同步加载大型场景——在主线程上执行 load("res://large_scene.tscn") 会在关卡切换期间造成“卡顿”或完全冻结。请使用 ResourceLoader.load_threaded_request() 进行异步加载并显示进度条。
• 绝不要将 get_tree().change_scene_to_file() 用于临时状态——此方法会清除当前场景及其所有局部变量。请使用 Autoload（单例） 或持久化的 Game 节点来保存跨关卡状态。
• 绝不要在一帧内实例化 100 个以上相同节点——请使用 对象池 来重复利用子弹、碎片或敌人。不断调用 instantiate() 和 queue_free() 会使 CPU 突增，并过于频繁地触发垃圾回收器。
• 绝不要硬编码 get_node("../../Path/To/Node")——一旦在编辑器中移动节点，这些路径就会失效。请使用 场景唯一名称（%NodeName）或 @export var target_node: Node 来实现可靠引用。
• 绝不要不加考虑地在物理步中重新挂载节点——重新挂载可能导致变换出现一帧的“瞬移”。请务必保存 global_transform，并在调用 add_child() 后重新应用它。
• 绝不要让 SceneTree 管理 10,000 个以上的对象——如果不需要 SceneTree 功能（信号、逐节点脚本），请直接使用 PhysicsServer 和 RenderingServer，以获得原始性能。
• 绝不要忘记处理 NOTIFICATION_WM_CLOSE_REQUEST——在桌面平台上，如果没有在持久化节点中处理关闭请求，游戏可能会在关键保存操作期间退出。
• 绝不要使用深度递归清理节点——在 Godot 4 中，queue_free() 本身会递归执行。释放根节点会自动清理所有子节点。手动循环既多余又低效。
• 绝不要在没有规划的情况下混用 SubViewport 和主世界输入——默认情况下，输入事件会向上冒泡。请使用 set_input_as_handled()，防止子视口中的 UI 点击触发主世界中的游戏操作。
• 绝不要使用 change_scene 来“重置”关卡——这会从磁盘重新加载所有内容。若要快速重生，只需重置变量并将玩家移回起始位置。

---

决策树：如何更改内容

目标	优先选择	必须使用的脚本
完整切换关卡并显示进度界面	线程化加载 → 在 THREAD_LOAD_LOADED 时切换	async_scene_manager.gd
在门/触发器前消除卡顿	游戏过程中提前启动线程化请求	background_resource_loader.gd
在切换前后淡入淡出 / 擦除	由过渡 Autoload 包装管理器	scene_transition_manager.gd
保留世界；显示暂停界面/地图/库存	添加式 UI 层（不要使用 change_scene）	additive_ui_layering.gd
手动切换根节点 / 延迟释放	自行管理 current_scene 生命周期	同领域文档 + godot-autoload-architecture 中的 safe 模式
生成大量相同的角色	使用对象池，切勿大量直接实例化/释放	scene_pool.gd / scene_instancing_pooling.gd
小地图 / 分屏渲染	SubViewport + 更新模式 + 输入隔离	subviewport_scene_layering.gd
在场景清理后保留	使用 Autoload / 持久化组，而非局部变量	persistent_data_preservation.gd / scene_state_manager.gd
快速重生	重置状态 + 传送，而不是 change_scene	—
DLC / 热修补场景	ProjectSettings.load_resource_pack，然后加载路径	（PCK）参见官方文档

专家说明（暂存 / 完整性）

• 对象池预填充：在加载画面期间（PROCESS_MODE_DISABLED + 隐藏）通过 scene_pool.gd 提前承担实例化开销。
• 后台暂存：在游戏过程中调用 load_threaded_request；仅在加载完成后切换（background_resource_loader.gd）。
• PCK 覆盖：挂载资源包，然后对相同的 res:// 路径调用 change_scene/load，以加载修补后的内容。
• 孤儿审计：切换后，Performance.OBJECT_ORPHAN_NODE_COUNT > 0 表示仍有泄漏的引用持有已释放的节点。
• 清理：在 Godot 4 中，对根节点调用 queue_free() 会递归释放；无需手动循环处理子节点。
• 快速重生：重置状态 + 传送；绝不要仅为重启关卡而调用 change_scene。

深入了解（按需加载）

淡入淡出 Autoload、加载画面、生成追踪、持久化容器、PCK 修补——references/scene-patterns-deep.md。

参考

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

官方文档

• 后台加载 — 使用 ResourceLoader.load_threaded_request / 状态轮询，实现无卡顿的关卡加载和进度条。
• 手动切换场景 — 安全切换器背后的延迟释放 + 根节点重新挂载模式（对于分阶段转换，优先于盲目使用 change_scene_to_file）。
• 使用 SceneTree — current_scene、暂停、分组，以及场景切换时树与 Autoload 根子节点的关系。
• 场景组织 — 了解所有权关系，避免加载器 / UI 层在嵌套子场景时演变成上帝对象。
• 节点和场景实例 — PackedScene.instantiate()、所有权，以及何时使用预加载而非运行时加载。
• 场景唯一节点 — 与脆弱的 get_node("../../…") 路径相比，%Name 引用在层级编辑后更稳定。
• Autoload 与常规节点 — 将跨场景状态保存在单例中；将关卡内容保存在树可以卸载的场景中。
• 使用 Viewports — 使用 SubViewport 世界实现小地图、分屏和分层渲染，无需切换主场景。
• 分组 — 在场景转换时，通过持久化分组进行保存 / 恢复和批量清理。
• 导出 PCK、补丁和模组 — 使用 ProjectSettings.load_resource_pack 为 res:// 路径上的 DLC / 模组覆盖场景。
• ResourceLoader — 异步管理器使用的线程化加载 API（load_threaded_*、exists）。
• PackedScene — 用于对象池、change_scene_to_packed 和实例缓存的场景资源类型。

相关技能

前置要求

• godot-project-foundations — 项目布局、场景树基础知识和加载器及 Autoload 注册表所依赖的导入路径。
• godot-gdscript-mastery — 线程化加载循环和转换分阶段处理所需的类型化信号、await 和逐帧轮询。
• godot-autoload-architecture — 单例启动顺序和所有权，确保 Game / 状态持有者在 change_scene 后继续存在，而不会演变成上帝对象。

互补技能

• godot-signal-architecture — 交换场景后重新连接信号或通过总线发送信号，避免加载器在场景释放后留下无效监听器。
• godot-resource-data-patterns — 使用关卡注册表和负载 Resources 将 ID 映射到 .tscn 路径，而不是使用硬编码字符串。
• godot-save-load-systems — 序列化 persist-group / Autoload 状态；场景交换不得另行创建第二套存档路径。
• godot-tweening — 使用淡入淡出和擦除 Tweens 包装场景切换，同时不阻塞加载线程。
• godot-ui-containers — 将加载画面和叠加式菜单层设为持久化 UI 根节点的子节点。
• godot-performance-optimization — 池预算、孤立节点监视器，以及密集生成时 SceneTree 何时应让出执行权以便服务处理。
• godot-composition — 组件场景和所有权关系，让实例化的游戏组件无需耦合路径即可替换。

下游 / 使用方

• godot-genre-open-world — 基于此技能中的线程化 ResourceLoader 队列实现区块流式加载和后台预加载。
• godot-export-builds — PCK/补丁打包，为场景修补器挂载提供运行时包。
• godot-multiplayer-networking — 权限感知的场景生成和迟加入同步，复用对象池与安全切换模式。

主技能

• godot-master — 技能库路由器和镜像模块入口；查找负责加载、持久化或 UI 的领域技能时打开此项。