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/systems/BehaviorSystem.ts

@@ -30,7 +30,7 @@ import { type AudioSink, SILENT_AUDIO } from './Audio';
 import type { Entity } from '../Entity';
 import type { World } from '../World';
 import type { Rapier } from '../physics/engine';
-import { PhysicsSystem } from '../physics/PhysicsSystem';
+import { type BodyMotion, PhysicsSystem } from '../physics/PhysicsSystem';
 import { behaviorContext, type TimeScaled } from './behaviorContext';
 import {
   animationFinishedPulses,
@@ -79,11 +79,23 @@ const MAX_STATE_ROUNDS = 100;
 
 const ERROR_PREFIX = 'Error in behavior';
 
+/**
+ * What the kept objects of a scene take into the world of the next one besides themselves (#165):
+ * their running behaviors, the index of the graphs those run on, and how their bodies were moving.
+ */
+export interface KeptState {
+  instances: Instance[];
+  graphs: GraphCache;
+  motion: ReadonlyMap<Entity, BodyMotion>;
+}
+
 export interface GameSystemOptions {
   shouldRun?: (entity: Entity) => boolean;
   audio?: AudioSink;
   /** What a scene swap hands over from the world before it (see `BehaviorSystem.carryOver`). */
   carried?: Readonly<SharedState> | null;
+  /** What the kept objects of the world before bring along (see `BehaviorSystem.release`). */
+  kept?: KeptState | null;
   /**
    * The loaded engine: a played game simulates its rigidbodies on it (#146). Without one the
    * collisions are detected only, which is what the editor run still does.
@@ -107,6 +119,7 @@ export function addGameSystems(
     shouldRun,
     audio = SILENT_AUDIO,
     carried = null,
+    kept = null,
     physics = null,
     clock = null,
     saves = null,
@@ -117,6 +130,10 @@ export function addGameSystems(
   const sources = { collisions, animations, audio, clock, saves };
   const behaviors = new BehaviorSystem(project, input, sources, shouldRun);
   if (carried) behaviors.carryOver(carried);
+  if (kept) {
+    behaviors.adopt(kept);
+    if (collisions instanceof PhysicsSystem) collisions.resume(kept.motion);
+  }
   world.addSystem(collisions);
   world.addSystem(animations);
   world.addSystem(behaviors);
@@ -164,7 +181,9 @@ export class BehaviorSystem implements System {
   /** The declarations as last read; an edit is what differs from these (see `syncDeclarations`). */
   private declared: Record<string, PropertyBag> = {};
   /** Shared by every instance; an edit to the project empties it (see `syncFromModel`). */
-  private readonly graphs = new GraphCache();
+  private graphs = new GraphCache();
+  /** Running behaviors of kept objects, handed over by the world before; consumed by the next `start`. */
+  private adopted: Instance[] = [];
   private readonly collisions: CollisionSource | null;
   private readonly animations: AnimationSystem | null;
   private readonly audio: AudioSink;
@@ -227,9 +246,42 @@ export class BehaviorSystem implements System {
     this.restarted = restartedAssets(this.project);
   }
 
+  /**
+   * Hands out the running behaviors on these entities, so the end of this world is not theirs: no
+   * `On destroy`, their sounds play on, and the next world's system carries them on where they are
+   * (see `adopt`). Call before the world is destroyed.
+   */
+  release(entities: readonly Entity[]): KeptState {
+    const leaving = new Set(entities);
+    const instances = this.instances.filter((i) => leaving.has(i.entity));
+    this.instances = this.instances.filter((i) => !leaving.has(i.entity));
+    const physics = this.collisions instanceof PhysicsSystem ? this.collisions : null;
+    return { instances, graphs: this.graphs, motion: physics?.motionOf(entities) ?? new Map() };
+  }
+
+  /**
+   * Takes over behaviors that ran in the world before. They are no new instances, so they hear no
+   * `On start`; their timers, variables and local machines stand where they stood. Call before the
+   * world is started.
+   */
+  adopt(kept: KeptState): void {
+    this.adopted = kept.instances;
+    // Their interpreters read this index, and an edit to the project has to reach it through us.
+    this.graphs = kept.graphs;
+  }
+
   start(world: World): void {
     this.world = world;
-    this.instances = [];
+    this.instances = this.adopted;
+    this.adopted = [];
+    // The trace is timed by the world, and this one starts at second zero.
+    for (const instance of this.instances) {
+      instance.trace.edges.clear();
+      instance.trace.nodes.clear();
+      for (const byNode of instance.values.values())
+        for (const produced of byNode.values()) produced.time = 0;
+      this.listen(instance, world);
+    }
     this.pending = [];
     const carried = this.carried;
     this.carried = null;
@@ -296,16 +348,8 @@ export class BehaviorSystem implements System {
       const trace = { edges: new Map<string, number>(), nodes: new Map<string, number>() };
       const values = new Map<Graph, Map<string, Produced>>();
       const interpreter = new GraphInterpreter(asset.graph, graphLookup(this.project), this.graphs);
-      interpreter.trace = {
-        onEdge: (id) => trace.edges.set(id, world.time),
-        onNode: (id) => trace.nodes.set(id, world.time),
-        onValues: (graph, id, produced) => {
-          let byNode = values.get(graph);
-          if (!byNode) values.set(graph, (byNode = new Map<string, Produced>()));
-          byNode.set(id, { time: world.time, values: produced });
-        },
-      } satisfies TraceListener;
       const instance: Instance = { entity, interpreter, trace, values, states: {}, active: true };
+      this.listen(instance, world);
       this.instances.push(instance);
       born.add(instance);
     }
@@ -318,6 +362,19 @@ export class BehaviorSystem implements System {
     this.flushStateChanges();
   }
 
+  /** Has the instance note what it runs, timed by the world it runs in. */
+  private listen({ interpreter, trace, values }: Instance, world: World): void {
+    interpreter.trace = {
+      onEdge: (id) => trace.edges.set(id, world.time),
+      onNode: (id) => trace.nodes.set(id, world.time),
+      onValues: (graph, id, produced) => {
+        let byNode = values.get(graph);
+        if (!byNode) values.set(graph, (byNode = new Map<string, Produced>()));
+        byNode.set(id, { time: world.time, values: produced });
+      },
+    } satisfies TraceListener;
+  }
+
   /**
    * Puts the instances in hierarchy order – what equal orders fall back on (#264). Only when one is
    * born or the scene was edited, since the hierarchy is walked in full.