@genex-ai/multiplayer 0.16.2 → 0.17.0

package/README.md

@@ -8,6 +8,17 @@ Tiny realtime multiplayer for genex games.
 import { connect } from '@genex-ai/multiplayer';
 ```
 
+**Wire protocol.** This SDK speaks Genex relay protocol 3 over Colyseus 0.18. The language-neutral
+contract — room state, messages, limits, close codes, reconnection, interpolation — is
+[`PROTOCOL.md`](./PROTOCOL.md), and its machine-readable constants ship as
+`@genex-ai/multiplayer/protocol` (the shared room schema as `@genex-ai/multiplayer/schema`).
+Another engine's client conforms to that, not to this README.
+
+> **0.17.0 is a breaking release: it needs a protocol-3 relay (Colyseus 0.18).** 0.16.x speaks
+> protocol 2 on Colyseus 0.17 and is refused by the new relay, and 0.17.0 cannot join an old one —
+> rebuild and republish a game to move it across. The game-facing API is unchanged except for the
+> additions marked *0.17.0* below.
+
 ---
 
 ## Connect
@@ -65,6 +76,13 @@ for (const [id, p] of room.players) {
 
 Remote players glide instead of teleporting between network updates — see **[Smoothing remote players](#smoothing-remote-players)**.
 
+Each player carries `p.uid` (*0.17.0*): their stable id **in this game** — the same across reloads,
+devices and rooms of the game, different in every other game, never the account id. Key anything
+that outlives a session (scores, colours, saves, "is this me") by `uid`, never by `id`, which is a
+session id and changes on every reload. It is opaque; never parse it. `p.team` (*0.17.0*) is the
+team index the relay assigned (`-1` = none): the `open` preset's `teams: N` knob (kept by `uid` for the
+room's life) or the `teams` preset's current round.
+
 Each player also carries `p.avatarUrl` — the VRM avatar that player picked on their genex profile (guests get a per-session pick), verified server-side from their identity token so it can't be spoofed. It's the **fallback** body, not the default one: in a game that generated its own character, every player wears that character, and `p.avatarUrl` renders each player's own look only when the game has none. The genex controller kit's `loadRemotePlayerCharacter({ avatarUrl: p.avatarUrl })` makes that decision for you and shares one parsed base across remotes. The field is `''` when unknown (older relay/API), so always keep a bundled fallback. Don't put an avatar URL in your `me.set` state — this field replaces that.
 
 ## `shared` — shared room state
@@ -112,24 +130,22 @@ 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 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
+`objects.set()` and `objects.snap()` are owner-only: the SDK 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.
+write; `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
-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`.
+reassert is a true no-op: it does not extend that hold. `claim()`, `release()` and `remove()` are
+fire-and-forget: they send the same request as the confirmed methods and ignore the answer — a lost
+`claim()` reverts its optimistic ownership. Use the confirmed methods when feedback, impulses, seats,
+scoring, release, or removal must not lie. Every request carries a stable request id and is resent
+after a reconnect, so an accepted operation is idempotent. A rejected result reports the current
+owner and, for `held` / `rate-limited`, `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).
+authoritative before tearing anything down.
 
 `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
@@ -153,7 +169,9 @@ room.on('host', (id) => {});                             // host changed (migrat
 ```
 
 `isHost`/`host` settle within the first patch after `connect()` — read them in your loop (or react
-to `on('host')`), not once at startup.
+to `on('host')`), not once at startup. `isHost` is `false` while the session is reconnecting, until
+the fresh snapshot says who the host is now (*0.17.0*), so a write behind it is never a stale
+ex-host's; `host` is the raw field.
 
 ## `on` — events
 
@@ -166,6 +184,8 @@ room.on('object', (id)        => {});  // an object's owner changed — the rend
 room.on('host',   (id)        => {});  // the room host changed
 room.on('hit',    (payload)   => {});  // a custom event someone sent (see `send`)
 
+room.on('room:open', ({ open })  => {}); // the host opened/closed the room to newcomers (setRoomOpen)
+
 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
@@ -176,7 +196,8 @@ room.on('disconnect',   (code)        => {}); // terminal — connect() fresh to
 ## Reconnection (automatic)
 
 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
