@irtio/runtime 0.8.0 → 0.9.0

package/dist/{chunk-ZCD2TBXB.js → chunk-ADZZEVJU.js}

@@ -250,7 +250,7 @@ function createCallProxy(core, clientId) {
     }
   );
 }
-function createBroadcastProxy(core) {
+function createBroadcastProxy(core, except) {
   return new Proxy(
     {},
     {
@@ -259,13 +259,19 @@ function createBroadcastProxy(core) {
         return (params) => {
           const desc = descFor(core, prop);
           for (const entry of core.clients.values()) {
-            if (entry.connected) sendCall(core, entry.clientId, desc, params ?? {});
+            if (!entry.connected) continue;
+            if (except?.has(entry.clientId)) continue;
+            sendCall(core, entry.clientId, desc, params ?? {});
           }
         };
       }
     }
   );
 }
+function createBroadcastExceptProxy(core, except) {
+  const ids = typeof except === "string" ? [except] : except;
+  return createBroadcastProxy(core, new Set(ids));
+}
 function handleReply(core, clientId, payload) {
   let reply;
   try {
@@ -956,6 +962,7 @@ function decodeMatterBodies(bytes) {
 function bodyKey(collection, id) {
   return `${collection}\0${id}`;
 }
+var PLANAR_CHANNELS = /* @__PURE__ */ new Set(["x", "y", "qz", "qw", "vx", "vy", "wz"]);
 var MatterRuntime = class {
   engineKind = "matter2d";
   /** rapier3d only; present so both runtimes satisfy one internal shape. */
@@ -981,6 +988,15 @@ var MatterRuntime = class {
   restore;
   stepMs;
   sleepSynced = /* @__PURE__ */ new Set();
+  /**
+   * The plain record object each body was built from. See `PhysicsRuntime.sourceRecords`: `add()`
+   * installs a new record object, so an id removed and re-added between two reconciles (a pooled
+   * projectile) is identifiable by identity, and is the one case where a live body has to be
+   * rebuilt so the new row's spawn pose and velocity are honoured.
+   */
+  sourceRecords = /* @__PURE__ */ new Map();
+  /** `collection.field` pairs already warned about a channel a plane cannot hold. */
+  warnedChannels = /* @__PURE__ */ new Set();
   constructor(core, matter, options) {
     const config = core.definition.config.physics;
     if (!config) throw new Error("MatterRuntime: the room config declares no physics");
@@ -1050,6 +1066,7 @@ var MatterRuntime = class {
     } else {
       this.applyRecordToBody(desc, spec.body, record);
     }
+    this.sourceRecords.set(key, record);
     return spec.body;
   }
   // ---- M6 lane F: rewind ----
@@ -1089,6 +1106,17 @@ var MatterRuntime = class {
     for (const [channel, field] of physics.channels) {
       const raw = record[field];
       if (typeof raw !== "number") continue;
+      if (raw !== 0 && !PLANAR_CHANNELS.has(channel)) {
+        const key = `${desc.name}.${field}`;
+        if (!this.warnedChannels.has(key)) {
+          this.warnedChannels.add(key);
+          this.core.log(
+            "warn",
+            `irtio: ${desc.name}.${field} maps body channel ${channel}, which a matter2d room cannot hold (the world is a plane); the ${raw} it was added with was dropped`
+          );
+        }
+        continue;
+      }
       applyChannel2d(channel, raw, t);
     }
     this.applyState(body, {
@@ -1110,8 +1138,21 @@ var MatterRuntime = class {
       for (const id of coll.ids()) {
         const key = bodyKey(desc.name, id);
         live.add(key);
-        if (this.bodies.has(key)) continue;
         const record = coll.get(id);
+        const existing = this.bodies.get(key);
+        if (existing) {
+          if (record === void 0) continue;
+          const source = this.sourceRecords.get(key);
+          if (source === void 0) {
+            this.sourceRecords.set(key, record);
+            continue;
+          }
+          if (source === record) continue;
+          this.bodies.delete(key);
+          this.sleepSynced.delete(key);
+          this.sourceRecords.delete(key);
+          this.matter.Composite.remove(this.engine.world, [existing.body, ...existing.constraints]);
+        }
         if (record !== void 0) this.create(desc, id, record);
       }
     }
@@ -1119,6 +1160,7 @@ var MatterRuntime = class {
       if (live.has(key)) continue;
       this.bodies.delete(key);
       this.sleepSynced.delete(key);
+      this.sourceRecords.delete(key);
       this.matter.Composite.remove(this.engine.world, [attached.body, ...attached.constraints]);
     }
   }
@@ -1349,6 +1391,19 @@ var PhysicsRuntime = class {
    * world rebuilt from schema state would wake it with a kick). Found by the drift check.
    */
   sleepSynced = /* @__PURE__ */ new Set();
+  /**
+   * The plain record object each body was built from, by body key. `add()` always installs a
+   * **new** record object (`normalizeRecord` builds one), so an id that is removed and re-added
+   * between two reconciles — the pooled-projectile shape — is identifiable by identity alone,
+   * which is the only way to see it from here: both edits happened before this module looked.
+   * Without it the old body kept its pose and velocity and the new row's spawn values were lost.
+   *
+   * Unknown means adopt, never rebuild: a world restored from a hibernation blob has bodies with
+   * no recorded source, and rebuilding those would throw away exactly what the blob preserved.
+   */
+  sourceRecords = /* @__PURE__ */ new Map();
+  /** `collection.field` pairs already warned about a channel value the engine would not take. */
+  warnedChannels = /* @__PURE__ */ new Set();
   constructor(core, rapier, options) {
     const config = core.definition.config.physics;
     if (!config) throw new Error("PhysicsRuntime: the room config declares no physics");
@@ -1423,10 +1478,50 @@ var PhysicsRuntime = class {
     }
     const body = this.world.createRigidBody(spec.body);
     for (const collider of spec.colliders ?? []) this.world.createCollider(collider, body);
+    this.warnLockedChannels(desc, spec, record);
     this.applyRecordToBody(desc, body, record);
     this.bodies.set(bodyKey2(desc.name, id), body);
+    this.sourceRecords.set(bodyKey2(desc.name, id), record);
     return body;
   }
+  /**
+   * A spawn value the engine will not take, said once per field.
+   *
+   * Rapier accepts `setLinvel` on an axis the body has disabled and then keeps zero, and it
+   * accepts one on a fixed body and then ignores it — both read back as "the field was applied"
+   * and behave as if it never was. The desc says which, before the body exists, so the check is
+   * on the desc: the usual case is the 2D-in-3D recipe (`enabledTranslations(true, true, false)`)
+   * meeting a row that spawns with a `vz`. Named by field, because the field is what the author
+   * wrote and what they will grep for.
+   */
+  warnLockedChannels(desc, spec, record) {
+    const physics = desc.physics;
+    if (!physics) return;
+    const b = spec.body;
+    const frozen = b.status !== 0;
+    const enabled = {
+      vx: b.translationsEnabledX,
+      vy: b.translationsEnabledY,
+      vz: b.translationsEnabledZ,
+      wx: b.rotationsEnabledX,
+      wy: b.rotationsEnabledY,
+      wz: b.rotationsEnabledZ
+    };
+    for (const [channel, field] of physics.channels) {
+      const allowed = enabled[channel];
+      if (allowed === void 0) continue;
+      const raw = record[field];
+      if (typeof raw !== "number" || raw === 0) continue;
+      if (allowed && !frozen) continue;
+      const key = `${desc.name}.${field}`;
+      if (this.warnedChannels.has(key)) continue;
+      this.warnedChannels.add(key);
+      this.core.log(
+        "warn",
+        `irtio: ${desc.name}.${field} (body channel ${channel}) was added as ${raw}, but ` + (frozen ? `physics.bodies.${desc.name} builds a non-dynamic body, which never moves under it` : `that degree of freedom is disabled by physics.bodies.${desc.name}`) + " \u2014 the value was dropped"
+      );
+    }
+  }
   // ---- M6 lane F: rewind ----
   /**
    * D72: every tracked body, in the order `sync()` walks them (collection order, then instance
@@ -1522,8 +1617,21 @@ var PhysicsRuntime = class {
       for (const id of coll.ids()) {
         const key = bodyKey2(desc.name, id);
         live.add(key);
-        if (this.bodies.has(key)) continue;
         const record = coll.get(id);
+        const existing = this.bodies.get(key);
+        if (existing) {
+          if (record === void 0) continue;
+          const source = this.sourceRecords.get(key);
+          if (source === void 0) {
+            this.sourceRecords.set(key, record);
+            continue;
+          }
+          if (source === record) continue;
+          this.bodies.delete(key);
+          this.sleepSynced.delete(key);
+          this.sourceRecords.delete(key);
+          this.world.removeRigidBody(existing);
+        }
         if (record !== void 0) this.create(desc, id, record);
       }
     }
@@ -1531,6 +1639,7 @@ var PhysicsRuntime = class {
       if (live.has(key)) continue;
       this.bodies.delete(key);
       this.sleepSynced.delete(key);
+      this.sourceRecords.delete(key);
       this.world.removeRigidBody(body);
     }
   }
@@ -1630,6 +1739,14 @@ function channelValue(channel, t, r, v, w) {
 }
 
 // src/core/random.ts
+function seedFromRoomId(roomId) {
+  let h = 2166136261;
+  for (let i = 0; i < roomId.length; i++) {
+    h ^= roomId.charCodeAt(i);
+    h = Math.imul(h, 16777619) >>> 0;
+  }
+  return h === 0 ? 2654435769 : h >>> 0;
+}
 var Mulberry32 = class {
   /** Current internal state (u32). Survives hibernation. */
   state;
@@ -1691,6 +1808,16 @@ var Rapier2dRuntime = class {
   bodies = /* @__PURE__ */ new Map();
   /** See `PhysicsRuntime.sleepSynced`: the one extra sync a body owes on the tick it sleeps. */
   sleepSynced = /* @__PURE__ */ new Set();
+  /**
+   * See `PhysicsRuntime.sourceRecords`: the plain record object each body was built from. `add()`
+   * always installs a new record object, so an id removed and re-added between two reconciles —
+   * the pooled-projectile shape — is identifiable by identity alone, and its body is rebuilt so
+   * the new row's spawn pose and velocity are what the world gets. Unknown means adopt, never
+   * rebuild: a world restored from a hibernation blob has bodies with no recorded source.
+   */
+  sourceRecords = /* @__PURE__ */ new Map();
+  /** `collection.field` pairs already warned about a channel value the engine would not take. */
+  warnedChannels = /* @__PURE__ */ new Set();
   constructor(core, rapier, options) {
     const config = core.definition.config.physics;
     if (!config) throw new Error("Rapier2dRuntime: the room config declares no physics");
@@ -1760,10 +1887,48 @@ var Rapier2dRuntime = class {
     }
     const body = this.world.createRigidBody(spec.body);
     for (const collider of spec.colliders ?? []) this.world.createCollider(collider, body);
+    this.warnLockedChannels(desc, spec, record);
     this.applyRecordToBody(desc, body, record);
     this.bodies.set(bodyKey3(desc.name, id), body);
+    this.sourceRecords.set(bodyKey3(desc.name, id), record);
     return body;
   }
+  /**
+   * A spawn value the engine will not take, said once per field — the planar half of
+   * `PhysicsRuntime.warnLockedChannels`.
+   *
+   * Rapier accepts `setLinvel` on an axis the body has disabled and then keeps zero, and it
+   * accepts one on a fixed body and then ignores it: both read back as "the field was applied"
+   * and behave as if it never was. The desc says which, before the body exists, so the check is on
+   * the desc. In the plane there are three movable channels — `vx`, `vy` and the one rotation
+   * `wz` — and the desc carries exactly those three flags. Named by field, because the field is
+   * what the author wrote and what they will grep for.
+   */
+  warnLockedChannels(desc, spec, record) {
+    const physics = desc.physics;
+    if (!physics) return;
+    const b = spec.body;
+    const frozen = b.status !== 0;
+    const enabled = {
+      vx: b.translationsEnabledX,
+      vy: b.translationsEnabledY,
+      wz: b.rotationsEnabled
+    };
+    for (const [channel, field] of physics.channels) {
+      const allowed = enabled[channel];
+      if (allowed === void 0) continue;
+      const raw = record[field];
+      if (typeof raw !== "number" || raw === 0) continue;
+      if (allowed && !frozen) continue;
+      const key = `${desc.name}.${field}`;
+      if (this.warnedChannels.has(key)) continue;
+      this.warnedChannels.add(key);
+      this.core.log(
+        "warn",
+        `irtio: ${desc.name}.${field} (body channel ${channel}) was added as ${raw}, but ` + (frozen ? `physics.bodies.${desc.name} builds a non-dynamic body, which never moves under it` : `that degree of freedom is disabled by physics.bodies.${desc.name}`) + " \u2014 the value was dropped"
+      );
+    }
+  }
   // ---- M6 lane F: rewind ----
   /**
    * D72: every tracked body, in the order `sync()` walks them (collection order, then instance
@@ -1814,8 +1979,21 @@ var Rapier2dRuntime = class {
       for (const id of coll.ids()) {
         const key = bodyKey3(desc.name, id);
         live.add(key);
-        if (this.bodies.has(key)) continue;
         const record = coll.get(id);
+        const existing = this.bodies.get(key);
+        if (existing) {
+          if (record === void 0) continue;
+          const source = this.sourceRecords.get(key);
+          if (source === void 0) {
+            this.sourceRecords.set(key, record);
+            continue;
+          }
+          if (source === record) continue;
+          this.bodies.delete(key);
+          this.sleepSynced.delete(key);
+          this.sourceRecords.delete(key);
+          this.world.removeRigidBody(existing);
+        }
         if (record !== void 0) this.create(desc, id, record);
       }
     }
@@ -1823,6 +2001,7 @@ var Rapier2dRuntime = class {
       if (live.has(key)) continue;
       this.bodies.delete(key);
       this.sleepSynced.delete(key);
+      this.sourceRecords.delete(key);
       this.world.removeRigidBody(body);
     }
   }
@@ -2144,8 +2323,8 @@ function catchUpDirty(ext, plain, fromRole, toRole) {
 // src/core/snapshot.ts
 import { withBuiltins } from "@irtio/protocol";
 import { ByteReader as ByteReader3, ByteWriter as ByteWriter3, decodeSnapshot } from "@irtio/schema";
-var SNAPSHOT_FORMAT_VERSION = 2;
-var READABLE_SNAPSHOT_VERSIONS = [1, 2];
+var SNAPSHOT_FORMAT_VERSION = 3;
+var READABLE_SNAPSHOT_VERSIONS = [1, 2, 3];
 function parseHibernationBlob(bytes) {
   const r = new ByteReader3(bytes);
   const version = r.u8();
@@ -2156,22 +2335,31 @@ function parseHibernationBlob(bytes) {
   const rngState = r.u32();
   const tick = r.u32();
   const mode = r.u8() === 1 ? "event" : "tick";
+  const schemaHash8 = version >= 3 ? r.bytes(8).slice() : void 0;
   let physics;
   if (version >= 2) {
     const section = r.blob();
     if (section.length > 0) physics = section;
   }
-  return { version, seed, rngState, tick, mode, physics, snapshot: r.rest() };
+  return { version, seed, rngState, tick, mode, schemaHash8, physics, snapshot: r.rest() };
+}
+function sameSchemaHash(a, b) {
+  if (!a || !b) return true;
+  if (a.length !== b.length) return false;
+  for (let i = 0; i < a.length; i++) if (a[i] !== b[i]) return false;
+  return true;
 }
 function writeHibernationBlob(header, snapshot, physics) {
-  const version = physics ? 2 : 1;
-  const w = new ByteWriter3(snapshot.length + (physics?.length ?? 0) + 24);
+  const hash = header.schemaHash8;
+  const version = hash ? 3 : physics ? 2 : 1;
+  const w = new ByteWriter3(snapshot.length + (physics?.length ?? 0) + 32);
   w.u8(version);
   w.u32(header.seed >>> 0);
   w.u32(header.rngState >>> 0);
   w.u32(header.tick >>> 0);
   w.u8(header.mode === "event" ? 1 : 0);
-  if (physics) w.blob(physics);
+  if (hash) w.bytes(hash);
+  if (version >= 2) w.blob(physics ?? new Uint8Array(0));
   w.bytes(snapshot);
   return w.finish();
 }
@@ -3284,9 +3472,20 @@ function createRoomApi(core, publicUrl) {
     get id() {
       return core.roomId;
     },
+    /**
+     * The same tracked state object handlers get. The one caller that has no other way to it is
+     * `physics.setup`, which runs before `onCreate` on a fresh room and after the snapshot is
+     * decoded on a rebuild — see the doc on `Room.state`.
+     */
+    get state() {
+      return core.anyState;
+    },
     get link() {
       return link();
     },
+    get seed() {
+      return core.seed;
+    },
     get tick() {
       return core.tick;
     },
@@ -3477,6 +3676,9 @@ function createRoomApi(core, publicUrl) {
     },
     get broadcast() {
       return broadcast;
+    },
+    broadcastExcept(clientId) {
+      return createBroadcastExceptProxy(core, clientId);
     }
   };
   const broadcast = createBroadcastProxy(core);
@@ -3665,8 +3867,13 @@ var RoomCore = class _RoomCore {
     }
     let restored;
     let plain;
-    if (options.restoreFrom) {
-      restored = parseHibernationBlob(options.restoreFrom);
+    const candidate = options.restoreFrom ? parseHibernationBlob(options.restoreFrom) : void 0;
+    if (candidate && !sameSchemaHash(candidate.schemaHash8, this.ext.hash8)) {
+      host.log("warn", [`irtio: room ${options.roomId}: schema changed, snapshot discarded`]);
+    } else if (candidate) {
+      restored = candidate;
+    }
+    if (restored) {
       plain = decodeSnapshot2(this.ext, restored.snapshot).state;
       const presence = plainEntity(plain, PRESENCE_COLLECTION);
       for (const id of [...presence.ids()]) presence.remove(id);
@@ -3681,7 +3888,7 @@ var RoomCore = class _RoomCore {
     this.plain = plain;
     this.tracked = track(this.ext, plain);
     this.anyState = this.tracked.state;
-    this.seed = restored?.seed ?? options.seed ?? 1;
+    this.seed = restored?.seed ?? options.seed ?? seedFromRoomId(this.roomId);
     this.rng = new Mulberry32(restored?.rngState ?? this.seed);
     this.tick = restored?.tick ?? 0;
     const self = this;
@@ -4025,7 +4232,13 @@ var RoomCore = class _RoomCore {
   snapshot() {
     const physics = this.physics ? encodeSection(this.physics) : void 0;
     return writeHibernationBlob(
-      { seed: this.seed, rngState: this.rng.state, tick: this.tick, mode: this.mode },
+      {
+        seed: this.seed,
+        rngState: this.rng.state,
+        tick: this.tick,
+        mode: this.mode,
+        schemaHash8: this.ext.hash8
+      },
       encodeSnapshot2(this.ext, this.plain, { tick: this.tick }),
       physics
     );

package/dist/{chunk-DBGMG2S3.js → chunk-SBDZ45JG.js}

@@ -1,7 +1,7 @@
 import {
   parseHibernationBlob,
   writeHibernationBlob
-} from "./chunk-ZCD2TBXB.js";
+} from "./chunk-ADZZEVJU.js";
 
 // src/migrate.ts
 import { PRESENCE_COLLECTION, withBuiltins } from "@irtio/protocol";
@@ -53,7 +53,15 @@ function migrateSnapshot(blob, chain, options) {
   }
   plain = fromMigrationState(withBuiltins(schema), state, last.version);
   const bytes = writeHibernationBlob(
-    { seed: parsed.seed, rngState: parsed.rngState, tick: parsed.tick, mode: parsed.mode },
+    {
+      seed: parsed.seed,
+      rngState: parsed.rngState,
+      tick: parsed.tick,
+      mode: parsed.mode,
+      // Stamped with the *target* schema: these bytes are now that schema's, and a room waking on
+      // it must not see them as a mismatch.
+      schemaHash8: withBuiltins(schema).hash8
+    },
     encodeSnapshot(withBuiltins(schema), plain, { tick: parsed.tick })
   );
   return {

package/dist/{contract-CRilLVdx.d.ts → contract-C5aqs49-.d.ts}

@@ -302,7 +302,11 @@ interface RoomHost {
 }
 interface RoomCoreOptions {
     readonly roomId: string;
-    /** Seed for `room.random()`; default 1. */
+    /**
+     * Seed for `room.random()`. Defaults to a stable 32-bit hash of `roomId`, so two rooms of the
+     * same game generate different worlds; pass a number to pin the sequence instead. A room
+     * restored from a snapshot ignores both and keeps the seed it was created with.
+     */
     readonly seed?: number;
     /** Base URL for `room.link` (`<publicUrl>?room=<id>`); default `http://localhost/`. */
     readonly publicUrl?: string;

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-export { D as DEFAULT_TIMELINE_MAX_RECORDS, a as DEFAULT_TIMELINE_MAX_TICKS, E as EVENT_RING_SIZE, H as HOST_CALL_TIMEOUT_MS, b as HostCall, c as HostCallResult, J as JoinOptions, d as JoinResult, L as LogLevel, R as RoomCoreApi, e as RoomCoreOptions, f as RoomEvent, g as RoomEventKind, h as RoomFullError, i as RoomHost, j as RoomInspection, k as RoomStats, T as TimelineDump, l as TimelineFrame, m as TimelineRecorder, n as TimelineRecorderOptions, o as inspectState } from './contract-CRilLVdx.js';
-export { C as CRASH_AFTER_THROWS, M as MAX_CATCHUP, a as MatterBodyRecord, b as MatterSection, c as Mulberry32, P as PhysicsEngineTag, d as PhysicsSection, R as RoomCore, e as decodeMatterBodies, f as decodeMatterSectionEnvelope, g as decodePhysicsSection, h as decodeRapier2dSectionEnvelope, i as encodeMatterBodies, j as encodeMatterSectionEnvelope, k as encodePhysicsSection, l as encodeRapier2dSectionEnvelope, m as initMatter, n as initPhysics, o as initRapier2d, p as loadedMatter, q as loadedPhysics, r as loadedRapier2d, s as physicsSectionEngine, t as resetMatterForTests, u as resetPhysicsForTests, v as resetRapier2dForTests } from './room-YJGz6Caw.js';
+export { D as DEFAULT_TIMELINE_MAX_RECORDS, a as DEFAULT_TIMELINE_MAX_TICKS, E as EVENT_RING_SIZE, H as HOST_CALL_TIMEOUT_MS, b as HostCall, c as HostCallResult, J as JoinOptions, d as JoinResult, L as LogLevel, R as RoomCoreApi, e as RoomCoreOptions, f as RoomEvent, g as RoomEventKind, h as RoomFullError, i as RoomHost, j as RoomInspection, k as RoomStats, T as TimelineDump, l as TimelineFrame, m as TimelineRecorder, n as TimelineRecorderOptions, o as inspectState } from './contract-C5aqs49-.js';
+export { C as CRASH_AFTER_THROWS, M as MAX_CATCHUP, a as MatterBodyRecord, b as MatterSection, c as Mulberry32, P as PhysicsEngineTag, d as PhysicsSection, R as RoomCore, e as decodeMatterBodies, f as decodeMatterSectionEnvelope, g as decodePhysicsSection, h as decodeRapier2dSectionEnvelope, i as encodeMatterBodies, j as encodeMatterSectionEnvelope, k as encodePhysicsSection, l as encodeRapier2dSectionEnvelope, m as initMatter, n as initPhysics, o as initRapier2d, p as loadedMatter, q as loadedPhysics, r as loadedRapier2d, s as physicsSectionEngine, t as resetMatterForTests, u as resetPhysicsForTests, v as resetRapier2dForTests } from './room-C4RZJ2KO.js';
 import { CollectionDesc, AnySchema, PlainState, DirtySet } from '@irtio/schema';
 import '@irtio/protocol';
 import '@irtio/server';
@@ -70,9 +70,16 @@ declare function catchUpDirty(ext: AnySchema, plain: PlainState, fromRole: strin
  *   u32 rng state
  *   u32 tick
  *   u8  mode (1 = event, 0 = tick)
+ *   [v3] 8 bytes schema hash (`withBuiltins(schema).hash8`)
  *   [v2] blob physics section (varint length + bytes; length 0 = no world)
  *   ... encodeSnapshot(withBuiltins(schema), state)
  *
+ * **v3** adds the schema hash. Before it, restoring a snapshot written under a different schema
+ * fed the old bytes to the new decoder and surfaced as a `TypeError` from deep inside the string
+ * decoder; the room could only be started again by hand-deleting `.irtio/snapshots`. The hash is
+ * in the envelope (not only in the codec payload) so the check costs no decode: a mismatch is
+ * seen, logged and the snapshot discarded before anything is parsed against the wrong schema.
+ *
  * **v2 (week 9, D22)** adds the physics section: the Rapier world snapshot plus the entity↔handle
  * map (`core/physics.ts` encodes it). It rides *inside* this blob rather than beside it so that
  * wake is atomic — state and world always come back from the same bytes, and every store, cache
@@ -89,8 +96,8 @@ declare function catchUpDirty(ext: AnySchema, plain: PlainState, fromRole: strin
  * instead of parsing bytes it may not yet know how to read.
  */
 
-/** Written when the blob carries a physics world; v1 otherwise (and v1 is still read). */
-declare const SNAPSHOT_FORMAT_VERSION = 2;
+/** Written when the header carries a schema hash (every room does); older versions still read. */
+declare const SNAPSHOT_FORMAT_VERSION = 3;
 /** Versions this build can parse. */
 declare const READABLE_SNAPSHOT_VERSIONS: readonly number[];
 type SnapshotMode = 'tick' | 'event';
@@ -99,6 +106,12 @@ interface SnapshotHeader {
     readonly rngState: number;
     readonly tick: number;
     readonly mode: SnapshotMode;
+    /**
+     * `withBuiltins(schema).hash8` of the schema these bytes were written under. Omitted only by a
+     * writer that has no schema in hand; a restore that finds it absent cannot check and proceeds
+     * as pre-v3 builds did.
+     */
+    readonly schemaHash8?: Uint8Array | undefined;
 }
 interface ParsedSnapshot extends SnapshotHeader {
     /** The blob's own format version (1 or 2). */

package/dist/index.js

@@ -2,7 +2,7 @@ import {
   fromMigrationState,
   migrateSnapshot,
   toMigrationState
-} from "./chunk-DBGMG2S3.js";
+} from "./chunk-SBDZ45JG.js";
 import {
   CRASH_AFTER_THROWS,
   DEFAULT_TIMELINE_MAX_RECORDS,
@@ -47,7 +47,7 @@ import {
   visibleNames,
   visibleTo,
   writeHibernationBlob
-} from "./chunk-ZCD2TBXB.js";
+} from "./chunk-ADZZEVJU.js";
 export {
   CRASH_AFTER_THROWS,
   DEFAULT_TIMELINE_MAX_RECORDS,

package/dist/{room-YJGz6Caw.d.ts → room-C4RZJ2KO.d.ts}

@@ -1,12 +1,8 @@
 import { AttributeOptions, ProfileSnapshot } from '@irtio/protocol';
 import { DirtySet, AnySchema, PlainState, Tracked, State } from '@irtio/schema';
 import { RoomDefinition, RoomMode, Room, RewindView, Ctx, MatterModule, MatterEngine, MatterBody, RapierModule, RapierWorld, RapierRigidBody, Rapier2dModule, Rapier2dWorld, Rapier2dRigidBody, ResolvedRoomConfig, LeaveReason } from '@irtio/server';
-import { i as RoomHost, k as RoomStats, L as LogLevel, R as RoomCoreApi, e as RoomCoreOptions, g as RoomEventKind, n as TimelineRecorderOptions, T as TimelineDump, j as RoomInspection, J as JoinOptions, d as JoinResult, c as HostCallResult } from './contract-CRilLVdx.js';
+import { i as RoomHost, k as RoomStats, L as LogLevel, R as RoomCoreApi, e as RoomCoreOptions, g as RoomEventKind, n as TimelineRecorderOptions, T as TimelineDump, j as RoomInspection, J as JoinOptions, d as JoinResult, c as HostCallResult } from './contract-C5aqs49-.js';
 
-/**
- * `room.random()` — mulberry32 over a u32 seed. Deterministic, tiny, and serializable: the
- * generator's whole state is one u32, so `serialize()`/`restore()` round-trip it exactly.
- */
 declare class Mulberry32 {
     /** Current internal state (u32). Survives hibernation. */
     state: number;
@@ -139,6 +135,8 @@ interface RoomInternals {
     readonly ext: AnySchema;
     readonly host: RoomHost;
     readonly roomId: string;
+    /** The resolved RNG seed: explicit option, else derived from the room id; restored on wake. */
+    readonly seed: number;
     readonly mode: RoomMode;
     /** The plain state the tracked proxies wrap (what the codec reads). */
     readonly plain: PlainState;
@@ -346,6 +344,15 @@ declare class MatterRuntime {
     private readonly restore;
     private readonly stepMs;
     private readonly sleepSynced;
+    /**
+     * The plain record object each body was built from. See `PhysicsRuntime.sourceRecords`: `add()`
+     * installs a new record object, so an id removed and re-added between two reconciles (a pooled
+     * projectile) is identifiable by identity, and is the one case where a live body has to be
+     * rebuilt so the new row's spawn pose and velocity are honoured.
+     */
+    private readonly sourceRecords;
+    /** `collection.field` pairs already warned about a channel a plane cannot hold. */
+    private readonly warnedChannels;
     constructor(core: RoomInternals, matter: MatterModule, options: MatterRuntimeOptions);
     get timestep(): number;
     runSetup(room: Room): void;
@@ -488,6 +495,19 @@ declare class PhysicsRuntime {
      * world rebuilt from schema state would wake it with a kick). Found by the drift check.
      */
     private readonly sleepSynced;
+    /**
+     * The plain record object each body was built from, by body key. `add()` always installs a
+     * **new** record object (`normalizeRecord` builds one), so an id that is removed and re-added
+     * between two reconciles — the pooled-projectile shape — is identifiable by identity alone,
+     * which is the only way to see it from here: both edits happened before this module looked.
+     * Without it the old body kept its pose and velocity and the new row's spawn values were lost.
+     *
+     * Unknown means adopt, never rebuild: a world restored from a hibernation blob has bodies with
+     * no recorded source, and rebuilding those would throw away exactly what the blob preserved.
+     */
+    private readonly sourceRecords;
+    /** `collection.field` pairs already warned about a channel value the engine would not take. */
+    private readonly warnedChannels;
     constructor(core: RoomInternals, rapier: RapierModule, options: PhysicsRuntimeOptions);
     get timestep(): number;
     /** Runs the room's `setup` — static geometry — on a world that was built rather than restored. */
@@ -496,6 +516,17 @@ declare class PhysicsRuntime {
     /** The body behind an instance, created on demand so a handler's own `add` is usable at once. */
     bodyFor(collection: string, id: string): RapierRigidBody | undefined;
     private create;
+    /**
+     * A spawn value the engine will not take, said once per field.
+     *
+     * Rapier accepts `setLinvel` on an axis the body has disabled and then keeps zero, and it
+     * accepts one on a fixed body and then ignores it — both read back as "the field was applied"
+     * and behave as if it never was. The desc says which, before the body exists, so the check is
+     * on the desc: the usual case is the 2D-in-3D recipe (`enabledTranslations(true, true, false)`)
+     * meeting a row that spawns with a `vz`. Named by field, because the field is what the author
+     * wrote and what they will grep for.
+     */
+    private warnLockedChannels;
     /**
      * D72: every tracked body, in the order `sync()` walks them (collection order, then instance
      * order). Read-only: it hands out the live bodies and nothing else, and the map stays private.
@@ -585,6 +616,16 @@ declare class Rapier2dRuntime {
     private readonly bodies;
     /** See `PhysicsRuntime.sleepSynced`: the one extra sync a body owes on the tick it sleeps. */
     private readonly sleepSynced;
+    /**
+     * See `PhysicsRuntime.sourceRecords`: the plain record object each body was built from. `add()`
+     * always installs a new record object, so an id removed and re-added between two reconciles —
+     * the pooled-projectile shape — is identifiable by identity alone, and its body is rebuilt so
+     * the new row's spawn pose and velocity are what the world gets. Unknown means adopt, never
+     * rebuild: a world restored from a hibernation blob has bodies with no recorded source.
+     */
+    private readonly sourceRecords;
+    /** `collection.field` pairs already warned about a channel value the engine would not take. */
+    private readonly warnedChannels;
     constructor(core: RoomInternals, rapier: Rapier2dModule, options: Rapier2dRuntimeOptions);
     get timestep(): number;
     /** Runs the room's `setup` — static geometry — on a world that was built rather than restored. */
@@ -593,6 +634,18 @@ declare class Rapier2dRuntime {
     /** The body behind an instance, created on demand so a handler's own `add` is usable at once. */
     bodyFor(collection: string, id: string): Rapier2dRigidBody | undefined;
     private create;
+    /**
+     * A spawn value the engine will not take, said once per field — the planar half of
+     * `PhysicsRuntime.warnLockedChannels`.
+     *
+     * Rapier accepts `setLinvel` on an axis the body has disabled and then keeps zero, and it
+     * accepts one on a fixed body and then ignores it: both read back as "the field was applied"
+     * and behave as if it never was. The desc says which, before the body exists, so the check is on
+     * the desc. In the plane there are three movable channels — `vx`, `vy` and the one rotation
+     * `wz` — and the desc carries exactly those three flags. Named by field, because the field is
+     * what the author wrote and what they will grep for.
+     */
+    private warnLockedChannels;
     /**
      * D72: every tracked body, in the order `sync()` walks them (collection order, then instance
      * order). The rapier2d third of the same read-only accessor the other two runtimes carry.
@@ -668,7 +721,7 @@ declare class RoomCore<S extends AnySchema = AnySchema> implements RoomCoreApi<S
      * it again over its next `history` ticks.
      */
     private readonly rewindState;
-    private readonly seed;
+    readonly seed: number;
     private readonly api;
     private readonly internals;
     private started;

package/dist/test/index.d.ts

@@ -1,8 +1,8 @@
-import { R as RoomCore } from '../room-YJGz6Caw.js';
-export { m as initMatter, n as initPhysics, o as initRapier2d } from '../room-YJGz6Caw.js';
+import { R as RoomCore } from '../room-C4RZJ2KO.js';
+export { m as initMatter, n as initPhysics, o as initRapier2d } from '../room-C4RZJ2KO.js';
 import { ErrorCodeName, FrameType } from '@irtio/protocol';
 import { NpcConfig, LeaveReason, Room, RoomDefinition } from '@irtio/server';
-import { i as RoomHost, L as LogLevel, R as RoomCoreApi, b as HostCall, c as HostCallResult, k as RoomStats } from '../contract-CRilLVdx.js';
+import { i as RoomHost, L as LogLevel, R as RoomCoreApi, b as HostCall, c as HostCallResult, k as RoomStats } from '../contract-C5aqs49-.js';
 import { AnySchema, PlainState, EntityCollection, State } from '@irtio/schema';
 
 /**
@@ -331,7 +331,7 @@ interface FakeClient<S extends AnySchema = AnySchema> {
  */
 
 interface HarnessOptions {
-    /** `room.random()` seed; default 1 (same as `RoomCore`). */
+    /** `room.random()` seed; defaults to a hash of `roomId`, exactly as `RoomCore` does. */
     readonly seed?: number;
     /** Base URL for `room.link`. */
     readonly publicUrl?: string;

package/dist/test/index.js

@@ -5,7 +5,7 @@ import {
   initPhysics,
   initRapier2d,
   visibleNames
-} from "../chunk-ZCD2TBXB.js";
+} from "../chunk-ADZZEVJU.js";
 
 // src/test/clock.ts
 var FakeClock = class {
@@ -677,7 +677,7 @@ var Harness = class {
     this.host.onSend = (clientId, frame) => this.deliver(clientId, frame);
     this.coreRef = new RoomCore(definition, this.host, {
       roomId: options.roomId ?? "test-room",
-      seed: options.seed ?? 1,
+      ...options.seed !== void 0 ? { seed: options.seed } : {},
       ...options.publicUrl !== void 0 ? { publicUrl: options.publicUrl } : {},
       ...options.restoreFrom !== void 0 ? { restoreFrom: options.restoreFrom } : {}
     });
@@ -963,7 +963,7 @@ var Harness = class {
     this.nextClientId = 1;
     this.coreRef = RoomCore.restore(this.definition, bytes, this.host, {
       roomId: this.options.roomId ?? "test-room",
-      seed: this.options.seed ?? 1,
+      ...this.options.seed !== void 0 ? { seed: this.options.seed } : {},
       ...this.options.publicUrl !== void 0 ? { publicUrl: this.options.publicUrl } : {}
     });
     this.coreRef.start();

package/dist/worker/index.d.ts

@@ -1,4 +1,4 @@
-import { L as LogLevel, T as TimelineDump, k as RoomStats, b as HostCall, c as HostCallResult, R as RoomCoreApi, i as RoomHost } from '../contract-CRilLVdx.js';
+import { L as LogLevel, T as TimelineDump, k as RoomStats, b as HostCall, c as HostCallResult, R as RoomCoreApi, i as RoomHost } from '../contract-C5aqs49-.js';
 import { ErrorCodeName, ProfileSnapshot } from '@irtio/protocol';
 import { NpcConfig, LeaveReason } from '@irtio/server';
 import '@irtio/schema';

package/dist/worker/index.js

@@ -1,6 +1,6 @@
 import {
   migrateSnapshot
-} from "../chunk-DBGMG2S3.js";
+} from "../chunk-SBDZ45JG.js";
 import {
   RoomCore,
   RoomFullError,
@@ -9,7 +9,7 @@ import {
   initRapier2d,
   onFirstRapierStep,
   rapierHasStepped
-} from "../chunk-ZCD2TBXB.js";
+} from "../chunk-ADZZEVJU.js";
 
 // src/worker/index.ts
 import { getHeapStatistics } from "v8";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@irtio/runtime",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "irtio room runtime: RoomCore, worker_threads host, in-process test harness",
   "license": "MIT",
   "publishConfig": {
@@ -31,9 +31,9 @@
     "@dimforge/rapier2d-compat": "0.20.0",
     "@dimforge/rapier3d-compat": "0.20.0",
     "matter-js": "0.20.0",
-    "@irtio/protocol": "0.8.0",
-    "@irtio/schema": "0.8.0",
-    "@irtio/server": "0.8.0"
+    "@irtio/schema": "0.9.0",
+    "@irtio/server": "0.9.0",
+    "@irtio/protocol": "0.9.0"
   },
   "devDependencies": {
     "@types/matter-js": "0.20.2"