Godot Scene Management

Available Scripts

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

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

Expert WHY (staging / integrity)

• Pool pre-fill during loading screens (PROCESS_MODE_DISABLED + hide) — absorb instantiate cost up front via scene_pool.gd.
• Background staging — load_threaded_request mid-gameplay; transition only when loaded (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.