# game.scene.switchTo() [Scene lifecycle](https://rustic-game-engine.pages.dev/markdown/api/scene-lifecycle.md) ## Compatibility **Supported languages:** C, C++, C#, Python, JavaScript, Lua 5.4, Luau, Java, PHP and HTML/inline JavaScript (binding spellings and return shapes differ). Use a compatible native engine build and the language tools required by your binding. This does not establish browser/mobile export or release qualification for every OS. The signature below is the shared reference notation; language examples show the actual binding syntax. Question marks mark optional arguments and explicit defaults are shown where recorded. Do not copy reference notation as a typed declaration. See [Feature status and compatibility](https://rustic-game-engine.pages.dev/markdown/reference/compatibility.md) for API 1.0/1.1 and per-method restrictions. Engine release tags and Docs v0.1 are independent versions. ## Signature `game.scene.switchTo(scene)` ## Setup and usage 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](https://rustic-game-engine.pages.dev/markdown/guides/scene-lifecycle.md) for exact setup, memory lifetime and errors. ## Parameters | Variable | Type | Required | Description | | --- | --- | --- | --- | | `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 Returns no value. Selects a document name or relative scene file path, automatically loading it if needed. Switching away automatically unloads scenes loaded this way, after the callback batch. Explicitly loaded scenes remain resident. Missing, ambiguous or invalid destinations raise an error without releasing the current scene. Switching to the same scene preserves its state. ## Execution behavior Core write timing differs between immediate Lua host calls, deferred JavaScript/Web commands and external SDK query flushes. Scheduled actions advance with the scene clock; synchronous queries evaluate at the call. Follow [execution rules](https://rustic-game-engine.pages.dev/markdown/guides/scripting.md#when-mutations-take-effect) and the return/timing notes for this category. ## Language examples Use these snippets inside Start/on_start after generating the Programming Workspace and attaching the script. Python imports rustic, Game and instance from rustic; C++ includes rustic.hpp; C includes rustic.h; C# uses using static Rustic; Java runs inside a Rustic subclass; PHP declares global $rustic, $Game, $instance in its callback. HTML uses an inline script in a ui/ asset. See [Lifecycle callbacks](https://rustic-game-engine.pages.dev/markdown/callbacks.md) for complete registration examples. Public-property examples require a declared integer health property. Scene examples require the named objects to exist before Play. ### Lua 5.4 ```lua local level = game.scene.load('scene/level.scene') assert(game.scene.isLoaded(level)) game.scene.switchTo(level) game.scene.unload('Menu') print(game.scene.getActive(), #game.scene.getLoaded()) ``` ### JavaScript ```javascript const level = game.scene.load('scene/level.scene'); game.scene.switchTo(level); game.scene.unload('Menu'); print(game.scene.getActive(), game.scene.getLoaded()); ``` ### Python ```python from rustic import game level = game.scene.load('scene/level.scene') game.scene.switchTo(level) game.scene.unload('Menu') assert game.scene.isLoaded(level) ``` ### C++ ```cpp auto level = game.scene.load("scene/level.scene"); game.scene.switchTo(level); game.scene.unload("Menu"); if (!game.scene.isLoaded(level)) throw std::runtime_error("Level missing"); ``` ### C# ```csharp var level = game.scene.load("scene/level.scene"); game.scene.switchTo(level); game.scene.unload("Menu"); if (!game.scene.isLoaded(level)) throw new System.Exception("Level missing"); ``` ### Luau ```lua local level = game.scene.load('scene/level.scene') game.scene.switchTo(level) game.scene.unload('Menu') assert(game.scene.isLoaded(level)) ``` ### C ```c const char *level = Game.scene.load("scene/level.scene"); Game.scene.switchTo(level); Game.scene.unload("Menu"); if (!Game.scene.isLoaded(level)) r_fail("Level missing"); ``` ### Java ```java String level = game.scene.load("scene/level.scene"); game.scene.switchTo(level); game.scene.unload("Menu"); if (!game.scene.isLoaded(level)) throw new RuntimeException("Level missing"); ``` ### PHP ```php global $game; $level = $game->scene->load("scene/level.scene"); $game->scene->switchTo($level); $game->scene->unload("Menu"); if (!$game->scene->isLoaded($level)) throw new Exception("Level missing"); ``` ### HTML / inline JS ```javascript const level = game.scene.load('scene/level.scene'); game.scene.switchTo(level); game.scene.unload('Menu'); if (!game.scene.isLoaded(level)) throw Error('Level missing'); ``` ## Shared Scene lifecycle constraints - 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. ## Errors and debugging Read the constraints above and the Console diagnostic. Invalid types, non-finite values, stale targets or unavailable native services can fail validation. A failed callback disables the behavior; a failed source reload keeps the last good instance. Exact error messages depend on the language adapter. See [Troubleshooting](https://rustic-game-engine.pages.dev/markdown/troubleshooting.md). ## Related APIs - [game.scene.load()](https://rustic-game-engine.pages.dev/markdown/api/scene-lifecycle/load.md) - [game.scene.unload()](https://rustic-game-engine.pages.dev/markdown/api/scene-lifecycle/unload.md) - [game.scene.isLoaded()](https://rustic-game-engine.pages.dev/markdown/api/scene-lifecycle/is-loaded.md) - [game.scene.getLoaded()](https://rustic-game-engine.pages.dev/markdown/api/scene-lifecycle/get-loaded.md) - [game.scene.getActive()](https://rustic-game-engine.pages.dev/markdown/api/scene-lifecycle/get-active.md) [All scene-lifecycle APIs](https://rustic-game-engine.pages.dev/markdown/api/scene-lifecycle.md)