@genex-ai/multiplayer 0.7.0 → 0.8.0

package/README.md

@@ -103,10 +103,52 @@ room.on('shared', (key, value) => {}); // a shared key changed
 room.on('object', (id)        => {});  // an object's owner changed (handoff)
 room.on('host',   (id)        => {});  // the room host changed
 room.on('hit',    (payload)   => {});  // a custom event someone sent (see `send`)
+
+room.on('reconnecting', ({ attempt }) => {}); // connection dropped — auto-reconnect underway
+room.on('reconnected',  ()            => {}); // back in the SAME seat: id, objects, host intact
+room.on('disconnect',   (code)        => {}); // terminal — connect() fresh to play again
 ```
 
 `on(...)` returns an unsubscribe function.
 
+## Reconnection (automatic)
+
+A dropped socket (Wi-Fi blip, brief signal loss) is **not** a leave: the relay holds your
+seat for a grace window (~30s) and the SDK reconnects with backoff. On success nothing
+changed — same session id, owned objects still yours, host status intact, and mid-match a
+blip is **not a forfeit**. Render `reconnecting`/`reconnected` as an overlay and keep your
+loop running. `disconnect` is terminal (server restart, revoked session, or the link never
+recovered): read a fresh token and `connect()` again. A deliberate `leave()` never
+reconnects. The relay also broadcasts `server:restart` right before a deploy — flush saves
+when you see it.
+
+**One seat per player:** the relay enforces a single session per identity per room — a
+second tab / device / reloaded page supersedes the previous session (old one gets
+`disconnect`, code 4409), so the same player never appears twice and reloads never leave
+a ghost. Reload/close sockets ("going away") get only a ~5s seat-hold; genuine network
+drops keep the full reconnection grace.
+
+## `inputs` + `onHostTick` — host-authoritative physics (contested objects)
+
+Claim-on-touch is right for one-touch objects (kick a ball). For **sustained contact**
+(two players pushing one crate) let ONE simulation own the contest: everyone sends inputs —
+the relay routes them to the **current host only** — and the host applies them on a fixed
+tick and publishes results via `objects` (auto-smoothed for everyone):
+
+```ts
+if (pushing) room.inputs.send({ obj: 'crate', push: dir });   // any client → host only
+
+room.inputs.on((fromId, payload) => queue.push(payload));      // fires only while YOU host
+room.onHostTick(30, (dtMs) => {                                // runs only on the host,
+  // adopt objects + seed from stateRaw on first tick, apply    //  auto-migrates with the
+  // queued inputs to YOUR one physics world, then:             //  host election
+  room.objects.set('crate', { x, y, z, q });
+});
+```
+
+`onHostTick` auto-starts on election and auto-stops on demotion; a new host seeds its world
+from each object's `stateRaw`, so the simulation survives host migration without a snap.
+
 ## `send` — custom one-off events
 
 Fire-and-forget to all **other** clients (not stored in state). For shots, emotes, chat, pings.

package/dist/index.d.ts

@@ -95,21 +95,59 @@ type Session<TState extends Record<string, unknown>> = {
     readonly isHost: boolean;
     /** Session id of the current room host, or `undefined` until the first host patch lands. */
     readonly host: string | undefined;
+    /**
+     * Input channel for host-authoritative patterns (contested physics, host-simulated
+     * NPCs): anyone `send`s an input; the server delivers it ONLY to the current host
+     * (never broadcast). The host applies inputs in its one authoritative simulation and
+     * publishes results via `objects` — everyone renders them auto-smoothed.
+     */
+    readonly inputs: {
+        /** Send an input/impulse to the current host (single receiver, cheap). */
+        send(payload: unknown): void;
+        /** Receive inputs — only ever fires while YOU are the host. Returns unsubscribe. */
+        on(cb: (fromId: string, payload: unknown) => void): () => void;
+    };
+    /**
+     * Run `cb(dtMs)` on a fixed tick ONLY while this client is the host — auto-starts on
+     * election and auto-stops on demotion/leave, so host-simulation code needs no "am I
+     * host this frame?" bookkeeping. Returns a disposer.
+     */
+    onHostTick(hz: number, cb: (dtMs: number) => void): () => void;
     /** A player appeared/updated. **Also fires for you** on connect — filter `id === room.id`. */
     on(event: 'join' | 'change', cb: (id: string, state: TState) => void): () => void;
     /** A player left. */
     on(event: 'leave', cb: (id: string) => void): () => void;
     /** A shared key changed (reserved `__*` keys are hidden). For live values just read `shared.get`. */
     on(event: 'shared', cb: (key: string, value: unknown) => void): () => void;
-    /** An object's owner or state changed (fires with its id). */
+    /** An object's OWNERSHIP changed (claim/handoff), or it appeared/was destroyed — fires
+     * with its id. NOT per-tick state: poll `objects.get(id)` in your loop for state. */
     on(event: 'object', cb: (id: string) => void): () => void;
     /** The room host changed (fires with the new host's id, or `undefined`). */
     on(event: 'host', cb: (host: string | undefined) => void): () => void;
+    /**
+     * The connection dropped unexpectedly and auto-reconnect is underway (attempts run
+     * ~0.5s→8s backoff inside the server's grace window). Show a "reconnecting…" overlay;
+     * keep your loop running — the world resumes seamlessly on `reconnected`.
+     */
+    on(event: 'reconnecting', cb: (info: {
+        attempt: number;
+        code: number;
+    }) => void): () => void;
+    /** Auto-reconnect succeeded: same session id, same seat — nothing was torn down. */
+    on(event: 'reconnected', cb: () => void): () => void;
+    /**
+     * The connection is gone for good: the server closed it on purpose (restart, revoked
+     * session, match eviction) or every reconnect attempt failed. The session is dead —
+     * to play again, read a FRESH `getColyseusAuth()` and `connect()` anew.
+     */
+    on(event: 'disconnect', cb: (code: number) => void): () => void;
     /** A custom event another client sent via `send(type, ...)`. */
     on(event: string & {}, cb: (payload: unknown) => void): () => void;
-    /** Fire-and-forget event to all OTHER clients (not stored in state). */
+    /** Fire-and-forget event to all OTHER clients (not stored in state). Event names used
+     * by the relay itself (`state`, `shared`, `claim`, `obj`, `release`, `destroy`, and the
+     * `match:`/`__` prefixes) are refused with a console warning — pick another name. */
     send(type: string, payload?: unknown): void;
-    /** Leave the room. */
+    /** Leave the room (deliberate — no auto-reconnect, no `disconnect` event). */
     leave(): void;
 };
 /**

package/dist/index.js

@@ -16,6 +16,7 @@ var RESERVED_PREFIX = "__";
 var OBJ_PREFIX = "__obj:";
 var HOST_KEY = "__host";
 var MATCH_KEY = "__match";
+var INPUT_MSG = "__input";
 var MP_PROTOCOL = 1;
 function parseData(s) {
   if (!s) return { state: {} };
@@ -135,9 +136,15 @@ async function connect(opts) {
     __v: MP_PROTOCOL
     // tells the relay this client hides reserved `__` keys (see MP_PROTOCOL)
   });
-  return attachSession(room);
+  return attachSession(client, room);
 }
-function attachSession(room) {
+var RESERVED_SEND_TYPES = /* @__PURE__ */ new Set(["state", "shared", "claim", "obj", "release", "destroy"]);
+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");
+var roomOf = (s) => s[ROOM_REF]();
+function attachSession(client, initialRoom) {
+  let room = initialRoom;
   const buffers = /* @__PURE__ */ new Map();
   const lastStamp = /* @__PURE__ */ new Map();
   const clockOffsets = /* @__PURE__ */ new Map();
@@ -211,23 +218,20 @@ function attachSession(room) {
   };
   const emitters = /* @__PURE__ */ new Map();
   const bridged = /* @__PURE__ */ new Set();
-  const reserved = /* @__PURE__ */ new Set(["join", "leave", "change", "shared", "object", "host"]);
+  const reserved = /* @__PURE__ */ new Set([
+    "join",
+    "leave",
+    "change",
+    "shared",
+    "object",
+    "host",
+    "reconnecting",
+    "reconnected",
+    "disconnect",
+    INPUT_MSG
+    // inputs.on() has its own channel — never bridged as a custom event
+  ]);
   const emit = (event, ...args) => emitters.get(event)?.forEach((cb) => cb(...args));
-  const $ = getStateCallbacks(room);
-  $(room.state).players.onAdd((player, id) => {
-    const { state, sendTime } = parseData(player.data);
-    emit("join", id, state);
-    if (id !== room.sessionId) pushSnap(id, state, sendTime);
-    $(player).onChange(() => {
-      const { state: st, sendTime: ts } = parseData(player.data);
-      emit("change", id, st);
-      if (id !== room.sessionId) pushSnap(id, st, ts);
-    });
-  });
-  $(room.state).players.onRemove((_player, id) => {
-    emit("leave", id);
-    clearStream(id);
-  });
   const lastShared = /* @__PURE__ */ new Map();
   const handleShared = (value, key) => {
     if (lastShared.get(key) === value) return;
@@ -261,26 +265,90 @@ function attachSession(room) {
     }
     emit("shared", key, parseValue(value));
   };
-  $(room.state).shared.onAdd(handleShared);
-  $(room.state).shared.onChange(handleShared);
-  $(room.state).shared.onRemove((_value, key) => {
-    lastShared.delete(key);
-    if (key === HOST_KEY) {
-      if (hostId !== void 0) {
-        hostId = void 0;
-        emit("host", void 0);
+  const parseCache = /* @__PURE__ */ new Map();
+  const cachedParse = (id, raw) => {
+    if (!raw) return {};
+    const hit = parseCache.get(id);
+    if (hit && hit.raw === raw) return hit.state;
+    const { state } = parseData(raw);
+    parseCache.set(id, { raw, state });
+    return state;
+  };
+  let intentionalLeave = false;
+  let dead = false;
+  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);
+      $(player).onChange(() => {
+        const { state: st, sendTime: ts } = parseData(player.data);
+        emit("change", id, st);
+        if (id !== room.sessionId) pushSnap(id, st, ts);
+      });
+    });
+    $(r.state).players.onRemove((_player, id) => {
+      emit("leave", id);
+      clearStream(id);
+      parseCache.delete(id);
+    });
+    $(r.state).shared.onAdd(handleShared);
+    $(r.state).shared.onChange(handleShared);
+    $(r.state).shared.onRemove((_value, key) => {
+      lastShared.delete(key);
+      if (key === HOST_KEY) {
+        if (hostId !== void 0) {
+          hostId = void 0;
+          emit("host", void 0);
+        }
+        return;
       }
+      if (key.startsWith(OBJ_PREFIX)) {
+        const id = key.slice(OBJ_PREFIX.length);
+        clearStream(key);
+        objRaw.delete(id);
+        objOwners.delete(id);
+        localObjState.delete(id);
+        emit("object", id);
+      }
+    });
+    r.onMessage(INPUT_MSG, (msg) => {
+      if (msg && typeof msg.from === "string") emit(INPUT_MSG, msg.from, msg.d);
+    });
+    for (const event of bridged) r.onMessage(event, (msg) => emit(event, msg));
+    r.onLeave((code) => handleLeave(r, code ?? 1006));
+    r.onError(() => {
+    });
+  };
+  const handleLeave = (left, code) => {
+    if (left !== room || dead) return;
+    if (intentionalLeave) return;
+    if (code === 1e3 || code >= 4e3) {
+      dead = true;
+      emit("disconnect", code);
       return;
     }
-    if (key.startsWith(OBJ_PREFIX)) {
-      const id = key.slice(OBJ_PREFIX.length);
-      clearStream(key);
-      objRaw.delete(id);
-      objOwners.delete(id);
-      localObjState.delete(id);
-      emit("object", id);
+    void attemptReconnect(left.reconnectionToken, code);
+  };
+  const attemptReconnect = async (token, code) => {
+    for (let attempt = 1; attempt <= RECONNECT_DELAYS_MS.length; 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");
+        return;
+      } catch {
+      }
     }
-  });
+    dead = true;
+    emit("disconnect", code);
+  };
+  wireRoom(room);
   const on = ((event, cb) => {
     let set = emitters.get(event);
     if (!set) emitters.set(event, set = /* @__PURE__ */ new Set());
@@ -293,13 +361,13 @@ function attachSession(room) {
       set?.delete(cb);
     };
   });
-  return {
+  const session = {
     id: room.sessionId,
     get players() {
       const out = /* @__PURE__ */ new Map();
       const localNow = nowMs();
       room.state?.players?.forEach((p, id) => {
-        const { state: latest } = parseData(p.data);
+        const latest = cachedParse(id, p.data);
         let state = latest;
         let raw = latest;
         if (id === room.sessionId) {
@@ -387,14 +455,58 @@ function attachSession(room) {
     get host() {
       return hostId;
     },
+    inputs: {
+      send(payload) {
+        room.send(INPUT_MSG, payload);
+      },
+      on(cb) {
+        let set = emitters.get(INPUT_MSG);
+        if (!set) emitters.set(INPUT_MSG, set = /* @__PURE__ */ new Set());
+        const listener = (from, payload) => cb(from, payload);
+        set.add(listener);
+        return () => void set?.delete(listener);
+      }
+    },
+    onHostTick(hz, cb) {
+      let timer = null;
+      let last = 0;
+      const sync = () => {
+        const shouldRun = hostId !== void 0 && hostId === room.sessionId;
+        if (shouldRun && !timer) {
+          last = nowMs();
+          timer = setInterval(() => {
+            const t = nowMs();
+            cb(t - last);
+            last = t;
+          }, Math.max(10, Math.round(1e3 / hz)));
+        } else if (!shouldRun && timer) {
+          clearInterval(timer);
+          timer = null;
+        }
+      };
+      const off = on("host", sync);
+      sync();
+      return () => {
+        off();
+        if (timer) clearInterval(timer);
+        timer = null;
+      };
+    },
     on,
     send(type, payload) {
+      if (isReservedSendType(type)) {
+        console.warn(`[multiplayer] send('${type}') collides with a relay-internal channel \u2014 use a different event name`);
+        return;
+      }
       room.send(type, payload);
     },
     leave() {
+      intentionalLeave = true;
       void room.leave();
     }
   };
+  Object.defineProperty(session, ROOM_REF, { value: () => room, enumerable: false });
+  return session;
 }
 var resolveAuth = (auth) => typeof auth === "function" ? auth() : auth;
 var matchJoinOptions = (opts) => ({
@@ -498,6 +610,18 @@ async function matchmake(opts) {
       "seat",
       (msg) => void consumeSeat(msg.reservation, msg.role)
     );
+    q.onLeave(() => {
+      if (cancelled || queueRoom !== q) return;
+      queueRoom = null;
+      void (async () => {
+        for (const delayMs of RECONNECT_DELAYS_MS) {
+          await new Promise((r) => setTimeout(r, delayMs));
+          if (cancelled || queueRoom || session) return;
+          await search();
+          if (queueRoom || session) return;
+        }
+      })();
+    });
     emit("searching");
   };
   const consumeSeat = async (reservation, role) => {
@@ -508,10 +632,14 @@ async function matchmake(opts) {
         return;
       }
       matchRoom = mr;
-      session = attachSession(mr);
-      mr.onMessage("match:start", (m) => emit("matchStart", m));
-      mr.onMessage("match:ended", (m) => emit("matchEnded", m));
-      mr.onMessage("match:requeue", () => void requeue());
+      const s = attachSession(client, mr);
+      session = s;
+      s.on("match:start", (m) => emit("matchStart", m));
+      s.on("match:ended", (m) => emit("matchEnded", m));
+      s.on("match:requeue", () => void requeue());
+      s.on("disconnect", () => {
+        if (!cancelled && session === s) void requeue();
+      });
       if (queueRoom) {
         void queueRoom.leave();
         queueRoom = null;
@@ -523,34 +651,34 @@ async function matchmake(opts) {
     }
   };
   const requeue = async () => {
-    if (matchRoom) {
-      void matchRoom.leave();
-      matchRoom = null;
-    }
+    session?.leave();
+    matchRoom = null;
     session = null;
     await search();
   };
   await search();
+  const liveRoom = () => session ? roomOf(session) : null;
   return {
     get session() {
       return session;
     },
     get matchmaking() {
-      return buildView(matchRoom, queueInfo);
+      return buildView(liveRoom(), queueInfo);
     },
     on,
     eliminated() {
-      matchRoom?.send("match:eliminated", {});
+      liveRoom()?.send("match:eliminated", {});
     },
     score(delta = 1) {
-      matchRoom?.send("match:score", { delta });
+      liveRoom()?.send("match:score", { delta });
     },
     finish() {
-      matchRoom?.send("match:finish", {});
+      liveRoom()?.send("match:finish", {});
     },
     cancel() {
       cancelled = true;
-      if (matchRoom) void matchRoom.leave();
+      session?.leave();
+      if (!session && matchRoom) void matchRoom.leave();
       if (queueRoom) void queueRoom.leave();
       matchRoom = null;
       queueRoom = null;
@@ -567,33 +695,33 @@ function wirePrivate(client, room) {
     set.add(cb);
     return () => void set?.delete(cb);
   });
-  let matchRoom = room;
-  const session = attachSession(room);
-  room.onMessage("match:start", (m) => emit("matchStart", m));
-  room.onMessage("match:ended", (m) => emit("matchEnded", m));
-  room.onMessage("match:requeue", () => void (matchRoom = null));
-  room.onLeave(() => void (matchRoom = null));
+  let live = true;
+  const session = attachSession(client, room);
+  session.on("match:start", (m) => emit("matchStart", m));
+  session.on("match:ended", (m) => emit("matchEnded", m));
+  session.on("match:requeue", () => void (live = false));
+  session.on("disconnect", () => void (live = false));
+  const liveRoom = () => live ? roomOf(session) : null;
   return {
     get session() {
-      return matchRoom ? session : null;
+      return live ? session : null;
     },
     get matchmaking() {
-      return buildView(matchRoom, { position: 0, size: 0 });
+      return buildView(liveRoom(), { position: 0, size: 0 });
     },
     on,
     eliminated() {
-      matchRoom?.send("match:eliminated", {});
+      liveRoom()?.send("match:eliminated", {});
     },
     score(delta = 1) {
-      matchRoom?.send("match:score", { delta });
+      liveRoom()?.send("match:score", { delta });
     },
     finish() {
-      matchRoom?.send("match:finish", {});
+      liveRoom()?.send("match:finish", {});
     },
     cancel() {
-      if (matchRoom) void matchRoom.leave();
-      matchRoom = null;
-      void client;
+      session.leave();
+      live = false;
     }
   };
 }

package/package.json

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