@irtio/client 0.2.0 → 0.4.0

package/dist/physics-H2VDQLAU.js

@@ -0,0 +1,1059 @@
+import {
+  MAX_PREDICTED_BODIES,
+  PREDICTION_EPSILON,
+  RESIM_DEPTH,
+  SMOOTHING_HALF_LIFE_MS,
+  SMOOTHING_SNAP_UNITS
+} from "./chunk-7UTJ7RSF.js";
+
+// src/physics.ts
+var MAX_FREE_STEPS_PER_FRAME = 5;
+var FREE_RUN_GRACE = 0.5;
+var POSE_RING = 4;
+var LAG_TARGET_MIN = 0.7;
+var LAG_TARGET_MAX = 1.4;
+var CLOCK_TRIM = 0.12;
+var GAP_ALPHA = 0.3;
+function emptyPose() {
+  return {
+    t: { x: 0, y: 0, z: 0 },
+    r: { x: 0, y: 0, z: 0, w: 1 },
+    v: { x: 0, y: 0, z: 0 },
+    w: { x: 0, y: 0, z: 0 }
+  };
+}
+function readPose(body, into) {
+  const t = body.translation();
+  const r = body.rotation();
+  const v = body.linvel();
+  const w = body.angvel();
+  into.t.x = t.x;
+  into.t.y = t.y;
+  into.t.z = t.z;
+  into.r.x = r.x;
+  into.r.y = r.y;
+  into.r.z = r.z;
+  into.r.w = r.w;
+  into.v.x = v.x;
+  into.v.y = v.y;
+  into.v.z = v.z;
+  into.w.x = w.x;
+  into.w.y = w.y;
+  into.w.z = w.z;
+}
+function copyPose(from, into) {
+  into.t.x = from.t.x;
+  into.t.y = from.t.y;
+  into.t.z = from.t.z;
+  into.r.x = from.r.x;
+  into.r.y = from.r.y;
+  into.r.z = from.r.z;
+  into.r.w = from.r.w;
+  into.v.x = from.v.x;
+  into.v.y = from.v.y;
+  into.v.z = from.v.z;
+  into.w.x = from.w.x;
+  into.w.y = from.w.y;
+  into.w.z = from.w.z;
+}
+function quatMul(a, b, out) {
+  out.x = a.w * b.x + a.x * b.w + a.y * b.z - a.z * b.y;
+  out.y = a.w * b.y - a.x * b.z + a.y * b.w + a.z * b.x;
+  out.z = a.w * b.z + a.x * b.y - a.y * b.x + a.z * b.w;
+  out.w = a.w * b.w - a.x * b.x - a.y * b.y - a.z * b.z;
+}
+function decayQuat(q, k) {
+  const s = 1 - k;
+  const sign = q.w < 0 ? -1 : 1;
+  let x = q.x * s * sign;
+  let y = q.y * s * sign;
+  let z = q.z * s * sign;
+  let w = q.w * s * sign + k;
+  const len = Math.hypot(x, y, z, w);
+  if (len > 1e-9) {
+    x /= len;
+    y /= len;
+    z /= len;
+    w /= len;
+  } else {
+    x = 0;
+    y = 0;
+    z = 0;
+    w = 1;
+  }
+  q.x = x;
+  q.y = y;
+  q.z = z;
+  q.w = w;
+}
+function lerpPose(a, b, alpha, out) {
+  const k = 1 - alpha;
+  out.t.x = a.t.x * k + b.t.x * alpha;
+  out.t.y = a.t.y * k + b.t.y * alpha;
+  out.t.z = a.t.z * k + b.t.z * alpha;
+  out.v.x = a.v.x * k + b.v.x * alpha;
+  out.v.y = a.v.y * k + b.v.y * alpha;
+  out.v.z = a.v.z * k + b.v.z * alpha;
+  out.w.x = a.w.x * k + b.w.x * alpha;
+  out.w.y = a.w.y * k + b.w.y * alpha;
+  out.w.z = a.w.z * k + b.w.z * alpha;
+  const dot = a.r.x * b.r.x + a.r.y * b.r.y + a.r.z * b.r.z + a.r.w * b.r.w;
+  const s = dot < 0 ? -alpha : alpha;
+  let x = a.r.x * k + b.r.x * s;
+  let y = a.r.y * k + b.r.y * s;
+  let z = a.r.z * k + b.r.z * s;
+  let w = a.r.w * k + b.r.w * s;
+  const len = Math.hypot(x, y, z, w);
+  if (len > 1e-9) {
+    x /= len;
+    y /= len;
+    z /= len;
+    w /= len;
+  }
+  out.r.x = x;
+  out.r.y = y;
+  out.r.z = z;
+  out.r.w = w;
+}
+function slotOf(tick) {
+  return (tick % POSE_RING + POSE_RING) % POSE_RING;
+}
+function poseAt(entry, tick) {
+  const slot = slotOf(tick);
+  return entry.poseTicks[slot] === tick ? entry.poses[slot] : void 0;
+}
+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;
+}
+function planarLockWarning(spec) {
+  const boxed = (spec.colliders ?? []).some(
+    (c) => c.shape.type === CUBOID_SHAPE || c.shape.type === ROUND_CUBOID_SHAPE
+  );
+  if (!boxed) return void 0;
+  const b = spec.body;
+  const t = [b.translationsEnabledX, b.translationsEnabledY, b.translationsEnabledZ];
+  const r = [b.rotationsEnabledX, b.rotationsEnabledY, b.rotationsEnabledZ];
+  const axes = ["x", "y", "z"];
+  for (let i = 0; i < 3; i++) {
+    if (t[i]) continue;
+    if (r[(i + 1) % 3] || r[(i + 2) % 3]) continue;
+    const free = axes[i] === "z" ? "enabledRotations(true, false, true)" : "one of the other two rotations";
+    return `locks translation on ${axes[i]} and both rotations across that plane on a box-shaped body. That removes friction entirely: the box slides at a constant speed until it hits something. Free one out-of-plane rotation \u2014 in the xy plane that is ${free}, and it costs nothing, because geometry symmetric about the plane generates no torque about it.`;
+  }
+  return void 0;
+}
+var CUBOID_SHAPE = 1;
+var ROUND_CUBOID_SHAPE = 12;
+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,
+    smoothing: 0,
+    stampGap: 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;
+  /**
+   * The local world's head, on the server's tick timeline: the authoritative tick the last
+   * rebase started from plus the lead it re-stepped, then one per free-run step.
+   */
+  headTick = 0;
+  /** The newest server tick any authority has been seen for. `headTick`'s base. */
+  authorityTick = 0;
+  /** The newest tick a pose has been stored for. `-1` until the first capture. */
+  curTick = -1;
+  /**
+   * Where the renderer is, as a fractional tick. Advanced by wall time every frame and steered
+   * to sit about a tick behind `curTick`; `read()` draws between the stored poses either side
+   * of it.
+   */
+  renderTick;
+  /** Scratch for one interpolated pose. `read()` is synchronous, so one is enough. */
+  scratch = emptyPose();
+  /** Scratch quaternions, so the per-body per-frame offset maths allocates nothing. */
+  qa = { x: 0, y: 0, z: 0, w: 1 };
+  qb = { x: 0, y: 0, z: 0, w: 1 };
+  qc = { x: 0, y: 0, z: 0, w: 1 };
+  /**
+   * 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();
+  /** Smoothed stamp-minus-applied gap; see `noteWriteApplied`. */
+  stampGap = 0;
+  gapMeasured = false;
+  /** The newest stamp already folded into `stampGap`, so a repeated echo is not re-weighted. */
+  gapSampledThrough = 0;
+  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;
+    this.renderTick = void 0;
+    this.curTick = -1;
+    for (const entry of this.bodies.values()) {
+      entry.poseTicks.fill(-1);
+      entry.preValid = false;
+      this.clearOffset(entry);
+    }
+    this.stampGap = 0;
+    this.gapMeasured = false;
+    this.gapSampledThrough = 0;
+    this.stats.stampGap = 0;
+  }
+  /**
+   * Authoritative body state arrived (`DELTA` on a non-owned body, `CORRECT` on an owned one).
+   *
+   * `tick` is the server tick it carried, and it is the base of the predictor's own head clock —
+   * which the renderer's interpolation is paced against. It has to be the *world's* clock rather
+   * than any one body's: a client with nothing of its own to own still draws a world full of
+   * predicted bodies.
+   */
+  noteAuthority(tick) {
+    this.authorityDirty = true;
+    if (tick !== void 0 && tick > this.authorityTick) this.authorityTick = tick;
+  }
+  /** 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);
+  }
+  /**
+   * A `CORRECT` reported both halves of a judged write: the stamp the client put on it and the
+   * server tick it was actually applied at (bug 1). The gap between them is the systematic error
+   * in the rebase's replay, and it is not zero even on a loopback: the stamp is the predictor's
+   * *head* (authority + lead), while the server applies on arrival, at a tick barely past the
+   * authority the client is replaying from. Replaying at the stamp therefore held the previous
+   * intent for `gap` ticks the server had already simulated under the new one — the overshoot on
+   * every key release, sized `gap x speed`.
+   *
+   * Smoothed, because it rides on delivery jitter and the measurement is one sample per judged
+   * write. Clamped into `[0, RESIM_DEPTH]`: a stamp taken before this client had any physics
+   * authority is on the session's bare write counter rather than the server's tick stream, and
+   * differencing the two clocks is meaningless — 0 is the old behaviour and the honest default.
+   */
+  noteWriteApplied(stampTick, appliedTick) {
+    if (stampTick <= 0 || appliedTick <= 0 || stampTick <= this.gapSampledThrough) return;
+    this.gapSampledThrough = stampTick;
+    const sample = Math.min(RESIM_DEPTH, Math.max(0, stampTick - appliedTick));
+    this.stampGap = this.gapMeasured ? this.stampGap + (sample - this.stampGap) * GAP_ALPHA : sample;
+    this.gapMeasured = true;
+    this.stats.stampGap = this.stampGap;
+  }
+  /** 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;
+    const elapsedMs = this.lastFrameNow === void 0 ? 0 : Math.max(0, now - this.lastFrameNow);
+    this.advanceRenderClock(now);
+    this.lastFrameNow = now;
+    this.reconcileBodies();
+    this.decayOffsets(elapsedMs);
+    this.snapshotDrawn();
+    if (this.authorityDirty) {
+      this.authorityDirty = false;
+      this.rebase();
+      this.accumulatorMs = -FREE_RUN_GRACE * this.timestepMs();
+      this.lastNow = now;
+      if (this.curTick < this.headTick) this.capturePoses();
+    } else {
+      this.freeRun(now);
+    }
+    this.holdRenderTick();
+    this.absorbJump();
+  }
+  // -------------------------------------------------------------------------
+  // The render clock
+  // -------------------------------------------------------------------------
+  /**
+   * The head moved: store every predicted body's pose under the tick it now holds.
+   *
+   * A tick can be simulated more than once — a `DELTA` and a `CORRECT` both arrive for the same
+   * tick and each rebases — so the slot is simply rewritten with the better answer. It can also
+   * move backwards, when a free-run step is discarded by the rebase behind it; `curTick` does
+   * not follow it down, because moving the newest label backwards would drag the segment the
+   * renderer is crossing backwards with it.
+   */
+  capturePoses() {
+    const tick = this.headTick;
+    const slot = slotOf(tick);
+    for (const entry of this.bodies.values()) {
+      readPose(entry.body, entry.poses[slot]);
+      entry.poseTicks[slot] = tick;
+    }
+    if (tick > this.curTick) this.curTick = tick;
+  }
+  /**
+   * Advance the render clock by one frame of wall time, steering it towards a target distance
+   * behind the head rather than clamping it there.
+   *
+   * `renderTick` and `curTick` agree on rate — one tick per tick period — but not on phase, and
+   * the phase error is delivery jitter: authority arrives when the network hands it over, not
+   * every 33 ms however steady the server is. Left alone the two would wander apart, so the
+   * clock is steered, by rate rather than by position. What the network did to a packet is not
+   * something the player's character should be seen doing.
+   */
+  advanceRenderClock(now) {
+    if (this.renderTick === void 0 || this.lastFrameNow === void 0) return;
+    const period = this.timestepMs();
+    if (period <= 0) return;
+    const lag = this.curTick - this.renderTick;
+    const rate = lag > LAG_TARGET_MAX ? 1 + CLOCK_TRIM : lag < LAG_TARGET_MIN ? 1 - CLOCK_TRIM : 1;
+    this.renderTick += Math.max(0, now - this.lastFrameNow) / period * rate;
+  }
+  /**
+   * Keep the render clock inside the span there are poses for.
+   *
+   * Both ends are real. At `curTick` there is nothing further to draw towards, so a late arrival
+   * holds the pose rather than extrapolating motion the next tick would have to take back — the
+   * same trade that sized the prediction lead (bug 1). At the far end the ring has recycled the
+   * slot and the pose is genuinely gone. Between them the clock floats, and the rate trim above
+   * is what keeps it from spending its time against either stop.
+   */
+  holdRenderTick() {
+    if (this.renderTick === void 0) {
+      this.renderTick = this.curTick;
+      return;
+    }
+    const oldest = this.curTick - (POSE_RING - 1);
+    if (this.renderTick > this.curTick) this.renderTick = this.curTick;
+    else if (this.renderTick < oldest) this.renderTick = oldest;
+  }
+  /** `smoothingHalfLifeMs`, or 0 when the game turned the smoothing off. */
+  halfLifeMs() {
+    return Math.max(0, this.options.smoothingHalfLifeMs ?? SMOOTHING_HALF_LIFE_MS);
+  }
+  /** Remember where every body is being drawn, before this frame re-simulates anything. */
+  snapshotDrawn() {
+    if (this.halfLifeMs() === 0) return;
+    const from = this.renderTick === void 0 ? void 0 : Math.floor(this.renderTick);
+    for (const entry of this.bodies.values()) {
+      entry.preValid = from !== void 0 && poseAt(entry, from) !== void 0;
+      if (entry.preValid) copyPose(this.rawPose(entry), entry.pre);
+    }
+  }
+  /**
+   * Take whatever the re-simulation moved the drawn pose by and put it in the offset instead.
+   *
+   * This is the whole of correction smoothing, and it is smoothing the *error*: the difference
+   * measured here is between two answers to the same question — where is this body at the render
+   * clock — asked either side of a rebase. Motion the simulation produced is not in it, because
+   * the render clock advanced before the snapshot. So real movement is never slowed, which is
+   * the thing a rate limiter on the drawn position cannot promise: it sees a position that moved
+   * and has no way to know whether the body ran or was corrected.
+   *
+   * It absorbs more than server disagreement. A newly flushed intent changes what the last few
+   * ticks should have been, and the replay hands that over as a jump the same way; so does the
+   * render clock being pulled back inside the poses it has. All of it is the same defect from
+   * the player's side — the character was drawn somewhere it now turns out it was not — and all
+   * of it eases away here.
+   */
+  absorbJump() {
+    const halfLife = this.halfLifeMs();
+    if (halfLife === 0) return;
+    const snap = Math.max(0, this.options.smoothingSnapUnits ?? SMOOTHING_SNAP_UNITS);
+    const eps = this.epsilon;
+    let worst = 0;
+    for (const entry of this.bodies.values()) {
+      if (!entry.preValid) continue;
+      entry.preValid = false;
+      const after = this.rawPose(entry);
+      const dx = entry.pre.t.x - after.t.x;
+      const dy = entry.pre.t.y - after.t.y;
+      const dz = entry.pre.t.z - after.t.z;
+      if (Math.abs(dx) + Math.abs(dy) + Math.abs(dz) >= eps) {
+        entry.offset.x += dx;
+        entry.offset.y += dy;
+        entry.offset.z += dz;
+      }
+      if (entry.pre.r.x !== after.r.x || entry.pre.r.y !== after.r.y || entry.pre.r.z !== after.r.z || entry.pre.r.w !== after.r.w) {
+        this.qa.x = -after.r.x;
+        this.qa.y = -after.r.y;
+        this.qa.z = -after.r.z;
+        this.qa.w = after.r.w;
+        quatMul(entry.pre.r, this.qa, this.qb);
+        quatMul(entry.rotOffset, this.qb, this.qc);
+        entry.rotOffset.x = this.qc.x;
+        entry.rotOffset.y = this.qc.y;
+        entry.rotOffset.z = this.qc.z;
+        entry.rotOffset.w = this.qc.w;
+      }
+      const size = Math.hypot(entry.offset.x, entry.offset.y, entry.offset.z);
+      if (size > snap) this.clearOffset(entry);
+      else if (size > worst) worst = size;
+    }
+    this.stats.smoothing = worst;
+  }
+  /**
+   * Ease every offset towards zero. Exponential, so the rate is proportional to the error and
+   * there is no world-scale speed to pick: a correction worth a tenth of a unit is worked off
+   * gently and one worth a whole unit is not left hanging around for a second.
+   */
+  decayOffsets(elapsedMs) {
+    const halfLife = this.halfLifeMs();
+    if (halfLife === 0 || elapsedMs <= 0) return;
+    const k = 1 - 2 ** (-elapsedMs / halfLife);
+    for (const entry of this.bodies.values()) {
+      const o = entry.offset;
+      if (o.x !== 0 || o.y !== 0 || o.z !== 0) {
+        o.x -= o.x * k;
+        o.y -= o.y * k;
+        o.z -= o.z * k;
+        if (Math.abs(o.x) < 1e-6) o.x = 0;
+        if (Math.abs(o.y) < 1e-6) o.y = 0;
+        if (Math.abs(o.z) < 1e-6) o.z = 0;
+      }
+      if (entry.rotOffset.w < 1 - 1e-9) decayQuat(entry.rotOffset, k);
+    }
+  }
+  clearOffset(entry) {
+    entry.offset.x = 0;
+    entry.offset.y = 0;
+    entry.offset.z = 0;
+    entry.rotOffset.x = 0;
+    entry.rotOffset.y = 0;
+    entry.rotOffset.z = 0;
+    entry.rotOffset.w = 1;
+  }
+  /**
+   * The pose to draw one body at: the stored poses either side of the render clock, blended.
+   * Falls back to the body's live transform when the ring cannot bracket it — before the first
+   * capture, and for a body that appeared this frame.
+   */
+  rawPose(entry) {
+    const rt = this.renderTick;
+    if (rt !== void 0) {
+      const from = Math.floor(rt);
+      const a = poseAt(entry, from);
+      const b = poseAt(entry, from + 1);
+      if (a && b) {
+        lerpPose(a, b, rt - from, this.scratch);
+        return this.scratch;
+      }
+      if (a) {
+        copyPose(a, this.scratch);
+        return this.scratch;
+      }
+    }
+    readPose(entry.body, this.scratch);
+    return this.scratch;
+  }
+  /** `rawPose` with the render-error offset applied — what the draw loop actually gets. */
+  renderPose(entry) {
+    const pose = this.rawPose(entry);
+    const o = entry.offset;
+    if (o.x !== 0 || o.y !== 0 || o.z !== 0) {
+      pose.t.x += o.x;
+      pose.t.y += o.y;
+      pose.t.z += o.z;
+    }
+    if (entry.rotOffset.w < 1 - 1e-9) {
+      quatMul(entry.rotOffset, pose.r, this.qa);
+      pose.r.x = this.qa.x;
+      pose.r.y = this.qa.y;
+      pose.r.z = this.qa.z;
+      pose.r.w = this.qa.w;
+    }
+    return pose;
+  }
+  /**
+   * 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.
+   *
+   * Drawn *between* two simulated ticks, not at the head. The local world steps at the room's
+   * tick rate, and only when authority arrives to rebase it; a display runs at two to four times
+   * that and asks on every frame. Handing back the head means the answer changes on some frames
+   * and not others, so a character running at a steady nine units a second is drawn standing
+   * still for half of them and moving at twenty for the rest. It is the player's own character
+   * answering their own key, and it reads as the game hitching.
+   *
+   * This is a *render* read. `room.state` and every correctness path — `predictedValues`, the
+   * per-tick history a correction is judged against — still see the head exactly as before.
+   */
+  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 pose = this.renderPose(entry);
+    for (const [channel, field] of physics.channels) {
+      const value = channelValue(channel, pose.t, pose.r, pose.v, pose.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 planar = planarLockWarning(spec);
+    if (planar !== void 0) {
+      this.warnOnce(`planar:${desc.name}`, `irtio: physics.bodies.${desc.name} ${planar}`);
+    }
+    const body = world.createRigidBody(spec.body);
+    for (const collider of spec.colliders ?? []) world.createCollider(collider, body);
+    const entry = {
+      desc,
+      id,
+      body,
+      owned,
+      poses: Array.from({ length: POSE_RING }, emptyPose),
+      poseTicks: new Array(POSE_RING).fill(-1),
+      offset: { x: 0, y: 0, z: 0 },
+      rotOffset: { x: 0, y: 0, z: 0, w: 1 },
+      pre: emptyPose(),
+      preValid: false
+    };
+    this.applyRecord(entry, record);
+    for (let i = 0; i < POSE_RING; i++) {
+      readPose(body, entry.poses[i]);
+    }
+    for (let back = 0; back < POSE_RING; back++) {
+      const tick = this.curTick - back;
+      if (tick < 0) break;
+      entry.poseTicks[slotOf(tick)] = tick;
+    }
+    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: the one-way transit the authority in hand has
+   * already spent in flight, rounded to the nearest tick. Nothing more.
+   *
+   * Every tick of lead beyond that transit is a tick of motion the client draws on the
+   * assumption that the input it is holding will still be held when the server gets there. On a
+   * release that assumption is wrong by construction, and the invented travel is handed back as
+   * a backwards yank — bug 1's "keeps moving after key up and then snaps back". It was
+   * `ceil(owd) + 1`, which on a fast link is two whole ticks of margin over a transit of nearly
+   * zero. Measured on the arena fixture at no injected latency (release overshoot of a 6 u/s
+   * held-input character, `physics-predict.test.ts`):
+   *
+   * | lead | drawn overshoot past the server's stop | worst backwards step |
+   * | --- | --- | --- |
+   * | `ceil(owd) + 1` (was) | 0.585 u | -0.585 u |
+   * | `max(1, round(owd))` (is) | 0.293 u | -0.292 u |
+   * | `round(owd)`, floor 0 | 0.0008 u | -0.0008 u |
+   *
+   * One tick of running is 0.3 u there: the overshoot is the lead, in ticks, and nothing else.
+   * On a link with no transit to cover, every tick of lead is a tick of guessing that the key is
+   * still held.
+   *
+   * The floor of 1 is not margin, it is the smallest lead that is still prediction. At 0 the
+   * rebase takes no steps: the local world is pinned to the authority it just received, which is
+   * already a tick old, so the client responds to its own input only when the next `CORRECT`
+   * arrives and every moving body reads as mispredicted by one tick of motion. Measured: the
+   * bot suites' correction-storm invariant fires immediately (21 corrections/s per bot against a
+   * threshold of 5 in `packages/cli/test/simulate-physics.test.ts`). One tick of speculation is
+   * the price of predicting at all; two was the bug.
+   *
+   * Erring low is also the cheap direction — a lead shorter than the transit means authority
+   * arrives slightly *ahead* of the prediction, and a correction that pulls the character the way
+   * it is already going is the one nobody can see.
+   *
+   * Measured earlier the same day (dive e2e): a *full*-round-trip lead was worse again
+   * (-1.4 to -1.8 u worst backwards step vs -0.6 at half), which is the same finding from the
+   * other end. `stats.stampGap` is the running check on all of this — it reports how far ahead
+   * of the server's application the stamps still land, and it should sit at 0.
+   */
+  leadTicks() {
+    return Math.max(1, Math.round(this.rttOf() / 2 / this.timestepMs()));
+  }
+  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();
+    this.headTick = this.authorityTick;
+    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;
+        const gap = Math.round(this.stampGap);
+        while (r.next < r.frames.length && r.frames[r.next].tick - gap <= 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.headTick++;
+      if (lead - step <= POSE_RING) this.capturePoses();
+      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);
+    }
+  }
+  /** Returns the number of steps taken, so the caller knows whether the head moved. */
+  freeRun(now) {
+    const world = this.world;
+    const rapier = this.rapier;
+    if (!world || !rapier) return 0;
+    if (this.lastNow === void 0) {
+      this.lastNow = now;
+      return 0;
+    }
+    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;
+    }
+    let steps = 0;
+    while (this.accumulatorMs >= dtMs) {
+      this.accumulatorMs -= dtMs;
+      this.applyIntents(rapier, world, () => void 0);
+      world.step();
+      this.recordStep();
+      this.headTick++;
+      this.capturePoses();
+      this.stats.freeSteps++;
+      steps++;
+    }
+    return steps;
+  }
+  /**
+   * 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
+};