@genex-ai/multiplayer 0.10.1 → 0.11.0

package/README.md

@@ -34,6 +34,13 @@ across reconnects. Never log it.
 
 Different `room` ids are **fully isolated** — players in game A never see game B.
 
+`connect()` joins immediately. Use it for one ongoing drop-in world. If the game has a
+Play/Online/Local/Bots menu, call it only after the online click and call `room.leave()` when the
+player returns to the offline menu. Immediate connect + spawn is valid only when loading the game
+already means joining the always-online world; do not put a fake Play screen in front of a player
+who is already present. Use `matchmake()` below for fresh bounded sessions with queue/quorum/fair
+start/backfill behavior.
+
 ---
 
 ## `me` — publish your own state
@@ -101,7 +108,11 @@ 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.
+player. `state` is render-only and smoothed; `stateRaw` is the raw latest for every gameplay read
+(hit-tests, reach, pickups, physics adoption, discrete values). `objects.ids()` lists them.
+`objects.set()` and `objects.snap()` are owner-only: SDK 0.10.2+ ignores an unowned call and warns
+once per object/operation. Await `claimConfirmed()` and check `accepted` before an irreversible
+write; legacy `claim(); set()` remains valid because `claim()` is optimistic locally.
 
 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

package/dist/index.d.ts

@@ -9,6 +9,11 @@ type ConnectOptions = {
     /** Regional relay urls (pass `getColyseusUrls()`) — the SDK pings each and connects to the
      *  lowest-latency one; a single entry just connects. */
     urls: string[];
+    /** Cross-region invite override: connect to THIS exact relay url, skipping latency selection. Two
+     *  players are only in the same room if they share one region's relay, so an invitee must follow the
+     *  inviter's region (carried in the invite) instead of picking its own nearest. Omit for normal
+     *  nearest-region play. */
+    url?: 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;
@@ -34,8 +39,9 @@ type PlayerView<TState> = {
     name: string;
     /** Transport is live now. False while this reserved seat is inside reconnect grace. */
     connected: boolean;
-    /** State to render — for remote players this is **auto-smoothed** (interpolated);
-     * for yourself it's live. Numeric fields are lerped; everything else snaps. */
+    /** RENDER ONLY — for remote players this is **auto-smoothed** (interpolated) and delayed;
+     * for yourself it's live. Numeric fields are lerped; everything else snaps. Use `stateRaw`
+     * for every gameplay read (hits, reach, pickups, flags, physics adoption). */
     state: TState;
     /** The latest raw snapshot (never smoothed/delayed) — use for hit-tests / logic. */
     stateRaw: TState;
@@ -49,8 +55,8 @@ type ObjectView<TState> = {
     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. */
+    /** RENDER ONLY — **auto-smoothed** and delayed like a remote player when someone else owns it;
+     * live (your last `set`) when it's yours. Use `stateRaw` for every gameplay read. */
     state: TState;
     /** The latest raw snapshot (never smoothed/delayed) — for hit-tests / logic. */
     stateRaw: TState;
@@ -276,6 +282,9 @@ type Matchmaking<TState extends Record<string, unknown>> = {
 type MatchmakeOptions = {
     /** Regional relay urls (pass `getColyseusUrls()`) — pings each, connects to the lowest-latency one. */
     urls: string[];
+    /** Cross-region override: matchmake on THIS exact relay url, skipping latency selection — an invitee
+     *  follows the inviter's region so both land on the same relay. Omit for normal nearest-region play. */
+    url?: string;
     /** Game id (your project slug/id) — isolates this game's matchmaking. */
     room: string;
     name?: string;

package/dist/index.js

@@ -28,6 +28,7 @@ var STATE_SNAP_MSG = "__state:snap";
 var OBJECT_SNAP_MSG = "__object:snap";
 var MP_PROTOCOL = 2;
 async function relayClient(opts) {
+  if (opts.url) return new Client(opts.url);
   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");
@@ -208,6 +209,7 @@ function attachSession(client, initialRoom) {
   const objEpochs = /* @__PURE__ */ new Map();
   const objRaw = /* @__PURE__ */ new Map();
   const localObjState = /* @__PURE__ */ new Map();
+  const warnedUnownedWrites = /* @__PURE__ */ new Set();
   const pendingBridge = /* @__PURE__ */ new Map();
   let hostId;
   let objectControlVersion = 0;
@@ -215,6 +217,17 @@ function attachSession(client, initialRoom) {
   const pendingControls = /* @__PURE__ */ new Map();
   const testSkew = typeof globalThis !== "undefined" && globalThis.__GENEX_MP_TEST_SKEW__ || 0;
   const now = testSkew ? () => nowMs() + testSkew : nowMs;
+  const rejectUnownedWrite = (operation, id) => {
+    if (objOwners.get(id) === room.sessionId) return false;
+    const warningKey = `${operation}:${id}`;
+    if (!warnedUnownedWrites.has(warningKey)) {
+      warnedUnownedWrites.add(warningKey);
+      console.warn(
+        `[multiplayer] objects.${operation}('${id}') ignored because this session does not own the object \u2014 await objects.claimConfirmed('${id}') and check accepted before publishing`
+      );
+    }
+    return true;
+  };
   const pushSnap = (id, state, sendTime) => {
     const arrival = now();
     const t = sendTime ?? arrival;
@@ -801,12 +814,14 @@ function attachSession(client, initialRoom) {
       },
       set(id, state) {
         const key = String(id);
+        if (rejectUnownedWrite("set", key)) return;
         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);
+        if (rejectUnownedWrite("snap", key)) return;
         const clean = sanitizeFinite(state);
         if (objOwners.get(key) === room.sessionId) localObjState.set(key, clean);
         send0(OBJECT_SNAP_MSG, { id: key, d: clean, t: now() });

package/package.json

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