@genex-ai/multiplayer 0.8.8 → 0.10.0

package/README.md

@@ -13,13 +13,13 @@ import { connect } from '@genex-ai/multiplayer';
 ## Connect
 
 ```ts
-import { waitForPlayer, getColyseusAuth } from '@genex-ai/embed-sdk';
+import { waitForPlayer, getColyseusAuth, getColyseusUrls } from '@genex-ai/embed-sdk';
 
 type State = { x: number; y: number; z: number };   // YOUR per-player state — any JSON shape
 
 await waitForPlayer();                        // identity gate — resolves for guests AND accounts
 const room = await connect<State>({
-  url:  'wss://demo-colyseus.glotech.world',  // the genex multiplayer server
+  urls: getColyseusUrls(),          // regional relays for this session — SDK joins the fastest
   room: '<game-id>',                          // everyone with the same id shares a room (use the project slug)
   name: 'ada',                                // optional display name
   auth: getColyseusAuth()!,                   // REQUIRED — the relay rejects tokenless joins
@@ -41,6 +41,7 @@ Replaces your state wholesale. Call on a **fixed tick (~10–20Hz)**, not every
 
 ```ts
 room.me.set({ x, y, z });
+room.me.snap({ x: spawnX, y: spawnY, z: spawnZ }); // respawn/teleport: hard-reset remote history
 ```
 
 ## `players` — everyone in the room
@@ -74,21 +75,57 @@ everyone else reads it **auto-smoothed**, on the same interpolation as remote pl
 survives the owner leaving — the object is reassigned to the room host.
 
 ```ts
-if (iKicked) room.objects.claim('ball');           // take ownership (last claim wins)
+// Legacy fire-and-forget claim: optimistic locally, corrected by the relay if rejected.
+if (iTouched) room.objects.claim('ball');
+
+// Irreversible action: wait for the authoritative result.
+const result = await room.objects.claimConfirmed('ball');
+if (result.accepted) applyKick();
+else if (result.reason === 'held') retryWhileStillTouching(result.retryAfterMs);
 
 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 }
+const ball = room.objects.get('ball');             // { owner, isMine, epoch, 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
+
+await room.objects.releaseConfirmed('ball');       // acknowledged + idempotent under reconnect
+await room.objects.removeConfirmed('bullet');      // acknowledged owner-only removal
+
+// Deliberate discontinuity: one hard reseed, never an old-to-new interpolation sweep.
+room.objects.snap('ball', { x: 0, y: 1, z: 0, q: [0, 0, 0, 1] });
 ```
 
 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.
 
+The relay enforces a short minimum ownership hold to prevent contact thrash. A current-owner
+reassert is a true no-op: it does not extend that hold. Legacy `claim()` remains optimistic for
+0.8.x compatibility; use the confirmed methods when feedback, impulses, seats, scoring, release,
+or removal must not lie. Confirmed requests have stable request ids internally and are resent after
+a reconnect, so an accepted operation is idempotent. A rejected result reports the current owner and,
+for `held`, `retryAfterMs`.
+
+A `timeout` result means the outcome is **unknown**, not "failed": the relay may have applied the
+operation and only the answer was lost. Shared owner truth (`objects.get(id)?.isMine` /
+`owner`) converges through the state mirror regardless — treat it, not the timed-out promise, as
+authoritative before tearing anything down. On a relay that predates protocol v2, `me.snap` /
+`objects.snap` degrade gracefully: the discontinuity write itself is not stored (peers converge on
+your next ordinary `set`, without the history reset) — which is why the relay must be upgraded
+before games ship an SDK that relies on snaps (see the migration note).
+
+`claimConfirmed(id)` is an ordinary fair player claim, including when the caller happens to be host.
+Only host-owned lifecycle work such as initial seeding or a goal reset should request
+`claimConfirmed(id, { authority: 'host' })`; the relay accepts that bypass only from the current host.
+When it actually bypasses an active hold the result reason is `host-authority`; a non-host request is
+rejected as `not-host`. Do not use host authority for ordinary host-player collisions.
+
+`me.snap` and `objects.snap` are for discontinuities only: respawn, teleport, reset, or a player mode
+edge such as exiting a vehicle. Ordinary movement must use `set`, otherwise motion will visibly snap.
+
 ## `isHost` / `host` — the elected room authority
 
 One client is the **host** — the earliest **signed-in** player still present (guests host only
@@ -124,14 +161,19 @@ room.on('disconnect',   (code)        => {}); // terminal — connect() fresh to
 
 ## 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.
+A dropped socket (Wi-Fi blip, brief signal loss) is **not** immediately a leave: the relay holds your
+seat for a grace window (~30s) and the SDK reconnects with backoff. A short blip keeps the same session
+id, owned objects, and host status. Simulation availability is a separate lease: if the disconnected
+seat is host for longer than the relay's short host-failover grace, an active peer becomes host and
+host-owned objects move once. A returning old host keeps its seat but does not steal authority back.
+Host-tick callbacks pause while their socket is reconnecting and resume only if that session still owns
+the host role. After a long reconnect, remote interpolation histories are rebased to current truth so
+they cannot draw a whole-map catch-up streak.
+
+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
@@ -160,8 +202,10 @@ room.onHostTick(30, (dtMs) => {                                // runs only on t
 });
 ```
 