+seat for a grace window (~30s) and the Colyseus client reconnects the same room in place, with backoff
+(~0.25s→4s, nine attempts, the last one ~24s in — inside the grace). 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.
@@ -184,15 +205,20 @@ Host-tick callbacks pause while their socket is reconnecting and resume only if
 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.
 
+Every drop takes this path, however long the session has been up. `reconnecting` fires once per
+attempt; `reconnected` fires only after the room's state is current again, so `isHost`, owners and the
+roster are safe to read in it. Nothing you send while disconnected is queued: player and object state
+self-heal on the next publish, and lost `send()` events / inputs are counted in a console warning.
+
 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
+(server restart, revoked session `4401`, or the link never recovered `4003`): 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
+`disconnect`, code 4409 — do not reconnect automatically on it: the player is playing in the newer
+tab), 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)
@@ -223,7 +249,9 @@ and seed its world from each object's `stateRaw`, so simulation survives host mi
 
 ## `send` — custom one-off events
 
-Fire-and-forget to all **other** clients (not stored in state). For shots, emotes, pings.
+Fire-and-forget to all **other** clients (not stored in state). For shots, emotes, pings. The relay's
+own names are refused with a warning: `state`, `shared`, `claim`, `release`, `destroy`, `obj`,
+`queue`, `seat`, anything starting `__`, `match:`, `server:` or `rate:`, and names over 128 characters.
 
 ```ts
 room.send('hit', { from: room.id, target: 'xyz', dmg: 10 });
@@ -369,6 +397,44 @@ bounded extrapolation.
 
 ---
 
+## Experimental options (off by default)
+
+These are A/B arms of the netcode bench ([PROTOCOL.md](PROTOCOL.md) §15). Each stays off by default
+until it wins its gate, and one that loses is marked rejected below; leave them alone unless you are
+running that experiment. They are accepted by
+`connect()`, `matchmake()`, `createPrivate()` and `joinPrivate()`.
+
+**`pose: true` — typed pose** (PROTOCOL.md §6.6). The reserved keys `x y z yaw vx vy vz anim` of
+`me.set()` / `me.snap()` travel as typed relay fields (float32 deltas instead of the whole JSON state
+re-sent on every tick); everything else is `data`, sent only when it changes. Omit `vx/vy/vz` and they
+are derived from successive positions. Turn it on for **every** client of a game at once. With it on,
+remote players interpolate **only** the pose (`yaw` in radians, along the shortest arc; `anim` switches
+when the rendered pose reaches it) and **snap** everything else — a rotation synced as a quaternion is
+no longer smoothed, so put the heading in `yaw`. A remote posed player's `state` always carries all
+eight pose keys. Needs a relay that accepts `__pose`.
+
+```ts
+const room = await connect<State>({ urls, room: gameId, auth, pose: true });
+room.me.set({ x, y, z, yaw, anim: 'run', hp });   // x..anim → typed pose, hp → data
+```
+
+**`smoothing: 'predict'` — REJECTED, bench-only. Do not ship it.** It lost its A/B: with the clock
+off, remote players under it showed 18–23 teleports and a speed CV of about 1.9–2.0 on broadband,
+mixed-ping skew and a background-tab sender, against 0 teleports and about 0.40 for the default engine,
+and on a burst stall a 753 ms freeze (default 436 ms). The numbers are in the
+[netcode-bench README](../netcode-bench/README.md#predict-rejected). The option stays only so the bench
+can rerun the comparison; games keep the default `'genex'`. (It hands posed players' numeric pose to
+Colyseus `Predict`: receive-time stamps, a fixed delay, no dead reckoning past the newest sample.)
+
+**Server clock** (PROTOCOL.md §16). Against a relay that publishes its clock, every session sends a
+small heartbeat at 10 Hz and exposes `room.serverNow()` (ms since the room was created), `room.rtt`
+(smoothed round trip in ms) and `room.clockSynced`. Against any other relay they are `undefined` /
+`false` and nothing is sent. `room.timeUntil(epochMs)` works everywhere: milliseconds until a relay
+deadline, on the server clock once synced and on `Date.now()` before. Remote smoothing never uses the
+server clock.
+
+---
+
 ## Complete minimal example (move a cube, see others as cubes)
 
 ```ts
