godot-scene-management

Imported from xZeroW/project-r (.opencode/skills/godot-master/godot-scene-management/SKILL.md). Install upstream with npx skills add xZeroW/project-r --skill godot-scene-management. Copyright stays with the author.

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.

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.