@genex-ai/multiplayer 0.10.2 → 0.12.0

package/README.md

@@ -65,6 +65,8 @@ 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 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. Render each player's own look with it (e.g. `loadVrm(p.avatarUrl || "./assets/avatar.vrm")` in a VRM-lane game); it's `''` 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
 
 A key/value store (any JSON) synced to everyone. Use for world state, scores, the current round, etc.

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;
@@ -32,6 +37,11 @@ type ConnectOptions = {
 type PlayerView<TState> = {
     id: string;
     name: string;
+    /** This player's verified VRM avatar URL (the avatar they picked on their
+     * genex profile; guests get a per-session pick). Server-set from the embed
+     * token — cannot be spoofed. `''` when unknown (old relay/API). Load it for
+     * the player's visual; fall back to your bundled model when empty. */
+    avatarUrl: string;
     /** Transport is live now. False while this reserved seat is inside reconnect grace. */
     connected: boolean;
     /** RENDER ONLY — for remote players this is **auto-smoothed** (interpolated) and delayed;
@@ -277,6 +287,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");
@@ -735,6 +736,8 @@ function attachSession(client, initialRoom) {
         out.set(id, {
           id,
           name: p.name,
+          avatarUrl: p.avatarUrl ?? "",
+          // old relay schemas did not carry the field
           connected: p.connected !== false,
           // old relay schemas did not carry the field
           state,

package/dist/schema.d.ts

@@ -6,11 +6,13 @@ declare const PlayerState: _colyseus_schema.SchemaWithExtendsConstructor<{
     data: "string";
     epoch: "number";
     connected: "boolean";
+    avatarUrl: "string";
 }, _colyseus_schema.AssignableProps<_colyseus_schema.InferSchemaInstanceType<{
     name: "string";
     data: "string";
     epoch: "number";
     connected: "boolean";
+    avatarUrl: "string";
 }>>, typeof _colyseus_schema.Schema>;
 type PlayerState = SchemaType<typeof PlayerState>;
 declare const RoomState: _colyseus_schema.SchemaWithExtendsConstructor<{
@@ -20,17 +22,20 @@ declare const RoomState: _colyseus_schema.SchemaWithExtendsConstructor<{
             data: "string";
             epoch: "number";
             connected: "boolean";
+            avatarUrl: "string";
         }, _colyseus_schema.AssignableProps<_colyseus_schema.InferSchemaInstanceType<{
             name: "string";
             data: "string";
             epoch: "number";
             connected: "boolean";
+            avatarUrl: "string";
         }>>, typeof _colyseus_schema.Schema>;
         default: MapSchema<_colyseus_schema.InferSchemaInstanceType<{
             name: "string";
             data: "string";
             epoch: "number";
             connected: "boolean";
+            avatarUrl: "string";
         }>, string>;
     };
     shared: {
@@ -44,17 +49,20 @@ declare const RoomState: _colyseus_schema.SchemaWithExtendsConstructor<{
             data: "string";
             epoch: "number";
             connected: "boolean";
+            avatarUrl: "string";
         }, _colyseus_schema.AssignableProps<_colyseus_schema.InferSchemaInstanceType<{
             name: "string";
             data: "string";
             epoch: "number";
             connected: "boolean";
+            avatarUrl: "string";
         }>>, typeof _colyseus_schema.Schema>;
         default: MapSchema<_colyseus_schema.InferSchemaInstanceType<{
             name: "string";
             data: "string";
             epoch: "number";
             connected: "boolean";
+            avatarUrl: "string";
         }>, string>;
     };
     shared: {

package/dist/schema.js

@@ -9,7 +9,12 @@ var PlayerState = schema(
     epoch: "number",
     // Seat presence is distinct from connectivity: a dropped player keeps the
     // seat during reconnection grace but flips connected=false immediately.
-    connected: "boolean"
+    connected: "boolean",
+    // The player's verified VRM avatar URL (AG-804) — set by the relay from the
+    // embed token, never client-writable. '' = none (old API / empty library).
+    // NEW FIELDS GO AFTER THIS ONE: @colyseus/schema keeps old clients decoding
+    // only when fields are appended at the end, never inserted or reordered.
+    avatarUrl: "string"
   },
   "PlayerState"
 );

package/package.json

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