@genex-ai/multiplayer 0.8.1 → 0.8.3

package/README.md

@@ -178,13 +178,13 @@ room.leave();
 
 ## Smoothing remote players
 
-Remote players are **smoothed automatically** — nothing to configure. `room.players` gives each remote player's `state` rendered slightly in the past and interpolated between snapshots, so motion glides between network updates (you send ~10–20Hz but render at 60). Interpolation runs on the **sender's clock** (each update is timestamped and mapped to your local clock), the way Valve/Unity/Mirror do it — so jitter doesn't distort the motion. The delay **self-tunes to the live snapshot rate**, so it works whether you send at 5Hz or 30Hz.
+Remote players are **smoothed automatically** — nothing to configure. `room.players` gives each remote player's `state` rendered slightly in the past and interpolated between snapshots, so motion glides between network updates (you send ~10–20Hz but render at 60). Interpolation runs on the **sender's clock** (each update is timestamped and mapped to your local clock), the way Valve/Unity/Mirror do it — so jitter doesn't distort the motion. The delay **self-tunes to both the live snapshot rate and the link's measured jitter**, so it stays smooth whether you send at 5Hz or 30Hz and whether the connection is a clean LAN or a jittery mobile link — a deeper buffer is used only where the jitter demands it.
 
 - `player.state` is the **smoothed** value (what you draw); `player.stateRaw` is the **latest raw** snapshot — use it for hit-tests / discrete logic.
 - **Your own player is never delayed** — you always render yourself live.
 - **Numbers** are interpolated; a 4-element `[x, y, z, w]` **quaternion** is **slerped** (shortest-arc); anything else snaps.
 - **Send rotation as a quaternion:** `state.q = mesh.quaternion.toArray()`, then on the remote `mesh.quaternion.fromArray(p.state.q)`. The package slerps it and **output-smooths** it so it glides through turns.
-- **Late/dropped packets keep moving:** **position** dead-reckons forward from its last velocity (capped ~0.25s, Source-style) until fresh snapshots arrive; **rotation** holds its last orientation rather than extrapolating (extrapolating a turn overshoots and snaps — Mirror/Unity interpolate rotation only). Both are output-smoothed, so the catch-up glides. This is what holds up on high-latency links.
+- **Late/dropped packets keep moving:** **position** dead-reckons forward from its last velocity (capped ~0.25s, Source-style) until fresh snapshots arrive; **rotation** also continues the turn but on a **tighter cap** (~0.15s), so a remote's heading keeps moving through a brief gap instead of freezing and then snapping when the next packet lands — the short cap plus output-smoothing bound any overshoot. This is what holds up on high-latency links.
 
 > No client-side prediction/reconciliation: in this relay you're authoritative over **yourself** (you render instantly, the server never corrects you), so there's nothing to predict — smoothing *remote* players is the piece that matters.
 

package/dist/index.js

@@ -4,10 +4,13 @@ var RELAY_ROOM_TYPE = "play";
 var QUEUE_ROOM_TYPE = "queue";
 var MATCH_ROOM_TYPE = "match";
 var INTERP_RATIO = 1.5;
-var INTERP_MIN_MS = 50;
+var INTERP_MIN_MS = 90;
 var INTERP_MAX_MS = 300;
+var JITTER_SAFETY = 1.2;
+var POISON_GUARD_MS = 2e3;
 var INTERP_EASE = 0.1;
 var MAX_EXTRAP_MS = 250;
+var ROT_EXTRAP_MS = 150;
 var CLOCK_WIN = 80;
 var SMOOTH_TAU_POS = 30;
 var SMOOTH_TAU_ROT = 70;
@@ -43,6 +46,14 @@ function parseValue(s) {
     return void 0;
   }
 }
