godot-scene-management

Available Scripts

> MANDATORY triggers below — read the matching script; do not paste incomplete Autoload loaders.

• [async_scene_manager.gd](scripts/async_scene_manager.gd) — MANDATORY before loading screens / threaded level swaps (THREAD_LOAD_FAILED included).
• [background_resource_loader.gd](scripts/background_resource_loader.gd) — MANDATORY when preloading the next level during gameplay (hitch avoidance).
• [scene_transition_manager.gd](scripts/scene_transition_manager.gd) — Fade/wipe Tweens wrapping a safe change.
• [scene_pool.gd](scripts/scene_pool.gd) — MANDATORY before frequent spawn/despawn (bullets, enemies, VFX).
• [scene_instancing_pooling.gd](scripts/scene_instancing_pooling.gd) — Pool fill / reclaim patterns.
• [additive_ui_layering.gd](scripts/additive_ui_layering.gd) — Menus/overlays without destroying the world scene.
• [subviewport_scene_layering.gd](scripts/subviewport_scene_layering.gd) — Parallel worlds / minimaps (SubViewport input plan required).
• [persistent_data_preservation.gd](scripts/persistent_data_preservation.gd) — Autoload / root holders across swaps.
• [scene_state_manager.gd](scripts/scene_state_manager.gd) — Persist-group save/restore across transitions.
• [node_unparent_reparent.gd](scripts/node_unparent_reparent.gd) — Transform-preserving reparent (never mid-physics blindly).
• [node_path_safe_retrieval.gd](scripts/node_path_safe_retrieval.gd) — %UniqueName / guarded @onready.
• [dynamic_script_attachment.gd](scripts/dynamic_script_attachment.gd) — Runtime script attach for mods/dynamic entities.

NEVER Do in Scene Management

• NEVER load large scenes synchronously — load("res://large_scene.tscn") on the Main Thread causes "hiccups" or full freezes during level transitions. Use ResourceLoader.load_threaded_request() for async loading with a progress bar.
• NEVER use get_tree().change_scene_to_file() for transient state — This method purges the current scene and all its local variables. Use an Autoload (Singleton) or a persistent 'Game' node to store state across levels.
• NEVER instance 100+ identical nodes per frame — Use Object Pooling to reuse bullets, debris, or enemies. Constant instantiate() and queue_free() calls spike CPU and trigger the Garbage Collector too often.
• NEVER hardcode get_node("../../Path/To/Node") — These paths break as soon as you move a node in the editor. Use Scene Unique Names (%NodeName) or @export var target_node: Node for robust references.
• NEVER reparent nodes mid-physics-step without care — Reparenting can cause one-frame transform "teleports". Always store the global_transform and re-apply it after the add_child() call.
• NEVER rely on the SceneTree for 10,000+ objects — If you don't need SceneTree features (signals, per-node scripts), use PhysicsServer and RenderingServer directly for raw performance.
• NEVER forget to handle NOTIFICATION_WM_CLOSE_REQUEST — On desktop, if you don't handle the close request in a persistent node, the game may close during a critical save operation.
• NEVER use deep recursion for node cleanup — queue_free() is natively recursive in Godot 4. Freeing the root node automatically cleans up all children. Manual loops are redundant and inefficient.
• NEVER mix SubViewport and main world inputs without a plan — By default, input events bubble up. Use set_input_as_handled() to prevent UI clicks in a subviewport from triggering gameplay in the main world.
• NEVER use change_scene to "Reset" a level — It reloads everything from disk. For a quick respawn, just reset the variables and move the player to the start position.

---

Decision Tree: How to Change Content

| Goal | Prefer | MANDATORY script |

|------|--------|------------------|

| Full level swap with progress UI | Threaded load → swap when THREAD_LOAD_LOADED | [async_scene_manager.gd](scripts/async_scene_manager.gd) |

| Hide hitch before a door/trigger | Start threaded request early during play | [background_resource_loader.gd](scripts/background_resource_loader.gd) |

| Fade / wipe around a swap | Transition Autoload wraps the manager | [scene_transition_manager.gd](scripts/scene_transition_manager.gd) |

| Keep world; show pause/map/inventory | Additive UI layer (do not change_scene) | [additive_ui_layering.gd](scripts/additive_ui_layering.gd) |

| Manual root swap / deferred free | Own current_scene lifecycle | Peer docs + safe patterns in godot-autoload-architecture |

