@genex-ai/multiplayer 0.2.6 → 0.4.1

package/README.md

@@ -57,6 +57,42 @@ room.shared.get('round');   // 3
 room.shared.keys();         // ['round', ...]
 ```
 
+## `objects` — shared objects nobody owns until claimed
+
+For a **ball, a puck, an NPC** — a moving thing that isn't any one player. Exactly one client
+**owns** an object at a time (the server enforces it); the owner simulates it and `set`s it, and
+everyone else reads it **auto-smoothed**, on the same interpolation as remote players. Ownership
+survives the owner leaving — the object is reassigned to the room host.
+
+```ts
+if (iKicked) room.objects.claim('ball');           // take ownership (last claim wins)
+
+if (room.objects.get('ball')?.isMine) {
+  room.objects.set('ball', simulateBall());        // only the owner's writes land
+}
+const ball = room.objects.get('ball');             // { owner, isMine, state, stateRaw }
+drawBall(ball.state);                              // smoothed for everyone (live for the owner)
+
+room.objects.release('ball');                      // give it up (stays until reclaimed)
+room.objects.remove('bullet');                     // destroy transient objects when done
+```
+
+Keep object state **flat** (top-level numbers + a 4-number quaternion) so it smooths, same as a
+player. `state` is smoothed; `stateRaw` is the raw latest (hit-tests). `objects.ids()` lists them.
+
+## `isHost` / `host` — the elected room authority
+
+One client is the **host** (the first joiner still present, re-elected automatically when they
+leave). Use it to pick a single writer for scores/rounds or a single simulator for NPCs.
+
+```ts
+if (room.isHost) room.shared.set('round', nextRound);   // only the host advances the round
+room.on('host', (id) => {});                             // host changed (migration)
+```
+
+`isHost`/`host` settle within the first patch after `connect()` — read them in your loop (or react
+to `on('host')`), not once at startup.
+
 ## `on` — events
 
 ```ts
@@ -64,6 +100,8 @@ room.on('join',   (id, state) => {});  // a player appeared (also fires for YOU
 room.on('change', (id, state) => {});  // a player updated their me-state
 room.on('leave',  (id)        => {});  // a player left
 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`)
 ```
 
@@ -143,13 +181,18 @@ onKey('right', () => { me.x += 1; });
 
 ## Persistent worlds (optional)
 
-The relay is in-memory — room state is gone when everyone leaves or the server restarts. To persist world state across restarts, save/load a JSON blob via the API (keyed by the project slug):
+The relay is in-memory — room state is gone when everyone leaves or the server restarts. To persist world state across restarts, use `@genex-ai/embed-sdk`'s state helpers (they own auth tokens, guest handling, and write-conflict decoding):
 
 ```ts
+import { loadWorldState, saveWorldState } from '@genex-ai/embed-sdk';
+
 // load on boot
-const { data } = await fetch(`${API}/api/projects/${slug}/state`).then(r => r.json());
+const { data, version } = await loadWorldState();
 initWorld(data ?? defaultWorld());
 
-// save whenever (from ONE authority — e.g. a host client — to avoid races)
-fetch(`${API}/api/projects/${slug}/state`, { method: 'PUT', body: JSON.stringify(world) });
+// save (from ONE authority — the elected host — debounced, with ifVersion so
+// races surface as { conflict: true } instead of silently clobbering)
+if (room.isHost) await saveWorldState(world, { ifVersion: version });
 ```