@@ -430,6 +496,9 @@ mm.on("spectate", () => {/* DEPRECATED — never fires: there are no server-side
                             An overflow searcher now waits in the queue instead of watching. */});
 mm.on("error", (e) => {/* queue join failed even after the SDK's automatic retries — persistent
                           (broken auth / server unreachable); fix the cause, then mm.retry() */});
+mm.on("disconnect", (code) => {/* *0.17.0*: the match seat ended with 4409 (opened in another tab or
+                          device) or 4401 (signed out). The handle stops and does NOT requeue —
+                          tell the player; mm.retry() only if they choose to play here again */});
 
 // Report ONLY your own outcome — the server adjudicates. Pick the call that matches the win condition:
 mm.eliminated();   // I'm out              (lastStanding)
@@ -442,9 +511,11 @@ mm.cancel();       // stop searching / leave the match
 
 A failed queue join is **retried automatically** with backoff (~10s total), so transient failures
 (a token mid-rotation, identity still settling on page load) never surface. Only a persistent
-failure emits `error`; the handle then idles until you call `mm.retry()`.
+failure emits `error`; the handle then idles until you call `mm.retry()`. A relay that refuses this
+SDK's protocol (error code `426`) emits `error` at once — the game needs an SDK update, and retrying
+cannot help (`connect()` rejects with the same code).
 
-**`mm.matchmaking`** (read every frame for your HUD): `status` (`searching` | `waiting` | `countdown` | `playing` | `ended`; the legacy `spectating` is never emitted — server-side spectators were removed), `queue` (`{ position, size }`), `players` (reserved seats), `connectedPlayers` (live transports), `opponents`, `teams`, `myTeam`, `scores`, `winCondition`, `config` (numeric knobs), `roundId`, `winnerId`, `message`. `championId`/`challengerId` are 1v1 aliases. During an automatic reconnect, the SDK retains the last coherent roster and match view until the replacement room hydrates, so status does not transiently regress to `waiting`.
+**`mm.matchmaking`** (read every frame for your HUD): `status` (`searching` | `waiting` | `countdown` | `playing` | `ended`; the legacy `spectating` is never emitted — server-side spectators were removed), `queue` (`{ position, size }`), `players` (reserved seats), `connectedPlayers` (live transports), `opponents`, `teams`, `myTeam`, `scores`, `winCondition`, `config` (numeric knobs), `roundId`, `winnerId`, `message`, and the relay's deadlines: `startsAt` / `endsBy` (epoch ms, or `null`) with `startsInMs` / `endsInMs` — the time left as of this read, measured on the relay's server clock once it is synced, so a countdown is right even when the player's device clock is wrong. Draw countdowns from `startsInMs` / `endsInMs`, never from `startsAt − Date.now()`. `championId`/`challengerId` are 1v1 aliases. During an automatic reconnect the room keeps its decoded state, so status does not transiently regress to `waiting`.
 
 Configure once in the game's `package.json` (reported at `genex preview` AND `genex publish`;
 removing it clears the stored config on the next preview/publish — never sent from the client):
@@ -461,7 +532,7 @@ removing it clears the stored config on the next preview/publish — never sent
 
 Presets: **open** (a room of N players, your rules — see below), **duel** (1v1 winner-stays), **arena** (N-player FFA, join-anytime), **teams** (balanced N-v-N), **private** (invite-code lobby). Win conditions (for the batteries-included presets): **lastStanding**, **firstToScore**, **highScoreInTime**, **firstToFinish**; a round that hits the time cap undecided is a draw.
 