-`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.
+`onHostTick` auto-starts on election, pauses during reconnect, resumes after reconnect only if still
+host, and stops on demotion, deliberate `leave()`, or terminal disconnect. The disposer is still useful
+when the game removes that subsystem earlier. A new host must confirm an explicit host-authority claim
+and seed its world from each object's `stateRaw`, so simulation survives host migration without a snap.
 
 ## `send` — custom one-off events
 
@@ -183,6 +227,11 @@ room.leave();
 
 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.
 
+Do not add another lerp, snapshot buffer, or remote physics predictor on top. `state` is already the
+render value. This relay does not implement classic client-side prediction plus server reconciliation:
+your own player is client-authoritative and renders locally; remote entities use interpolation and
+bounded extrapolation.
+
 - `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.
@@ -197,12 +246,12 @@ Remote players are **smoothed automatically** — nothing to configure. `room.pl
 
 ```ts
 import { connect } from '@genex-ai/multiplayer';
-import { waitForPlayer, getColyseusAuth } from '@genex-ai/embed-sdk';
+import { waitForPlayer, getColyseusAuth, getColyseusUrls } from '@genex-ai/embed-sdk';
 type S = { x: number; z: number };
 
 await waitForPlayer();   // identity gate (guest OR signed-in) — see Connect above
 const room = await connect<S>({
-  url: 'wss://demo-colyseus.glotech.world',
+  urls: getColyseusUrls(),
   room: GAME_ID,
   auth: getColyseusAuth()!,   // REQUIRED — tokenless joins are rejected
 });
@@ -240,7 +289,7 @@ import { matchmake } from "@genex-ai/multiplayer";
 
 // Pass `auth` as a FUNCTION — a handle re-joins many times (re-search/requeue) and tokens rotate
 // (~10 min); a function is read fresh each join, a static object goes stale mid-session.
-const mm = await matchmake<State>({ url, room: slug, auth: () => getColyseusAuth() });
+const mm = await matchmake<State>({ urls, room: slug, auth: () => getColyseusAuth() });
 
 // `session` is null WHILE SEARCHING — render your own "finding a match…" HUD until it goes live.
 // each frame:
@@ -295,11 +344,11 @@ For `preset: 'private'` games, skip the queue: a host mints an invite **code**,
 import { createPrivate, joinPrivate } from "@genex-ai/multiplayer";
 
 // host
-const lobby = await createPrivate<State>({ url, room: slug, auth: () => getColyseusAuth() });
+const lobby = await createPrivate<State>({ urls, room: slug, auth: () => getColyseusAuth() });
 share(lobby.code);                 // e.g. show it in the UI
 
 // friend (elsewhere)