+
+The relay prefers signed-in players when electing the host (guests cannot write saves), so host-driven persistence works whenever any account is in the room. Per-player progression belongs in `savePlayerState()` (each player's own slot), never in the shared world blob.

package/dist/index.d.ts

@@ -7,8 +7,20 @@ type ConnectOptions = {
     /** Game id — everyone who passes the same id shares a room; different ids are
      * fully isolated. Use your project slug (or any stable per-game string). */
     room: string;
-    /** Display name for this player (anonymous is fine). */
+    /** Display name for this player. The server prefers the verified identity's
+     * name (from `auth`) when present; this is the display fallback. */
     name?: string;
+    /**
+     * Verified-identity credential — REQUIRED to actually join: the relay
+     * rejects tokenless joins (there is no anonymous play). Pass
+     * `genexEmbed.getColyseusAuth()` AFTER `await genexEmbed.waitForAuth()`
+     * (from `@genex-ai/embed-sdk`), and read it fresh at every connect() call —
+     * never cache the object across reconnects (tokens rotate every ~10 min).
+     * NEVER log this value.
+     */
+    auth?: {
+        embedToken: string;
+    };
     /** Extra join options passed to the room. */
     options?: Record<string, unknown>;
 };
@@ -21,6 +33,19 @@ type PlayerView<TState> = {
     /** The latest raw snapshot (never smoothed/delayed) — use for hit-tests / logic. */
     stateRaw: TState;
 };
+/** A shared object (a ball, a puck, an NPC) owned by exactly one client at a time. */
+type ObjectView<TState> = {
+    id: string;
+    /** Session id of the current owner, or `undefined` if unowned. */
+    owner: string | undefined;
+    /** True if you own it (so you should simulate + `objects.set` it). */
+    isMine: boolean;
+    /** State to render — **auto-smoothed** like a remote player when someone else owns it;
+     * live (your last `set`) when it's yours. */
+    state: TState;
+    /** The latest raw snapshot (never smoothed/delayed) — for hit-tests / logic. */
+    stateRaw: TState;
+};
 type Session<TState extends Record<string, unknown>> = {
     /** Your own session id. */
     readonly id: string;
@@ -45,12 +70,41 @@ type Session<TState extends Record<string, unknown>> = {
         /** All shared keys currently set. */
         keys(): string[];
     };
+    /**
+     * Shared objects nobody owns until claimed — a ball, a puck, an NPC. Exactly one client
+     * owns an object at a time (server-enforced); the owner simulates it and `set`s it, and
+     * everyone else reads it **auto-smoothed**, on the same interpolation as remote players.
+     * Ownership survives an owner leaving: the object is reassigned to the room host.
+     */
+    readonly objects: {
+        /** Take ownership (last claim wins — call it when you kick/touch the object). */
+        claim(id: string): void;
+        /** Give up ownership (leaves the object unowned until someone claims it). */
+        release(id: string): void;
+        /** Destroy the object everywhere (owner-only) — use for transient objects (bullets, pickups). */
+        remove(id: string): void;
+        /** Publish the object's state — only takes effect while you own it. Full object each call. */
+        set(id: string, state: Record<string, unknown>): void;
+        /** Read an object, or `undefined` if it doesn't exist yet. */
+        get<T extends Record<string, unknown> = Record<string, unknown>>(id: string): ObjectView<T> | undefined;
+        /** Ids of every object seen so far. */
+        ids(): string[];
+    };
+    /** True if you are the elected room host (first joiner still present). Settles within the
+     * first state patch after connect — read it in your loop or react to `on('host')`, not once. */
+    readonly isHost: boolean;
+    /** Session id of the current room host, or `undefined` until the first host patch lands. */
+    readonly host: string | undefined;
     /** 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 (fires on first set; for live values just read `shared.get`). */
+    /** 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). */
+    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;
     /** 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). */
@@ -75,4 +129,4 @@ type Session<TState extends Record<string, unknown>> = {
  */
 declare function connect<TState extends Record<string, unknown> = never>(opts: ConnectOptions): Promise<Session<TState>>;
 
-export { type ConnectOptions, type PlayerView, type Session, connect };
+export { type ConnectOptions, type ObjectView, type PlayerView, type Session, connect };

package/dist/index.js

@@ -10,6 +10,10 @@ var CLOCK_WIN = 80;
 var SMOOTH_TAU_POS = 30;
 var SMOOTH_TAU_ROT = 70;
 var SEND_TIME_KEY = "__t";
+var RESERVED_PREFIX = "__";
+var OBJ_PREFIX = "__obj:";
+var HOST_KEY = "__host";
+var MP_PROTOCOL = 1;
 function parseData(s) {
   if (!s) return { state: {} };
   try {
@@ -123,7 +127,10 @@ async function connect(opts) {
   const room = await client.joinOrCreate(RELAY_ROOM_TYPE, {
     gameId: opts.room,
     name: opts.name,
-    ...opts.options
+    embedToken: opts.auth?.embedToken,
+    ...opts.options,
+    __v: MP_PROTOCOL
+    // tells the relay this client hides reserved `__` keys (see MP_PROTOCOL)
   });
   const buffers = /* @__PURE__ */ new Map();
   const lastStamp = /* @__PURE__ */ new Map();
@@ -131,8 +138,13 @@ async function connect(opts) {
   const offsetWin = /* @__PURE__ */ new Map();
   const smoothed = /* @__PURE__ */ new Map();
   const smoothedAt = /* @__PURE__ */ new Map();
-  const intervals = [];
-  let autoDelay = 100;
+  const intervalsById = /* @__PURE__ */ new Map();
+  const autoDelayById = /* @__PURE__ */ new Map();
+  let localState;
+  const objOwners = /* @__PURE__ */ new Map();
+  const objRaw = /* @__PURE__ */ new Map();
+  const localObjState = /* @__PURE__ */ new Map();
+  let hostId;
   const pushSnap = (id, state, sendTime) => {
     const arrival = nowMs();
     const t = sendTime ?? arrival;
@@ -148,10 +160,13 @@ async function connect(opts) {
     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 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 cur = autoDelayById.get(id) ?? 100;
+        autoDelayById.set(id, cur + (target - cur) * INTERP_EASE);
       }
     }
     let buf = buffers.get(id);
@@ -160,9 +175,37 @@ async function connect(opts) {
     const cutoff = t - 1500;
     while (buf.length > 2 && buf[0].t < cutoff) buf.shift();
   };
+  const sampleSmoothed = (streamKey, localNow) => {
+    const buf = buffers.get(streamKey);
+    const autoDelay = autoDelayById.get(streamKey) ?? 100;
+    const renderTime = localNow - (clockOffsets.get(streamKey) ?? 0) - autoDelay;
+    const sampled = buf && sampleBuffer(buf, renderTime);
+    if (!sampled) return void 0;
+    const prev = smoothed.get(streamKey);
+    let out;
+    if (prev) {
+      const dt = Math.min(250, Math.max(0, localNow - (smoothedAt.get(streamKey) ?? localNow)));
+      out = easeState(prev, sampled, 1 - Math.exp(-dt / SMOOTH_TAU_POS), 1 - Math.exp(-dt / SMOOTH_TAU_ROT));
+    } else {
+      out = sampled;
+    }
+    smoothed.set(streamKey, out);
+    smoothedAt.set(streamKey, localNow);
+    return out;
+  };
+  const clearStream = (streamKey) => {
+    buffers.delete(streamKey);
+    lastStamp.delete(streamKey);
+    clockOffsets.delete(streamKey);
+    offsetWin.delete(streamKey);
+    smoothed.delete(streamKey);
+    smoothedAt.delete(streamKey);
+    intervalsById.delete(streamKey);
+    autoDelayById.delete(streamKey);
+  };
   const emitters = /* @__PURE__ */ new Map();
   const bridged = /* @__PURE__ */ new Set();
-  const reserved = /* @__PURE__ */ new Set(["join", "leave", "change", "shared"]);
+  const reserved = /* @__PURE__ */ new Set(["join", "leave", "change", "shared", "object", "host"]);
   const emit = (event, ...args) => emitters.get(event)?.forEach((cb) => cb(...args));
   const $ = getStateCallbacks(room);
   $(room.state).players.onAdd((player, id) => {
@@ -177,14 +220,60 @@ async function connect(opts) {
   });
   $(room.state).players.onRemove((_player, id) => {
     emit("leave", id);
-    buffers.delete(id);
-    lastStamp.delete(id);
-    clockOffsets.delete(id);
-    offsetWin.delete(id);
-    smoothed.delete(id);
-    smoothedAt.delete(id);
+    clearStream(id);
+  });
+  const lastShared = /* @__PURE__ */ new Map();
+  const handleShared = (value, key) => {
+    if (lastShared.get(key) === value) return;
+    lastShared.set(key, value);
+    if (key === HOST_KEY) {
+      const next = parseValue(value) || void 0;
+      if (next !== hostId) {
+        hostId = next;
+        emit("host", hostId);
+      }
+      return;
+    }
+    if (key.startsWith(OBJ_PREFIX)) {
+      const id = key.slice(OBJ_PREFIX.length);
+      const blob = parseValue(value);
+      if (!blob || typeof blob !== "object") return;
+      const owner = typeof blob.o === "string" && blob.o ? blob.o : void 0;
+      const ownerChanged = owner !== objOwners.get(id);
+      if (ownerChanged) {
+        if (owner) objOwners.set(id, owner);
+        else objOwners.delete(id);
+        if (owner !== room.sessionId) localObjState.delete(id);
+      }
+      if (blob.d && typeof blob.d === "object" && Object.keys(blob.d).length > 0) {
+        objRaw.set(id, blob.d);
+        if (owner !== room.sessionId) pushSnap(key, blob.d, blob.t);
+      }
+      if (ownerChanged) emit("object", id);
+      return;
+    }
+    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);
+      }
+      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);
+    }
   });
-  $(room.state).shared.onAdd((value, key) => emit("shared", key, parseValue(value)));
   const on = ((event, cb) => {
     let set = emitters.get(event);
     if (!set) emitters.set(event, set = /* @__PURE__ */ new Set());
@@ -205,42 +294,92 @@ async function connect(opts) {
       room.state?.players?.forEach((p, id) => {
         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) {
-            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);
+        let raw = latest;
+        if (id === room.sessionId) {
+          if (localState) {
+            state = localState;
+            raw = localState;
           }
+        } else {
+          state = sampleSmoothed(id, localNow) ?? latest;
         }
-        out.set(id, { id, name: p.name, state, stateRaw: latest });
+        out.set(id, { id, name: p.name, state, stateRaw: raw });
       });
       return out;
     },
     me: {
       set(state) {
+        localState = { ...state };
         room.send("state", JSON.stringify({ ...state, [SEND_TIME_KEY]: nowMs() }));
       }
     },
     shared: {
       get(key) {
+        if (key.startsWith(RESERVED_PREFIX)) return void 0;
         return parseValue(room.state?.shared?.get(key));
       },
       set(key, value) {
+        if (key.startsWith(RESERVED_PREFIX)) return;
         room.send("shared", { key, value: JSON.stringify(value) });
       },
       keys() {
-        return room.state?.shared ? Array.from(room.state.shared.keys()) : [];
+        return room.state?.shared ? Array.from(room.state.shared.keys()).filter((k) => !k.startsWith(RESERVED_PREFIX)) : [];
+      }
+    },
+    objects: {
+      claim(id) {
+        const key = String(id);
+        objOwners.set(key, room.sessionId);
+        room.send("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 });
+      },
+      remove(id) {
+        const key = String(id);
+        if (objOwners.get(key) === room.sessionId) {
+          localObjState.delete(key);
+          objRaw.delete(key);
+          objOwners.delete(key);
+          clearStream(OBJ_PREFIX + key);
+        }
+        room.send("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 } });
+      },
+      get(id) {
+        const key = String(id);
+        const owner = objOwners.get(key);
+        const mine = localObjState.get(key);
+        if (owner === void 0 && !objRaw.has(key) && !mine) return void 0;
+        const isMine = owner !== void 0 && owner === room.sessionId;
+        let state;
+        let raw;
+        if (isMine && mine) {
+          state = mine;
+          raw = mine;
+        } else {
+          raw = objRaw.get(key) ?? {};
+          state = sampleSmoothed(OBJ_PREFIX + key, nowMs()) ?? raw;
+        }
+        return { id: key, owner, isMine, state, stateRaw: raw };
+      },
+      ids() {
+        return [.../* @__PURE__ */ new Set([...objOwners.keys(), ...objRaw.keys(), ...localObjState.keys()])];
       }
     },
+    get isHost() {
+      return hostId !== void 0 && hostId === room.sessionId;
+    },
+    get host() {
+      return hostId;
+    },
     on,
     send(type, payload) {
       room.send(type, payload);

package/package.json

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