Keep objects through a Load scene with a switch (#165)

A Load scene destroyed every object of the old scene. A player, a HUD
or a music object had to be built again in each scene, with its state
pushed through shared variables. A top-level object with the new switch
Keep on scene load now travels into the next scene as the same entity,
with everything below it.

- The switch is a common property right under Enabled, off by default,
  on the asset and on a placed object. The inspector shows the row on
  top-level objects of a scene only, as answered in the issue.
- runtime/keptObjects.ts holds the rules as pure functions.
  keptEntities picks what travels, objectsToBring copies the stored
  objects as the run parents them, and bringObjects puts them into the
  next scene.
- World.instantiate takes a handed entity as it is instead of making
  one. The next syncToModel then writes the run's values into the
  scene.
- BehaviorSystem.release takes the running instances out before the
  old world is destroyed, and the next system adopts them. They hear
  no On destroy and no second On start, and their sounds play on.
- PhysicsSystem.resume gives a dynamic body the velocity and spin it
  had.
- Duplicates: the object brought along wins. The next scene does not
  build its own object with the same id, which is the way back into
  the scene the object came from.
- Decided here: the next scene does not build a top-level object of
  the same asset that is kept itself either. The issue only names the
  id. With the id alone a level that places its own player would hold
  two after a swap.
- Decided here: kept objects land behind the scene's own, the switch
  is no animation row, and collisions are found anew.

A finding, fixed along with it: Load scene did not build a scene as it
is stored, but as the run had left it. A moved object stayed moved and
a destroyed one stayed gone. The way back into a scene needs a clean
build.

- GameRun copies a scene's objects and groups before it first builds
  it and puts them back before it builds it again.
- GameRun.end puts every such scene back. The player calls it on stop,
  so spawned objects no longer stay for "Click to play again".
- The consequence: an edit made in a scene during Play is gone the
  next time that scene is loaded.

Tests:
- Gate: 199 files, 2944 tests (2929 + 15), exit 0
- e2e, full run: 1625 checks passed (1619 + 6), exit 0
- Smokes: 24 / 19 / 21, exit 0
- 15 unit tests in tests/core/keep-on-scene-load.test.ts
- Six e2e checks in module 35: the switch is set with a real mouse,
  the child has no row, the object is in the new scene, its counter
  still reads 1, its sound plays on, and the stored scenes are
  unchanged after Stop
- Eleven tests with fixed row lists only count the new schema row
- 16 unit counter-probes all fail tests, run on stein2. One did not
  fail at first (same id not left out), it has its own test now.
- The browser counter-probe fails 4 of the 6 new checks
- Not looked at in the browser: the switch as a port of the Properties
  node, and a released game with a kept object

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

src/runtime/GameRun.ts

@@ -3,10 +3,12 @@
  * editor's Play and a released game (#266), so both build, swap and end a scene the same way.
  */
 import type { SaveArea } from '../core/graph/savedValues';
-import type { Project } from '../core/model/Project';
+import type { SceneAsset } from '../core/model/Asset';
+import { findScene, type Project } from '../core/model/Project';
 import type { AudioSink } from './systems/Audio';
 import { addGameSystems, type BehaviorSystem, type TimeScaled } from './systems/BehaviorSystem';
 import type { Input } from './systems/Input';
+import { bringObjects, keptEntities, objectsToBring } from './keptObjects';
 import type { Rapier } from './physics/engine';
 import { World } from './World';
 
@@ -17,7 +19,16 @@ export interface RunServices {
   saves: SaveArea;
 }
 
+/** What a scene holds of objects, which is all a run writes into it. */
+type StoredObjects = Pick<SceneAsset, 'objects' | 'groups'>;
+
 export class GameRun {
+  /**
+   * Every scene this run built, as it was before: a run writes what it does into the scene it is in,
+   * and a scene loaded again has to be the stored one, not what was left of it.
+   */
+  private readonly stored = new Map<string, StoredObjects>();
+
   private constructor(
     private readonly project: Project,
     private readonly input: Input,
@@ -27,8 +38,12 @@ export class GameRun {
   ) {}
 
   static start(project: Project, sceneId: string, input: Input, services: RunServices): GameRun {
+    const scene = findScene(project, sceneId);
+    const before = scene && structuredClone<StoredObjects>({ objects: scene.objects, groups: scene.groups });
     const world = World.instantiate(project, sceneId);
-    return new GameRun(project, input, services, world, addGameSystems(world, project, input, services));
+    const run = new GameRun(project, input, services, world, addGameSystems(world, project, input, services));
+    if (before) run.stored.set(sceneId, before);
+    return run;
   }
 
   /**
@@ -49,14 +64,59 @@ export class GameRun {
 
   /**
    * Swaps the running scene for another one, inside the same run: the world is torn down and built
-   * again, while what belongs to the run – the clock, the shared variables, the global machines –
-   * carries on. The sounds of the old scene end with it, because the behaviors playing them are
-   * destroyed; a voice that was started detached is nobody's and plays on.
+   * again from the scene as it is stored, while what belongs to the run – the clock, the shared
+   * variables, the global machines – carries on. So do the objects that are kept (#165): they move
+   * into the next scene as they are, with their running behaviors and how their bodies move. The
+   * sounds of the old scene end with it, because the behaviors playing them are destroyed; a voice
+   * that was started detached is nobody's and plays on, and so does one of a kept behavior.
    */
   loadScene(sceneId: string): void {
+    const scene = findScene(this.project, sceneId);
+    const from = findScene(this.project, this.world.sceneId);
+    if (!scene) throw new Error(`Scene ${sceneId} not found`);
+    const leaving = from
+      ? objectsToBring(from, keptEntities(this.world.entities))
+      : { entities: [], objects: [] };
     const carried = this.behaviors.shared;
+    const kept = this.behaviors.release(leaving.entities);
     this.world.destroy();
-    this.world = World.instantiate(this.project, sceneId);
-    this.behaviors = addGameSystems(this.world, this.project, this.input, { ...this.services, carried });
+    this.asStored(scene);
+    const standIns = bringObjects(this.project, scene, leaving.objects);
+    this.world = World.instantiate(this.project, sceneId, {
+      brought: { entities: leaving.entities, standIns },
+    });
+    this.behaviors = addGameSystems(this.world, this.project, this.input, {
+      ...this.services,
+      carried,
+      kept,
+    });
+  }
+
+  /**
+   * Ends the run: the world is torn down, and the scenes get back what they held before it. A host
+   * that runs on a copy it throws away has no use for the second half, one that plays the project
+   * itself does.
+   */
+  end(): void {
+    this.world.destroy();
+    for (const [sceneId, before] of this.stored) {
+      const scene = findScene(this.project, sceneId);
+      if (scene) restore(scene, before);
+    }
+    this.stored.clear();
+  }
+
+  /** Puts a scene back to what it stored before this run first built it; remembers that on the first time. */
+  private asStored(scene: SceneAsset): void {
+    const before = this.stored.get(scene.id);
+    if (before) restore(scene, before);
+    else this.stored.set(scene.id, structuredClone({ objects: scene.objects, groups: scene.groups }));
   }
 }
+
+function restore(scene: SceneAsset, before: StoredObjects): void {
+  const { objects, groups } = structuredClone(before);
+  scene.objects = objects;
+  if (groups) scene.groups = groups;
+  else delete scene.groups;
+}