| Spawn many identical actors | Pool, never raw instantiate/free storms | [scene_pool.gd](scripts/scene_pool.gd) / [scene_instancing_pooling.gd](scripts/scene_instancing_pooling.gd) |

| Minimap / split render | SubViewport + update mode + input isolation | [subviewport_scene_layering.gd](scripts/subviewport_scene_layering.gd) |

| Survive scene purge | Autoload / persist group — not locals | [persistent_data_preservation.gd](scripts/persistent_data_preservation.gd) / [scene_state_manager.gd](scripts/scene_state_manager.gd) |

| Quick respawn | Reset state + teleport — not change_scene | — |

| DLC / hot patch scenes | ProjectSettings.load_resource_pack then load path | (PCK) see Official Docs |

Expert WHY (staging / integrity)

• Pool pre-fill during loading screens (PROCESS_MODE_DISABLED + hide) — absorb instantiate cost up front via [scene_pool.gd](scripts/scene_pool.gd).
• Background staging — load_threaded_request mid-gameplay; transition only when loaded ([background_resource_loader.gd](scripts/background_resource_loader.gd)).
• PCK overrides — mount pack, then change_scene/load the same res:// path for patched content.
• Orphan audit — after swaps, Performance.OBJECT_ORPHAN_NODE_COUNT > 0 means leaked refs still hold freed nodes.
• Cleanup — queue_free() on a root is recursive in Godot 4; no manual child loops.
• Quick respawn — reset state + teleport; NEVER change_scene just to restart a level.

Deep dive (load on demand)

Fade Autoloads, loading screens, spawn tracking, persistence holders, PCK patch — [references/scene-patterns-deep.md](references/scene-patterns-deep.md).

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

• Background loading — ResourceLoader.load_threaded_request / status polling for hitch-free level loads and progress bars.
• Change scenes manually — Deferred free + root reparent patterns behind safe switchers (prefer over blind change_scene_to_file for staged transitions).
• Using SceneTree — current_scene, pause, groups, and how the tree relates to Autoload root children across swaps.
• Scene organization — Ownership edges so loaders/UI layers do not become God Objects when nesting sub-scenes.
• Nodes and scene instances — PackedScene.instantiate(), ownership, and when to preload vs load at runtime.
• Scene unique nodes — %Name references that survive hierarchy edits better than brittle get_node("../../…") paths.
• Autoloads versus regular nodes — Keep cross-scene state in singletons; keep level content in scenes the tree can unload.
• Using Viewports — SubViewport worlds for minimaps, split-screen, and layered rendering without swapping the main scene.
• Groups — Persist-group save/restore and bulk cleanup across scene transitions.
• Exporting packs, patches, and mods — ProjectSettings.load_resource_pack for DLC/mod scene overrides on res:// paths.
• ResourceLoader — Threaded load API surface (load_threaded_*, exists) used by async managers.
• PackedScene — Scene resource type for pooling, change_scene_to_packed, and instance caches.

Related Skills

Prerequisites

• godot-project-foundations — Project layout, scene tree basics, and import paths loaders and Autoload registries assume.
• godot-gdscript-mastery — Typed signals, await, and process-frame polling required by threaded load loops and transition staging.
• godot-autoload-architecture — Singleton boot order and ownership so Game/state holders survive change_scene without becoming God Objects.

Complements

• godot-signal-architecture — Reconnect or bus-emit after swaps so loaders do not leave ghost listeners on freed scenes.
• godot-resource-data-patterns — Level registries and payload Resources that map IDs to .tscn paths instead of hardcoded strings.
• godot-save-load-systems — Serialize persist-group / Autoload state; scene swaps must not invent a second save path.
• godot-tweening — Fade and wipe Tweens that wrap scene changes without blocking the load thread.
• godot-ui-containers — Loading screens and additive menu layers parented under persistent UI roots.
• godot-performance-optimization — Pool budgets, orphan-node monitors, and when SceneTree should yield to servers for dense spawns.
• godot-composition — Component scenes and ownership edges that keep instanced gameplay pieces swappable without path coupling.

Downstream / consumers

• godot-genre-open-world — Chunk streaming and background preloads built on threaded ResourceLoader queues from this skill.
• godot-export-builds — PCK/patch packaging that supplies the runtime packs scene patchers mount.
• godot-multiplayer-networking — Authority-aware scene spawns and late-join sync that reuse pooling and safe change patterns.

Master

• godot-master — Library router and mirrored module entry; open when discovering which Domain Skill owns loading vs persistence vs UI.