@genex-ai/multiplayer 0.2.2 → 0.2.6

package/README.md

@@ -87,11 +87,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 lerped between snapshots, so motion glides instead of teleporting between network updates (you send ~10–20Hz but render at 60). The delay **self-tunes to the live snapshot rate** (held ~2 snapshots back, the way Valve Source / Unity do it), 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 the live snapshot rate**, so it works whether you send at 5Hz or 30Hz.
 
 - `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.
-- Only **numeric** top-level fields are lerped; everything else snaps.
+- **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.
 
 > 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.
 
@@ -114,7 +116,7 @@ setInterval(() => room.me.set(me), 66);
 function frame() {
   for (const [id, p] of room.players) {
     const cube = cubeFor(id);                 // create-or-reuse a mesh per id
-    cube.position.set(p.state.x ?? 0, 0, p.state.z ?? 0);   // smoothed if interpolation:true, else snaps
+    cube.position.set(p.state.x ?? 0, 0, p.state.z ?? 0);   // auto-smoothed
   }
   requestAnimationFrame(frame);
 }
@@ -134,7 +136,7 @@ onKey('right', () => { me.x += 1; });
 - **`me` / `shared` are synced; everything else is local.** Movement input → mutate a local object → `me.set` it on the tick.
 - **Tick `me.set` at ~10–20Hz**, render at your own framerate. One `me.set` = one network message.
 - **`room` (game id) must be stable per game** — use the project slug. Same id = same room; different id = isolated.
-- **Smooth remote players** with `interpolation` (or read `stateRaw` and smooth yourself). No server-side prediction — you render yourself live.
+- **Remote players are smoothed automatically** — read `stateRaw` when you need the raw latest (hit-tests). No server-side prediction — you render yourself live.
 - `me.set` replaces your whole state object — send the full object each time, not a partial.
 
 ---

package/dist/index.js

@@ -1,17 +1,30 @@
 // src/index.ts
 import { Client, getStateCallbacks } from "colyseus.js";
 var RELAY_ROOM_TYPE = "play";
-var INTERP_RATIO = 2;
-var INTERP_MIN_MS = 60;
-var INTERP_MAX_MS = 400;
+var INTERP_RATIO = 1.5;
+var INTERP_MIN_MS = 50;
+var INTERP_MAX_MS = 300;
 var INTERP_EASE = 0.1;
-function parseObject(s) {
-  if (!s) return {};
+var MAX_EXTRAP_MS = 250;
+var CLOCK_WIN = 80;
+var SMOOTH_TAU_POS = 30;
+var SMOOTH_TAU_ROT = 70;
+var SEND_TIME_KEY = "__t";
+function parseData(s) {
+  if (!s) return { state: {} };
   try {
     const v = JSON.parse(s);
-    return v && typeof v === "object" ? v : {};
+    if (!v || typeof v !== "object") return { state: {} };
+    const o = v;
+    const t = o[SEND_TIME_KEY];
+    if (typeof t === "number" && Number.isFinite(t)) {
+      const state = { ...o };
+      delete state[SEND_TIME_KEY];
+      return { state, sendTime: t };
+    }
+    return { state: o };
   } catch {
-    return {};
+    return { state: {} };
   }
 }
 function parseValue(s) {
@@ -23,26 +36,82 @@ function parseValue(s) {
   }
 }
 var nowMs = () => typeof performance !== "undefined" && performance.now ? performance.now() : Date.now();
-function lerpState(a, b, alpha) {
+function slerp(a, b, t) {
+  let [bx, by, bz, bw] = b;
+  const [ax, ay, az, aw] = a;
+  let dot = ax * bx + ay * by + az * bz + aw * bw;
+  if (dot < 0) {
+    bx = -bx;
+    by = -by;
+    bz = -bz;
+    bw = -bw;
+    dot = -dot;
+  }
+  if (dot > 0.9995) {
+    const x = ax + (bx - ax) * t, y = ay + (by - ay) * t, z = az + (bz - az) * t, w = aw + (bw - aw) * t;
+    const l = Math.hypot(x, y, z, w) || 1;
+    return [x / l, y / l, z / l, w / l];
+  }
+  const theta0 = Math.acos(dot);
+  const sin0 = Math.sin(theta0);
+  const s0 = Math.sin(theta0 - theta0 * t) / sin0;
+  const s1 = Math.sin(theta0 * t) / sin0;
+  return [ax * s0 + bx * s1, ay * s0 + by * s1, az * s0 + bz * s1, aw * s0 + bw * s1];
+}
+function isQuat(v) {
+  return Array.isArray(v) && v.length === 4 && v.every((n) => typeof n === "number" && Number.isFinite(n));
+}
+function blend(a, b, tNum, tQuat) {
   const out = {};
   for (const k in b) {
     const av = a[k];
     const bv = b[k];
-    out[k] = typeof av === "number" && typeof bv === "number" && Number.isFinite(av) && Number.isFinite(bv) ? av + (bv - av) * alpha : bv;
+    if (typeof av === "number" && typeof bv === "number" && Number.isFinite(av) && Number.isFinite(bv)) {
+      out[k] = av + (bv - av) * tNum;
+    } else if (isQuat(av) && isQuat(bv)) {
+      out[k] = slerp(av, bv, tQuat);
+    } else {
+      out[k] = bv;
+    }
+  }
+  return out;
+}
+function easeState(prev, target, aNum, aQuat) {
+  const out = {};
+  for (const k in target) {
+    const tv = target[k];
+    const pv = prev[k];
+    if (typeof pv === "number" && typeof tv === "number" && Number.isFinite(pv) && Number.isFinite(tv)) {
+      out[k] = pv + (tv - pv) * aNum;
+    } else if (isQuat(pv) && isQuat(tv)) {
+      out[k] = slerp(pv, tv, aQuat);
+    } else {
+      out[k] = tv;
+    }
   }
   return out;
 }
 function sampleBuffer(buf, renderTime) {
   const n = buf.length;
   if (n === 0) return void 0;
+  if (n === 1) return buf[0].state;
   let j = 0;
   while (j < n && buf[j].t <= renderTime) j++;
   if (j === 0) return buf[0].state;
-  if (j >= n) return buf[n - 1].state;
+  if (j >= n) {
+    const a2 = buf[n - 2];
+    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 a = buf[j - 1];
   const b = buf[j];
   const span = b.t - a.t;
-  return lerpState(a.state, b.state, span > 0 ? (renderTime - a.t) / span : 1);
+  const t = span > 0 ? (renderTime - a.t) / span : 1;
+  return blend(a.state, b.state, t, t);
 }
 function median(xs) {
   if (xs.length === 0) return 66;
@@ -57,13 +126,25 @@ async function connect(opts) {
     ...opts.options
   });
   const buffers = /* @__PURE__ */ new Map();
-  const lastArrival = /* @__PURE__ */ new Map();
+  const lastStamp = /* @__PURE__ */ new Map();
+  const clockOffsets = /* @__PURE__ */ new Map();
+  const offsetWin = /* @__PURE__ */ new Map();
+  const smoothed = /* @__PURE__ */ new Map();
+  const smoothedAt = /* @__PURE__ */ new Map();
   const intervals = [];
   let autoDelay = 100;
-  const pushSnap = (id, state) => {
-    const t = nowMs();
-    const prev = lastArrival.get(id);
-    lastArrival.set(id, t);
+  const pushSnap = (id, state, sendTime) => {
+    const arrival = nowMs();
+    const t = sendTime ?? arrival;
+    if (sendTime != null) {
+      let win = offsetWin.get(id);
+      if (!win) offsetWin.set(id, win = []);
+      win.push(arrival - sendTime);
+      if (win.length > CLOCK_WIN) win.shift();
+      clockOffsets.set(id, Math.min(...win));
+    }
+    const prev = lastStamp.get(id);
+    lastStamp.set(id, t);
     if (prev != null) {
       const gap = t - prev;
       if (gap > 5 && gap < 1e3) {
@@ -85,19 +166,23 @@ async function connect(opts) {
   const emit = (event, ...args) => emitters.get(event)?.forEach((cb) => cb(...args));
   const $ = getStateCallbacks(room);
   $(room.state).players.onAdd((player, id) => {
-    const initial = parseObject(player.data);
-    emit("join", id, initial);
-    if (id !== room.sessionId) pushSnap(id, initial);
+    const { state, sendTime } = parseData(player.data);
+    emit("join", id, state);
+    if (id !== room.sessionId) pushSnap(id, state, sendTime);
     $(player).onChange(() => {
-      const st = parseObject(player.data);
+      const { state: st, sendTime: ts } = parseData(player.data);
       emit("change", id, st);
-      if (id !== room.sessionId) pushSnap(id, st);
+      if (id !== room.sessionId) pushSnap(id, st, ts);
     });
   });
   $(room.state).players.onRemove((_player, id) => {
     emit("leave", id);
     buffers.delete(id);
-    lastArrival.delete(id);
+    lastStamp.delete(id);
+    clockOffsets.delete(id);
+    offsetWin.delete(id);
+    smoothed.delete(id);
+    smoothedAt.delete(id);
   });
   $(room.state).shared.onAdd((value, key) => emit("shared", key, parseValue(value)));
   const on = ((event, cb) => {
@@ -116,14 +201,25 @@ async function connect(opts) {
     id: room.sessionId,
     get players() {
       const out = /* @__PURE__ */ new Map();
-      const renderTime = nowMs() - autoDelay;
+      const localNow = nowMs();
       room.state?.players?.forEach((p, id) => {
-        const latest = parseObject(p.data);
+        const { state: latest } = parseData(p.data);
         let state = latest;
         if (id !== room.sessionId) {
           const buf = buffers.get(id);
+          const renderTime = localNow - (clockOffsets.get(id) ?? 0) - autoDelay;
           const sampled = buf && sampleBuffer(buf, renderTime);
-          if (sampled) state = sampled;
+          if (sampled) {
+            const prev = smoothed.get(id);
+            if (prev) {
+              const dt = Math.min(250, Math.max(0, localNow - (smoothedAt.get(id) ?? localNow)));
+              state = easeState(prev, sampled, 1 - Math.exp(-dt / SMOOTH_TAU_POS), 1 - Math.exp(-dt / SMOOTH_TAU_ROT));
+            } else {
+              state = sampled;
+            }
+            smoothed.set(id, state);
+            smoothedAt.set(id, localNow);
+          }
         }
         out.set(id, { id, name: p.name, state, stateRaw: latest });
       });
@@ -131,7 +227,7 @@ async function connect(opts) {
     },
     me: {
       set(state) {
-        room.send("state", JSON.stringify(state));
+        room.send("state", JSON.stringify({ ...state, [SEND_TIME_KEY]: nowMs() }));
       }
     },
     shared: {

package/package.json

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