Folded Paper Engine | Sub Scenes and Level Loading

Sub Scenes and Level Loading

Friendly recipes for doors, hubs, and streamed interiors

Proper Usage

Keep a root Folded Paper Engine node active and load sub-scenes under it so feature registration stays stable.

Place a trigger near your doorway or portal (see Triggers guide).
Add a Load Level command and point it at the next GLB path (relative to your project).
When fired, FPE unloads the current level, clears global registries (speakers, cameras, animations), and loads the new GLB cleanly.
Tip: pair with a quick fade or loading screen sub-scene so the player sees a smooth handoff.

Create a simple full-screen 2D color-rect in Godot (black or dark gray works well) and animate its opacity.
Export it as a sub-scene and trigger Load Sub Scene to show the fade, then run Load Level. When the new level is ready, remove the fade scene or animate the fade back down by loading another sub-scene.
This keeps the player from seeing mid-load pops.

Select the mesh that should act as the placeholder (e.g., a building doorway or elevator cage).
Open the FPE panel and check Sub Scene.
Provide the File Path to the GLB you want to stream in. You should name the sub-scene appropriately so commands can easily target it later.
Decide if the host should Auto Load on start. If unchecked, load it later with a Scene Event.
Export to GLB. In Godot, the host replaces its mesh with the streamed content while keeping its transform.

Load Sub Scene: Load a sub-scene by name. Great for stepping inside a house while keeping the street loaded.
Unload Sub Scene: Unload a named sub-scene and optionally wait a few seconds (with Unload Delay) to finish fades/audio/etc.
Unload This Sub Scene: From inside a sub-scene, call this to close yourself (handy on an exit trigger inside the streamed area).

Cleanup tips

Delete or move (with animations) trigger objects tied to loading areas so they don't fire twice if the player re-enters quickly.
Move reusable fades or HUD overlays into a shared sub-scene instead of duplicating them in every level.
For large hubs, unload distant interiors as soon as the exit trigger fires to keep memory predictable.

Sub scene hosts can pause parent activities while the child is loaded. That keeps NPCs or physics from running while the player is away.
Use Deactivate Player Controls plus a camera cut to hide loading, then Reactivate Player Controls when returning.

Interior door: Trigger on the doorframe → Load Sub Scene for the interior → on the interior exit trigger, run Unload This Sub Scene and, if you disabled it, Reactivate Player Camera.
Hub world with portals: Each portal trigger runs Load Level to another GLB. Keep a shared UI scene loaded to show tips during transitions.
Elevator cutscene: Trigger → Deactivate Player Controls → play lift animation with frame events → Load Level to the next floor.

Verify paths: GLB paths are relative to the project. Typos silently skip loading.
Apply transforms before export so the sub-scene spawns at the expected size and position.
If old sounds or cameras keep playing after a load, make sure you are using Load Level and not a custom script so the engine is able to do typical cleanup work.