-const joined = await joinPrivate<State>(code, { url, room: slug, auth: () => getColyseusAuth() });
+const joined = await joinPrivate<State>(code, { urls, room: slug, auth: () => getColyseusAuth() });
 
 // then identical to matchmake(): .session, .matchmaking, eliminated()/score()/finish(), cancel()
 ```

package/dist/index.d.ts

@@ -2,8 +2,9 @@ export { PlayerState, RoomState } from './schema.js';
 import '@colyseus/schema';
 
 type ConnectOptions = {
-    /** Colyseus server url, e.g. "ws://localhost:2567". */
-    url: string;
+    /** Regional relay urls (pass `getColyseusUrls()`) — the SDK pings each and connects to the
+     *  lowest-latency one; a single entry just connects. */
+    urls: string[];
     /** 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;
@@ -37,6 +38,8 @@ type PlayerView<TState> = {
 /** A shared object (a ball, a puck, an NPC) owned by exactly one client at a time. */
 type ObjectView<TState> = {
     id: string;
+    /** Relay-owned discontinuity epoch. Helpers direct-place physics when this changes. */
+    epoch: number;
     /** 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). */
@@ -47,6 +50,28 @@ type ObjectView<TState> = {
     /** The latest raw snapshot (never smoothed/delayed) — for hit-tests / logic. */
     stateRaw: TState;
 };
+type ObjectControlOperation = 'claim' | 'release' | 'remove';
+type ObjectControlReason = 'accepted' | 'already-owner' | 'held' | 'rate-limited' | 'not-owner' | 'capacity' | 'invalid' | 'missing' | 'host-authority' | 'not-host' | 'unsupported' | 'timeout' | 'aborted' | 'disconnected';
+type ObjectControlResult = {
+    requestId: string;
+    operation: ObjectControlOperation;
+    id: string;
+    accepted: boolean;
+    owner?: string;
+    sequence: number;
+    reason: ObjectControlReason;
+    retryAfterMs?: number;
+};
+type ObjectControlOptions = {
+    /** Ordinary player claims are subject to the hold. Host authority is for seeding/reset only. */
+    authority?: 'player' | 'host';
+    /** Locally mark a claim as owned while awaiting the result. Default false. */
+    optimistic?: boolean;
+    /** Maximum wait including reconnect resend. Default 5000 ms. */
+    timeoutMs?: number;
+    /** Cancels the pending operation and resolves with reason `aborted`. */
+    signal?: AbortSignal;
+};
 type Session<TState extends Record<string, unknown>> = {
     /** Your own session id. */
     readonly id: string;
@@ -62,6 +87,8 @@ type Session<TState extends Record<string, unknown>> = {
          * (~10–20Hz), not every render frame — each call sends one network message.
          */
         set(state: TState): void;
+        /** Publish a deliberate discontinuity (respawn/teleport/mode edge) and clear remote history. */
+        snap(state: TState): void;
     };
     readonly shared: {
         /** Read a shared value (any JSON), or `undefined`. */
@@ -79,14 +106,22 @@ type Session<TState extends Record<string, unknown>> = {
      * 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). */
+        /** Legacy optimistic ownership request. Prefer claimConfirmed for actions that need a result. */
         claim(id: string): void;
+        /** Request ownership and receive the relay's accepted/rejected result. */
+        claimConfirmed(id: string, options?: ObjectControlOptions): Promise<ObjectControlResult>;
         /** Give up ownership (leaves the object unowned until someone claims it). */
         release(id: string): void;
+        /** Give up ownership only after an explicit relay acknowledgement. */
+        releaseConfirmed(id: string, options?: ObjectControlOptions): Promise<ObjectControlResult>;
         /** Destroy the object everywhere (owner-only) — use for transient objects (bullets, pickups). */
         remove(id: string): void;
+        /** Destroy the object and receive an idempotent relay acknowledgement. */
+        removeConfirmed(id: string, options?: ObjectControlOptions): Promise<ObjectControlResult>;
         /** Publish the object's state — only takes effect while you own it. Full object each call. */
         set(id: string, state: Record<string, unknown>): void;
+        /** Owner-only deliberate discontinuity (reset/teleport), rendered as one hard reseed. */
+        snap(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. */
@@ -230,8 +265,8 @@ type Matchmaking<TState extends Record<string, unknown>> = {
     cancel(): void;
 };
 type MatchmakeOptions = {
-    /** Colyseus server url. */
-    url: string;
+    /** Regional relay urls (pass `getColyseusUrls()`) — pings each, connects to the lowest-latency one. */
+    urls: string[];
     /** Game id (your project slug/id) — isolates this game's matchmaking. */
     room: string;
     name?: string;
@@ -276,4 +311,4 @@ declare function createPrivate<TState extends Record<string, unknown> = never>(o
  */
 declare function joinPrivate<TState extends Record<string, unknown> = never>(code: string, opts: MatchmakeOptions): Promise<Matchmaking<TState>>;
 
-export { type ConnectOptions, type MatchStatus, type MatchmakeOptions, type Matchmaking, type MatchmakingView, type ObjectView, type PlayerView, type PrivateMatch, type Session, connect, createPrivate, joinPrivate, matchmake };
+export { type ConnectOptions, type MatchStatus, type MatchmakeOptions, type Matchmaking, type MatchmakingView, type ObjectControlOperation, type ObjectControlOptions, type ObjectControlReason, type ObjectControlResult, type ObjectView, type PlayerView, type PrivateMatch, type Session, connect, createPrivate, joinPrivate, matchmake };

package/dist/index.js

@@ -1,12 +1,12 @@
 // src/index.ts
-import { Client, getStateCallbacks } from "colyseus.js";
+import { Client, getStateCallbacks } from "@colyseus/sdk";
 var RELAY_ROOM_TYPE = "play";
 var QUEUE_ROOM_TYPE = "queue";
 var MATCH_ROOM_TYPE = "match";
 var INTERP_RATIO = 1.5;
 var INTERP_MIN_MS = 90;
 var INTERP_MAX_MS = 300;
-var JITTER_SAFETY = 1.2;
+var JITTER_SAFETY = 1.25;
 var POISON_GUARD_MS = 2e3;
 var INTERP_EASE = 0.1;
 var MAX_EXTRAP_MS = 250;
@@ -20,7 +20,19 @@ var OBJ_PREFIX = "__obj:";
 var HOST_KEY = "__host";
 var MATCH_KEY = "__match";
 var INPUT_MSG = "__input";
-var MP_PROTOCOL = 1;
+var CAPABILITIES_MSG = "__capabilities";
+var CAPABILITIES_REQUEST_MSG = "__capabilities:request";
+var OBJECT_CONTROL_RESULT_MSG = "__object:result";
+var OBJECT_CONTROL_VERSION = 2;
+var STATE_SNAP_MSG = "__state:snap";
+var OBJECT_SNAP_MSG = "__object:snap";
+var MP_PROTOCOL = 2;
+async function relayClient(opts) {
+  if (opts.urls.length > 1) return Client.selectByLatency(opts.urls);
+  const url = opts.urls[0];
+  if (!url) throw new Error("genex multiplayer: `urls` must contain at least one relay URL");
+  return new Client(url);
+}
 function parseData(s) {
   if (!s) return { state: {} };
   try {
@@ -145,7 +157,7 @@ function quantile(xs, q) {
   return s[i];
 }
 async function connect(opts) {
-  const client = new Client(opts.url);
+  const client = await relayClient(opts);
   const room = await client.joinOrCreate(RELAY_ROOM_TYPE, {
     gameId: opts.room,
     name: opts.name,
@@ -163,13 +175,18 @@ var RESERVED_SEND_TYPES = /* @__PURE__ */ new Set([
   "obj",
   "release",
   "destroy",
+  STATE_SNAP_MSG,
+  OBJECT_SNAP_MSG,
   // 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"
+  "seat",
+  CAPABILITIES_MSG,
+  CAPABILITIES_REQUEST_MSG,
+  OBJECT_CONTROL_RESULT_MSG
 ]);
 var isReservedSendType = (type) => RESERVED_SEND_TYPES.has(type) || type.startsWith("match:") || type.startsWith(RESERVED_PREFIX);
 var RECONNECT_DELAYS_MS = [500, 1e3, 2e3, 4e3, 8e3];
@@ -187,10 +204,14 @@ function attachSession(client, initialRoom) {
   const autoDelayById = /* @__PURE__ */ new Map();
   let localState;
   const objOwners = /* @__PURE__ */ new Map();
+  const objEpochs = /* @__PURE__ */ new Map();
   const objRaw = /* @__PURE__ */ new Map();
   const localObjState = /* @__PURE__ */ new Map();
   const pendingBridge = /* @__PURE__ */ new Map();
   let hostId;
+  let objectControlVersion = 0;
+  let requestCounter = 0;
+  const pendingControls = /* @__PURE__ */ new Map();
   const testSkew = typeof globalThis !== "undefined" && globalThis.__GENEX_MP_TEST_SKEW__ || 0;
   const now = testSkew ? () => nowMs() + testSkew : nowMs;
   const pushSnap = (id, state, sendTime) => {
@@ -286,8 +307,13 @@ function attachSession(client, initialRoom) {
     "disconnect",
     INPUT_MSG,
     // inputs.on() has its own channel — never bridged as a custom event
-    "rate:drop"
+    "rate:drop",
     // relay → us only (over-budget warning); handled internally, never bridged
+    CAPABILITIES_MSG,
+    CAPABILITIES_REQUEST_MSG,
+    OBJECT_CONTROL_RESULT_MSG,
+    STATE_SNAP_MSG,
+    OBJECT_SNAP_MSG
   ]);
   const emit = (event, ...args) => emitters.get(event)?.forEach((cb) => cb(...args));
   const lastShared = /* @__PURE__ */ new Map();
@@ -309,18 +335,26 @@ function attachSession(client, initialRoom) {
       if (!blob || typeof blob !== "object") return;
       const owner = typeof blob.o === "string" && blob.o ? blob.o : void 0;
       const ownerChanged = owner !== objOwners.get(id);
+      const epoch = typeof blob.e === "number" && Number.isFinite(blob.e) ? blob.e : 0;
+      const epochChanged = objEpochs.has(id) && epoch !== objEpochs.get(id);
+      objEpochs.set(id, epoch);
+      if (epochChanged) clearStream(key);
       if (ownerChanged) {
         if (owner) objOwners.set(id, owner);
         else objOwners.delete(id);
         if (owner !== room.sessionId) {
           localObjState.delete(id);
-          clearStreamClock(key);
+          if (!epochChanged) clearStreamClock(key);
         }
       }
       if (blob.d && typeof blob.d === "object" && Object.keys(blob.d).length > 0) {
         objRaw.set(id, blob.d);
         if (owner !== room.sessionId) {
-          if (ownerChanged) {
+          if (epochChanged) {
+            smoothed.set(key, blob.d);
+            smoothedAt.set(key, now());
+            pushSnap(key, blob.d, blob.t);
+          } else if (ownerChanged) {
             pendingBridge.set(key, smoothed.get(key) ?? blob.d);
           } else {
             pushSnap(key, blob.d, blob.t);
@@ -333,6 +367,7 @@ function attachSession(client, initialRoom) {
     emit("shared", key, parseValue(value));
   };
   const parseCache = /* @__PURE__ */ new Map();
+  const playerEpochs = /* @__PURE__ */ new Map();
   const cachedParse = (id, raw) => {
     if (!raw) return {};
     const hit = parseCache.get(id);
@@ -343,6 +378,145 @@ function attachSession(client, initialRoom) {
   };
   let intentionalLeave = false;
   let dead = false;
+  let connected = true;
+  let reconnectStartedAt = 0;
+  const hostTickSyncs = /* @__PURE__ */ new Set();
+  const syncHostTicks = () => hostTickSyncs.forEach((sync) => sync());
+  const settleControl = (pending, result) => {
+    pendingControls.delete(pending.requestId);
+    if (pending.timeout) clearTimeout(pending.timeout);
+    if (pending.capabilityTimer) clearTimeout(pending.capabilityTimer);
+    pending.abort?.();
+    if (pending.operation === "claim" && pending.optimistic && !result.accepted) {
+      if (result.owner) objOwners.set(pending.id, result.owner);
+      else objOwners.delete(pending.id);
+      if (result.owner !== room.sessionId) localObjState.delete(pending.id);
+      clearStreamClock(OBJ_PREFIX + pending.id);
+    }
+    if (pending.operation === "claim" && result.accepted) {
+      objOwners.set(pending.id, room.sessionId);
+      clearStreamClock(OBJ_PREFIX + pending.id);
+    }
+    if (pending.operation === "release" && result.accepted) {
+      localObjState.delete(pending.id);
+      if (objOwners.get(pending.id) === room.sessionId) objOwners.delete(pending.id);
+      clearStreamClock(OBJ_PREFIX + pending.id);
+    }
+    if (pending.operation === "remove" && result.accepted) {
+      localObjState.delete(pending.id);
+      objRaw.delete(pending.id);
+      objOwners.delete(pending.id);
+      clearStream(OBJ_PREFIX + pending.id);
+    }
+    pending.resolve(result);
+  };
+  const settleAllControls = (reason) => {
+    for (const pending of [...pendingControls.values()]) {
+      settleControl(pending, {
+        requestId: pending.requestId,
+        operation: pending.operation,
+        id: pending.id,
+        accepted: false,
+        owner: pending.optimistic ? pending.previousOwner : objOwners.get(pending.id),
+        sequence: 0,
+        reason
+      });
+    }
+  };
+  const sendPendingControl = (pending) => {
+    if (!connected || !room.connection?.isOpen) return;
+    send0(
+      pending.operation === "remove" ? "destroy" : pending.operation,
+      pending.payload
+    );
+  };
+  const flushCapabilityWaiters = () => {
+    if (objectControlVersion < OBJECT_CONTROL_VERSION) return;
+    for (const pending of pendingControls.values()) {
+      if (pending.capabilityTimer) {
+        clearTimeout(pending.capabilityTimer);
+        pending.capabilityTimer = null;
+      }
+      sendPendingControl(pending);
+    }
+  };
+  const confirmedControl = (operation, id, options = {}) => {
+    const key = String(id);
+    const requestId = `${room.sessionId.slice(0, 12)}:${Date.now().toString(36)}:${(++requestCounter).toString(36)}`;
+    const timeoutMs = Math.max(250, Math.min(options.timeoutMs ?? 5e3, 6e4));
+    return new Promise((resolve) => {
+      const pending = {
+        operation,
+        id: key,
+        requestId,
+        payload: {
+          id: key,
+          requestId,
+          ...options.authority === "host" ? { authority: "host" } : {}
+        },
+        optimistic: operation === "claim" && options.optimistic === true,
+        previousOwner: objOwners.get(key),
+        resolve,
+        timeout: null,
+        capabilityTimer: null,
+        abort: void 0
+      };
+      if (pending.optimistic) objOwners.set(key, room.sessionId);
+      pending.timeout = setTimeout(() => {
+        settleControl(pending, {
+          requestId,
+          operation,
+          id: key,
+          accepted: false,
+          owner: pending.optimistic ? pending.previousOwner : objOwners.get(key),
+          sequence: 0,
+          reason: "timeout"
+        });
+      }, timeoutMs);
+      if (options.signal) {
+        const onAbort = () => settleControl(pending, {
+          requestId,
+          operation,
+          id: key,
+          accepted: false,
+          owner: pending.optimistic ? pending.previousOwner : objOwners.get(key),
+          sequence: 0,
+          reason: "aborted"
+        });
+        options.signal.addEventListener("abort", onAbort, { once: true });
+        pending.abort = () => options.signal?.removeEventListener("abort", onAbort);
+      }
+      pendingControls.set(requestId, pending);
+      if (options.signal?.aborted) {
+        settleControl(pending, {
+          requestId,
+          operation,
+          id: key,
+          accepted: false,
+          owner: pending.optimistic ? pending.previousOwner : objOwners.get(key),
+          sequence: 0,
+          reason: "aborted"
+        });
+        return;
+      }
+      if (objectControlVersion >= OBJECT_CONTROL_VERSION) {
+        sendPendingControl(pending);
+      } else {
+        pending.capabilityTimer = setTimeout(() => {
+          if (!pendingControls.has(requestId) || objectControlVersion >= OBJECT_CONTROL_VERSION) return;
+          settleControl(pending, {
+            requestId,
+            operation,
+            id: key,
+            accepted: false,
+            owner: pending.optimistic ? pending.previousOwner : objOwners.get(key),
+            sequence: 0,
+            reason: "unsupported"
+          });
+        }, 500);
+      }
+    });
+  };
   let droppedWhileOffline = 0;
   const send0 = (type, payload, countIfDropped = false) => {
     if (room.connection?.isOpen) {
@@ -355,13 +529,22 @@ function attachSession(client, initialRoom) {
     if (countIfDropped) droppedWhileOffline++;
   };
   const wireRoom = (r) => {
+    let hydrated;
     const $ = getStateCallbacks(r);
     $(r.state).players.onAdd((player, id) => {
       const { state, sendTime } = parseData(player.data);
+      const addEpoch = Number.isFinite(player.epoch) ? player.epoch : 0;
+      const addEpochChanged = playerEpochs.has(id) && addEpoch !== playerEpochs.get(id);
+      playerEpochs.set(id, addEpoch);
+      if (id !== room.sessionId && addEpochChanged) clearStream(id);
       emit("join", id, state);
       if (id !== room.sessionId && sendTime != null) pushSnap(id, state, sendTime);
       $(player).onChange(() => {
         const { state: st, sendTime: ts } = parseData(player.data);
+        const epoch = Number.isFinite(player.epoch) ? player.epoch : 0;
+        const epochChanged = epoch !== (playerEpochs.get(id) ?? epoch);
+        playerEpochs.set(id, epoch);
+        if (id !== room.sessionId && epochChanged) clearStream(id);
         emit("change", id, st);
         if (id !== room.sessionId) pushSnap(id, st, ts);
       });
@@ -370,6 +553,7 @@ function attachSession(client, initialRoom) {
       emit("leave", id);
       clearStream(id);
       parseCache.delete(id);
+      playerEpochs.delete(id);
     });
     $(r.state).shared.onAdd(handleShared);
     $(r.state).shared.onChange(handleShared);
@@ -387,9 +571,57 @@ function attachSession(client, initialRoom) {
         clearStream(key);
         objRaw.delete(id);
         objOwners.delete(id);
+        objEpochs.delete(id);
+        localObjState.delete(id);
+        emit("object", id);
+      }
+    });
+    const hydrateShared = (state) => {
+      const shared = state?.shared;
+      shared?.forEach((value, key) => handleShared(value, key));
+      if (!shared) return;
+      for (const id of /* @__PURE__ */ new Set([...objOwners.keys(), ...objRaw.keys(), ...localObjState.keys()])) {
+        const key = OBJ_PREFIX + id;
+        if (shared.has(key)) continue;
+        lastShared.delete(key);
+        clearStream(key);
+        objRaw.delete(id);
+        objOwners.delete(id);
+        objEpochs.delete(id);
         localObjState.delete(id);
         emit("object", id);
       }
+      if (hostId !== void 0 && !shared.has(HOST_KEY)) {
+        lastShared.delete(HOST_KEY);
+        hostId = void 0;
+        emit("host", void 0);
+      }
+    };
+    if (r.state?.shared) {
+      hydrateShared(r.state);
+      hydrated = Promise.resolve();
+    } else {
+      hydrated = new Promise((resolve) => {
+        r.onStateChange.once((state) => {
+          hydrateShared(state);
+          resolve();
+        });
+      });
+    }
+    r.onMessage(CAPABILITIES_MSG, (msg) => {
+      if (typeof msg?.objectControl === "number") {
+        objectControlVersion = Math.max(objectControlVersion, msg.objectControl);
+        flushCapabilityWaiters();
+      }
+    });
+    r.onMessage(CAPABILITIES_REQUEST_MSG, () => {
+    });
+    send0(CAPABILITIES_REQUEST_MSG, { objectControl: OBJECT_CONTROL_VERSION });
+    r.onMessage(OBJECT_CONTROL_RESULT_MSG, (msg) => {
+      if (!msg || typeof msg.requestId !== "string") return;
+      const pending = pendingControls.get(msg.requestId);
+      if (!pending || msg.operation !== pending.operation || msg.id !== pending.id) return;
+      settleControl(pending, msg);
     });
     r.onMessage(INPUT_MSG, (msg) => {
       if (msg && typeof msg.from === "string") emit(INPUT_MSG, msg.from, msg.d);
@@ -403,12 +635,17 @@ function attachSession(client, initialRoom) {
     r.onLeave((code) => handleLeave(r, code ?? 1006));
     r.onError(() => {
     });
+    return hydrated;
   };
   const handleLeave = (left, code) => {
     if (left !== room || dead) return;
+    connected = false;
+    reconnectStartedAt ||= nowMs();
+    syncHostTicks();
     if (intentionalLeave) return;
     if (code === 1e3 || code >= 4e3) {
       dead = true;
+      settleAllControls("disconnected");
       emit("disconnect", code);
       return;
     }
@@ -421,7 +658,17 @@ function attachSession(client, initialRoom) {
       try {
         const next = await client.reconnect(token);
         room = next;
-        wireRoom(next);
+        connected = true;
+        const reconnectGap = reconnectStartedAt ? nowMs() - reconnectStartedAt : 0;
+        reconnectStartedAt = 0;
+        if (reconnectGap > 1e3) {
+          for (const streamKey of [...buffers.keys()]) clearStream(streamKey);
+        }
+        const hydrated = wireRoom(next);
+        await Promise.race([hydrated, new Promise((r) => setTimeout(r, 2e3))]);
+        if (room !== next || dead || intentionalLeave) return;
+        syncHostTicks();
+        for (const pending of pendingControls.values()) sendPendingControl(pending);
         emit("reconnected");
         if (droppedWhileOffline > 0) {
           console.warn(
@@ -438,6 +685,7 @@ function attachSession(client, initialRoom) {
       }
     }
     dead = true;
+    settleAllControls("disconnected");
     emit("disconnect", code);
   };
   wireRoom(room);
@@ -482,6 +730,14 @@ function attachSession(client, initialRoom) {
         const clean = sanitizeFinite(state);
         localState = clean;
         send0("state", JSON.stringify({ ...clean, [SEND_TIME_KEY]: now() }));
+      },
+      snap(state) {
+        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_SNAP_MSG, JSON.stringify({ ...clean, [SEND_TIME_KEY]: now() }));
       }
     },
     shared: {
@@ -503,6 +759,9 @@ function attachSession(client, initialRoom) {
         objOwners.set(key, room.sessionId);
         send0("claim", { id: key });
       },
+      claimConfirmed(id, options) {
+        return confirmedControl("claim", id, options);
+      },
       release(id) {
         const key = String(id);
         localObjState.delete(key);
@@ -510,6 +769,9 @@ function attachSession(client, initialRoom) {
         clearStreamClock(OBJ_PREFIX + key);
         send0("release", { id: key });
       },
+      releaseConfirmed(id, options) {
+        return confirmedControl("release", id, options);
+      },
       remove(id) {
         const key = String(id);
         if (objOwners.get(key) === room.sessionId) {
@@ -520,12 +782,21 @@ function attachSession(client, initialRoom) {
         }
         send0("destroy", { id: key });
       },
+      removeConfirmed(id, options) {
+        return confirmedControl("remove", id, options);
+      },
       set(id, state) {
         const key = String(id);
         const clean = sanitizeFinite(state);
         if (objOwners.get(key) === room.sessionId) localObjState.set(key, clean);
         send0("obj", { id: key, d: clean, t: now() });
       },
+      snap(id, state) {
+        const key = String(id);
+        const clean = sanitizeFinite(state);
+        if (objOwners.get(key) === room.sessionId) localObjState.set(key, clean);
+        send0(OBJECT_SNAP_MSG, { id: key, d: clean, t: now() });
+      },
       get(id) {
         const key = String(id);
         const owner = objOwners.get(key);
@@ -543,7 +814,14 @@ function attachSession(client, initialRoom) {
           raw = objRaw.get(key) ?? {};
           state = sampleSmoothed(OBJ_PREFIX + key, now()) ?? raw;
         }
-        return { id: key, owner, isMine, state, stateRaw: raw };
+        return {
+          id: key,
+          epoch: objEpochs.get(key) ?? 0,
+          owner,
+          isMine,
+          state,
+          stateRaw: raw
+        };
       },
       ids() {
         return [.../* @__PURE__ */ new Set([...objOwners.keys(), ...objRaw.keys(), ...localObjState.keys()])];
@@ -570,24 +848,28 @@ function attachSession(client, initialRoom) {
     onHostTick(hz, cb) {
       let timer = null;
       let last = 0;
+      const safeHz = Number.isFinite(hz) && hz > 0 ? Math.min(hz, 100) : 20;
+      const intervalMs = Math.max(10, Math.round(1e3 / safeHz));
       const sync = () => {
-        const shouldRun = hostId !== void 0 && hostId === room.sessionId;
+        const shouldRun = connected && !intentionalLeave && !dead && hostId !== void 0 && hostId === room.sessionId;
         if (shouldRun && !timer) {
           last = nowMs();
           timer = setInterval(() => {
             const t = nowMs();
             cb(Math.min(t - last, 250));
             last = t;
-          }, Math.max(10, Math.round(1e3 / hz)));
+          }, intervalMs);
         } else if (!shouldRun && timer) {
           clearInterval(timer);
           timer = null;
         }
       };
       const off = on("host", sync);
+      hostTickSyncs.add(sync);
       sync();
       return () => {
         off();
+        hostTickSyncs.delete(sync);
         if (timer) clearInterval(timer);
         timer = null;
       };
@@ -602,6 +884,9 @@ function attachSession(client, initialRoom) {
     },
     leave() {
       intentionalLeave = true;
+      connected = false;
+      syncHostTicks();
+      settleAllControls("aborted");
       void room.leave();
     }
   };
@@ -668,7 +953,7 @@ function buildView(matchRoom, queueInfo) {
   };
 }
 async function matchmake(opts) {
-  const client = new Client(opts.url);
+  const client = await relayClient(opts);
   const emitters = /* @__PURE__ */ new Map();
   const emit = (event, ...args) => emitters.get(event)?.forEach((cb) => cb(...args));
   const on = ((event, cb) => {
@@ -849,14 +1134,14 @@ function wirePrivate(client, room) {
   };
 }
 async function createPrivate(opts) {
-  const client = new Client(opts.url);
+  const client = await relayClient(opts);
   const room = await client.create(MATCH_ROOM_TYPE, matchJoinOptions(opts));
   const handle = wirePrivate(client, room);
   Object.defineProperty(handle, "code", { value: room.roomId, enumerable: true });
   return handle;
 }
 async function joinPrivate(code, opts) {
-  const client = new Client(opts.url);
+  const client = await relayClient(opts);
   const room = await client.joinById(code, matchJoinOptions(opts));
   return wirePrivate(client, room);
 }

package/dist/schema.d.ts

@@ -4,9 +4,11 @@ import { SchemaType, MapSchema } from '@colyseus/schema';
 declare const PlayerState: _colyseus_schema.SchemaWithExtendsConstructor<{
     name: "string";
     data: "string";
+    epoch: "number";
 }, _colyseus_schema.AssignableProps<_colyseus_schema.InferSchemaInstanceType<{
     name: "string";
     data: "string";
+    epoch: "number";
 }>>, typeof _colyseus_schema.Schema>;
 type PlayerState = SchemaType<typeof PlayerState>;
 declare const RoomState: _colyseus_schema.SchemaWithExtendsConstructor<{
@@ -14,13 +16,16 @@ declare const RoomState: _colyseus_schema.SchemaWithExtendsConstructor<{
         map: _colyseus_schema.SchemaWithExtendsConstructor<{
             name: "string";
             data: "string";
+            epoch: "number";
         }, _colyseus_schema.AssignableProps<_colyseus_schema.InferSchemaInstanceType<{
             name: "string";
             data: "string";
+            epoch: "number";
         }>>, typeof _colyseus_schema.Schema>;
         default: MapSchema<_colyseus_schema.InferSchemaInstanceType<{
             name: "string";
             data: "string";
+            epoch: "number";
         }>, string>;
     };
     shared: {
@@ -32,13 +37,16 @@ declare const RoomState: _colyseus_schema.SchemaWithExtendsConstructor<{
         map: _colyseus_schema.SchemaWithExtendsConstructor<{
             name: "string";
             data: "string";
+            epoch: "number";
         }, _colyseus_schema.AssignableProps<_colyseus_schema.InferSchemaInstanceType<{
             name: "string";
             data: "string";
+            epoch: "number";
         }>>, typeof _colyseus_schema.Schema>;
         default: MapSchema<_colyseus_schema.InferSchemaInstanceType<{
             name: "string";
             data: "string";
+            epoch: "number";
         }>, string>;
     };
     shared: {

package/dist/schema.js

@@ -3,7 +3,10 @@ import { schema, MapSchema } from "@colyseus/schema";
 var PlayerState = schema(
   {
     name: "string",
-    data: "string"
+    data: "string",
+    // Relay-owned discontinuity epoch. Ordinary state updates keep it stable;
+    // state:snap increments it so new SDKs discard interpolation history.
+    epoch: "number"
   },
   "PlayerState"
 );

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@genex-ai/multiplayer",
-  "version": "0.8.8",
+  "version": "0.10.0",
   "description": "The multiplayer client wrapper + shared room schema for genex.",
   "type": "module",
   "main": "./dist/index.js",
@@ -30,8 +30,8 @@
     "access": "public"
   },
   "dependencies": {
-    "@colyseus/schema": "^3.0.76",
-    "colyseus.js": "^0.16.22"
+    "@colyseus/schema": "^4.0.27",
+    "@colyseus/sdk": "^0.17.43"
   },
   "peerDependencies": {
     "three": ">=0.160.0"