Scene lifecycle
Load, unload and switch scenes from every supported scripting language.
Feature status and language/platform compatibility
Choose an API to see its signature, parameters, examples and behavior.
APIs
- game.scene.load()
- game.scene.unload()
- game.scene.switchTo()
- game.scene.isLoaded()
- game.scene.getLoaded()
- game.scene.getActive()
Module guide
When to call it
Save Menu and Level as distinct scene documents, with Level at scene/level.scene. Put one example inside a generated Start/on_start callback, preferably a Global Startup Script, open Menu, then press Play. Keep the language template imports and callback registration. See Load, unload and switch scenes for exact setup, memory lifetime and errors.
Variables
| Variable | Type | Required | Description |
|---|---|---|---|
path | relative project path | Yes | A saved scene file in the Play snapshot, such as scene/level.scene. Parent traversal and paths outside the snapshot are rejected. |
scene | document name string | Yes | Document name; switchTo also accepts a relative file path and tries to load a missing destination. Names are case-sensitive. Automatic name discovery searches scene/ and scenes/ and requires an unambiguous valid document. |
Return and timing
load returns the document name; isLoaded returns a boolean; getLoaded returns loaded names in sorted order; getActive returns the selected name or nil/null/None. switchTo and unload return no value. C uses RusticList for getLoaded; C++ returns a RusticValue array and a nullable RusticValue for getActive. Calls update membership/selection immediately; scene activation, teardown and final release happen after the current callback batch.
Constraints and behavior
- Loading creates a world without selecting it. Scene/object startup scripts run on first activation. Explicitly loaded inactive scenes retain state and do not tick or render. Switching back to those scenes does not rerun Start. switchTo automatically loads missing destinations by name or path, and switching away releases scenes loaded this way. Switching to the same scene preserves it.
- Unloading discards unsaved runtime state, destroys scene/object script instances and releases world, physics, audio and capture state. No unloaded scene cache is retained. Global scripts survive and can load/select a scene when none is active. Shared renderer/asset caches have their own lifetime.
- A missing or ambiguous saved destination, duplicate loads, unknown unloads, invalid or incompatible files and checksum failures raise errors. Failed load/switch operations preserve the selection. Loading never silently recovers a backup. Lifecycle mutations are unavailable during final Play teardown.
- The example requires Menu to be the initially open document name. Save Level before starting Play; scene files are staged from scene/ and scenes/. C uses Game.scene; PHP uses $game->scene. CSS is styling only; HTML uses inline JavaScript.