-**`open` — bring your own rules.** The minimal preset: the server owns only seating, capacity, and refill; you build teams, rounds, scoring, and win logic yourself on `session.shared` + host election. It runs no match loop, so `status` only goes `waiting`→`playing` (never `ended`), `scores`/`winnerId` stay empty, and **nobody is ever evicted** (no `matchEnded`, no requeue). Config knobs: `minPlayers` (quorum to flip to `playing`; default 1), `maxPlayers` (seat cap, clamped 2–64), `fill` (`1` = keep the room full — grow to max and refill a seat a leaver frees, the default; `0` = lock the room for good once it is simultaneously full (max players at once) — a match with no substitutes; a freed seat stays closed). Pick `open` when you want your own rules; pick duel/arena/teams for a ready-made match loop.
+**`open` — bring your own rules.** The minimal preset: the server owns only seating, capacity, and refill; you build teams, rounds, scoring, and win logic yourself on `session.shared` + host election. It runs no match loop, so `status` only goes `waiting`→`playing` (never `ended`), `scores`/`winnerId` stay empty, and **nobody is ever evicted** (no `matchEnded`, no requeue). Config knobs: `minPlayers` (quorum to flip to `playing`; default 1), `maxPlayers` (seat cap, clamped 2–64), `fill` (`1` = keep the room full — grow to max and refill a seat a leaver frees, the default; `0` = lock the room for good once it is simultaneously full (max players at once) — a match with no substitutes; a freed seat stays closed), and `teams` (*0.17.0*; `2`…`min(8, maxPlayers)`: the relay puts each seated player on the smallest team and reports it as `p.team` and in `matchmaking.teams`, never moves a seated player, and gives a returning player — matched by `uid` — the team they had; any other value means no teams). Pick `open` when you want your own rules; pick duel/arena/teams for a ready-made match loop.
 
 ### Private lobbies — `createPrivate` / `joinPrivate`
 
@@ -514,6 +585,25 @@ closed, or its host is on another region's relay than this player's nearest one.
 and show the menu. Keep the typed code as the second way in: a shell that does not pass the
 link's parameter on yet opens the game without it.
 
+## Engine bridge — `@genex-ai/multiplayer/bridge`
+
+For engines that build to the web and cannot hold JS objects: Rust (`wasm-bindgen`), Godot web
+exports. A flat facade over this SDK: a session is a numeric handle, every value crosses as a JSON
+string, a number or a boolean, and `drainEventsJson(handle)` hands over everything that happened
+since the last call, once per frame. Identity comes from `@genex-ai/embed-sdk` (an optional peer of
+this package; install it to use the bridge), with a fresh token for every join. The contract is
+[`sdks/rust/BRIDGE.md`](../../sdks/rust/BRIDGE.md).
+
+```js
+import { connect, setMe, playersJson, drainEventsJson } from '@genex-ai/multiplayer/bridge';
+const h = await connect(JSON.stringify({ gameId: 'my-game', name: 'ada', urls: [] }));
+setMe(h, JSON.stringify({ x: 1 }));
+for (const e of JSON.parse(drainEventsJson(h))) { /* { type: 'playerJoined', id }, … */ }
+```
+
+Pages with no bundler load `dist/bridge.global.js` (the SDK and embed-sdk bundled in), which sets
+`window.GenexMultiplayerBridge`. A JS game should use the SDK directly, not the bridge.
+
 ## Rules of thumb
 
 - **`me` / `shared` are synced; everything else is local.** Movement input → mutate a local object → `me.set` it on the tick.

package/dist/bridge.d.ts

