godot-scene-management

Available Scripts

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

• [asyncscenemanager.gd](scripts/asyncscenemanager.gd) — MANDATORY before loading screens / threaded level swaps (THREADLOADFAILED included).
• [backgroundresourceloader.gd](scripts/backgroundresourceloader.gd) — MANDATORY when preloading the next level during gameplay (hitch avoidance).
• [scenetransitionmanager.gd](scripts/scenetransitionmanager.gd) — Fade/wipe Tweens wrapping a safe change.
• [scenepool.gd](scripts/scenepool.gd) — MANDATORY before frequent spawn/despawn (bullets, enemies, VFX).
• [sceneinstancingpooling.gd](scripts/sceneinstancingpooling.gd) — Pool fill / reclaim patterns.
• [additiveuilayering.gd](scripts/additiveuilayering.gd) — Menus/overlays without destroying the world scene.
• [subviewportscenelayering.gd](scripts/subviewportscenelayering.gd) — Parallel worlds / minimaps (SubViewport input plan required).
• [persistentdatapreservation.gd](scripts/persistentdatapreservation.gd) — Autoload / root holders across swaps.
• [scenestatemanager.gd](scripts/scenestatemanager.gd) — Persist-group save/restore across transitions.
• [nodeunparentreparent.gd](scripts/nodeunparentreparent.gd) — Transform-preserving reparent (never mid-physics blindly).
• [nodepathsaferetrieval.gd](scripts/nodepathsaferetrieval.gd) — %UniqueName / guarded @onready.
• [dynamicscriptattachment.gd](scripts/dynamicscriptattachment.gd) — Runtime script attach for mods/dynamic entities.

NEVER Do in Scene Management

• NEVER load large scenes synchronously — load("res://largescene.tscn") on the Main Thread causes "hiccups" or full freezes during level transitions. Use ResourceLoader.loadthreaded_request() for async loading with a progress bar.
• NEVER use gettree().changescenetofile() 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 getnode("../../Path/To/Node") — These paths break as soon as you move a node in the editor. Use Scene Unique Names (%NodeName) or @export var targetnode: Node for robust references.
• NEVER reparent nodes mid-physics-step without care — Reparenting can cause one-frame transform "teleports". Always store the globaltransform and re-apply it after the addchild() 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 NOTIFICATIONWMCLOSE_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 setinputas_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

Expert WHY (staging / integrity)

• Pool pre-fill during loading screens (PROCESSMODEDISABLED + hide) — absorb instantiate cost up front via [scenepool.gd](scripts/scenepool.gd).
• Background staging — loadthreadedrequest mid-gameplay; transition only when loaded ([backgroundresourceloader.gd](scripts/backgroundresourceloader.gd)).
• PCK overrides — mount pack, then change_scene/load the same res:// path for patched content.
• Orphan audit — after swaps, Performance.OBJECTORPHANNODE_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.loadthreaded_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 changesceneto_file for staged transitions).
• Using SceneTree — currentscene, 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.loadresource_pack for DLC/mod scene overrides on res:// paths.
• ResourceLoader — Threaded load API surface (loadthreaded_*, exists) used by async managers.
• PackedScene — Scene resource type for pooling, changescenetopacked, 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.