From 2366b1087236ec520192d946c26414e0d10fc0d0 Mon Sep 17 00:00:00 2001
From: Jamie Wells <jamiet.wells10@gmail.com>
Date: Wed, 28 Oct 2026 01:07:03 +0000
Subject: [PATCH 1/3] docs: document scene lifecycle APIs in every script
 language

---
 content/engine/scene-system.md |   8 +-
 docs/Scripting/sceneObjects.md |   6 +-
 docs/scene-lifecycle.md        | 217 +++++++++++++++++++++++++--------
 lib/api-docs.ts                |  46 +++++++
 lib/api-reference-markdown.ts  |  10 +-
 lib/api-reference.ts           |   8 ++
 lib/docs-catalog.ts            |   3 +-
 7 files changed, 240 insertions(+), 58 deletions(-)

diff --git a/content/engine/scene-system.md b/content/engine/scene-system.md
index 07e6f37..f74cc14 100644
--- a/content/engine/scene-system.md
+++ b/content/engine/scene-system.md
@@ -18,11 +18,11 @@ The current scene schema is version 2. Version 1 migrates in memory; future sche
 
 ## Editor and runtime ownership
 
-Rust hosts can use [`SceneManager`](/docs/guides/scene-lifecycle) to explicitly
-load worlds, switch only to loaded worlds, and drop worlds on unload. Loading
+Scripts use [`game.scene`](/docs/guides/scene-lifecycle) to load scenes, switch
+only to loaded scenes, and unload their worlds and runtime resources. Loading
 does not activate a scene; unloading the active scene clears the selection.
-This API manages world ownership; hosts coordinate scripting, physics, audio
-and rendering separately.
+Global scripts remain available across transitions. Rust hosts can also use
+`engine_world::SceneManager` for lower-level ECS world ownership.
 
 The editor owns the authored document. Play starts from an immutable staged snapshot and creates a separate runtime world. Stopping Play does not automatically overwrite the authored scene; the runtime-change review/apply operation is explicit and undoable.
 