+var finiteReplacer = (_k, v) => {
+  if (typeof v === "number") return Number.isFinite(v) ? v : 0;
+  if (typeof v === "bigint") return Number(v);
+  return v;
+};
+function sanitizeFinite(obj) {
+  return JSON.parse(JSON.stringify(obj, finiteReplacer));
+}
 var nowMs = () => typeof performance !== "undefined" && performance.now ? performance.now() : Date.now();
 function slerp(a, b, t) {
   let [bx, by, bz, bw] = b;
@@ -71,6 +82,7 @@ function isQuat(v) {
 }
 function blend(a, b, tNum, tQuat) {
   const out = {};
+  const interpolating = tNum < 1;
   for (const k in b) {
     const av = a[k];
     const bv = b[k];
@@ -79,7 +91,7 @@ function blend(a, b, tNum, tQuat) {
     } else if (isQuat(av) && isQuat(bv)) {
       out[k] = slerp(av, bv, tQuat);
     } else {
-      out[k] = bv;
+      out[k] = interpolating && k in a ? av : bv;
     }
   }
   return out;
@@ -111,9 +123,9 @@ function sampleBuffer(buf, renderTime) {
     const b2 = buf[n - 1];
     const span2 = b2.t - a2.t;
     if (span2 <= 0) return b2.state;
-    const capped = Math.min(renderTime, b2.t + MAX_EXTRAP_MS);
-    const t2 = (capped - a2.t) / span2;
-    return blend(a2.state, b2.state, t2, 1);
+    const tPos = (Math.min(renderTime, b2.t + MAX_EXTRAP_MS) - a2.t) / span2;
+    const tRot = (Math.min(renderTime, b2.t + ROT_EXTRAP_MS) - a2.t) / span2;
+    return blend(a2.state, b2.state, tPos, tRot);
   }
   const a = buf[j - 1];
   const b = buf[j];
@@ -126,6 +138,12 @@ function median(xs) {
   const s = [...xs].sort((a, b) => a - b);
   return s[s.length >> 1];
 }
+function quantile(xs, q) {
+  if (xs.length === 0) return 0;
+  const s = [...xs].sort((a, b) => a - b);
+  const i = Math.min(s.length - 1, Math.max(0, Math.round(q * (s.length - 1))));
+  return s[i];
+}
 async function connect(opts) {
   const client = new Client(opts.url);
   const room = await client.joinOrCreate(RELAY_ROOM_TYPE, {
@@ -138,7 +156,21 @@ async function connect(opts) {
   });
   return attachSession(client, room);
 }
-var RESERVED_SEND_TYPES = /* @__PURE__ */ new Set(["state", "shared", "claim", "obj", "release", "destroy"]);
+var RESERVED_SEND_TYPES = /* @__PURE__ */ new Set([
+  "state",
+  "shared",
+  "claim",
+  "obj",
+  "release",
+  "destroy",
+  // Server→client control verbs a game must never ORIGINATE — they'd broadcast to peers via the
+  // relay's `*` handler: 'server:restart' would trip every peer's save-flush, 'rate:drop' a bogus
+  // over-budget warning, 'queue'/'seat' spurious matchmaking control.
+  "server:restart",
+  "rate:drop",
+  "queue",
+  "seat"
+]);
 var isReservedSendType = (type) => RESERVED_SEND_TYPES.has(type) || type.startsWith("match:") || type.startsWith(RESERVED_PREFIX);
 var RECONNECT_DELAYS_MS = [500, 1e3, 2e3, 4e3, 8e3];
 var ROOM_REF = /* @__PURE__ */ Symbol("genex.roomRef");
@@ -158,8 +190,10 @@ function attachSession(client, initialRoom) {
   const objRaw = /* @__PURE__ */ new Map();
   const localObjState = /* @__PURE__ */ new Map();
   let hostId;
+  const testSkew = typeof globalThis !== "undefined" && globalThis.__GENEX_MP_TEST_SKEW__ || 0;
+  const now = testSkew ? () => nowMs() + testSkew : nowMs;
   const pushSnap = (id, state, sendTime) => {
-    const arrival = nowMs();
+    const arrival = now();
     const t = sendTime ?? arrival;
     if (sendTime != null) {
       let win = offsetWin.get(id);
@@ -172,12 +206,17 @@ function attachSession(client, initialRoom) {
     lastStamp.set(id, t);
     if (prev != null) {
       const gap = t - prev;
-      if (gap > 5 && gap < 1e3) {
+      if (gap > 5 && gap < 2e3) {
         let iv = intervalsById.get(id);
         if (!iv) intervalsById.set(id, iv = []);
         iv.push(gap);
         if (iv.length > 30) iv.shift();
-        const target = Math.min(INTERP_MAX_MS, Math.max(INTERP_MIN_MS, INTERP_RATIO * median(iv)));
+        const ow = offsetWin.get(id);
+        const jitter = ow && ow.length >= 8 ? quantile(ow, 0.9) - Math.min(...ow) : 0;
+        const target = Math.min(
+          INTERP_MAX_MS,
+          Math.max(INTERP_MIN_MS, INTERP_RATIO * median(iv), JITTER_SAFETY * jitter)
+        );
         const cur = autoDelayById.get(id) ?? 100;
         autoDelayById.set(id, cur + (target - cur) * INTERP_EASE);
       }
@@ -187,6 +226,7 @@ function attachSession(client, initialRoom) {
     buf.push({ t, state });
     const cutoff = t - 1500;
     while (buf.length > 2 && buf[0].t < cutoff) buf.shift();
+    while (buf.length > 1 && buf[0].t > buf[buf.length - 1].t + POISON_GUARD_MS) buf.shift();
   };
   const sampleSmoothed = (streamKey, localNow) => {
     const buf = buffers.get(streamKey);
@@ -228,8 +268,10 @@ function attachSession(client, initialRoom) {
     "reconnecting",
     "reconnected",
     "disconnect",
-    INPUT_MSG
+    INPUT_MSG,
     // inputs.on() has its own channel — never bridged as a custom event
+    "rate:drop"
+    // relay → us only (over-budget warning); handled internally, never bridged
   ]);
   const emit = (event, ...args) => emitters.get(event)?.forEach((cb) => cb(...args));
   const lastShared = /* @__PURE__ */ new Map();
@@ -254,7 +296,10 @@ function attachSession(client, initialRoom) {
       if (ownerChanged) {
         if (owner) objOwners.set(id, owner);
         else objOwners.delete(id);
-        if (owner !== room.sessionId) localObjState.delete(id);
+        if (owner !== room.sessionId) {
+          localObjState.delete(id);
+          clearStream(key);
+        }
       }
       if (blob.d && typeof blob.d === "object" && Object.keys(blob.d).length > 0) {
         objRaw.set(id, blob.d);
@@ -276,12 +321,23 @@ function attachSession(client, initialRoom) {
   };
   let intentionalLeave = false;
   let dead = false;
+  let droppedWhileOffline = 0;
+  const send0 = (type, payload, countIfDropped = false) => {
+    if (room.connection?.isOpen) {
+      try {
+        room.send(type, payload);
+        return;
+      } catch {
+      }
+    }
+    if (countIfDropped) droppedWhileOffline++;
+  };
   const wireRoom = (r) => {
     const $ = getStateCallbacks(r);
     $(r.state).players.onAdd((player, id) => {
       const { state, sendTime } = parseData(player.data);
       emit("join", id, state);
-      if (id !== room.sessionId) pushSnap(id, state, sendTime);
+      if (id !== room.sessionId && sendTime != null) pushSnap(id, state, sendTime);
       $(player).onChange(() => {
         const { state: st, sendTime: ts } = parseData(player.data);
         emit("change", id, st);
@@ -316,6 +372,11 @@ function attachSession(client, initialRoom) {
     r.onMessage(INPUT_MSG, (msg) => {
       if (msg && typeof msg.from === "string") emit(INPUT_MSG, msg.from, msg.d);
     });
+    r.onMessage("rate:drop", (msg) => {
+      console.warn(
+        `[multiplayer] the relay dropped ${msg?.dropped ?? "some"} of your messages in the last second \u2014 you are publishing over budget. Publish idle/unchanged objects at \u22642Hz keepalive, not every tick (see the multiplayer skill's "message budget" section).`
+      );
+    });
     for (const event of bridged) r.onMessage(event, (msg) => emit(event, msg));
     r.onLeave((code) => handleLeave(r, code ?? 1006));
     r.onError(() => {
@@ -332,18 +393,27 @@ function attachSession(client, initialRoom) {
     void attemptReconnect(left.reconnectionToken, code);
   };
   const attemptReconnect = async (token, code) => {
-    for (let attempt = 1; attempt <= RECONNECT_DELAYS_MS.length; attempt++) {
+    for (let attempt = 1; attempt <= RECONNECT_DELAYS_MS.length + 1; attempt++) {
       emit("reconnecting", { attempt, code });
-      await new Promise((r) => setTimeout(r, RECONNECT_DELAYS_MS[attempt - 1]));
       if (intentionalLeave || dead) return;
       try {
         const next = await client.reconnect(token);
         room = next;
         wireRoom(next);
         emit("reconnected");
+        if (droppedWhileOffline > 0) {
+          console.warn(
+            `[multiplayer] ${droppedWhileOffline} fire-and-forget event(s)/input(s) were dropped while reconnecting \u2014 they are not buffered; player/object state re-synced automatically.`
+          );
+          droppedWhileOffline = 0;
+        }
         return;
       } catch {
       }
+      if (attempt <= RECONNECT_DELAYS_MS.length) {
+        await new Promise((r) => setTimeout(r, RECONNECT_DELAYS_MS[attempt - 1]));
+        if (intentionalLeave || dead) return;
+      }
     }
     dead = true;
     emit("disconnect", code);
@@ -365,7 +435,7 @@ function attachSession(client, initialRoom) {
     id: room.sessionId,
     get players() {
       const out = /* @__PURE__ */ new Map();
-      const localNow = nowMs();
+      const localNow = now();
       room.state?.players?.forEach((p, id) => {
         const latest = cachedParse(id, p.data);
         let state = latest;
@@ -384,8 +454,12 @@ function attachSession(client, initialRoom) {
     },
     me: {
       set(state) {
-        localState = { ...state };
-        room.send("state", JSON.stringify({ ...state, [SEND_TIME_KEY]: nowMs() }));
+        if (SEND_TIME_KEY in state) {
+          console.warn(`[multiplayer] '${SEND_TIME_KEY}' is a reserved field name and will be overwritten by the send timestamp \u2014 rename it.`);
+        }
+        const clean = sanitizeFinite(state);
+        localState = clean;
+        send0("state", JSON.stringify({ ...clean, [SEND_TIME_KEY]: now() }));
       }
     },
     shared: {
@@ -395,7 +469,7 @@ function attachSession(client, initialRoom) {
       },
       set(key, value) {
         if (key.startsWith(RESERVED_PREFIX)) return;
-        room.send("shared", { key, value: JSON.stringify(value) });
+        send0("shared", { key, value: JSON.stringify(sanitizeFinite(value)) });
       },
       keys() {
         return room.state?.shared ? Array.from(room.state.shared.keys()).filter((k) => !k.startsWith(RESERVED_PREFIX)) : [];
@@ -405,13 +479,13 @@ function attachSession(client, initialRoom) {
       claim(id) {
         const key = String(id);
         objOwners.set(key, room.sessionId);
-        room.send("claim", { id: key });
+        send0("claim", { id: key });
       },
       release(id) {
         const key = String(id);
         localObjState.delete(key);
         if (objOwners.get(key) === room.sessionId) objOwners.delete(key);
-        room.send("release", { id: key });
+        send0("release", { id: key });
       },
       remove(id) {
         const key = String(id);
@@ -421,12 +495,13 @@ function attachSession(client, initialRoom) {
           objOwners.delete(key);
           clearStream(OBJ_PREFIX + key);
         }
-        room.send("destroy", { id: key });
+        send0("destroy", { id: key });
       },
       set(id, state) {
         const key = String(id);
-        if (objOwners.get(key) === room.sessionId) localObjState.set(key, { ...state });
-        room.send("obj", { id: key, d: { ...state } });
+        const clean = sanitizeFinite(state);
+        if (objOwners.get(key) === room.sessionId) localObjState.set(key, clean);
+        send0("obj", { id: key, d: clean, t: now() });
       },
       get(id) {
         const key = String(id);
@@ -441,7 +516,7 @@ function attachSession(client, initialRoom) {
           raw = mine;
         } else {
           raw = objRaw.get(key) ?? {};
-          state = sampleSmoothed(OBJ_PREFIX + key, nowMs()) ?? raw;
+          state = sampleSmoothed(OBJ_PREFIX + key, now()) ?? raw;
         }
         return { id: key, owner, isMine, state, stateRaw: raw };
       },
@@ -457,7 +532,7 @@ function attachSession(client, initialRoom) {
     },
     inputs: {
       send(payload) {
-        room.send(INPUT_MSG, payload);
+        send0(INPUT_MSG, sanitizeFinite(payload), true);
       },
       on(cb) {
         let set = emitters.get(INPUT_MSG);
@@ -476,7 +551,7 @@ function attachSession(client, initialRoom) {
           last = nowMs();
           timer = setInterval(() => {
             const t = nowMs();
-            cb(t - last);
+            cb(Math.min(t - last, 250));
             last = t;
           }, Math.max(10, Math.round(1e3 / hz)));
         } else if (!shouldRun && timer) {
@@ -498,7 +573,7 @@ function attachSession(client, initialRoom) {
         console.warn(`[multiplayer] send('${type}') collides with a relay-internal channel \u2014 use a different event name`);
         return;
       }
-      room.send(type, payload);
+      send0(type, payload, true);
     },
     leave() {
       intentionalLeave = true;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@genex-ai/multiplayer",
-  "version": "0.8.1",
+  "version": "0.8.3",
   "description": "The multiplayer client wrapper + shared room schema for genex.",
   "type": "module",
   "main": "./dist/index.js",