@genex-ai/multiplayer 0.1.0 → 0.2.0

package/README.md

@@ -2,7 +2,7 @@
 
 Tiny realtime multiplayer for genex games.
 
-**Relay model:** whatever you write to `me` or `shared` is synced to everyone; everything else stays local. The server does **no physics, no prediction, no interpolation** — you run your own game logic, this just shares state.
+**Relay model:** whatever you write to `me` or `shared` is synced to everyone; everything else stays local. The server does **no physics, no prediction** — you run your own game logic, this just shares state. Remote players are **smoothed automatically** (client-side entity interpolation — see [Smoothing remote players](#smoothing-remote-players)).
 
 ```ts
 import { connect } from '@genex-ai/multiplayer';
@@ -36,7 +36,7 @@ room.me.set({ x, y, z });
 
 ## `players` — everyone in the room
 
-A fresh `Map` each read; **includes you** (skip with `id === room.id`). It's the latest snapshot — snap to it (or smooth client-side if you want; there's no built-in interpolation).
+A fresh `Map` each read; **includes you** (skip with `id === room.id`). For remote players `p.state` is **auto-smoothed** (interpolated); for yourself it's live. `p.stateRaw` is always the latest raw snapshot (use it for hit-tests / logic).
 
 ```ts
 for (const [id, p] of room.players) {
@@ -45,6 +45,8 @@ for (const [id, p] of room.players) {
 }
 ```
 
+Remote players glide instead of teleporting between network updates — see **[Smoothing remote players](#smoothing-remote-players)**.
+
 ## `shared` — shared room state
 
 A key/value store (any JSON) synced to everyone. Use for world state, scores, the current round, etc.
@@ -83,6 +85,18 @@ 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.
+
+- `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.
+
+> 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.
+
+---
+
 ## Complete minimal example (move a cube, see others as cubes)
 
 ```ts
@@ -100,7 +114,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);   // snap — no interpolation
+    cube.position.set(p.state.x ?? 0, 0, p.state.z ?? 0);   // smoothed if interpolation:true, else snaps
   }
   requestAnimationFrame(frame);
 }
@@ -120,7 +134,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.
-- **No interpolation / prediction.** You get the latest state; snap to it, or smooth it yourself.
+- **Smooth remote players** with `interpolation` (or read `stateRaw` and smooth yourself). 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.d.ts

@@ -15,15 +15,19 @@ type ConnectOptions = {
 type PlayerView<TState> = {
     id: string;
     name: string;
-    /** This player's latest synced state (what they passed to `me.set`). */
+    /** State to render — for remote players this is **auto-smoothed** (interpolated);
+     * for yourself it's live. Numeric fields are lerped; everything else snaps. */
     state: TState;
+    /** The latest raw snapshot (never smoothed/delayed) — use for hit-tests / logic. */
+    stateRaw: TState;
 };
 type Session<TState extends Record<string, unknown>> = {
     /** Your own session id. */
     readonly id: string;
     /**
      * Everyone in the room, **including you** — skip yourself with
-     * `if (id === room.id)`. Returns a fresh Map on each read.
+     * `if (id === room.id)`. Returns a fresh Map on each read. Remote players'
+     * `state` is auto-smoothed; read `stateRaw` for the raw latest value.
      */
     readonly players: Map<string, PlayerView<TState>>;
     readonly me: {
@@ -62,11 +66,12 @@ type Session<TState extends Record<string, unknown>> = {
  *   url: 'ws://localhost:2567', room: gameId, name: 'ada',
  * });
  * room.me.set({ x, y, z });          // typed + validated by the compiler
- * room.players.get(id)?.state.x;     // number — no cast
+ * room.players.get(id)?.state.x;     // number — auto-smoothed for remote players
  * ```
  *
- * Relay model: no physics, no prediction, no interpolation. Whatever you write
- * to `me` or `shared` syncs to everyone; everything else stays local.
+ * Relay model: no server physics/prediction. Whatever you write to `me`/`shared`
+ * syncs to everyone; everything else stays local. Remote players are smoothed
+ * automatically (entity interpolation) — `state` is smooth, `stateRaw` is raw.
  */
 declare function connect<TState extends Record<string, unknown> = never>(opts: ConnectOptions): Promise<Session<TState>>;
 

package/dist/index.js

@@ -1,6 +1,10 @@
 // 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_EASE = 0.1;
 function parseObject(s) {
   if (!s) return {};
   try {
@@ -18,6 +22,33 @@ function parseValue(s) {
     return void 0;
   }
 }
+var nowMs = () => typeof performance !== "undefined" && performance.now ? performance.now() : Date.now();
+function lerpState(a, b, alpha) {
+  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;
+  }
+  return out;
+}
+function sampleBuffer(buf, renderTime) {
+  const n = buf.length;
+  if (n === 0) return void 0;
+  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;
+  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);
+}
+function median(xs) {
+  if (xs.length === 0) return 66;
+  const s = [...xs].sort((a, b) => a - b);
+  return s[s.length >> 1];
+}
 async function connect(opts) {
   const client = new Client(opts.url);
   const room = await client.joinOrCreate(RELAY_ROOM_TYPE, {
@@ -25,16 +56,49 @@ async function connect(opts) {
     name: opts.name,
     ...opts.options
   });
+  const buffers = /* @__PURE__ */ new Map();
+  const lastArrival = /* @__PURE__ */ new Map();
+  const intervals = [];
+  let autoDelay = 100;
+  const pushSnap = (id, state) => {
+    const t = nowMs();
+    const prev = lastArrival.get(id);
+    lastArrival.set(id, t);
+    if (prev != null) {
+      const gap = t - prev;
+      if (gap > 5 && gap < 1e3) {
+        intervals.push(gap);
+        if (intervals.length > 30) intervals.shift();
+        const target = Math.min(INTERP_MAX_MS, Math.max(INTERP_MIN_MS, INTERP_RATIO * median(intervals)));
+        autoDelay += (target - autoDelay) * INTERP_EASE;
+      }
+    }
+    let buf = buffers.get(id);
+    if (!buf) buffers.set(id, buf = []);
+    buf.push({ t, state });
+    const cutoff = t - 1500;
+    while (buf.length > 2 && buf[0].t < cutoff) buf.shift();
+  };
   const emitters = /* @__PURE__ */ new Map();
   const bridged = /* @__PURE__ */ new Set();
   const reserved = /* @__PURE__ */ new Set(["join", "leave", "change", "shared"]);
   const emit = (event, ...args) => emitters.get(event)?.forEach((cb) => cb(...args));
   const $ = getStateCallbacks(room);
   $(room.state).players.onAdd((player, id) => {
-    emit("join", id, parseObject(player.data));
-    $(player).onChange(() => emit("change", id, parseObject(player.data)));
+    const initial = parseObject(player.data);
+    emit("join", id, initial);
+    if (id !== room.sessionId) pushSnap(id, initial);
+    $(player).onChange(() => {
+      const st = parseObject(player.data);
+      emit("change", id, st);
+      if (id !== room.sessionId) pushSnap(id, st);
+    });
+  });
+  $(room.state).players.onRemove((_player, id) => {
+    emit("leave", id);
+    buffers.delete(id);
+    lastArrival.delete(id);
   });
-  $(room.state).players.onRemove((_player, id) => emit("leave", id));
   $(room.state).shared.onAdd((value, key) => emit("shared", key, parseValue(value)));
   const on = ((event, cb) => {
     let set = emitters.get(event);
@@ -52,9 +116,17 @@ async function connect(opts) {
     id: room.sessionId,
     get players() {
       const out = /* @__PURE__ */ new Map();
-      room.state?.players?.forEach(
-        (p, id) => out.set(id, { id, name: p.name, state: parseObject(p.data) })
-      );
+      const renderTime = nowMs() - autoDelay;
+      room.state?.players?.forEach((p, id) => {
+        const latest = parseObject(p.data);
+        let state = latest;
+        if (id !== room.sessionId) {
+          const buf = buffers.get(id);
+          const sampled = buf && sampleBuffer(buf, renderTime);
+          if (sampled) state = sampled;
+        }
+        out.set(id, { id, name: p.name, state, stateRaw: latest });
+      });
       return out;
     },
     me: {

package/package.json

@@ -1,23 +1,34 @@
 {
   "name": "@genex-ai/multiplayer",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "The multiplayer client wrapper + shared room schema for genex.",
   "type": "module",
   "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
-    },
-    "./schema": {
-      "types": "./dist/schema.d.ts",
-      "import": "./dist/schema.js"
-    }
+    ".": "./src/index.ts",
+    "./schema": "./src/schema.ts"
   },
   "files": [
     "dist"
   ],
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "prepack": "pnpm build"
+  },
   "publishConfig": {
-    "access": "public"
+    "access": "public",
+    "main": "./dist/index.js",
+    "types": "./dist/index.d.ts",
+    "exports": {
+      ".": {
+        "types": "./dist/index.d.ts",
+        "import": "./dist/index.js"
+      },
+      "./schema": {
+        "types": "./dist/schema.d.ts",
+        "import": "./dist/schema.js"
+      }
+    }
   },
   "dependencies": {
     "@colyseus/schema": "^3.0.76",
@@ -39,11 +50,5 @@
     "url": "git+https://github.com/me-ai-org/genex-demo.git",
     "directory": "packages/multiplayer"
   },
-  "license": "MIT",
-  "scripts": {
-    "build": "tsup",
-    "typecheck": "tsc --noEmit"
-  },
-  "main": "./dist/index.js",
-  "types": "./dist/index.d.ts"
-}
+  "license": "MIT"
+}