@irtio/client 0.2.0 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@irtio/client",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "irtio client SDK: joinRoom, owned-write batching, corrections, typed RPCs, presence, reconnection",
   "license": "MIT",
   "publishConfig": {
@@ -19,8 +19,8 @@
     "dist"
   ],
   "dependencies": {
-    "@irtio/protocol": "0.2.0",
-    "@irtio/schema": "0.2.0"
+    "@irtio/schema": "0.3.0",
+    "@irtio/protocol": "0.3.0"
   },
   "peerDependencies": {
     "@dimforge/rapier3d-compat": ">=0.20.0"

package/dist/physics-BBFSQEYL.js

@@ -1,583 +0,0 @@
-import {
-  MAX_PREDICTED_BODIES,
-  PREDICTION_EPSILON,
-  RESIM_DEPTH
-} from "./chunk-AJHN3YF6.js";
-
-// src/physics.ts
-var MAX_FREE_STEPS_PER_FRAME = 5;
-function key(collection, id) {
-  return `${collection}\0${id}`;
-}
-var engine;
-var loading;
-async function loadEngine() {
-  if (engine) return engine;
-  loading ??= (async () => {
-    const mod = await import("@dimforge/rapier3d-compat");
-    const ns = mod.default ?? mod;
-    await ns.init();
-    engine = ns;
-    return ns;
-  })();
-  return loading;
-}
-var PhysicsPredictor = class _PhysicsPredictor {
-  constructor(ext, store, options, meOf, rttOf, tickIntervalOf, log = (m) => console.warn(m)) {
-    this.store = store;
-    this.options = options;
-    this.meOf = meOf;
-    this.rttOf = rttOf;
-    this.tickIntervalOf = tickIntervalOf;
-    this.log = log;
-    this.collections = ext.collections.filter(
-      (c) => c.kind === "entity" && c.physics !== void 0
-    );
-  }
-  store;
-  options;
-  meOf;
-  rttOf;
-  tickIntervalOf;
-  log;
-  stats = {
-    freeSteps: 0,
-    resimSteps: 0,
-    rebases: 0,
-    snaps: 0,
-    suppressed: 0,
-    overCap: 0,
-    lastResimMicros: 0
-  };
-  rapier;
-  world;
-  bodies = /* @__PURE__ */ new Map();
-  /** Physics-backed entity collections, in schema order. */
-  collections;
-  warned = /* @__PURE__ */ new Set();
-  /** Highest over-cap count warned about per collection, so growth re-warns and noise does not. */
-  overCapHigh = /* @__PURE__ */ new Map();
-  /** Authority arrived since the last frame: rebase before free-running. */
-  authorityDirty = false;
-  accumulatorMs = 0;
-  lastNow;
-  lastFrameNow;
-  failed = false;
-  /**
-   * Per owned body: the server tick its authoritative record is *from* (the tick of the last
-   * `CORRECT` that touched it), and the per-tick prediction history — after every local step,
-   * the body's channels are recorded under the tick that step predicted. A correction for tick T
-   * is then judged against the client's prediction **for tick T**, not against the current head
-   * of the simulation (which legitimately leads authority by the whole latency — comparing
-   * against it would report the lead as misprediction).
-   */
-  authorityTicks = /* @__PURE__ */ new Map();
-  predictedTicks = /* @__PURE__ */ new Map();
-  history = /* @__PURE__ */ new Map();
-  /** History kept per body — comfortably past the resim depth. */
-  static HISTORY_TICKS = 32;
-  get epsilon() {
-    return this.options.epsilon ?? PREDICTION_EPSILON;
-  }
-  /** `true` once the engine is loaded and the local world exists. */
-  get ready() {
-    return this.world !== void 0;
-  }
-  /**
-   * Kicks off the async engine load. Idempotent. Until it resolves, every read falls back to
-   * interpolation/authority — joining is never blocked on 2.9 MB of WASM.
-   */
-  start() {
-    if (this.world || this.failed) return Promise.resolve();
-    return loadEngine().then(
-      (rapier) => {
-        this.rapier = rapier;
-        const world = new rapier.World({ ...this.options.gravity });
-        const tickMs = this.tickIntervalOf();
-        world.timestep = this.options.timestep ?? (tickMs > 0 ? tickMs / 1e3 : 1 / 30);
-        if (this.options.setup) this.options.setup(world, rapier);
-        this.world = world;
-        this.authorityDirty = true;
-      },
-      (err) => {
-        this.failed = true;
-        this.log(
-          `irtio: physics prediction disabled \u2014 @dimforge/rapier3d-compat failed to load: ${err instanceof Error ? err.message : String(err)}`
-        );
-      }
-    );
-  }
-  free() {
-    this.bodies.clear();
-    this.world?.free();
-    this.world = void 0;
-  }
-  /** A resync (`WELCOME`) replaced the authority wholesale: rebase everything, drop banked time. */
-  reset() {
-    this.authorityDirty = true;
-    this.accumulatorMs = 0;
-    this.lastNow = void 0;
-  }
-  /** Authoritative body state arrived (`DELTA` on a non-owned body, `CORRECT` on an owned one). */
-  noteAuthority() {
-    this.authorityDirty = true;
-  }
-  /** The session tells us which server tick one body's authoritative record is from. */
-  noteAuthorityTick(collection, id, tick) {
-    this.authorityTicks.set(key(collection, id), tick);
-  }
-  /** Does the local world currently simulate `collection[id]`? */
-  has(collection, id) {
-    return this.bodies.has(key(collection, id));
-  }
-  /**
-   * Is a correction's every value within the suppression tolerance of the prediction it judges?
-   * Position (and rotation) channels compare against `epsilon` directly; velocity and angular
-   * channels against `epsilon / timestep`, because a velocity disagreement matters by what it
-   * moves in one tick.
-   */
-  withinEpsilon(desc, fields, patch, predicted) {
-    const physics = desc.physics;
-    if (!physics || fields.length === 0) return false;
-    const eps = this.epsilon;
-    const dt = this.world?.timestep ?? 1 / 30;
-    const channelOf = new Map(physics.channels.map(([c, f]) => [f, c]));
-    return fields.every((f) => {
-      const a = predicted[f];
-      const b = patch[f];
-      if (typeof a !== "number" || typeof b !== "number") return false;
-      const channel = channelOf.get(f);
-      const velocity = channel?.startsWith("v") === true || channel?.startsWith("w") === true;
-      const tolerance = velocity ? eps / dt : eps;
-      return Math.abs(a - b) <= tolerance;
-    });
-  }
-  /** Is `collection` one this client would predict at all (owned always; non-owned per D21)? */
-  predictsCollection(name) {
-    return this.collections.some((c) => c.name === name);
-  }
-  /**
-   * Advances the local world to `now`. Driven by render reads (one pass per timestamp), so a
-   * draw loop — or a bot's render sampling — is the clock; there is no timer.
-   */
-  frame(now) {
-    if (!this.world || now === this.lastFrameNow && !this.authorityDirty) return;
-    this.lastFrameNow = now;
-    this.reconcileBodies();
-    if (this.authorityDirty) {
-      this.authorityDirty = false;
-      this.rebase();
-      this.accumulatorMs = 0;
-      this.lastNow = now;
-      return;
-    }
-    this.freeRun(now);
-  }
-  /**
-   * The predicted record for `collection[id]`: the authoritative record (which already carries
-   * local intent writes — `track()` writes through to plain state) with the body-mapped channels
-   * replaced by the local world's values, `Math.fround`ed for f32 fields so what the draw loop
-   * reads is what the wire would carry.
-   */
-  read(desc, id, base) {
-    const entry = this.bodies.get(key(desc.name, id));
-    const physics = desc.physics;
-    if (!entry || !physics) return base;
-    const out = { ...base };
-    const t = entry.body.translation();
-    const r = entry.body.rotation();
-    const v = entry.body.linvel();
-    const w = entry.body.angvel();
-    for (const [channel, field] of physics.channels) {
-      const value = channelValue(channel, t, r, v, w);
-      out[field] = this.isF32(desc, field) ? Math.fround(value) : value;
-    }
-    return out;
-  }
-  /**
-   * The local world's current values for `fields` of one body — what a correction is judged
-   * against (`previous` on the `correct` event, and the epsilon-suppression comparison).
-   */
-  predictedValues(desc, id, fields, atTick) {
-    const entry = this.bodies.get(key(desc.name, id));
-    const physics = desc.physics;
-    if (!entry || !physics) return void 0;
-    const remembered = atTick !== void 0 ? this.history.get(key(desc.name, id))?.get(atTick) : void 0;
-    const t = entry.body.translation();
-    const r = entry.body.rotation();
-    const v = entry.body.linvel();
-    const w = entry.body.angvel();
-    const out = {};
-    for (const [channel, field] of physics.channels) {
-      if (!fields.includes(field)) continue;
-      const value = remembered !== void 0 && typeof remembered[field] === "number" ? remembered[field] : channelValue(channel, t, r, v, w);
-      out[field] = this.isF32(desc, field) ? Math.fround(value) : value;
-    }
-    return out;
-  }
-  // -------------------------------------------------------------------------
-  // Membership
-  // -------------------------------------------------------------------------
-  /**
-   * Mirrors the local world's bodies onto the instances this client predicts: every physics
-   * instance it owns, plus non-owned instances of `predicted: true` collections up to the cap
-   * (collection order, then insertion order — the same stated iteration guarantee the server
-   * follows, so which bodies fall over the cap is deterministic).
-   *
-   * Everything else — non-`predicted` collections, and `predicted` instances over the cap — gets
-   * no body and no collider here. Those instances still render (the interpolation path reads
-   * authoritative state directly), but nothing in the local world can touch them.
-   */
-  reconcileBodies() {
-    const world = this.world;
-    const rapier = this.rapier;
-    if (!world || !rapier) return;
-    const me = this.meOf();
-    const live = /* @__PURE__ */ new Set();
-    let nonOwned = 0;
-    let overCap = 0;
-    const overCapBy = /* @__PURE__ */ new Map();
-    const cap = this.options.maxPredictedBodies ?? MAX_PREDICTED_BODIES;
-    for (const desc of this.collections) {
-      const coll = this.store.plainCollection(desc.name);
-      for (const id of coll.ids()) {
-        const owned = coll.ownerOf(id) === me && me !== "";
-        if (!owned) {
-          if (!desc.predicted) continue;
-          if (nonOwned >= cap) {
-            overCap++;
-            overCapBy.set(desc.name, (overCapBy.get(desc.name) ?? 0) + 1);
-            continue;
-          }
-          nonOwned++;
-        }
-        const k = key(desc.name, id);
-        live.add(k);
-        if (this.bodies.has(k)) continue;
-        const record = coll.get(id);
-        if (record) this.createBody(desc, id, record, owned);
-      }
-    }
-    this.stats.overCap = overCap;
-    this.warnOverCap(cap, overCapBy);
-    for (const [k, entry] of [...this.bodies]) {
-      if (live.has(k)) continue;
-      this.bodies.delete(k);
-      this.authorityTicks.delete(k);
-      this.predictedTicks.delete(k);
-      this.history.delete(k);
-      this.world?.removeRigidBody(entry.body);
-    }
-  }
-  createBody(desc, id, record, owned) {
-    const world = this.world;
-    const rapier = this.rapier;
-    if (!world || !rapier) return;
-    const factory = this.options.bodies?.[desc.name];
-    if (!factory) {
-      this.warnOnce(
-        `factory:${desc.name}`,
-        `irtio: physics.bodies.${desc.name} is missing from joinRoom({ physics }). ${desc.name} instances render by interpolation but have no body in the local world, so predicted bodies pass through them.`
-      );
-      return;
-    }
-    const physics = desc.physics;
-    if (physics && !physics.channels.some(([c]) => c.startsWith("v"))) {
-      this.warnOnce(
-        `velocity:${desc.name}`,
-        `irtio: ${desc.name} maps no velocity channels (vx/vy/vz) \u2014 corrections can only rebase what the schema carries, and predicted bodies drift without them. Map the velocity channels on collections you predict.`
-      );
-    }
-    const spec = factory(rapier, record, id);
-    if (!spec || !spec.body) return;
-    const body = world.createRigidBody(spec.body);
-    for (const collider of spec.colliders ?? []) world.createCollider(collider, body);
-    const entry = { desc, id, body, owned };
-    this.applyRecord(entry, record);
-    this.bodies.set(key(desc.name, id), entry);
-  }
-  /**
-   * Over-cap is not a one-time tuning notice: it means those instances are missing from the local
-   * world right now, so a predicted body walks through them. Warn on every new high-water mark
-   * per collection — a game that grows past the cap mid-session hears about it, and a count that
-   * oscillates around one level does not turn the console into a log.
-   */
-  warnOverCap(cap, overCapBy) {
-    for (const [name, count] of overCapBy) {
-      if (count <= (this.overCapHigh.get(name) ?? 0)) continue;
-      this.overCapHigh.set(name, count);
-      this.log(
-        `irtio: ${count} ${name} instance(s) over the ${cap}-body prediction cap. They are ABSENT from the local world, not interpolated into it: predicted bodies pass through them until the next correction snaps them back. Raise maxPredictedBodies (the cost is a world step per lead tick, not a per-body-per-frame cost), or stop predicting what nothing collides with.`
-      );
-    }
-  }
-  warnOnce(k, message) {
-    if (this.warned.has(k)) return;
-    this.warned.add(k);
-    this.log(message);
-  }
-  // -------------------------------------------------------------------------
-  // Rebase and free-run
-  // -------------------------------------------------------------------------
-  /**
-   * The client's lead over authority, in ticks: one-way latency plus one tick of margin.
-   * Measured (dive e2e, 2026-08-27): a full-round-trip lead was tried for the tick-aligned
-   * replay and made release transitions *worse* (-1.4 to -1.8 u worst backwards step vs -0.6 at
-   * half), because the extra lead grows the standing overshoot a rest-settling body has to give
-   * back. Half the trip plus margin is where the stamp clock and the correction stream meet.
-   */
-  leadTicks() {
-    const tickMs = this.timestepMs();
-    return Math.max(1, Math.ceil(this.rttOf() / 2 / tickMs) + 1);
-  }
-  timestepMs() {
-    return (this.world?.timestep ?? 1 / 30) * 1e3;
-  }
-  /**
-   * Rebase + re-step: snap every predicted body to the authoritative record (server values —
-   * `DELTA` for non-owned bodies, `CORRECT` for owned ones; body fields are never client-
-   * written, so plain state holds exactly what the server said), then re-step the world by the
-   * client's lead, applying to each re-stepped tick the intent that was in force *at that tick*:
-   * the newest buffered unjudged write stamped at or before it, or the baseline (the newest
-   * judged write) before the first of them. Bounded by the shared resim depth: an outrun lead
-   * snaps to authority and counts (`stats.snaps`).
-   */
-  rebase() {
-    const world = this.world;
-    const rapier = this.rapier;
-    if (!world || !rapier) return;
-    this.stats.rebases++;
-    for (const entry of this.bodies.values()) {
-      const record = this.store.plainCollection(entry.desc.name).get(entry.id);
-      if (record) this.applyRecord(entry, record);
-    }
-    for (const entry of this.bodies.values()) {
-      if (!entry.owned) continue;
-      const k = key(entry.desc.name, entry.id);
-      this.predictedTicks.set(k, this.authorityTicks.get(k) ?? this.predictedTicks.get(k) ?? 0);
-    }
-    const lead = this.leadTicks();
-    if (lead > RESIM_DEPTH) {
-      this.stats.snaps++;
-      return;
-    }
-    const replays = /* @__PURE__ */ new Map();
-    for (const entry of this.bodies.values()) {
-      if (!entry.owned) continue;
-      const k = key(entry.desc.name, entry.id);
-      replays.set(k, {
-        frames: this.store.pendingWritePatches(entry.desc.name, entry.id),
-        next: 0,
-        inForce: this.store.baselineIntent(entry.desc.name, entry.id)
-      });
-    }
-    const started = performance.now();
-    for (let step = 0; step < lead; step++) {
-      this.applyIntents(rapier, world, (k) => {
-        const r = replays.get(k);
-        if (!r) return void 0;
-        const t = (this.predictedTicks.get(k) ?? 0) + 1;
-        while (r.next < r.frames.length && r.frames[r.next].tick <= t) {
-          const f = r.frames[r.next];
-          r.inForce = r.inForce ? { ...r.inForce, ...f.patch } : { ...f.patch };
-          r.next++;
-        }
-        return r.inForce;
-      });
-      world.step();
-      this.recordStep();
-      this.stats.resimSteps++;
-    }
-    this.stats.lastResimMicros = Math.round((performance.now() - started) * 1e3);
-  }
-  /**
-   * The tick a `WRITE` flushed right now should be stamped with: one past the newest predicted
-   * head across owned bodies — the first tick the new intent can affect. That puts the stamp on
-   * the same clock as `authorityTicks` and the resim window (the server's tick stream), which is
-   * what lets the rebase walk pending writes by tick instead of by array index. `undefined`
-   * until the engine runs or while nothing is owned; the session falls back to its counter.
-   */
-  stampTick() {
-    if (!this.world) return void 0;
-    let head;
-    for (const entry of this.bodies.values()) {
-      if (!entry.owned) continue;
-      const t = this.predictedTicks.get(key(entry.desc.name, entry.id));
-      if (t !== void 0 && (head === void 0 || t > head)) head = t;
-    }
-    return head === void 0 ? void 0 : head + 1;
-  }
-  /** After every step: advance each owned body's prediction clock and remember its channels. */
-  recordStep() {
-    for (const entry of this.bodies.values()) {
-      if (!entry.owned) continue;
-      const physics = entry.desc.physics;
-      if (!physics) continue;
-      const k = key(entry.desc.name, entry.id);
-      const tick = (this.predictedTicks.get(k) ?? 0) + 1;
-      this.predictedTicks.set(k, tick);
-      const t = entry.body.translation();
-      const r = entry.body.rotation();
-      const v = entry.body.linvel();
-      const w = entry.body.angvel();
-      const record = {};
-      for (const [channel, field] of physics.channels) {
-        record[field] = channelValue(channel, t, r, v, w);
-      }
-      let byTick = this.history.get(k);
-      if (!byTick) {
-        byTick = /* @__PURE__ */ new Map();
-        this.history.set(k, byTick);
-      }
-      byTick.set(tick, record);
-      byTick.delete(tick - _PhysicsPredictor.HISTORY_TICKS);
-    }
-  }
-  freeRun(now) {
-    const world = this.world;
-    const rapier = this.rapier;
-    if (!world || !rapier) return;
-    if (this.lastNow === void 0) {
-      this.lastNow = now;
-      return;
-    }
-    this.accumulatorMs += Math.max(0, now - this.lastNow);
-    this.lastNow = now;
-    const dtMs = this.timestepMs();
-    if (this.accumulatorMs > dtMs * MAX_FREE_STEPS_PER_FRAME) {
-      this.accumulatorMs = dtMs * MAX_FREE_STEPS_PER_FRAME;
-    }
-    while (this.accumulatorMs >= dtMs) {
-      this.accumulatorMs -= dtMs;
-      this.applyIntents(rapier, world, () => void 0);
-      world.step();
-      this.recordStep();
-      this.stats.freeSteps++;
-    }
-  }
-  /**
-   * Applies intents for every owned predicted body before one step: the intent in force at the
-   * tick this step predicts (during a rebase — see `rebase`'s replay walk), else the instance's
-   * current values (free-run: plain state carries the newest local intent writes, which is
-   * correct there because free-run steps are the ticks *after* every buffered write).
-   */
-  applyIntents(rapier, world, frameFor) {
-    for (const entry of this.bodies.values()) {
-      if (!entry.owned) continue;
-      const hook = this.options.intents?.[entry.desc.name];
-      if (!hook) continue;
-      const record = this.store.plainCollection(entry.desc.name).get(entry.id);
-      if (!record) continue;
-      const frame = frameFor(key(entry.desc.name, entry.id));
-      hook(entry.body, frame ? { ...record, ...frame } : record, rapier, world);
-    }
-  }
-  /** Server record → body channels (the same mapping the runtime's sync uses, inverted). */
-  applyRecord(entry, record) {
-    const physics = entry.desc.physics;
-    if (!physics) return;
-    const body = entry.body;
-    const t = { ...body.translation() };
-    const r = { ...body.rotation() };
-    const v = { ...body.linvel() };
-    const w = { ...body.angvel() };
-    let setT = false;
-    let setR = false;
-    let setV = false;
-    let setW = false;
-    for (const [channel, field] of physics.channels) {
-      const raw = record[field];
-      if (typeof raw !== "number") continue;
-      switch (channel) {
-        case "x":
-        case "y":
-        case "z":
-          t[channel] = raw;
-          setT = true;
-          break;
-        case "qx":
-          r.x = raw;
-          setR = true;
-          break;
-        case "qy":
-          r.y = raw;
-          setR = true;
-          break;
-        case "qz":
-          r.z = raw;
-          setR = true;
-          break;
-        case "qw":
-          r.w = raw;
-          setR = true;
-          break;
-        case "vx":
-          v.x = raw;
-          setV = true;
-          break;
-        case "vy":
-          v.y = raw;
-          setV = true;
-          break;
-        case "vz":
-          v.z = raw;
-          setV = true;
-          break;
-        case "wx":
-          w.x = raw;
-          setW = true;
-          break;
-        case "wy":
-          w.y = raw;
-          setW = true;
-          break;
-        case "wz":
-          w.z = raw;
-          setW = true;
-          break;
-      }
-    }
-    if (setT) body.setTranslation(t, true);
-    if (setR) body.setRotation(r, true);
-    if (setV) body.setLinvel(v, true);
-    if (setW) body.setAngvel(w, true);
-  }
-  isF32(desc, field) {
-    const idx = desc.fieldIndex.get(field);
-    if (idx === void 0) return false;
-    return desc.fields[idx]?.type.kind === "f32";
-  }
-};
-function channelValue(channel, t, r, v, w) {
-  switch (channel) {
-    case "x":
-      return t.x;
-    case "y":
-      return t.y;
-    case "z":
-      return t.z;
-    case "qx":
-      return r.x;
-    case "qy":
-      return r.y;
-    case "qz":
-      return r.z;
-    case "qw":
-      return r.w;
-    case "vx":
-      return v.x;
-    case "vy":
-      return v.y;
-    case "vz":
-      return v.z;
-    case "wx":
-      return w.x;
-    case "wy":
-      return w.y;
-    default:
-      return w.z;
-  }
-}
-export {
-  PhysicsPredictor
-};