godot-scene-management

$npx mdskill add thedivergentai/GD-Agentic-Skills/godot-scene-management

Manages scene loading, transitions, async loading, and instance caching in Godot.

  • Solves scene loading delays and hitches during level changes.
  • Depends on Godot's ResourceLoader, PackedScene, and Tween APIs.
  • Selects async loading, fade transitions, or pooling based on context.
  • Delivers scripts for autoload, transitions, and resource caching.

SKILL.md

.github/skills/godot-scene-managementView on GitHub ↗
---
name: godot-scene-management
description: "Expert blueprint for scene loading, transitions, async (background) loading, instance management, and caching. Covers fade transitions, loading screens, dynamic spawning, and scene persistence. Use when implementing level changes OR dynamic content loading. Keywords scene, loading, transition, async, ResourceLoader, change_scene, preload, PackedScene, fade."
---

## Godot 4.7 Baseline

- Expert patterns in this skill target **Godot 4.7+** (stable, 2026-06-18).
- Consult the [Godot 4.7 migration guide](https://docs.godotengine.org/en/4.7/tutorials/migrating/upgrading_to_godot_4.7.html) when upgrading projects from 4.6.
- **NEVER** assume 4.6 defaults (stretch mode, audio area_mask, RichTextLabel percent flags) without checking 4.7 migration notes.

# Scene Management

Async loading, transitions, instance pooling, and caching define smooth scene workflows.

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

### Related Skills

#### Prerequisites
- [godot-project-foundations](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-project-foundations/SKILL.md) — Project layout, scene tree basics, and import paths loaders and Autoload registries assume.
- [godot-gdscript-mastery](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-gdscript-mastery/SKILL.md) — Typed signals, `await`, and process-frame polling required by threaded load loops and transition staging.
- [godot-autoload-architecture](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-autoload-architecture/SKILL.md) — Singleton boot order and ownership so Game/state holders survive `change_scene` without becoming God Objects.

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

#### Downstream / consumers
- [godot-genre-open-world](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-genre-open-world/SKILL.md) — Chunk streaming and background preloads built on threaded `ResourceLoader` queues from this skill.
- [godot-export-builds](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-export-builds/SKILL.md) — PCK/patch packaging that supplies the runtime packs scene patchers mount.
- [godot-multiplayer-networking](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-multiplayer-networking/SKILL.md) — Authority-aware scene spawns and late-join sync that reuse pooling and safe change patterns.

#### Master
- [godot-master](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-master/SKILL.md) — Library router and mirrored module entry; open when discovering which Domain Skill owns loading vs persistence vs UI.

More from thedivergentai/GD-Agentic-Skills

SkillDescription
godot-2d-animationExpert patterns for 2D animation in Godot using AnimatedSprite2D and skeletal cutout rigs. Use when implementing sprite frame animations, procedural animation (squash/stretch), cutout bone hierarchies, or frame-perfect timing systems. Trigger keywords: AnimatedSprite2D, SpriteFrames, animation_finished, animation_looped, frame_changed, frame_progress, set_frame_and_progress, cutout animation, skeletal 2D, Bone2D, procedural animation, animation state machine, advance(0).
godot-2d-physicsExpert patterns for Godot 2D physics including collision layers/masks, Area2D triggers, raycasting, and PhysicsDirectSpaceState2D queries. Use when implementing collision detection, trigger zones, line-of-sight systems, or manual physics queries. Trigger keywords: CollisionShape2D, CollisionPolygon2D, collision_layer, collision_mask, set_collision_layer_value, set_collision_mask_value, Area2D, body_entered, body_exited, RayCast2D, force_raycast_update, PhysicsPointQueryParameters2D, PhysicsShapeQueryParameters2D, direct_space_state, move_and_collide, move_and_slide.
godot-3d-lightingExpert patterns for Godot 3D lighting including DirectionalLight3D shadow cascades, OmniLight3D attenuation, SpotLight3D projectors, VoxelGI vs SDFGI, and LightmapGI baking. Use when implementing realistic 3D lighting, shadow optimization, global illumination, or light probes. Trigger keywords: DirectionalLight3D, OmniLight3D, SpotLight3D, shadow_enabled, directional_shadow_mode, directional_shadow_split, omni_range, omni_attenuation, spot_range, spot_angle, VoxelGI, SDFGI, LightmapGI, ReflectionProbe, Environment, WorldEnvironment.
godot-3d-materialsExpert patterns for Godot 3D PBR materials using StandardMaterial3D including albedo, metallic/roughness workflows, normal maps, ORM texture packing, transparency modes, and shader conversion. Use when creating realistic 3D surfaces, PBR workflows, or material optimization. Trigger keywords: StandardMaterial3D, BaseMaterial3D, albedo_texture, metallic, metallic_texture, roughness, roughness_texture, normal_texture, normal_enabled, orm_texture, transparency, alpha_scissor, alpha_hash, cull_mode, ShaderMaterial, shader parameters.
godot-3d-world-buildingExpert patterns for 3D level design using GridMap with MeshLibrary, CSG constructive solid geometry, occlusion, and runtime GridMap builders. Use when building 3D levels, modular tilesets, or BSP-style geometry. For sky/fog/Environment recipes, route to godot-3d-lighting. Trigger keywords: GridMap, MeshLibrary, set_cell_item, get_cell_item, map_to_local, local_to_map, CSGCombiner3D, CSGBox3D, CSGSphere3D, CSGPolygon3D, OccluderInstance3D, bake CSG.
godot-ability-systemExpert patterns for RPG/action ability systems including cooldown strategies, combo systems, ability chaining, skill trees with prerequisites, upgrade paths, and resource management. Use when implementing unlockable abilities, character progression, or complex skill systems. Trigger keywords: PlayerAbility, AbilityManager, cooldown, SkillTree, SkillNode, prerequisites, can_use, execute, ComboSystem, ability_chain, global_cooldown, charge_system, upgrade_path.
godot-adapt-2d-to-3dExpert patterns for migrating 2D games to 3D including node type conversions, camera systems (third-person, first-person, orbit), physics layer migration, sprite-to-model art pipeline, and control scheme adaptations. Use when porting 2D projects to 3D or adding 3D elements. Trigger keywords: CharacterBody2D to CharacterBody3D, Area2D to Area3D, Camera2D to Camera3D, Vector2 to Vector3, collision_layer migration, sprite to MeshInstance3D, 2D to 3D conversion.
godot-adapt-3d-to-2dExpert patterns for simplifying 3D games to 2D including dimension reduction strategies, 2.5D fake-depth, isometric ports, camera flattening, physics conversion, 3D-to-sprite art pipeline, and control simplification. Use when porting 3D to 2D, building 2.5D / isometric / fake-depth gameplay, creating 2D versions for mobile, or prototyping. Trigger keywords: CharacterBody3D to CharacterBody2D, Camera3D to Camera2D, Vector3 to Vector2, flatten Z-axis, 2.5D, isometric, fake depth, Y-sort, simulated Z, orthogonal projection, 3D to sprite conversion, performance optimization.
godot-adapt-desktop-to-mobileExpert patterns for porting desktop games to mobile including touch control schemes (virtual joystick, gesture detection), UI scaling for small screens, performance optimization for mobile GPUs, battery life management, and platform-specific features. Use when creating mobile ports or cross-platform mobile builds. Trigger keywords: TouchScreenButton, virtual_joystick, gesture_detector, InputEventScreenTouch, InputEventScreenDrag, mobile_optimization, battery_saving, adaptive_performance, MOBILE_ENABLED.
godot-adapt-mobile-to-desktopExpert patterns for scaling mobile games to desktop including mouse/keyboard controls, increased resolution and graphical fidelity, expanded UI layouts, settings menus, window management, and platform-specific features. Use when creating desktop ports or cross-platform releases. Trigger keywords: mouse_controls, keyboard_shortcuts, resolution_scaling, graphics_settings, fullscreen_toggle, window_modes, Steam_integration, desktop_optimization.