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>
2026-10-01 17:30:16 +02:00
1 parent 3e8c88c66d
commit 1aa824ecb4
@@ -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;
+}
@@ -39,6 +39,17 @@ export interface WorldOptions {
   * but what it writes goes into the instance edits and it cannot destroy itself for good.
   */
  bakeContainers?: boolean;
+  /** What a `Load scene` brings along from the world before (#165); given, the scene counts as changed. */
+  brought?: BroughtEntities;
+}
+
+/**
+ * The kept entities of the world before, whose objects the scene holds by now, and the ids of the
+ * scene's own objects they stand in for (see `keptObjects.ts`).
+ */
+export interface BroughtEntities {
+  entities: readonly Entity[];
+  standIns: ReadonlyMap<string, string>;
 }

 /** What `syncToModel` wrote: `structure` = objects appeared or vanished, `values` = the rest. */
@@ -137,6 +148,10 @@ export class World {
  private entitiesGone = false;
  private readonly modelStates = new WeakMap<Entity, ModelState>();
  private tilesChanged = false;
+  /** Entities of the world before, by object id, until the scene's object takes each one up. */
+  private readonly arriving = new Map<string, Entity>();
+  /** Objects this scene did not build because one brought along is it already, by their id. */
+  private readonly standIns = new Map<string, Entity>();

  private constructor(
    readonly project: Project,
@@ -148,7 +163,16 @@ export class World {
  static instantiate(project: Project, sceneId: string, options: WorldOptions = {}): World {
    if (!findScene(project, sceneId)) throw new Error(`Scene ${sceneId} not found`);
    const world = new World(project, sceneId, options.bakeContainers ?? true);
+    const brought = options.brought;
+    for (const entity of brought?.entities ?? []) world.arriving.set(entity.objectId, entity);
    world.syncFromModel();
+    world.arriving.clear();
+    if (!brought) return world;
+    for (const [id, standIn] of brought.standIns) {
+      const entity = world.entities.find((e) => e.objectId === standIn);
+      if (entity) world.standIns.set(id, entity);
+    }
+    world.structureChanged = true;
    return world;
  }

@@ -263,7 +287,18 @@ export class World {

  /** The entity for a scene object, created when missing; position, name and props re-read. */
  private materialize(object: SceneObject, asset: Asset): Entity {
-    let entity = this.findByObjectId(object.id);
+    let entity = this.entities.find((e) => e.objectId === object.id);
+    const arrived = entity ? undefined : this.arriving.get(object.id);
+    if (arrived) {
+      // It comes as the run left it: what the scene says of it is only what the next write compares
+      // against, so the run's values reach the scene instead of the scene's replacing them.
+      this.entities.push(arrived);
+      arrived.assetId = asset.id;
+      arrived.type = asset.type;
+      arrived.name = objectName(object, asset);
+      this.modelStates.set(arrived, { asset, ...object.position, props: this.modelProps(asset, object) });
+      return arrived;
+    }
    if (!entity) {
      entity = {
        [ENTITY_HANDLE]: true,
@@ -516,8 +551,12 @@ export class World {
    );
  }

+  /** An object the scene left out for one brought along (#165) answers as that one. */
  findByObjectId(objectId: string): Entity | undefined {
-    return this.entities.find((e) => e.objectId === objectId);
+    const own = this.entities.find((e) => e.objectId === objectId);
+    if (own) return own;
+    const standIn = this.standIns.get(objectId);
+    return standIn && this.entities.includes(standIn) ? standIn : undefined;
  }

  /** The entity a reference on `from` names (#258): its own container placement's copy first. */
@@ -0,0 +1,91 @@
+/**
+ * Objects that travel through a `Load scene` (#165): which entities of the running world are kept,
+ * and how their objects are put into the scene loaded next.
+ */
+import type { SceneAsset } from '../core/model/Asset';
+import { removeSubtrees } from '../core/model/hierarchy';
+import { findAsset, type Project } from '../core/model/Project';
+import type { SceneObject } from '../core/model/SceneObject';
+import { KEEP_ON_SCENE_LOAD_KEY } from '../core/properties/PropertySchema';
+import { resolveSceneObjectProps } from '../core/properties/resolve';
+import type { Entity } from './Entity';
+
+/** Whether the switch is on for an object as the scene stores it. */
+function isKept(project: Project, object: SceneObject): boolean {
+  const asset = findAsset(project, object.assetId);
+  return (
+    asset !== undefined && resolveSceneObjectProps(project, asset, object)[KEEP_ON_SCENE_LOAD_KEY] === true
+  );
+}
+
+/**
+ * The entities a scene swap keeps: every top-level one with the switch on, and all below it. Only a
+ * top-level object can be kept – one further down would arrive without the parent it is placed in.
+ */
+export function keptEntities(entities: readonly Entity[]): Entity[] {
+  const kept = new Set<Entity>();
+  // A parent may come after its child in the list, so the chain is walked rather than the order trusted.
+  const travels = (entity: Entity): boolean => {
+    let top = entity;
+    while (top.parent) top = top.parent;
+    return top.props[KEEP_ON_SCENE_LOAD_KEY] === true;
+  };
+  for (const entity of entities) if (travels(entity)) kept.add(entity);
+  return entities.filter((e) => kept.has(e));
+}
+
+/**
+ * The stored objects of the kept entities, as copies ready for another scene: parented as the run
+ * has them now, and in no hierarchy folder, which belongs to the scene they leave. An entity the
+ * scene stores no object for cannot travel and is left out of `entities`.
+ */
+export function objectsToBring(
+  scene: SceneAsset,
+  entities: readonly Entity[],
+): { entities: Entity[]; objects: SceneObject[] } {
+  const stored = new Map(scene.objects.map((o) => [o.id, o]));
+  const brought: Entity[] = [];
+  const objects: SceneObject[] = [];
+  for (const entity of entities) {
+    const object = stored.get(entity.objectId);
+    if (!object) continue;
+    const copy = structuredClone(object);
+    copy.parentId = entity.parent?.objectId ?? '';
+    delete copy.groupId;
+    brought.push(entity);
+    objects.push(copy);
+  }
+  return { entities: brought, objects };
+}
+
+/**
+ * Puts the brought objects into the scene, after its own. What the scene holds of the same thing is
+ * not built, the one brought along wins: an object of the same id – the scene the object came from,
+ * loaded again – and a top-level object of the same asset that is kept itself, which is how each
+ * level can place its own player and still end up with one. Answers the ids of the objects left out
+ * that way, each with the id of the object standing in for it.
+ */
+export function bringObjects(
+  project: Project,
+  scene: SceneAsset,
+  brought: readonly SceneObject[],
+): Map<string, string> {
+  const ids = new Set(brought.map((o) => o.id));
+  const tops = brought.filter((o) => o.parentId === '');
+  const standIns = new Map<string, string>();
+  const leftOut: string[] = [];
+  for (const object of scene.objects) {
+    if (ids.has(object.id)) {
+      leftOut.push(object.id);
+      continue;
+    }
+    if (object.parentId !== '') continue;
+    const standIn = tops.find((top) => top.assetId === object.assetId);
+    if (!standIn || !isKept(project, object)) continue;
+    leftOut.push(object.id);
+    standIns.set(object.id, standIn.id);
+  }
+  removeSubtrees(scene, leftOut);
+  scene.objects.push(...brought);
+  return standIns;
+}
@@ -112,6 +112,12 @@ interface Part {
  owner: Body;
 }

+/** How a dynamic body moves, in the engine's own units. */
+export interface BodyMotion {
+  linear: Vec2;
+  angular: number;
+}
+
 /**
 * The played game's physics on Rapier (#146): rigidbodies fall, bounce and rest, and the collision
 * events come from the engine's contact pairs. Ticked first, like the collision system it stands in
@@ -147,6 +153,8 @@ export class PhysicsSystem implements System, CollisionSource {
  private frameDt = PHYSICS_STEP;
  private readonly hinted = new Set<string>();
  private world: World | null = null;
+  /** How bodies moved in the world before (#165), until the body of each is made here. */
+  private resumed = new Map<Entity, BodyMotion>();

  constructor(private readonly rapier: Rapier) {}

@@ -183,6 +191,7 @@ export class PhysicsSystem implements System, CollisionSource {
    this.backlog = 0;
    this.frameDt = PHYSICS_STEP;
    this.hinted.clear();
+    this.resumed.clear();
  }

  update(world: World, dt: number): void {
@@ -249,6 +258,23 @@ export class PhysicsSystem implements System, CollisionSource {
    return this.measure(this.engine!.getCollider(handles[0]), this.engine!.getCollider(handles[1]));
  }

+  /** How the dynamic bodies among these objects move right now, for the next world to `resume`. */
+  motionOf(entities: readonly Entity[]): Map<Entity, BodyMotion> {
+    const motion = new Map<Entity, BodyMotion>();
+    for (const entity of entities) {
+      const body = this.bodies.get(entity);
+      if (body?.kind !== 'rigid' || !body.body.isDynamic()) continue;
+      const v = body.body.linvel();
+      motion.set(entity, { linear: { x: v.x, y: v.y }, angular: body.body.angvel() });
+    }
+    return motion;
+  }
+
+  /** Bodies made for these objects start out moving as they did; call before the first tick. */
+  resume(motion: ReadonlyMap<Entity, BodyMotion>): void {
+    this.resumed = new Map(motion);
+  }
+
  /** A dynamic body's velocity in world units per second; null for an object the engine does not move. */
  velocityOf(target: Entity): Vec2 | null {
    const body = this.dynamicBodyOf(target)?.body;
@@ -378,6 +404,8 @@ export class PhysicsSystem implements System, CollisionSource {
      this.place(body, want, key, world);
      this.build(body, want, key, world);
    }
+    // Only the body an object arrives with moves on: one it gets later starts at rest like any other.
+    this.resumed.clear();
  }

  /**
@@ -422,6 +450,9 @@ export class PhysicsSystem implements System, CollisionSource {
              ? R.RigidBodyDesc.fixed()
              : R.RigidBodyDesc.kinematicPositionBased();
    desc.setTranslation(toMetres(pose.x), toMetres(pose.y)).setRotation(pose.angle);
+    const motion =
+      want.kind === 'rigid' && want.settings!.type === 'dynamic' ? this.resumed.get(key) : undefined;
+    if (motion) desc.setLinvel(motion.linear.x, motion.linear.y).setAngvel(motion.angular);
    return {
      kind: want.kind,
      body: this.engine!.createRigidBody(desc),
@@ -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.