@@ -0,0 +1,89 @@
+/** The contract version (BRIDGE.md). Bumped only on a breaking change to a signature or a shape. */
+declare const version = 1;
+type Json = Record<string, unknown>;
+/** One queued event: `{ type, ...fields }` (BRIDGE.md, "Events"). */
+type BridgeEvent = {
+    type: string;
+} & Json;
+/**
+ * Where the bridge gets the player's identity. The default is `@genex-ai/embed-sdk`; a host page
+ * or a test replaces it with {@link setIdentity}.
+ */
+type BridgeIdentity = {
+    /** Resolves once a player exists (guest or signed in); rejects when there never will be one. */
+    ready(gameId: string): Promise<unknown> | unknown;
+    /** The join credential, read fresh for EVERY join (never cached). `undefined` = tokenless. */
+    auth(): {
+        embedToken: string;
+    } | undefined;
+    /** The relay URLs to use when the engine passes none. */
+    urls(): string[];
+};
+/**
+ * Replace the identity source (`null` restores embed-sdk). For a host page that manages identity
+ * itself, and for tests against a token-free local relay. Not part of the engine contract.
+ */
+declare function setIdentity(next: BridgeIdentity | null): void;
+/**
+ * Start a join and return its handle at once. The outcome arrives as a `joined` (or, for
+ * `room: "queue"`, a `seated` then `joined` when a match is found) or a `joinFailed` event.
+ * Throws only for malformed options.
+ */
+declare function open(optsJson: string): number;
+/**
+ * Wait for the player's identity, then join. Resolves with the handle once seated (a queue join
+ * resolves once it is searching). Rejects with an `Error` carrying `code` when the join is
+ * refused (§3.4; 426 = never retry).
+ */
+declare function connect(optsJson: string): Promise<number>;
+/** Leave with consent: `disconnected` (4000, "left") follows, as on native. */
+declare function leave(handle: number): void;
+/**
+ * Leave (if still seated) and forget the handle, freeing its queue and views: the engine
+ * dropped its session object. Afterwards the handle answers as an unknown one. Idempotent.
+ */
+declare function dispose(handle: number): void;
+declare function setMe(handle: number, json: string): boolean;
+declare function snapMe(handle: number, json: string): boolean;
+declare function setShared(handle: number, key: string, json: string): boolean;
+declare function setObject(handle: number, id: string, json: string): boolean;
+declare function snapObject(handle: number, id: string, json: string): boolean;
+/** A game event to every other client. `false` for a reserved type or with no live session. */
+declare function send(handle: number, type: string, json: string): boolean;
+/**
+ * Kept for engine API parity, and deliberately a no-op: every game event already arrives as a
+ * `message` through the room's `*` handler. Subscribing by name went through `session.on(type)`,
+ * which for a name the session emits itself (`join`, `change`, `leave`, `host`, …) attached to
+ * that LOCAL event and queued a fake `message` per peer join or state change — while the real
+ * game event of the same name still arrived through `*`.
+ */
+declare function listen(_handle: number, _type: string): void;
+declare function sendInput(handle: number, json: string): boolean;
+declare function setRoomOpen(handle: number, open: boolean): boolean;
+declare function chatSend(handle: number, text: string): boolean;
+/** Ask for ownership; the answer is a `controlResult` event carrying the CALLER's `requestId`. */
+declare function claim(handle: number, id: string, requestId: string): void;
+/** `claim` with host authority: displaces an active owner's hold (seeding and resets only). */
+declare function claimAsHost(handle: number, id: string, requestId: string): void;
+declare function release(handle: number, id: string, requestId: string): void;
+/** Owner-only removal; its result's `operation` is `"remove"`. */
+declare function destroy(handle: number, id: string, requestId: string): void;
+declare function reportEliminated(handle: number): boolean;
+declare function reportScore(handle: number, delta?: number): boolean;
+declare function reportFinish(handle: number): boolean;
+/** The relay room clock (ms since the room was created), or `null` without one (§16). */
+declare function serverNow(handle: number): number | null;
+/** Milliseconds until a relay epoch-ms deadline: on the server clock once synced (§16.3). */
+declare function timeUntil(handle: number, epochMs: number): number;
+declare function sessionJson(handle: number): string;
+declare function playersJson(handle: number): string;
+declare function objectsJson(handle: number): string;
+declare function sharedJson(handle: number): string;
+/**
+ * Every event queued since the last call, oldest first, as a JSON array. Never throws; an unknown
+ * or finished handle answers `[]`. A finished handle keeps only its ids and queue; handles are never
+ * reused.
+ */
+declare function drainEventsJson(handle: number): string;
+
+export { type BridgeEvent, type BridgeIdentity, chatSend, claim, claimAsHost, connect, destroy, dispose, drainEventsJson, leave, listen, objectsJson, open, playersJson, release, reportEliminated, reportFinish, reportScore, send, sendInput, serverNow, sessionJson, setIdentity, setMe, setObject, setRoomOpen, setShared, sharedJson, snapMe, snapObject, timeUntil, version };