@irtio/client 0.6.0 → 0.8.0

package/dist/{chunk-6J6PKFUS.js → chunk-5Z4DHUA3.js}

@@ -1,6 +1,7 @@
 // src/contract.ts
 var E_CONNECT_FAILED = "E_CONNECT_FAILED";
 var MAX_PREDICTED_BODIES = 64;
+var MAX_PROXY_BODIES = 256;
 var PREDICTION_EPSILON = 0.05;
 var SMOOTHING_HALF_LIFE_MS = 70;
 var SMOOTHING_SNAP_UNITS = 4;
@@ -10,8 +11,11 @@ function emptyPredictionStats() {
     resimSteps: 0,
     rebases: 0,
     snaps: 0,
+    leadClamped: 0,
     suppressed: 0,
     overCap: 0,
+    proxies: 0,
+    absent: 0,
     lastResimMicros: 0,
     smoothing: 0,
     stampGap: 0,
@@ -620,6 +624,7 @@ var ClientStore = class {
 export {
   E_CONNECT_FAILED,
   MAX_PREDICTED_BODIES,
+  MAX_PROXY_BODIES,
   PREDICTION_EPSILON,
   SMOOTHING_HALF_LIFE_MS,
   SMOOTHING_SNAP_UNITS,

package/dist/{chunk-TE66EDBB.js → chunk-XFD6WYQW.js}

@@ -1,10 +1,11 @@
 import {
   MAX_PREDICTED_BODIES,
+  MAX_PROXY_BODIES,
   PREDICTION_EPSILON,
   RESIM_DEPTH,
   SMOOTHING_HALF_LIFE_MS,
   SMOOTHING_SNAP_UNITS
-} from "./chunk-6J6PKFUS.js";
+} from "./chunk-5Z4DHUA3.js";
 
 // src/predictor.ts
 var MAX_FREE_STEPS_PER_FRAME = 5;
@@ -132,8 +133,11 @@ var Predictor = class _Predictor {
     resimSteps: 0,
     rebases: 0,
     snaps: 0,
+    leadClamped: 0,
     suppressed: 0,
     overCap: 0,
+    proxies: 0,
+    absent: 0,
     lastResimMicros: 0,
     smoothing: 0,
     stampGap: 0,
@@ -146,11 +150,19 @@ var Predictor = class _Predictor {
   /** Seconds per step, fixed for the life of the world. */
   timestepSeconds;
   bodies = /* @__PURE__ */ new Map();
+  /** D71: kinematic proxies, keyed like `bodies`. The two maps are disjoint by construction. */
+  proxies = /* @__PURE__ */ new Map();
   /** Physics-backed entity collections, in schema order. D50: not `readonly`, see `swapSchema`. */
   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();
+  /** The same, for the proxy cap: `absent` is the count a game has to act on (D71-d). */
+  absentHigh = /* @__PURE__ */ new Map();
+  /** D71: where a proxy goes. Wired by the session; see {@link DrawnReader}. */
+  drawnReader;
+  /** `drawnReader`'s output buffer, reused: it is called once per proxy per frame. */
+  drawnChannels = {};
   /** Authority arrived since the last frame: rebase before free-running. */
   authorityDirty = false;
   accumulatorMs = 0;
@@ -227,8 +239,17 @@ var Predictor = class _Predictor {
     );
     for (const entry of this.bodies.values()) this.adapter.removeBody(entry.body);
     this.bodies.clear();
+    for (const entry of this.proxies.values()) this.adapter.removeBody(entry.body);
+    this.proxies.clear();
     this.reset();
   }
+  /**
+   * D71: tell the predictor where its proxies go. The session calls this once, with a reader over
+   * the D20 interpolation buffer; without it a proxy holds the pose it was built at.
+   */
+  setDrawnReader(reader) {
+    this.drawnReader = reader;
+  }
   get epsilon() {
     return this.tuning.epsilon ?? PREDICTION_EPSILON;
   }
@@ -260,6 +281,8 @@ var Predictor = class _Predictor {
   }
   free() {
     this.bodies.clear();
+    this.proxies.clear();
+    this.stats.proxies = 0;
     this.adapter.free();
     this.worldReady = false;
   }
@@ -330,10 +353,23 @@ var Predictor = class _Predictor {
     this.stats.lastStampTick = stampTick;
     this.stats.lastAppliedTick = appliedTick;
   }
-  /** Does the local world currently simulate `collection[id]`? */
+  /**
+   * Does the local world currently **simulate** `collection[id]`?
+   *
+   * Deliberately still false for a proxied instance (D71). Every caller of this asks it to decide
+   * whether the local world is the better answer than authority — the render read path, the
+   * correction classifier, `room.prediction.predicts` — and for a proxy it is not: a proxy is
+   * authority, one interpolation delay old, put into the world so that other bodies can touch it.
+   * Reading it back would be a round trip through the physics engine to learn what the render
+   * buffer already said. {@link proxied} is the question about proxies.
+   */
   has(collection, id) {
     return this.bodies.has(key(collection, id));
   }
+  /** D71: does `collection[id]` have a kinematic proxy in the local world right now? */
+  hasProxy(collection, id) {
+    return this.proxies.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
@@ -630,52 +666,168 @@ var Predictor = class _Predictor {
   // 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).
+   * Mirrors the local world onto the instances this client can see: a **simulated** body for every
+   * physics instance it owns plus non-owned instances of `predicted: true` collections up to
+   * `maxPredictedBodies`, and a **kinematic proxy** (D71) for everything else that has a body
+   * factory and has not opted out with `proxy: false`, up to `maxProxyBodies`.
    *
-   * 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.
+   * Slot order is collection order then insertion order — the same iteration guarantee the server
+   * states — so which instances fall over either cap is deterministic. There is no relevance
+   * policy and no distance ordering: the ninth crate spawned is still the ninth crate, it is just
+   * now solid rather than missing.
+   *
+   * Three transitions happen here, and each is a removal before a creation so the world never holds
+   * two colliders for one id:
+   *
+   * - **Promotion.** A proxied instance of a predicted collection finds a free slot (a predicted
+   *   body was removed, or the cap was raised). `createBody` applies the authority record, velocity
+   *   channels included, so the body carries on rather than starting from rest.
+   * - **Demotion.** A simulated instance loses its slot to an earlier-collection newcomer. That is
+   *   what this loop already did before proxies — it stopped marking the body live and the sweep
+   *   below removed it — and now it becomes a proxy at the drawn pose in the same frame. It costs
+   *   one visible pose step: the body was a lead ahead of authority and the proxy is an
+   *   interpolation delay behind it.
+   * - **Removal.** An instance the server removed, or one that left this client's area of interest
+   *   (D23), loses whichever of the two it had, the same frame.
+   *
+   * What is left over — over the proxy cap, `proxy: false`, or no factory — has no collider in the
+   * local world at all, is counted in `stats.absent`, and is the only case a predicted body still
+   * falls through.
    */
   reconcileBodies() {
     if (!this.worldReady) return;
     const me = this.meOf();
     const live = /* @__PURE__ */ new Set();
+    const liveProxies = /* @__PURE__ */ new Set();
     let nonOwned = 0;
     let overCap = 0;
+    let absent = 0;
     const overCapBy = /* @__PURE__ */ new Map();
+    const cappedBy = /* @__PURE__ */ new Map();
     const cap = this.tuning.maxPredictedBodies ?? MAX_PREDICTED_BODIES;
+    const proxyCap = this.tuning.maxProxyBodies ?? MAX_PROXY_BODIES;
     for (const desc of this.collections) {
       const coll = this.store.plainCollection(desc.name);
       for (const id of coll.ids()) {
+        const k = key(desc.name, id);
         const owned = coll.ownerOf(id) === me && me !== "";
-        if (!owned) {
-          if (!desc.predicted) continue;
-          if (nonOwned >= cap) {
+        let simulate = owned;
+        if (!owned && desc.predicted) {
+          if (nonOwned < cap) {
+            simulate = true;
+            nonOwned++;
+          } else {
             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;
+        if (simulate) {
+          live.add(k);
+          if (this.bodies.has(k)) continue;
+          this.removeProxy(k);
+          const record2 = coll.get(id);
+          if (record2) this.createBody(desc, id, record2, owned);
+          continue;
+        }
+        if (!desc.proxy || !this.adapter.hasFactory(desc.name)) {
+          absent++;
+          continue;
+        }
+        if (liveProxies.size >= proxyCap) {
+          absent++;
+          cappedBy.set(desc.name, (cappedBy.get(desc.name) ?? 0) + 1);
+          continue;
+        }
+        liveProxies.add(k);
+        if (this.proxies.has(k)) continue;
+        this.removePredicted(k);
         const record = coll.get(id);
-        if (record) this.createBody(desc, id, record, owned);
+        if (record) this.createProxy(desc, id, record);
       }
     }
     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.adapter.removeBody(entry.body);
+    this.stats.absent = absent;
+    this.warnCaps(cap, proxyCap, overCapBy, cappedBy);
+    for (const k of [...this.bodies.keys()]) {
+      if (!live.has(k)) this.removePredicted(k);
+    }
+    for (const k of [...this.proxies.keys()]) {
+      if (!liveProxies.has(k)) this.removeProxy(k);
+    }
+    this.stats.proxies = this.proxies.size;
+    this.refreshProxyTargets();
+  }
+  /** Drops one simulated body and everything the loop keeps per body. Safe on a missing key. */
+  removePredicted(k) {
+    const entry = this.bodies.get(k);
+    if (!entry) return;
+    this.bodies.delete(k);
+    this.authorityTicks.delete(k);
+    this.predictedTicks.delete(k);
+    this.history.delete(k);
+    this.adapter.removeBody(entry.body);
+  }
+  /** Drops one proxy. Safe on a missing key. */
+  removeProxy(k) {
+    const entry = this.proxies.get(k);
+    if (!entry) return;
+    this.proxies.delete(k);
+    this.adapter.removeBody(entry.body);
+  }
+  /**
+   * D71: builds one kinematic proxy through the **same factory call** the simulated path uses, so
+   * the collider is the server's collider by construction rather than by a second description of
+   * it, then hands it to the adapter to be made kinematic.
+   *
+   * The authority record is applied first — a proxy appears where the server last said it was, not
+   * at the factory's origin — and the drawn pose takes over on the next `refreshProxyTargets`.
+   */
+  createProxy(desc, id, record) {
+    if (!this.worldReady) return;
+    const body = this.adapter.createBody(
+      desc,
+      id,
+      record,
+      (k, message) => this.warnOnce(k, message)
+    );
+    if (!body) return;
+    const physics = desc.physics;
+    if (physics) this.adapter.applyRecord(body, physics.channels, record);
+    this.adapter.makeKinematic(body);
+    const entry = { desc, id, body, target: emptyPose(), targeted: false };
+    this.adapter.readPose(body, entry.target);
+    this.proxies.set(key(desc.name, id), entry);
+  }
+  /**
+   * Reads every proxy's drawn pose once per frame, and only once.
+   *
+   * Once, because a rebase re-steps the world up to `MAX_LEAD` times against a render clock that
+   * has not moved: asking again per step would return the same answer at a real cost. And once
+   * *because* of D71's rule — a proxy holds one pose for every re-step of a rebase. It cannot run
+   * ahead of the newest delta because the reader never extrapolates, and it cannot run ahead of the
+   * frame because it is only ever asked here.
+   *
+   * A proxy with nothing drawn (a delta gap, an entity not yet at the render clock) keeps the pose
+   * it had. That is the hold, and it is the difference between a crate that stays solid through a
+   * stall and a crate that slides off across the level.
+   */
+  refreshProxyTargets() {
+    const reader = this.drawnReader;
+    if (!reader || this.proxies.size === 0) return;
+    const channels = this.drawnChannels;
+    for (const entry of this.proxies.values()) {
+      const physics = entry.desc.physics;
+      if (!physics) continue;
+      for (const [, field] of physics.channels) channels[field] = Number.NaN;
+      if (!reader(entry.desc, entry.id, channels)) continue;
+      poseFromRecord(physics.channels, channels, entry.target);
+      entry.targeted = true;
+    }
+  }
+  /** Writes every proxy to its target pose. Runs immediately before each `adapter.step()`. */
+  driveProxies() {
+    for (const entry of this.proxies.values()) {
+      if (entry.targeted) this.adapter.moveKinematic(entry.body, entry.target);
     }
   }
   createBody(desc, id, record, owned) {
@@ -726,17 +878,29 @@ var Predictor = class _Predictor {
     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.
+   * The two cap notices, both on a new high-water mark per collection: a game that grows past a cap
+   * mid-session hears about it, and a count that oscillates around one level does not turn the
+   * console into a log.
+   *
+   * They say different things now, and only the second is an emergency (D71). Over the *prediction*
+   * cap an instance is still solid — it has a proxy — it just is not simulated, so a shove does
+   * nothing locally until the server agrees. Over the *proxy* cap it is genuinely not there, which
+   * is the failure `bugs.md` #3 was about, and the message names both numbers so it is obvious
+   * which one to raise.
    */
-  warnOverCap(cap, overCapBy) {
+  warnCaps(cap, proxyCap, overCapBy, cappedBy) {
     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.`
+        `irtio: ${count} ${name} instance(s) over the ${cap}-body prediction cap. They keep a kinematic proxy in the local world, so predicted bodies still collide with them, but they are not simulated ahead: pushing one does nothing locally until the server says so. Raise maxPredictedBodies for anything a player shoves (the cost is a world step per lead tick, not a per-body-per-frame cost); leave it for anything a player only stands on or is blocked by.`
+      );
+    }
+    for (const [name, count] of cappedBy) {
+      if (count <= (this.absentHigh.get(name) ?? 0)) continue;
+      this.absentHigh.set(name, count);
+      this.log(
+        `irtio: ${count} ${name} instance(s) over the ${proxyCap}-body proxy cap (maxProxyBodies ${proxyCap}, maxPredictedBodies ${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 maxProxyBodies, or set proxy: false on the collections nothing collides with so the budget goes to the ones that matter.`
       );
     }
   }
@@ -788,8 +952,8 @@ var Predictor = class _Predictor {
    * 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 `MAX_LEAD`: an outrun lead snaps to
-   * authority and counts (`stats.snaps`).
+   * judged write) before the first of them. Bounded by `MAX_LEAD`: an outrun lead re-steps that
+   * many and counts (`stats.leadClamped`, bugs.md #71).
    */
   rebase() {
     if (!this.worldReady) return;
@@ -803,7 +967,9 @@ var Predictor = class _Predictor {
       const k = key(entry.desc.name, entry.id);
       this.predictedTicks.set(k, Math.max(this.authorityTick, this.authorityTicks.get(k) ?? 0));
     }
-    const lead = this.leadTicks();
+    const wanted = this.leadTicks();
+    const lead = Math.min(wanted, MAX_LEAD);
+    if (wanted > MAX_LEAD) this.stats.leadClamped++;
     if (this.lastLead !== void 0 && lead !== this.lastLead && this.gapMeasured) {
       const delta = lead - this.lastLead;
       this.stampGap = Math.min(RESIM_DEPTH, Math.max(0, this.stampGap + delta));
@@ -812,10 +978,6 @@ var Predictor = class _Predictor {
     }
     this.lastLead = lead;
     this.headTick = this.authorityTick;
-    if (lead > MAX_LEAD) {
-      this.stats.snaps++;
-      return;
-    }
     const replays = /* @__PURE__ */ new Map();
     for (const entry of this.bodies.values()) {
       if (!entry.owned) continue;
@@ -840,6 +1002,7 @@ var Predictor = class _Predictor {
         }
         return r.inForce;
       });
+      this.driveProxies();
       this.adapter.step();
       this.recordStep();
       this.headTick++;
@@ -906,6 +1069,7 @@ var Predictor = class _Predictor {
     while (this.accumulatorMs >= dtMs) {
       this.accumulatorMs -= dtMs;
       this.applyIntents(() => void 0);
+      this.driveProxies();
       this.adapter.step();
       this.recordStep();
       this.headTick++;
@@ -925,6 +1089,11 @@ var Predictor = class _Predictor {
    * local body of a collection, owned or not, run after the whole intent pass rather than
    * interleaved with it. It is what gives a non-owned predicted body its gravity on an engine
    * whose world has none of its own.
+   *
+   * Both passes walk `this.bodies`, which is why neither ever reaches a proxy (D71): a proxy is not
+   * simulated, so an intent hook or a per-step gravity force on it would be a force on a body that
+   * cannot move, applied to a pose that is going to be overwritten before the next step anyway. The
+   * isolation is structural rather than a filter, which is the version that cannot rot.
    */
   applyIntents(frameFor) {
     for (const entry of this.bodies.values()) {
@@ -958,6 +1127,49 @@ var Predictor = class _Predictor {
     return desc.fields[idx]?.type.kind === "f32";
   }
 };
+function poseFromRecord(channels, record, into) {
+  for (const [channel, field] of channels) {
+    const raw = record[field];
+    if (typeof raw !== "number" || !Number.isFinite(raw)) continue;
+    switch (channel) {
+      case "x":
+      case "y":
+      case "z":
+        into.t[channel] = raw;
+        break;
+      case "qx":
+        into.r.x = raw;
+        break;
+      case "qy":
+        into.r.y = raw;
+        break;
+      case "qz":
+        into.r.z = raw;
+        break;
+      case "qw":
+        into.r.w = raw;
+        break;
+      case "vx":
+        into.v.x = raw;
+        break;
+      case "vy":
+        into.v.y = raw;
+        break;
+      case "vz":
+        into.v.z = raw;
+        break;
+      case "wx":
+        into.w.x = raw;
+        break;
+      case "wy":
+        into.w.y = raw;
+        break;
+      case "wz":
+        into.w.z = raw;
+        break;
+    }
+  }
+}
 function channelValue(channel, t, r, v, w) {
   switch (channel) {
     case "x":