diff --git a/docs/Scripting/sceneObjects.md b/docs/Scripting/sceneObjects.md
index 7c4b7de..d9b08bd 100644
--- a/docs/Scripting/sceneObjects.md
+++ b/docs/Scripting/sceneObjects.md
@@ -32,8 +32,10 @@ return {
    to return to the authored scene, or use the editor's runtime-change workflow
    when you want to retain supported changes.
 
-Only the currently loaded scene is accessible. Referring to another scene does
-not load it. Names are case-sensitive. Paths are resolved when a call applies;
+Only the active scene is accessible through object paths. Other loaded scenes
+retain their state until selected with `game.scene.switchTo(name)`. Use the
+[scene lifecycle API](/docs/guides/scene-lifecycle) to load and unload them.
+Referring to another scene does not load it. Names are case-sensitive. Paths are resolved when a call applies;
 if you rename or reparent an object, use its new path in subsequent calls.
 These functions edit engine attributes, not another script's public properties
 or arbitrary user-defined functions.
diff --git a/docs/scene-lifecycle.md b/docs/scene-lifecycle.md
index c70d567..5892e65 100644
--- a/docs/scene-lifecycle.md
+++ b/docs/scene-lifecycle.md
@@ -1,55 +1,172 @@
-# Load, unload and switch scenes (Rust)
-
-`engine_world::SceneManager` owns explicitly loaded scene worlds. Use this API
-in a Rust host with a path dependency on `crates/engine-world`. It is not exposed
-as a Lua, JavaScript, C, C++, C# or Python script function. No script attachment
-is required. Editor Play still uses its existing single-scene runtime.
-
-```rust
-use engine_world::{SceneManager, SceneManagerError};
-
-fn main() -> Result<(), SceneManagerError> {
-    let mut scenes = SceneManager::new();
-    let menu = scenes.load_file("assets/menu.rscene")?;
-    let level = scenes.load_file("assets/level.rscene")?;
-    scenes.switch(menu)?;
-    scenes.switch(level)?;
-    scenes.unload(menu)?;
-    assert!(!scenes.is_loaded(menu));
-    assert!(scenes.switch(menu).is_err());
-    assert_eq!(scenes.active_id(), Some(level));
-    Ok(())
+# Load, unload and switch scenes
+
+Use `game.scene` to manage scenes from Lua 5.4, Luau, JavaScript, Python, C++,
+C#, Java, PHP and HTML with inline JavaScript. C uses `Game.scene`.
+The scene open when Play starts is already loaded and active.
+
+## Set up and run
+
+1. Save two scenes with unique document names, such as **Menu** and **Level**.
+   Save Level as `scene/level.scene` (legacy `scenes/*.rscene` also works).
+   Scene names and scene IDs must both be unique among loaded scenes.
+2. Open Menu. Create a **Global Startup Script** through the Programming menu
+   and select a language. Paste the matching example into its Start/on_start
+   callback, keeping the generated imports and callback registration.
+   Object component and scene startup scripts can call these APIs too; they
+   belong to their scene and end when that scene is unloaded. Global scripts
+   remain alive and can load a scene even when none is active.
+3. Save all target scenes before pressing **Play**. Play snapshots include scene
+   files from `scene/` and `scenes/`; keeping a file on disk does not load its
+   world into runtime memory. Edits made on disk after Play starts require a
+   new Play session. The initially open scene includes its current editor state.
+4. Run the example. Level becomes the active scene on the next scene transition
+   boundary. Menu is unloaded, its scene/object scripts are destroyed, and its
+   world, physics, decoded audio, capture state and script runtimes are released.
+   Level must contain a camera to produce a camera view.
+
+```lua
+return {
+    Start = function()
+        local level = game.scene.load('scene/level.scene')
+        assert(game.scene.isLoaded(level))
+        game.scene.switchTo(level)
+        game.scene.unload('Menu')
+        assert(not game.scene.isLoaded('Menu'))
+    end,
+}
+```
+
+```javascript
+// JavaScript, or inside a <script> in a ui/ HTML asset.
+globalThis.behavior = {
+  Start() {
+    const level = game.scene.load('scene/level.scene');
+    game.scene.switchTo(level);
+    game.scene.unload('Menu');
+  }
+};
+```
+
+Use the same Lua example for Luau. Other language callback bodies:
+
+```python
+# from rustic import game, run
+# Register with run(globals()) after defining callbacks.
+def on_start():
+    level = game.scene.load('scene/level.scene')
+    game.scene.switchTo(level)
+    game.scene.unload('Menu')
+```
+
+```cpp
+// #include "rustic.hpp"; register start with RusticBehavior.on_start.
+void start() {
+    auto level = game.scene.load("scene/level.scene");
+    game.scene.switchTo(level);
+    game.scene.unload("Menu");
 }
 ```
 
-Replace the paths with valid saved scene files. The example leaves the level
-active and loaded, and releases the menu world. `load(SceneDocument)` also
-accepts an owned document created or loaded by the host.
+```csharp
+// using static Rustic; inside the generated on_start callback:
+var level = game.scene.load("scene/level.scene");
+game.scene.switchTo(level);
+game.scene.unload("Menu");
+```
+
+```c
+// #include "rustic.h"; register start with RusticBehavior.on_start.
+void start(void) {
+    const char *level = Game.scene.load("scene/level.scene");
+    Game.scene.switchTo(level);
+    Game.scene.unload("Menu");
+}
+```
+
+```java
+// Inside a Rustic subclass's on_start callback:
+String level = game.scene.load("scene/level.scene");
+game.scene.switchTo(level);
+game.scene.unload("Menu");
+```
 
-| Operation | Result |
+```php
+// require rustic.php and register on_start with rustic_run.
+function on_start(): void {
+    global $game;
+    $level = $game->scene->load("scene/level.scene");
+    $game->scene->switchTo($level);
+    $game->scene->unload("Menu");
+}
+```
+
+See the [language guides](/docs/guides/api-languages) for complete SDK setup.
+`Game.scene` also exposes these methods in each language. CSS alone has no
+callbacks; HTML runs the JavaScript API. PHP and HTML remain UI script types.
+
+## Calls and results
+
+| Call | Result |
 | --- | --- |
-| `load(document)` / `load_file(path)` | Build a world and return its scene ID, without selecting it. |
-| `switch(id)` | Select a loaded world. An unknown or unloaded ID returns `NotLoaded`. |
-| `unload(id)` | Drop that world and its entities/components. Unsaved edits are discarded. |
-| `is_loaded(id)` / `loaded_ids()` | Inspect the worlds currently owned by the manager. |
-| `active_id()` / `active_world()` / `active_world_mut()` | Inspect or edit the selected world; initially `None`. |
-| `world(id)` / `world_mut(id)` | Borrow any loaded world by ID. |
-
-Switching retains loaded worlds and their edits. Switching to the current world
-is allowed. Unloading the active world clears the selection, even if other worlds
-remain loaded. Load or switch another world explicitly. Duplicate loads return
-`AlreadyLoaded`; unloading an unknown ID returns `NotLoaded`. Failed operations
-preserve the loaded set and selection.
-
-The manager retains no unloaded entry, document, serialized bytes, or world cache.
-Reloading reads the file again and builds a fresh world. File loading rejects
-incompatible versions, damaged data and checksum mismatches, and does not read
-backup files. Inspect `SceneManagerError` for I/O, parsing or world validation
-failures; open and save externally edited scenes in the editor to refresh their
-checksum before runtime loading.
-
-The host must tick and render the selected world, and coordinate script callbacks,
-physics, audio and GPU resources separately. The manager owns ECS world data only;
-assets or resources retained elsewhere in the host are outside its ownership.
-Loading a document does not execute its startup scripts. Save authored changes
-explicitly before unloading if they should survive.
+| `game.scene.load(path)` | Read a saved relative scene file, build its world, and return its document name. Does not activate it or run its startup callbacks. |
+| `game.scene.switchTo(scene)` | Select an already loaded document name. Scene/object startup callbacks run on first activation. |
+| `game.scene.unload(scene)` | Remove that document name from the loaded set; discard its unsaved runtime state and release its world and scene-owned runtime resources. |
+| `game.scene.isLoaded(scene)` | Return whether the document name is loaded. |
+| `game.scene.getLoaded()` | Return loaded document names in deterministic name order. |
+| `game.scene.getActive()` | Return the selected document name, or nil/null/None when no scene is selected. |
+
+`load` returns a string in every language. Lua/Luau/JS/Python/C#/Java/PHP return
+native lists from `getLoaded`; C returns `RusticList` (`count`, `items`), and
+C++ returns a `RusticValue` array. C++ `getActive` returns a nullable `RusticValue`;
+check `is_null()` before `string()`. C query strings and lists last until the end
+of the callback; copy strings if keeping them across callbacks.
+
+## Lifetime and transitions
+
+Loading allocates only that scene's live world. Switching preserves other loaded
+worlds, edits and script state. Inactive loaded scenes do not tick or render;
+switching back resumes them without rerunning Start. Unloading releases a scene
+instead of caching it. Reloading reads the saved file and starts fresh.
+
+Calls update the loaded set and selected name synchronously, so loading and then
+switching in one callback works. Scene runtime activation, teardown callbacks and
+final memory release happen at the runtime boundary after the current callback
+batch. Code already running can finish; return after requesting a transition if
+it should do no more work on the old scene. A scene selected from a newly started
+scene's Start callback is activated at the following boundary.
+
+Unloading the active scene clears selection without choosing a fallback.
+Global scripts continue, but the view is empty until a loaded scene is selected.
+Scene/object OnDestroy and OnStop run on unload. Global scripts end only when
+Play ends or they are disabled. The engine owns shared renderer/asset caches;
+those are separate from the scene world and its scene-owned runtime state.
+
+Object-path lookup and rendering use the active scene. Apply Runtime Changes
+still compares the originally opened scene if it remains loaded; it does not save
+other scenes. Explicitly save authored changes before Play; runtime unload
+never writes to scene files.
+
+## Errors and diagnosis
+
+Switching to an unknown or unloaded name raises a script error and preserves the
+selection. Loading a duplicate name or scene ID, or unloading an unknown name,
+also raises an error. Catch expected errors with `pcall`/try/catch as appropriate.
+
+`load` takes a relative project file path, while switch/unload/query calls take
+the **document name returned by load**. Paths cannot escape the Play snapshot.
+Missing files, invalid RON, invalid world data, incompatible schema versions and
+checksum mismatches raise errors without adding a loaded scene. The loader does
+not silently use a backup. Open and save externally edited scene files in the
+editor to refresh their checksums, then start Play again.
+
+If a target's script source fails to load at first activation, the Console reports
+its startup failure and clears the selection. Fix the source, then reload the
+scene. Missing script attachments retain the existing warning-and-skip behavior.
+Scene lifecycle mutations are rejected during final Play teardown.
+
+## Rust host API
+
+Rust hosts can also use `engine_world::SceneManager` with `load`, `load_file`,
+`switch`, `unload`, `is_loaded`, `loaded_ids`, and active/world borrowing methods.
+That lower-level manager owns ECS worlds only; the scripting runtime above also
+coordinates callbacks, physics and audio lifetime.
diff --git a/lib/api-docs.ts b/lib/api-docs.ts
index 1276b5a..678aad7 100644
--- a/lib/api-docs.ts
+++ b/lib/api-docs.ts
@@ -136,6 +136,52 @@ const docs: Record<string, ApiDoc> = {
     returns: "No value. Lua updates host state directly; JavaScript/Web and external SDKs use their command boundary. The scheduler observes the resulting enabled state for lifecycle transitions. See [execution behavior](/docs/guides/scripting#when-mutations-take-effect).",
     examples: simpleMutationExamples("rustic.set_enabled(false)", "rustic.set_enabled(false);"), notes: [protocolNote],
   },
+  "scene-lifecycle": {
+    "title": "Scene lifecycle API",
+    "summary": "Load, unload and switch scenes explicitly from every supported scripting language. Only loaded scene worlds stay resident.",
+    "when": "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](/docs/guides/scene-lifecycle) for exact setup, memory lifetime and errors.",
+    "calls": [
+        "game.scene.load(path)",
+        "game.scene.unload(scene)",
+        "game.scene.switchTo(scene)",
+        "game.scene.isLoaded(scene)",
+        "game.scene.getLoaded()",
+        "game.scene.getActive()"
+    ],
+    "parameters": [
+        {
+            "name": "path",
+            "type": "relative project path",
+            "required": true,
+            "description": "A saved scene file in the Play snapshot, such as scene/level.scene. Parent traversal and paths outside the snapshot are rejected."
+        },
+        {
+            "name": "scene",
+            "type": "document name string",
+            "required": true,
+            "description": "Name returned by load, or the initially opened scene document name. Case-sensitive. Loading requires both the name and scene ID to be unique among loaded scenes."
+        }
+    ],
+    "returns": "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.",
+    "examples": {
+        "Lua 5.4": "local level = game.scene.load('scene/level.scene')\nassert(game.scene.isLoaded(level))\ngame.scene.switchTo(level)\ngame.scene.unload('Menu')\nprint(game.scene.getActive(), #game.scene.getLoaded())",
+        "JavaScript": "const level = game.scene.load('scene/level.scene');\ngame.scene.switchTo(level);\ngame.scene.unload('Menu');\nprint(game.scene.getActive(), game.scene.getLoaded());",
+        "Python": "from rustic import game\nlevel = game.scene.load('scene/level.scene')\ngame.scene.switchTo(level)\ngame.scene.unload('Menu')\nassert game.scene.isLoaded(level)",
+        "C++": "auto level = game.scene.load(\"scene/level.scene\");\ngame.scene.switchTo(level);\ngame.scene.unload(\"Menu\");\nif (!game.scene.isLoaded(level)) throw std::runtime_error(\"Level missing\");",
+        "C#": "var level = game.scene.load(\"scene/level.scene\");\ngame.scene.switchTo(level);\ngame.scene.unload(\"Menu\");\nif (!game.scene.isLoaded(level)) throw new System.Exception(\"Level missing\");",
+        "Luau": "local level = game.scene.load('scene/level.scene')\ngame.scene.switchTo(level)\ngame.scene.unload('Menu')\nassert(game.scene.isLoaded(level))",
+        "C": "const char *level = Game.scene.load(\"scene/level.scene\");\nGame.scene.switchTo(level);\nGame.scene.unload(\"Menu\");\nif (!Game.scene.isLoaded(level)) r_fail(\"Level missing\");",
+        "Java": "String level = game.scene.load(\"scene/level.scene\");\ngame.scene.switchTo(level);\ngame.scene.unload(\"Menu\");\nif (!game.scene.isLoaded(level)) throw new RuntimeException(\"Level missing\");",
+        "PHP": "global $game;\n$level = $game->scene->load(\"scene/level.scene\");\n$game->scene->switchTo($level);\n$game->scene->unload(\"Menu\");\nif (!$game->scene->isLoaded($level)) throw new Exception(\"Level missing\");",
+        "HTML / inline JS": "const level = game.scene.load('scene/level.scene');\ngame.scene.switchTo(level);\ngame.scene.unload('Menu');\nif (!game.scene.isLoaded(level)) throw Error('Level missing');"
+    },
+    "notes": [
+        "Loading creates a world without selecting it. Scene/object startup scripts run on first activation. Inactive loaded scenes retain state and do not tick or render. Switching back does not rerun Start.",
+        "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.",
+        "Switching to an unloaded name, 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."
+    ]
+},
   environment: {
     title: "Scene environment API", summary: "Read and update all loaded-scene sky, ambient light, sun light and haze settings in every scripting language.",
     when: "Call during Start or a later gameplay callback. Attach a scene startup or object component script, copy panoramas into the project before Play, and enable the environment. See [Sky & atmosphere](/docs/guides/scene-environment) for complete setup and all 13 fields.",
diff --git a/lib/api-reference-markdown.ts b/lib/api-reference-markdown.ts
index 0d4fa9b..6ccb7f7 100644
--- a/lib/api-reference-markdown.ts
+++ b/lib/api-reference-markdown.ts
@@ -177,7 +177,15 @@ export function buildApiCallMarkdown(category: ApiCategory, call: ApiCall, title
     return `| ${name} | ${meaning} |`;
   }).join("\n")}` : parametersFor(call, section(shared, "Parameters") || section(shared, "Variables"));
   const setup = section(shared, "Setup and language support") || section(shared, "When to call it");
-  const returns = audio ? audioReturn(method) : section(shared, "Return and timing");
+  const sceneReturns: Record<string, string> = {
+    load: "Returns the loaded document name as a string. Builds a world without activating it or running scene startup callbacks. Duplicate names/IDs and invalid files raise errors without changing the loaded set.",
+    unload: "Returns no value. Removes the name immediately; scene/object teardown and final world/runtime resource release happen after the callback batch. Unloading the active scene clears selection. Unsaved state is discarded.",
+    "switch-to": "Returns no value. Selects an already loaded name; activation occurs after the callback batch. An unloaded or unknown name raises an error without changing selection. Switching back to a loaded scene preserves its state.",
+    "is-loaded": "Returns true when this document name is in the loaded set, otherwise false. It does not read scene files or implicitly load a scene.",
+    "get-loaded": "Returns loaded document names in deterministic name order: a native list in Lua/Luau, JavaScript, Python, C#, Java and PHP; RusticList in C; a RusticValue array in C++.",
+    "get-active": "Returns the selected document name or nil/null/None if none is selected. C++ returns a nullable RusticValue; check is_null() before string(). Selection changes synchronously, before runtime activation completes.",
+  };
+  const returns = category.slug === "api/scene-lifecycle" ? sceneReturns[method] : audio ? audioReturn(method) : section(shared, "Return and timing");
   const name = call.signature.split("(")[0];
   const topic = category.slug.slice(4);
   const example = category.source.startsWith("api:")
diff --git a/lib/api-reference.ts b/lib/api-reference.ts
index 142b0aa..03d82c2 100644
--- a/lib/api-reference.ts
+++ b/lib/api-reference.ts
@@ -263,6 +263,14 @@ export const apiCategories: ApiCategory[] = [
   category("enabled", "api:enabled", [
     "rustic.set_enabled(enabled)",
   ]),
+  category("scene-lifecycle", "api:scene-lifecycle", [
+    "game.scene.load(path)",
+    "game.scene.unload(scene)",
+    "game.scene.switchTo(scene)",
+    "game.scene.isLoaded(scene)",
+    "game.scene.getLoaded()",
+    "game.scene.getActive()",
+  ]),
   category("environment", "api:environment", [
     "Game.scene.getEnvironment()",
     "Game.scene.setEnvironment(settings)",
diff --git a/lib/docs-catalog.ts b/lib/docs-catalog.ts
index 2d53c0c..7610cf3 100644
--- a/lib/docs-catalog.ts
+++ b/lib/docs-catalog.ts
@@ -5,7 +5,7 @@ export type DocGroup = { label: string; docs: DocEntry[] };
 
 const categoryGroups: DocGroup[] = [
   { label: "Start here", docs: [
-    { slug: "guides/scene-lifecycle", title: "Load, unload and switch scenes (Rust)", description: "Explicit ownership and active selection of loaded scene worlds in Rust hosts.", source: "docs/scene-lifecycle.md" },
+    { slug: "guides/scene-lifecycle", title: "Load, unload and switch scenes", description: "Manage scene loading, switching and memory lifetime from every scripting language.", source: "docs/scene-lifecycle.md" },
     { slug: "engine", title: "Using Rustic Engine", description: "Create a game, attach scripts, and learn how to use the editor and gameplay API.", source: "content/engine.md" },
     { slug: "tutorials/first-playable-scene", title: "First playable scene", description: "Create an object, attach Lua and test the startup callback.", source: "content/tutorials/first-playable-scene.md" },
     { slug: "api/overview", title: "API overview", description: "Rustic API concepts, language support, and execution rules.", source: "api:overview" },
@@ -86,6 +86,7 @@ const categoryGroups: DocGroup[] = [
   { label: "Scene API", docs: [
     { slug: "guides/api-paths", title: "Call APIs through paths", description: "Use scene object, global service and Explorer file API paths in every scripting language.", source: "docs/Scripting/apiPaths.md" },
     { slug: "guides/scene-objects", title: "Edit scene objects", description: "Target an object by scene name and hierarchy in any script language.", source: "docs/Scripting/sceneObjects.md" },
+    { slug: "api/scene-lifecycle", title: "Scene lifecycle", description: "Load, unload and switch scenes from every supported scripting language.", source: "api:scene-lifecycle" },
     { slug: "api/environment", title: "Scene environment", description: "Read and change sky textures, ambient and sun lighting, and haze from every script language.", source: "api:environment" },
     { slug: "api/scene", title: "Scene lookup", description: "Find entities and enumerate stable scene paths.", source: "api:scene" },
     { slug: "api/instances", title: "Add & clone instances", description: "Queue creation from a source path with an optional parent.", source: "api:instances" },

From eb9b7500cc3c437394d232b1467f7ca9b89c9e4d Mon Sep 17 00:00:00 2001
From: Jamie Wells <jamiet.wells10@gmail.com>
Date: Wed, 28 Oct 2026 02:02:17 +0000
Subject: [PATCH 2/3] docs: explain automatic scene switching lifetime

---
 content/engine/scene-system.md |  4 +++-
 docs/scene-lifecycle.md        | 40 +++++++++++++++++++++++++++-------
 lib/api-docs.ts                |  6 ++---
 lib/api-reference-markdown.ts  |  2 +-
 4 files changed, 39 insertions(+), 13 deletions(-)

diff --git a/content/engine/scene-system.md b/content/engine/scene-system.md
index f74cc14..0daf59d 100644
--- a/content/engine/scene-system.md
+++ b/content/engine/scene-system.md
@@ -19,7 +19,9 @@ The current scene schema is version 2. Version 1 migrates in memory; future sche
 ## Editor and runtime ownership
 
 Scripts use [`game.scene`](/docs/guides/scene-lifecycle) to load scenes, switch
-only to loaded scenes, and unload their worlds and runtime resources. Loading
+to saved scenes with automatic loading, and unload their worlds and runtime resources.
+Scenes automatically loaded by switching unload on switching away; explicitly
+loaded scenes remain resident. Loading
 does not activate a scene; unloading the active scene clears the selection.
 Global scripts remain available across transitions. Rust hosts can also use
 `engine_world::SceneManager` for lower-level ECS world ownership.
diff --git a/docs/scene-lifecycle.md b/docs/scene-lifecycle.md
index 5892e65..5de6d33 100644
--- a/docs/scene-lifecycle.md
+++ b/docs/scene-lifecycle.md
@@ -104,12 +104,35 @@ See the [language guides](/docs/guides/api-languages) for complete SDK setup.
 `Game.scene` also exposes these methods in each language. CSS alone has no
 callbacks; HTML runs the JavaScript API. PHP and HTML remain UI script types.
 
+## Automatic loading when switching
+
+`switchTo` also accepts a saved scene that is not in memory. Use its document
+name, or pass its relative file path directly:
+
+```lua
+game.scene.switchTo('Level') -- finds the saved document in scene/ or scenes/
+assert(game.scene.isLoaded('Level'))
+game.scene.switchTo('Menu') -- automatically unloads Level
+assert(not game.scene.isLoaded('Level'))
+```
+
+The same calls work with native member syntax in the other languages. C uses
+`Game.scene.switchTo("scene/level.scene")`. A document name can differ from its
+filename; name lookup searches nested scene directories on demand. If multiple
+valid saved scenes have the same document name, pass a path to choose one.
+
+A scene loaded automatically by switching is temporary: switching away unloads
+it and releases its state after the callback batch. Switching to it again reads
+the saved file and starts fresh. Switching to the same scene keeps its state.
+Scenes loaded explicitly with `load`, and the initial Play scene, stay loaded
+when you switch away. Call `unload` to release those scenes yourself.
+
 ## Calls and results
 
 | Call | Result |
 | --- | --- |
 | `game.scene.load(path)` | Read a saved relative scene file, build its world, and return its document name. Does not activate it or run its startup callbacks. |
-| `game.scene.switchTo(scene)` | Select an already loaded document name. Scene/object startup callbacks run on first activation. |
+| `game.scene.switchTo(scene)` | Select a document name or relative scene file path. If needed, load it automatically. Automatically loaded scenes unload on switching away; scene/object startup callbacks run on first activation. |
 | `game.scene.unload(scene)` | Remove that document name from the loaded set; discard its unsaved runtime state and release its world and scene-owned runtime resources. |
 | `game.scene.isLoaded(scene)` | Return whether the document name is loaded. |
 | `game.scene.getLoaded()` | Return loaded document names in deterministic name order. |
@@ -123,9 +146,9 @@ of the callback; copy strings if keeping them across callbacks.
 
 ## Lifetime and transitions
 
-Loading allocates only that scene's live world. Switching preserves other loaded
-worlds, edits and script state. Inactive loaded scenes do not tick or render;
-switching back resumes them without rerunning Start. Unloading releases a scene
+Loading allocates only that scene's live world. Switching preserves explicitly
+loaded worlds, edits and script state. Inactive explicitly loaded scenes do not
+tick or render; switching back resumes them without rerunning Start. Unloading releases a scene
 instead of caching it. Reloading reads the saved file and starts fresh.
 
 Calls update the loaded set and selected name synchronously, so loading and then
@@ -148,12 +171,13 @@ never writes to scene files.
 
 ## Errors and diagnosis
 
-Switching to an unknown or unloaded name raises a script error and preserves the
-selection. Loading a duplicate name or scene ID, or unloading an unknown name,
+Switching to an unloaded scene tries to load it first. If the destination cannot
+be found, is ambiguous, or fails file/world validation, the current scene stays
+selected and loaded, including when it was automatically loaded. Loading a duplicate name or scene ID, or unloading an unknown name,
 also raises an error. Catch expected errors with `pcall`/try/catch as appropriate.
 
-`load` takes a relative project file path, while switch/unload/query calls take
-the **document name returned by load**. Paths cannot escape the Play snapshot.
+`load` takes a relative project file path. `switchTo` accepts a document name or
+a relative file path; unload/query calls take the **document name returned by load**. Paths cannot escape the Play snapshot.
 Missing files, invalid RON, invalid world data, incompatible schema versions and
 checksum mismatches raise errors without adding a loaded scene. The loader does
 not silently use a backup. Open and save externally edited scene files in the
diff --git a/lib/api-docs.ts b/lib/api-docs.ts
index 678aad7..435eb77 100644
--- a/lib/api-docs.ts
+++ b/lib/api-docs.ts
@@ -159,7 +159,7 @@ const docs: Record<string, ApiDoc> = {
             "name": "scene",
             "type": "document name string",
             "required": true,
-            "description": "Name returned by load, or the initially opened scene document name. Case-sensitive. Loading requires both the name and scene ID to be unique among loaded scenes."
+            "description": "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."
         }
     ],
     "returns": "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.",
@@ -176,9 +176,9 @@ const docs: Record<string, ApiDoc> = {
         "HTML / inline JS": "const level = game.scene.load('scene/level.scene');\ngame.scene.switchTo(level);\ngame.scene.unload('Menu');\nif (!game.scene.isLoaded(level)) throw Error('Level missing');"
     },
     "notes": [
-        "Loading creates a world without selecting it. Scene/object startup scripts run on first activation. Inactive loaded scenes retain state and do not tick or render. Switching back does not rerun Start.",
+        "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.",
-        "Switching to an unloaded name, 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.",
+        "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."
     ]
 },
diff --git a/lib/api-reference-markdown.ts b/lib/api-reference-markdown.ts
index 6ccb7f7..a80a6b1 100644
--- a/lib/api-reference-markdown.ts
+++ b/lib/api-reference-markdown.ts
@@ -180,7 +180,7 @@ export function buildApiCallMarkdown(category: ApiCategory, call: ApiCall, title
   const sceneReturns: Record<string, string> = {
     load: "Returns the loaded document name as a string. Builds a world without activating it or running scene startup callbacks. Duplicate names/IDs and invalid files raise errors without changing the loaded set.",
     unload: "Returns no value. Removes the name immediately; scene/object teardown and final world/runtime resource release happen after the callback batch. Unloading the active scene clears selection. Unsaved state is discarded.",
-    "switch-to": "Returns no value. Selects an already loaded name; activation occurs after the callback batch. An unloaded or unknown name raises an error without changing selection. Switching back to a loaded scene preserves its state.",
+    "switch-to": "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.",
     "is-loaded": "Returns true when this document name is in the loaded set, otherwise false. It does not read scene files or implicitly load a scene.",
     "get-loaded": "Returns loaded document names in deterministic name order: a native list in Lua/Luau, JavaScript, Python, C#, Java and PHP; RusticList in C; a RusticValue array in C++.",
     "get-active": "Returns the selected document name or nil/null/None if none is selected. C++ returns a nullable RusticValue; check is_null() before string(). Selection changes synchronously, before runtime activation completes.",

From b2315063b3305235d309aeca8a8d4e6b65f53722 Mon Sep 17 00:00:00 2001
From: Jamie Wells <jamiet.wells10@gmail.com>
Date: Wed, 28 Oct 2026 02:10:55 +0000
Subject: [PATCH 3/3] fix(ci): refresh reviewed scene API drift baseline

---
 lib/engine-api-baseline.json   | 193 ++++++++++++++++++++++++++++++---
 scripts/check-engine-drift.mjs |   2 +-
 2 files changed, 176 insertions(+), 19 deletions(-)

diff --git a/lib/engine-api-baseline.json b/lib/engine-api-baseline.json
index a162e39..9f60c41 100644
--- a/lib/engine-api-baseline.json
+++ b/lib/engine-api-baseline.json
@@ -1,5 +1,5 @@
 {
-  "revision": "1f6d9bed41795e1cb40ec3dec588bec2b3d93941",
+  "revision": "d8d47866c29a0f268d75169920afd8ac6bb43fa2",
   "documented": {
     "languages": [
       "Lua 5.4",
@@ -171,6 +171,12 @@
       "capture:stop()",
       "capture:unload()",
       "connection.disconnect()",
+      "game.scene.getActive()",
+      "game.scene.getLoaded()",
+      "game.scene.isLoaded(scene)",
+      "game.scene.load(path)",
+      "game.scene.switchTo(scene)",
+      "game.scene.unload(scene)",
       "handle.cancel()",
       "handle.loop(enabled)",
       "handle.onFinished(callback)",
@@ -262,7 +268,7 @@
       ]
     },
     "crates/engine-scripting/src/lua.rs": {
-      "sha256": "e97ad601f6b1e69f5ff063c0d44180b5643a155ded935fbd70461045583b23e7",
+      "sha256": "e3125be5c6a2d2a0aa9fccc4ea6247afd55d13e9824b02375e7f1cd3be5b2df4",
       "declarations": [
         "pub enum LuaRuntimeError {",
         "pub fn fixed_update(&mut self, delta: f64) -> Result<(), LuaRuntimeError> {",
@@ -281,7 +287,7 @@
       ]
     },
     "crates/engine-scripting/src/javascript.rs": {
-      "sha256": "a8ff8c6554cb24da7efbbaa344dd76a11f1881b5685437cf1de2314e1e600473",
+      "sha256": "591f4edfdec12634739e0309f1182402a60e8340184f74f6229f5fa17c3d4b94",
       "declarations": [
         "pub enum JavaScriptRuntimeError {",
         "pub fn fixed_update(&mut self, delta: f64) -> Result<(), JavaScriptRuntimeError> {",
@@ -300,7 +306,7 @@
       ]
     },
     "crates/engine-scripting/src/external_runtime.rs": {
-      "sha256": "22bcff3022c24923c83be784eeae9359bb280f2427daac3bb5ab7e4164ccbd0f",
+      "sha256": "bfd608946c5b566b0a10aa34b5932cadfe0620cec50c1326fda88ce96d69b2ea",
       "declarations": [
         "def fixed_update(dt):",
         "def on_disable():",
@@ -327,24 +333,28 @@
       ]
     },
     "crates/engine-scripting/src/cpp_sdk.rs": {
-      "sha256": "aa39b6839438f63740a0960651cee413d4ecb1378518411db3b529cf4cb97539",
+      "sha256": "62cdffcfc5471ad898693cdfbd954b1d3f4b2913312c2c7b96bb0e6840253181",
       "declarations": []
     },
     "crates/engine-scripting/src/sdk/rustic.h": {
-      "sha256": "0f832e037993e5fa6def10aaa2a3abc09b0e019d61d3a3fb0c868ef47c26a5d0",
+      "sha256": "b6432d66fd0237bd7c45ceed0af3d5369e436a23153ad0273b8f7929912546ed",
       "declarations": []
     },
     "crates/engine-scripting/src/sdk/rustic.py": {
-      "sha256": "6b5cfa99fd798872e1fb3511d06d9a90086d7f058e6fc5279a2b9fe44f51660c",
+      "sha256": "d21babf4c8ca8ffd9f901487633c1824a684641ac4828d445b01d620ea5c4167",
       "declarations": [
         "def EditAttribute(self, name, value):",
         "def Find(self, path): return self.state.get(path)",
         "def GetAttribute(self,name): return rustic.query(dict(op=\"object_attribute\",source=self.source,name=name))",
         "def List(self, path=\"Game.scene\"):",
         "def __getattr__(self, name):",
+        "def __getattr__(self,name):",
         "def __getitem__(self, name): return ObjectPath(self.source + \".\" + str(name))",
+        "def __getitem__(self,name):",
         "def __init__(self): self.actions=[]",
         "def __init__(self): self.commands = []",
+        "def __init__(self): self.files=ApiPath('game.rustic.files','file','')",
+        "def __init__(self): self.scene=ApiPath('game.scene','scene'); self.rustic=GlobalApi()",
         "def __init__(self): self.state = {}",
         "def __init__(self): self.state = {}; self.commands = instance.commands",
         "def __init__(self, action, loop=False, repeats=0, ping_pong=False):",
@@ -353,6 +363,7 @@
         "def __init__(self,id): self.id=id",
         "def __init__(self,id,recording): self.id=id; self.recording=recording",
         "def __init__(self,name,fn,once=False,source=None):",
+        "def __init__(self,source,category,file_path=None):",
         "def _callback(fn, persistent=False):",
         "def _cleanup(self):",
         "def _complete(self):",
@@ -371,7 +382,9 @@
         "def addMarker(o,clip,time,name): return rustic.query(dict(op=\"animation_marker\",entity=_entity(o),clip=clip,time=time,name=name))",
         "def after(delay,fn): return GameplayHandle({\"kind\":\"sequence\",\"actions\":[{\"kind\":\"wait\",\"duration\":delay},{\"kind\":\"callback\",\"token\":_callback(fn)}]})",
         "def any_key_pressed(self): return self.state[\"any_key_pressed\"]",
+        "def argument(value):",
         "def blend(o,source,target,options=None):",
+        "def call(*args,**kwargs):",
         "def call(self,fn): self.actions.append({\"kind\":\"callback\",\"token\":_callback(fn)}); return self",
         "def cancel(self): return self._control(\"cancel\")",
         "def clips(o): return rustic.query(dict(op=\"animation_list\",entity=_entity(o)))",
@@ -410,7 +423,9 @@
         "def gameplay_callbacks(self): return self.state.get(\"gameplay_callbacks\", [])",
         "def gameplay_connections(self): return self.state.get(\"gameplay_connections\",[])",
         "def gameplay_states(self): return self.state.get(\"gameplay_states\", [])",
+        "def getActive(self): return rustic.query({\"op\":\"scene_active\"})",
         "def getEnvironment(self,field=None): return rustic.query({\"op\":\"scene_environment\"} if field is None else dict(op=\"scene_environment_field\",field=field))",
+        "def getLoaded(self): return rustic.query({\"op\":\"scene_loaded\"})",
         "def get_all(entity): return rustic.query({\"op\":\"components_get_all\",'entity':_entity(entity)})",
         "def get_attribute(self, name): return self.state[\"attributes\"].get(name)",
         "def get_children(entity): return rustic.query({\"op\":\"hierarchy_get_children\",'entity':_entity(entity)})",
@@ -424,6 +439,7 @@
         "def impulse(o,vector): return rustic.query(dict(op=\"physics_impulse\",entity=_entity(o),vector=vector))",
         "def input(self, name): return self.state.get(\"actions\", {}).get(name, {\"pressed\":False,\"released\":False,\"held\":False,\"axis\":0})",
         "def inverseLerp(a,b,v): return rustic.query({\"op\":\"inverse_lerp\",\"from\":a,\"to\":b,\"value\":v})",
+        "def isLoaded(self,scene): return rustic.query({\"op\":\"scene_is_loaded\",\"scene\":scene})",
         "def is_valid(entity): return rustic.query({\"op\":\"entity_is_valid\",'entity':_entity(entity)})",
         "def key(self, name): return self.state[\"keys\"].get(name, {\"pressed\":False,\"released\":False,\"held\":False,\"axis\":0})",
         "def key_events(self): return self.state[\"key_events\"][:]",
@@ -431,6 +447,7 @@
         "def lerp(a,b,t,easing=\"Linear\"): return rustic.query({\"op\":\"lerp\",\"from\":a,\"to\":b,\"progress\":t,\"easing\":easing})",
         "def load(o,source): return rustic.query(dict(op=\"animation_load\",entity=_entity(o),source=source))",
         "def load(self):",
+        "def load(self,scene): return rustic.query({\"op\":\"scene_load\",\"scene\":scene})",
         "def log(self, level, message): self.commands.append({\"op\":\"log\",\"level\":str(level),\"message\":str(message)})",
         "def lookAt(obj,position,duration=0,easing=Ease.Linear):",
         "def looping(v=True): rustic.gameplay(dict(command=\"loop\",handle=h.id,looping=v));return h",
@@ -489,11 +506,13 @@
         "def stop(self): return rustic.query(dict(op=\"audio_stop\",entity=self.id))",
         "def stop(self): rustic.query(dict(op=\"audio_loaded_stop\",entity=self._loaded()))",
         "def stop(self): rustic.query(dict(op=\"capture_recording_stop\" if self.recording else \"capture_mic_stop\",id=self.id))",
+        "def switchTo(self,scene): return rustic.query({\"op\":\"scene_switch\",\"scene\":scene})",
         "def timeScale(scale=None): return rustic.query(dict(op=\"clock\",**({} if scale is None else {\"scale\":scale})))[\"scale\"]",
         "def to(obj, property, to, duration, easing=Ease.Linear): return GameplayHandle(_tween(obj,property,to,duration,easing))",
         "def to(self,obj,property,to,duration,easing=Ease.Linear): self.actions.append(_tween(obj,property,to,duration,easing)); return self",
         "def unload(self):",
         "def unload(self): rustic.query(dict(op=\"capture_unload\",id=self.id))",
+        "def unload(self,scene): return rustic.query({\"op\":\"scene_unload\",\"scene\":scene})",
         "def value(from_value,to,duration,fn,easing=Ease.Linear): return GameplayHandle({\"kind\":\"value\",\"from\":from_value,\"to\":to,\"duration\":duration,\"easing\":easing,\"token\":_callback(fn,True)})",
         "def value(keys,fn): return GameplayHandle(rustic.query(dict(op=\"keyframes\",keys=keys,token=_callback(fn,True))))",
         "def volume(voice,value): return rustic.query(dict(op=\"audio_volume\",entity=_entity(voice),value=value))",
@@ -503,7 +522,7 @@
       ]
     },
     "crates/engine-scripting/src/sdk/rustic.php": {
-      "sha256": "17d2528f545480299343c06cdadf4a86622bd47e2ed81b9ee795d1e812ce7825",
+      "sha256": "f6271c4d6b2244c612159e91d152ea1e76fe316a397ac8f3eed5b9761f4b2160",
       "declarations": [
         "function __construct(private string $source){}",
         "function __construct(public string $id){}function stop():void{global $rustic;$rustic->query([\"op\"=>\"audio_stop\",\"entity\"=>$this->id]);}function pause():void{global $rustic;$rustic->query([\"op\"=>\"audio_pause\",\"entity\"=>$this->id]);}function resume():void{global $rustic;$rustic->query([\"op\"=>\"audio_resume\",\"entity\"=>$this->id]);}",
@@ -528,11 +547,16 @@
         "public function GetAttribute(string $name): mixed { return $this->state[\"attributes\"][$name] ?? null; }",
         "public function GetAttribute(string $name):mixed{global $rustic;return $rustic->query([\"op\"=>\"object_attribute\",\"source\"=>$this->source,\"name\"=>$name]);}",
         "public function List(string $path=\"Game.scene\"): array { return array_values(array_filter($this->state, fn($id,$name)=>str_starts_with($name,($path===\"\"?\"Game.scene\":$path).\".\"), ARRAY_FILTER_USE_BOTH)); }",
+        "public function __call(string $name,array $args):mixed {",
         "public function __call(string $name,array $args):mixed{global $Game;if($this->source!==\"rustic.game\")throw new BadMethodCallException($name);return $Game->$name(...$args);}",
+        "public function __construct(){$this->files=new ApiPath('game.rustic.files','file','');}",
+        "public function __construct(){$this->scene=new ApiPath('game.scene','scene');$this->rustic=new CanonicalGlobalApi();}",
         "public function __construct(private InstanceApi $instance){ $this->scene=new SceneApi(); }",
         "public function __construct(private InstanceApi $instance, private string $source=\"rustic.game\") {}",
         "public function __construct(public InstanceApi $instance) { $this->game=new ObjectPath($instance); }",
         "public function __construct(public string $id) {}",
+        "public function __construct(public string $source,private string $category,public ?string $filePath=null){}",
+        "public function __get(string $name): ApiPath { return $this->children[$name]??=new ApiPath($this->source.'.'.$name,$this->category,$this->category==='file'?($this->filePath? $this->filePath.'/':'').$name:null); }",
         "public function __get(string $name): ObjectPath { return new ObjectPath($this->instance, $this->source.\".\".$name); }",
         "public function add(string $source, ?string $parent = null): void {",
         "public function animation(?string $e,string $name,array $opts=[]):self{$this->actions[]=Animation::action($e,$name,$opts);return $this;}",
@@ -547,16 +571,20 @@
         "public function entity_id(): string { return $this->state[\"entity_id\"]; }",
         "public function find_entity(string $source):?string{return $this->query([\"op\"=>\"find_entity\",\"source\"=>$source]);}",
         "public function fixed_delta_time(): float { return $this->state[\"fixed_delta_time\"]; }",
+        "public function getActive():mixed{global $rustic;return $rustic->query([\"op\"=>\"scene_active\"]);}",
         "public function getEnvironment(): array { global $rustic; return $rustic->query([\"op\"=>\"scene_environment\"]); }",
         "public function getEnvironmentField(string $field):mixed{global $rustic;return $rustic->query([\"op\"=>\"scene_environment_field\",\"field\"=>$field]);}",
+        "public function getLoaded():mixed{global $rustic;return $rustic->query([\"op\"=>\"scene_loaded\"]);}",
         "public function get_attribute(string $name): mixed { return $this->GetAttribute($name); }",
         "public function get_attribute(string $name):mixed{return $this->GetAttribute($name);}",
         "public function get_object_attribute(string $source,string $name):mixed{return $this->query([\"op\"=>\"object_attribute\",\"source\"=>$source,\"name\"=>$name]);}",
         "public function get_property(string $name): mixed { return $this->state[\"properties\"][$name] ?? null; }",
         "public function get_translation(): array { return $this->state[\"translation\"]; }",
         "public function input(string $name): array { return $this->state[\"actions\"][$name] ?? [\"pressed\"=>false,\"released\"=>false,\"held\"=>false,\"axis\"=>0]; }",
+        "public function isLoaded(string $scene):mixed{global $rustic;return $rustic->query([\"op\"=>\"scene_is_loaded\",\"scene\"=>$scene]);}",
         "public function key(string $name): array { return $this->state[\"keys\"][$name] ?? [\"pressed\"=>false,\"released\"=>false,\"held\"=>false,\"axis\"=>0]; }",
         "public function key_events(): array { return $this->state[\"key_events\"]; }",
+        "public function load(string $scene):mixed{global $rustic;return $rustic->query([\"op\"=>\"scene_load\",\"scene\"=>$scene]);}",
         "public function log(string $level,string $message): void { $this->instance->commands[]=[\"op\"=>\"log\",\"level\"=>$level,\"message\"=>$message]; }",
         "public function loop(bool $looping=true):self{Gameplay::send([\"command\"=>\"loop\",\"handle\"=>$this->id,\"looping\"=>$looping]);return $this;}",
         "public function move(?string $e,array $p,float $d,string $ease=\"Linear\"): self {$this->actions[]=Tween::action($e,\"Position\",$p,$d,$ease);return $this;}",
@@ -578,7 +606,9 @@
         "public function speed(float $speed):self{Gameplay::send([\"command\"=>\"speed\",\"handle\"=>$this->id,\"speed\"=>$speed]);return $this;}",
         "public function state():?array{global $rustic;return $rustic->query([\"op\"=>\"operation_state\",\"handle\"=>$this->id]);}",
         "public function stop():self{return $this->cancel();}",
+        "public function switchTo(string $scene):mixed{global $rustic;return $rustic->query([\"op\"=>\"scene_switch\",\"scene\"=>$scene]);}",
         "public function to(?string $e,string $p,mixed $value,float $d,string $ease=\"Linear\"):self{$this->actions[]=Tween::action($e,$p,$value,$d,$ease);return $this;}",
+        "public function unload(string $scene):mixed{global $rustic;return $rustic->query([\"op\"=>\"scene_unload\",\"scene\"=>$scene]);}",
         "public function wait(float $duration): self {$this->actions[]=[\"kind\"=>\"wait\",\"duration\"=>$duration];return $this;}",
         "public function warn(mixed ...$values):void{$this->log(\"warn\",implode(\" \",array_map(\"strval\",$values)));}",
         "public static function action(?string $entity,string $property,mixed $to,float|array $duration,string $easing=\"Linear\"): array {",
@@ -586,7 +616,7 @@
         "public static function callback(callable $fn,bool $once=false):string{$id=bin2hex(random_bytes(16));self::$callbacks[$id]=$fn;self::$once[$id]=$once;return $id;}",
         "public static function create(): self {return new self();}",
         "public static function dispatch(): void {",
-        "public static function entity(?string $id): string {global $rustic,$Game;return $id===null?$rustic->entity_id():($Game->scene->Find($id)??$id);}",
+        "public static function entity(?string $id): string {global $rustic,$Game;return $id===null?$rustic->entity_id():(str_starts_with($id,\"game.scene.\")?$rustic->query([\"op\"=>\"scene_object\",\"source\"=>$id]):($Game->scene->Find($id)??$id));}",
         "public static function move(?string $entity,array $position,float|array $duration,string $easing=\"Linear\"): GameplayHandle {return self::to($entity,\"Position\",$position,$duration,$easing);}",
         "public static function moveTo(?string $entity,array $position,float|array $duration,string $easing=\"Linear\"): GameplayHandle {return Tween::move($entity,$position,$duration,$easing);}",
         "public static function release(GameplayHandle $h):void{foreach($h->tokens as $t){unset(self::$callbacks[$t],self::$once[$t]);}unset(self::$handles[$h->id]);}",
@@ -599,7 +629,7 @@
       ]
     },
     "crates/engine-scripting/src/sdk/rustic.luau": {
-      "sha256": "8f9b7a5172be785279a3cfdd37fe8b1ea288c6f2666080be43b9ae1caa2b5c8b",
+      "sha256": "75eb29f33bb7d7b55064723a835698b18bdc8a3ebe4c9111f553b5d7122927f6",
       "declarations": [
         "function Game.scene.Find(path) return state.scene_paths[path] end",
         "function Game.scene.List(path)",
@@ -633,21 +663,39 @@
       ]
     },
     "crates/engine-scripting/src/sdk/Rustic.java": {
-      "sha256": "a1379fe2a7bf0584848cf275e3a559a1e63063759d6c55df768e2187c95cfb5b",
+      "sha256": "d8b5da4587eecff6013c4dcfebb82f79b5654041bf13c4e8640d420fb53f2ef1",
       "declarations": []
     },
     "crates/engine-scripting/src/sdk/Rustic.cs": {
-      "sha256": "ee76e572c039f72d755730608de2a7311aa5f40ea125d1518dd1073ba7e22acb",
+      "sha256": "ae6af2e5b5e08da0a000a798fa982ad6e44a4f1d3609237b94b153c69b3485ec",
       "declarations": [
+        "public double clockTimeScale(double? scale=null) => Rustic.Clock.timeScale(scale);",
+        "public double delta_time() => Rustic.rustic.delta_time();",
         "public double delta_time() => State.GetProperty(\"delta_time\").GetDouble();",
+        "public double fixed_delta_time() => Rustic.rustic.fixed_delta_time();",
         "public double fixed_delta_time() => State.GetProperty(\"fixed_delta_time\").GetDouble();",
+        "public double inverseLerp(double a,double b,double value) => Rustic.Smooth.inverseLerp(a,b,value);",
+        "public double lerp(double a,double b,double t,string easing=\"Linear\") => Rustic.Smooth.lerp(a,b,t,easing);",
+        "public double remap(double value,double a,double b,double c,double d) => Rustic.Smooth.remap(value,a,b,c,d);",
+        "public double smoothInverseLerp(double a,double b,double value) => Rustic.Smooth.inverseLerp(a,b,value);",
+        "public double smoothLerp(double a,double b,double t,string easing=\"Linear\") => Rustic.Smooth.lerp(a,b,t,easing);",
+        "public double smoothRemap(double value,double a,double b,double c,double d) => Rustic.Smooth.remap(value,a,b,c,d);",
+        "public double timeScale(double? scale=null) => Rustic.Clock.timeScale(scale);",
+        "public double[] get_translation() => Rustic.rustic.get_translation();",
         "public double[] get_translation() => State.GetProperty(\"translation\").EnumerateArray().Select(x => x.GetDouble()).ToArray();",
+        "public double[] lerp(double[] a,double[] b,double t,string easing=\"Linear\") => Rustic.Smooth.lerp(a,b,t,easing);",
+        "public double[] slerp(double[] a,double[] b,double t,string easing=\"Linear\") => Rustic.Smooth.slerp(a,b,t,easing);",
+        "public double[] smoothLerp(double[] a,double[] b,double t,string easing=\"Linear\") => Rustic.Smooth.lerp(a,b,t,easing);",
+        "public double[] smoothSlerp(double[] a,double[] b,double t,string easing=\"Linear\") => Rustic.Smooth.slerp(a,b,t,easing);",
         "public object? GetAttribute(string name) => Read(\"attributes\", name);",
+        "public object? GetAttribute(string name) => Rustic.rustic.GetAttribute(name);",
         "public object? GetAttribute(string name)=>RusticApi.ConvertValue(Rustic.Query(new{op=\"object_attribute\",source,name}));",
         "public object? get_attribute(string name) => GetAttribute(name);",
+        "public object? get_attribute(string name) => Rustic.rustic.get_attribute(name);",
         "public object? get_attribute(string name)=>GetAttribute(name);",
         "public object? get_object_attribute(string source,string name)=>ConvertValue(Rustic.Query(new{op=\"object_attribute\",source,name}));",
         "public object? get_property(string name) => Read(\"properties\", name);",
+        "public object? get_property(string name) => Rustic.rustic.get_property(name);",
         "public static class Animation{",
         "public static class Audio{",
         "public static class Camera {",
@@ -707,41 +755,124 @@
         "public static void stop(Gameplay.Handle h)=>h.cancel();public static void pause(Gameplay.Handle h)=>h.pause();public static void speed(Gameplay.Handle h,double v)=>h.speed(v);public static void loop(Gameplay.Handle h,bool v=true)=>h.loop(v);",
         "public static void volume(Voice v,double value)=>Query(new{op=\"audio_volume\",entity=v.Id,value});public static void pitch(Voice v,double value)=>Query(new{op=\"audio_pitch\",entity=v.Id,value});",
         "public string Id {get;}",
+        "public string cameraCurrent() => Rustic.Camera.current();",
+        "public string currentCamera() => Rustic.Camera.current();",
+        "public string entity_id() => Rustic.rustic.entity_id();",
         "public string entity_id() => State.GetProperty(\"entity_id\").GetString()!;",
+        "public string load(string scene)=>Rustic.Game.scene.load(scene);",
+        "public string load(string scene)=>Rustic.Query(new{op=\"scene_load\",scene}).GetString()!;",
         "public string? Find(string path) => State.TryGetProperty(path, out var value) ? value.GetString() : null;",
         "public string? find_entity(string source)=>Rustic.Query(new{op=\"find_entity\",source}).GetString();",
+        "public string? getActive()=>Rustic.Game.scene.getActive();",
+        "public string? getActive()=>Rustic.Query(new{op=\"scene_active\"}).GetString();",
+        "public string[] animationClips() => Rustic.Animation.clips(this.source);",
+        "public string[] animationLoad(string? e) => Rustic.Animation.load(e,filePath);",
+        "public string[] componentsFindInChildren(string name) => Rustic.Components.find_in_children(this.source,name);",
+        "public string[] componentsGetAll() => Rustic.Components.get_all(this.source);",
+        "public string[] explosion(double[] center,double radius,double strength) => Rustic.Physics.explosion(center,radius,strength);",
+        "public string[] findInChildren(string name) => Rustic.Components.find_in_children(this.source,name);",
+        "public string[] getChildren() => Rustic.Hierarchy.get_children(this.source);",
+        "public string[] getComponents() => Rustic.Components.get_all(this.source);",
+        "public string[] getLoaded()=>Rustic.Game.scene.getLoaded();",
+        "public string[] getLoaded()=>Rustic.Query(new{op=\"scene_loaded\"}).EnumerateArray().Select(v=>v.GetString()!).ToArray();",
+        "public string[] groupsGetMembers(string name) => Rustic.Groups.get_members(name);",
+        "public string[] hierarchyGetChildren() => Rustic.Hierarchy.get_children(this.source);",
+        "public string[] loadAnimation(string? e) => Rustic.Animation.load(e,filePath);",
+        "public string[] overlap(double[] center,double radius) => Rustic.Physics.overlap(center,radius);",
+        "public string[] physicsExplosion(double[] center,double radius,double strength) => Rustic.Physics.explosion(center,radius,strength);",
+        "public string[] physicsOverlap(double[] center,double radius) => Rustic.Physics.overlap(center,radius);",
+        "public string[] tagsFindAll(string name) => Rustic.Tags.find_all(name);",
+        "public string[] worldFindByTag(string name) => Rustic.World.find_by_tag(name);",
+        "public string[] worldFindInRadius(double[] center,double radius) => Rustic.World.find_in_radius(center,radius);",
         "public void Add(string source, string? parent = null) => Commands.Add(new { op = \"add_instance\", source, parent });",
         "public void Clone(string source, string? parent = null) => Commands.Add(new { op = \"clone_instance\", source, parent });",
         "public void EditAttribute(string name, object? value) => Commands.Add(new { op=\"edit_attribute\", name, value });",
+        "public void EditAttribute(string name, object? value) => Rustic.rustic.EditAttribute(name,value);",
         "public void EditAttribute(string name, object? value) => commands.Add(new {op=\"edit_attribute\",source,name,value});",
+        "public void EditAttribute(string name,object? value) => Rustic.instance.Commands.Add(new{op=\"edit_attribute\",this.source,name,value});",
         "public void SetCurrentCamera(string source) => commands.Add(new { op=\"set_current_camera\", source });",
         "public void Unload()=>unload();",
         "public void add(string source, string? parent = null) => Add(source, parent);",
+        "public void add(string? parent=null) => Rustic.instance.add(filePath,parent);",
+        "public void add(string? parent=null) => Rustic.instance.add(source,parent);",
+        "public void animationAddMarker(string clip,double time,string name) => Rustic.Animation.addMarker(this.source,clip,time,name);",
+        "public void animationLoop(Rustic.Gameplay.Handle h,bool v=true) => Rustic.Animation.loop(h,v);",
+        "public void animationPause(Rustic.Gameplay.Handle h) => Rustic.Animation.pause(h);",
+        "public void animationRegister(Rustic.Animation.Clip clip) => Rustic.Animation.register(this.source,clip);",
+        "public void animationSpeed(Rustic.Gameplay.Handle h,double v) => Rustic.Animation.speed(h,v);",
+        "public void animationStop(Rustic.Gameplay.Handle h) => Rustic.Animation.stop(h);",
+        "public void audioPitch(Rustic.Audio.Voice v,double value) => Rustic.Audio.pitch(v,value);",
+        "public void audioSetInputDevice(string? device=null) => Rustic.Audio.set_input_device(device);",
+        "public void audioSetOutputDevice(string? device=null) => Rustic.Audio.set_output_device(device);",
+        "public void audioVolume(Rustic.Audio.Voice v,double value) => Rustic.Audio.volume(v,value);",
+        "public void clockPause() => Rustic.Clock.pause();",
+        "public void clockResume() => Rustic.Clock.resume();",
         "public void clone(string source, string? parent = null) => Clone(source, parent);",
+        "public void clone(string? parent=null) => Rustic.instance.clone(filePath,parent);",
+        "public void clone(string? parent=null) => Rustic.instance.clone(source,parent);",
+        "public void destroy() => Rustic.Entity.destroy(this.source);",
+        "public void destroyAfter(double delay) => Rustic.Entity.destroy_after(this.source,delay);",
+        "public void detach(bool keep_world=true) => Rustic.Hierarchy.detach(this.source,keep_world);",
+        "public void disconnect(Rustic.Events.Connection c) => Rustic.Events.disconnect(c);",
         "public void edit_attribute(string name, object? value) => EditAttribute(name, value);",
         "public void edit_attribute(string name, object? value) => EditAttribute(name,value);",
+        "public void edit_attribute(string name, object? value) => Rustic.rustic.edit_attribute(name,value);",
+        "public void edit_attribute(string name,object? value) => EditAttribute(name,value);",
         "public void edit_object_attribute(string source,string name,object? value)=>Commands.Add(new{op=\"edit_attribute\",source,name,value});",
+        "public void emit(string name,object[] arguments) => Rustic.Events.emit(name,arguments,source);",
+        "public void emit(string name,object[]? arguments=null,string? source=null) => Rustic.Events.emit(name,arguments,source);",
+        "public void entityDestroy() => Rustic.Entity.destroy(this.source);",
+        "public void entityDestroyAfter(double delay) => Rustic.Entity.destroy_after(this.source,delay);",
+        "public void eventsDisconnect(Rustic.Events.Connection c) => Rustic.Events.disconnect(c);",
+        "public void eventsEmit(string name,object[]? arguments=null,string? source=null) => Rustic.Events.emit(name,arguments,source);",
+        "public void force(double[] vector,double delta) => Rustic.Physics.force(this.source,vector,delta);",
+        "public void hierarchyDetach(bool keep_world=true) => Rustic.Hierarchy.detach(this.source,keep_world);",
+        "public void hierarchySetParent(string? parent,bool keep_world=true) => Rustic.Hierarchy.set_parent(this.source,parent,keep_world);",
+        "public void impulse(double[] vector) => Rustic.Physics.impulse(this.source,vector);",
+        "public void knockback(double[] vector) => Rustic.Physics.knockback(this.source,vector);",
+        "public void launch(double[] vector) => Rustic.Physics.launch(this.source,vector);",
         "public void log(string level,string message) => Commands.Add(new { op=\"log\", level, message });",
+        "public void log(string level,string message) => Rustic.rustic.log(level,message);",
+        "public void pause() => Rustic.Clock.pause();",
         "public void pause()=>Query(new{op=\"audio_loaded_pause\",entity=Loaded()});",
+        "public void physicsForce(double[] vector,double delta) => Rustic.Physics.force(this.source,vector,delta);",
+        "public void physicsImpulse(double[] vector) => Rustic.Physics.impulse(this.source,vector);",
+        "public void physicsKnockback(double[] vector) => Rustic.Physics.knockback(this.source,vector);",
+        "public void physicsLaunch(double[] vector) => Rustic.Physics.launch(this.source,vector);",
         "public void print(string message)=>log(\"info\",message);",
+        "public void resume() => Rustic.Clock.resume();",
         "public void resume()=>Query(new{op=\"audio_loaded_resume\",entity=Loaded()});",
+        "public void setCurrentCamera() => Rustic.Game.setCurrentCamera(source);",
+        "public void setCurrentCamera(string path) => Rustic.Game.setCurrentCamera(path);",
         "public void setCurrentCamera(string source) => SetCurrentCamera(source);",
+        "public void setInputDevice(string? device=null) => Rustic.Audio.set_input_device(device);",
+        "public void setOutputDevice(string? device=null) => Rustic.Audio.set_output_device(device);",
+        "public void setParent(string? parent,bool keep_world=true) => Rustic.Hierarchy.set_parent(this.source,parent,keep_world);",
         "public void set_enabled(bool enabled) => Commands.Add(new { op=\"set_enabled\", enabled });",
+        "public void set_enabled(bool enabled) => Rustic.rustic.set_enabled(enabled);",
+        "public void set_input_device(string? device=null) => Rustic.Audio.set_input_device(device);",
+        "public void set_output_device(string? device=null) => Rustic.Audio.set_output_device(device);",
         "public void set_property(string name, object value) => Commands.Add(new { op=\"set_property\", name, value });",
+        "public void set_property(string name, object value) => Rustic.rustic.set_property(name,value);",
         "public void set_translation(double x,double y,double z) => Commands.Add(new { op=\"set_translation\", value=new[]{x,y,z} });",
+        "public void set_translation(double x,double y,double z) => Rustic.rustic.set_translation(x,y,z);",
         "public void stop()=>Query(new{op=\"audio_loaded_stop\",entity=Loaded()});",
         "public void stop()=>Query(new{op=recording?\"capture_recording_stop\":\"capture_mic_stop\",id=Id});",
         "public void stopHotMic(Rustic.CaptureHandle? handle=null)=>Rustic.Game.stopHotMic(handle);",
         "public void stopHotMic(Rustic.CaptureHandle? handle=null)=>Rustic.Query(new{op=\"capture_mic_stop\",id=handle?.Id});",
         "public void stopRecording(Rustic.CaptureHandle? handle=null)=>Rustic.Game.stopRecording(handle);",
         "public void stopRecording(Rustic.CaptureHandle? handle=null)=>Rustic.Query(new{op=\"capture_recording_stop\",id=handle?.Id});",
+        "public void switchTo(string scene)=>Rustic.Game.scene.switchTo(scene);",
+        "public void switchTo(string scene)=>Rustic.Query(new{op=\"scene_switch\",scene});",
         "public void unload()=>Query(new{op=\"capture_unload\",id=Id});",
         "public void unload(){if(id is not null){Query(new{op=\"audio_unload\",entity=id});id=null;}}",
+        "public void unload(string scene)=>Rustic.Game.scene.unload(scene);",
+        "public void unload(string scene)=>Rustic.Query(new{op=\"scene_unload\",scene});",
         "public void warn(string message)=>log(\"warn\",message);"
       ]
     },
     "crates/engine-scripting/src/sdk/gameplay.lua": {
-      "sha256": "e7e40da4a63c0e0ef869e491b3cabac13aae7112e428b1e10a2976a6823236e6",
+      "sha256": "7263f77f8e4241c00e5a5f197546937b5e209b91c17c40491393293acd5410cd",
       "declarations": [
         "function Animation.addMarker(o,clip,time,name) return rustic.query({op=\"animation_marker\",entity=entity(o),clip=clip,time=time,name=name}) end",
         "function Animation.blend(o,from,to,opts) opts=opts or {};opts.blendIn=opts.duration or 0.3;opts.sourceClip=type(from)=='table' and from or rustic.query({op='animation_ref',entity=entity(o),name=from});return Animation.play(o,to,opts) end",
@@ -787,9 +918,15 @@
         "function Events.emit(name,arguments,source) send({command='emit',signal={name=name,source=source and entity(source)},arguments=arguments}) end",
         "function Events.on(name,fn) return connect(name,fn,false) end",
         "function Events.once(name,fn) return connect(name,fn,true) end",
+        "function Game.scene.getActive() local scene=rustic.query({op='scene_active'});if type(scene)=='string' then return scene end end",
         "function Game.scene.getEnvironment(field) return rustic.query(field and {op='scene_environment_field',field=field} or {op='scene_environment'}) end",
+        "function Game.scene.getLoaded() return rustic.query({op='scene_loaded'}) end",
+        "function Game.scene.isLoaded(scene) return rustic.query({op='scene_is_loaded' ,scene=scene}) end",
+        "function Game.scene.load(scene) return rustic.query({op='scene_load' ,scene=scene}) end",
         "function Game.scene.setEnvironment(settings)",
         "function Game.scene.setSkyTexture(path)",
+        "function Game.scene.switchTo(scene) return rustic.query({op='scene_switch' ,scene=scene}) end",
+        "function Game.scene.unload(scene) return rustic.query({op='scene_unload' ,scene=scene}) end",
         "function Game.startHotMic() return rustic.game:startHotMic() end",
         "function Game.startRecording(path,options) return rustic.game:startRecording(path,options) end",
         "function Game.stopHotMic(handle) return rustic.game:stopHotMic(handle) end",
@@ -833,6 +970,8 @@
         "function World.find_in_radius(center,radius) return rustic.query({op=\"world_find_in_radius\",center=center,radius=radius}) end",
         "function __rustic_audio_object(source)",
         "function __rustic_gameplay_dispatch()",
+        "function __rustic_path_method(proxy,name)",
+        "function game.rustic:setCurrentCamera(object)",
         "function handle:read() return rustic.query({op='capture_read',id=id}) end",
         "function handle:unload() rustic.query({op='capture_unload',id=id}) end",
         "function object:Unload()",
@@ -851,7 +990,7 @@
       ]
     },
     "crates/engine-scripting/src/sdk/gameplay.js": {
-      "sha256": "768b4ea097dab95c38a7ef93068bc4354bd7579371ad90fd13a70b8f676a756f",
+      "sha256": "ad26f4258f7253ed1cf67aac00e592253166e794c3f7687a978b84f1d31e6215",
       "declarations": []
     },
     "crates/engine-scripting/src/sdk/media-api.lua": {
@@ -958,13 +1097,15 @@
       ]
     },
     "crates/engine-play/src/script_runtime.rs": {
-      "sha256": "3e5b58c423ab6f7ac78eac1606e53ccc56b26c74e0a35950c88fe7df14ab2cb5",
+      "sha256": "38405b0cfe674c6671e9f16f56e6370aaa0fddb31679822cb0396decd855edcd",
       "declarations": [
         "def on_start():",
         "def on_start(): rustic.game.Demo.Player.EditAttribute(\"Position\",[1,2,3])",
         "def start():",
         "def start(): Events.emit('Hit',[rustic.entity_id(),'cross-language'])",
         "function on_start():void{global $Game;$Game->scene->setEnvironment([\"enabled\"=>true,\"sun_intensity\"=>2]);$Game->scene->setSkyTexture(\"assets/night.hdr\");if($Game->scene->getEnvironment()[\"sky_image\"]!==\"assets/night.hdr\")throw new Exception(\"stale sky\");}",
+        "function on_start():void{global $game;$game->scene->Demo->Room->Player->EditAttribute(\"Name\",\"Renamed\");$game->rustic->groupsCreate(\"selected\");$game->scene->Demo->Room->Renamed->groupsAdd(name:\"selected\");$game->scene->Demo->Room->Renamed->tween(\"Position\",[8,0,0],2,\"InQuad\");$game->rustic->after(0.5,fn()=>$game->rustic->log(\"info\",\"timer\"));$game->rustic->files->assets->{\"night.hdr\"}->setSkyTexture();}",
+        "function on_start():void{global $game;$level=$game->scene->load(\"scene/level.scene\");if(!$game->scene->isLoaded($level))throw new Exception(\"load\");$game->scene->switchTo($level);if($game->scene->getActive()!==$level||count($game->scene->getLoaded())!==2)throw new Exception(\"switch\");$game->scene->unload($level);if($game->scene->isLoaded($level))throw new Exception(\"unload\");$game->scene->switchTo($level);if(!$game->scene->isLoaded($level))throw new Exception(\"autoload\");$game->scene->switchTo(\"Menu\");if($game->scene->isLoaded($level))throw new Exception(\"auto unload\");}",
         "function on_start():void{global $rustic;$e=$rustic->entity_id();",
         "function on_start():void{global $rustic;$rustic->game->Demo->Player->EditAttribute(\"Position\",[1,2,3]);}",
         "function start():void{global $rustic;Animation::value([[\"time\"=>0,\"value\"=>0,\"easing\"=>Ease::InQuad],[\"time\"=>2,\"value\"=>8]],fn($v)=>$rustic->log(\"info\",\"keyframe\"))->onFinished(fn()=>$rustic->log(\"info\",\"keyframesdone\"));Animation::play(null,\"Grow\")->onMarker(\"Mid\",fn()=>$rustic->log(\"info\",\"marker\"))->onFinished(fn()=>$rustic->log(\"info\",\"animation\"));if(Smooth::lerp(0,8,0.5,Ease::InQuad)!=2)throw new RuntimeException(\"core interpolation differs\");Tween::move(null,[8,0,0],2,Ease::InQuad)->onFinished(fn()=>$rustic->log('info','done'));Timer::after(0.5,fn()=>$rustic->log('info','timer'));}",
@@ -972,8 +1113,6 @@
         "pub fn fixed_update(&mut self, delta: f64) {",
         "pub fn frame_update(&mut self, delta: f64) {",
         "pub fn live_entity(&self, id: EntityId) -> Result<Option<LiveEntityProperties>, String> {",
-        "pub fn load(snapshot_root: &std::path::Path, scene_bytes: &[u8]) -> Result<Self, String> {",
-        "pub fn reload(",
         "pub fn render_world<T>(",
         "pub fn runtime_changes(",
         "pub fn set_input_keys(&mut self, keys: Vec<String>) {",
@@ -981,7 +1120,25 @@
         "public static void main(String[]args)throws Exception{run((callback,dt)->{if(callback.equals(\"on_start\"))rustic.game.scene(\"Demo\").object(\"Player\").EditAttribute(\"Position\",new double[]{1,2,3});});}}\"#),",
         "public static void main(String[]args)throws Exception{run((callback,dt)->{if(callback.equals(\"on_start\")){Animation.value(java.util.List.of(new Animation.Key(0,0,Ease.InQuad),new Animation.Key(2,8)),v->rustic.log(\"info\",\"keyframe\")).onFinished(()->rustic.log(\"info\",\"keyframesdone\"));Animation.play(null,\"Grow\",null).onMarker(\"Mid\",()->rustic.log(\"info\",\"marker\")).onFinished(()->rustic.log(\"info\",\"animation\"));if(((Number)Smooth.lerp(0,8,0.5,Ease.InQuad)).doubleValue()!=2)throw new Exception(\"core interpolation differs\");Tween.move(null,new double[]{8,0,0},2,Ease.InQuad).onFinished(()->rustic.log(\"info\",\"done\"));Timer.after(0.5,()->rustic.log(\"info\",\"timer\"));}});}}\"#),",
         "public static void main(String[]args)throws Exception{run((callback,dt)->{if(callback.equals(\"on_start\")){Game.scene.setEnvironment(java.util.Map.of(\"enabled\",true,\"sun_intensity\",2));Game.scene.setSkyTexture(\"assets/night.hdr\");if(!((java.util.Map<?,?>)Game.scene.getEnvironment()).get(\"sky_image\").equals(\"assets/night.hdr\"))throw new RuntimeException(\"stale sky\");}});}}\"#),",
-        "public static void main(String[]args)throws Exception{run((callback,dt)->{if(callback.equals(\"on_start\")){String e=rustic.entity_id();"
+        "public static void main(String[]args)throws Exception{run((callback,dt)->{if(callback.equals(\"on_start\")){String e=rustic.entity_id();",
+        "public static void main(String[]args)throws Exception{run((callback,dt)->{if(callback.equals(\"on_start\")){String level=game.scene.load(\"scene/level.scene\");if(!game.scene.isLoaded(level))throw new RuntimeException(\"load\");game.scene.switchTo(level);if(!game.scene.getActive().equals(level)||game.scene.getLoaded().size()!=2)throw new RuntimeException(\"switch\");game.scene.unload(level);if(game.scene.isLoaded(level))throw new RuntimeException(\"unload\");game.scene.switchTo(level);if(!game.scene.isLoaded(level))throw new RuntimeException(\"autoload\");game.scene.switchTo(\"Menu\");if(game.scene.isLoaded(level))throw new RuntimeException(\"auto unload\");}});}}\"#),",
+        "public static void main(String[]args)throws Exception{run((callback,dt)->{if(callback.equals(\"on_start\")){game.scene.scene(\"Demo\").object(\"Room.Player\").EditAttribute(\"Name\",\"Renamed\");game.rustic.groupsCreate(\"selected\");game.scene.scene(\"Demo\").object(\"Room.Renamed\").groupsAdd(\"selected\");game.scene.scene(\"Demo\").object(\"Room.Renamed\").tween(\"Position\",new double[]{8,0,0},2,\"InQuad\");game.rustic.after(0.5,()->game.rustic.log(\"info\",\"timer\"));game.rustic.files.object(\"assets/night.hdr\").setSkyTexture();}});}}\"#),"
+      ]
+    },
+    "crates/engine-play/src/scene_lifecycle.rs": {
+      "sha256": "c5a3ae1c4b57ebb4e1668212d81ac329fe2e971e2472d8c6af512c697d771dfc",
+      "declarations": [
+        "pub fn drain_logs(&self) -> Vec<(String, String)> {",
+        "pub fn fixed_update(&mut self, delta: f64) {",
+        "pub fn frame_update(&mut self, delta: f64) {",
+        "pub fn live_entity(&self, id: EntityId) -> Result<Option<LiveEntityProperties>, String> {",
+        "pub fn load(root: &Path, bytes: &[u8]) -> Result<Self, String> {",
+        "pub fn query(",
+        "pub fn reload(&mut self, id: ScriptId, source: &[u8]) -> Result<usize, String> {",
+        "pub fn render_world<T>(&self, render: impl FnOnce(&SceneWorld) -> T) -> Result<T, String> {",
+        "pub fn runtime_changes(&self, hash: &str, bytes: &[u8]) -> Result<RuntimeChangeSet, String> {",
+        "pub fn set_input_keys(&mut self, keys: Vec<String>) {",
+        "pub fn stop(&mut self) {"
       ]
     }
   }
diff --git a/scripts/check-engine-drift.mjs b/scripts/check-engine-drift.mjs
index 8950fc2..522d89a 100644
--- a/scripts/check-engine-drift.mjs
+++ b/scripts/check-engine-drift.mjs
@@ -12,7 +12,7 @@ export const engineSources = [
   "crates/engine-scripting/src/external_runtime.rs", "crates/engine-scripting/src/cpp_sdk.rs",
   ...["rustic.h", "rustic.py", "rustic.php", "rustic.luau", "Rustic.java", "Rustic.cs", "gameplay.lua", "gameplay.js", "media-api.lua", "media-api.d.ts"].map((file) => `crates/engine-scripting/src/sdk/${file}`),
   ...["mod.rs", "query.rs", "audio.rs", "signals.rs", "ease.rs"].map((file) => `crates/engine-core/src/gameplay/${file}`),
-  ...["audio_output.rs", "audio_input.rs", "audio_capture.rs", "script_runtime.rs"].map((file) => `crates/engine-play/src/${file}`),
+  ...["audio_output.rs", "audio_input.rs", "audio_capture.rs", "script_runtime.rs", "scene_lifecycle.rs"].map((file) => `crates/engine-play/src/${file}`),
 ];
 export function sourceRecord(text) {
   return {