@genex-ai/multiplayer 0.1.0

package/README.md

@@ -0,0 +1,139 @@
+# @genex-ai/multiplayer
+
+Tiny realtime multiplayer for genex games.
+
+**Relay model:** whatever you write to `me` or `shared` is synced to everyone; everything else stays local. The server does **no physics, no prediction, no interpolation** — you run your own game logic, this just shares state.
+
+```ts
+import { connect } from '@genex-ai/multiplayer';
+```
+
+---
+
+## Connect
+
+```ts
+type State = { x: number; y: number; z: number };   // YOUR per-player state — any JSON shape
+
+const room = await connect<State>({
+  url:  'wss://demo-colyseus.glotech.world',  // the genex multiplayer server
+  room: '<game-id>',                          // everyone with the same id shares a room (use the project slug)
+  name: 'ada',                                // optional display name
+});
+```
+
+Different `room` ids are **fully isolated** — players in game A never see game B.
+
+---
+
+## `me` — publish your own state
+
+Replaces your state wholesale. Call on a **fixed tick (~10–20Hz)**, not every render frame — each call is one network message.
+
+```ts
+room.me.set({ x, y, z });
+```
+
+## `players` — everyone in the room
+
+A fresh `Map` each read; **includes you** (skip with `id === room.id`). It's the latest snapshot — snap to it (or smooth client-side if you want; there's no built-in interpolation).
+
+```ts
+for (const [id, p] of room.players) {
+  if (id === room.id) continue;
+  draw(p.name, p.state.x, p.state.y, p.state.z);   // p.state is typed as State
+}
+```
+
+## `shared` — shared room state
+
+A key/value store (any JSON) synced to everyone. Use for world state, scores, the current round, etc.
+
+```ts
+room.shared.set('round', 3);
+room.shared.get('round');   // 3
+room.shared.keys();         // ['round', ...]
+```
+
+## `on` — events
+
+```ts
+room.on('join',   (id, state) => {});  // a player appeared (also fires for YOU on connect)
+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('hit',    (payload)   => {});  // a custom event someone sent (see `send`)
+```
+
+`on(...)` returns an unsubscribe function.
+
+## `send` — custom one-off events
+
+Fire-and-forget to all **other** clients (not stored in state). For shots, emotes, chat, pings.
+
+```ts
+room.send('hit', { from: room.id, target: 'xyz', dmg: 10 });
+```
+
+## `leave`
+
+```ts
+room.leave();
+```
+
+---
+
+## Complete minimal example (move a cube, see others as cubes)
+
+```ts
+import { connect } from '@genex-ai/multiplayer';
+type S = { x: number; z: number };
+
+const room = await connect<S>({ url: 'wss://demo-colyseus.glotech.world', room: GAME_ID });
+
+const me = { x: 0, z: 0 };
+
+// publish my position ~15Hz (NOT per frame)
+setInterval(() => room.me.set(me), 66);
+
+// render loop (your engine / three.js): draw every player at their latest position
+function frame() {
+  for (const [id, p] of room.players) {
+    const cube = cubeFor(id);                 // create-or-reuse a mesh per id
+    cube.position.set(p.state.x ?? 0, 0, p.state.z ?? 0);   // snap — no interpolation
+  }
+  requestAnimationFrame(frame);
+}
+frame();
+
+// drop a player's cube when they leave
+room.on('leave', (id) => removeCube(id));
+
+// input just mutates `me`; the tick above syncs it
+onKey('right', () => { me.x += 1; });
+```
+
+---
+
+## Rules of thumb
+
+- **`me` / `shared` are synced; everything else is local.** Movement input → mutate a local object → `me.set` it on the tick.
+- **Tick `me.set` at ~10–20Hz**, render at your own framerate. One `me.set` = one network message.
+- **`room` (game id) must be stable per game** — use the project slug. Same id = same room; different id = isolated.
+- **No interpolation / prediction.** You get the latest state; snap to it, or smooth it yourself.
+- `me.set` replaces your whole state object — send the full object each time, not a partial.
+
+---
+
+## 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):
+
+```ts
+// load on boot
+const { data } = await fetch(`${API}/api/projects/${slug}/state`).then(r => r.json());
+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) });
+```

package/dist/index.d.ts

@@ -0,0 +1,73 @@
+export { PlayerState, RoomState } from './schema.js';
+import '@colyseus/schema';
+
+type ConnectOptions = {
+    /** Colyseus server url, e.g. "ws://localhost:2567". */
+    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;
+    /** Display name for this player (anonymous is fine). */
+    name?: string;
+    /** Extra join options passed to the room. */
+    options?: Record<string, unknown>;
+};
+type PlayerView<TState> = {
+    id: string;
+    name: string;
+    /** This player's latest synced state (what they passed to `me.set`). */
+    state: TState;
+};
+type Session<TState extends Record<string, unknown>> = {
+    /** Your own session id. */
+    readonly id: string;
+    /**
+     * Everyone in the room, **including you** — skip yourself with
+     * `if (id === room.id)`. Returns a fresh Map on each read.
+     */
+    readonly players: Map<string, PlayerView<TState>>;
+    readonly me: {
+        /**
+         * Publish your synced state (replaces it wholesale). Call on a **fixed tick**
+         * (~10–20Hz), not every render frame — each call sends one network message.
+         */
+        set(state: TState): void;
+    };
+    readonly shared: {
+        /** Read a shared value (any JSON), or `undefined`. */
+        get(key: string): unknown;
+        /** Set a shared value (any JSON). Any client may set any key (no auth — demo). */
+        set(key: string, value: unknown): void;
+        /** All shared keys currently set. */
+        keys(): string[];
+    };
+    /** 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`). */
+    on(event: 'shared', cb: (key: string, value: unknown) => 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). */
+    send(type: string, payload?: unknown): void;
+    /** Leave the room. */
+    leave(): void;
+};
+/**
+ * Connect to a genex multiplayer room. You must supply your player-state type:
+ *
+ * ```ts
+ * const room = await connect<{ x: number; y: number; z: number }>({
+ *   url: 'ws://localhost:2567', room: gameId, name: 'ada',
+ * });
+ * room.me.set({ x, y, z });          // typed + validated by the compiler
+ * room.players.get(id)?.state.x;     // number — no cast
+ * ```
+ *
+ * Relay model: no physics, no prediction, no interpolation. Whatever you write
+ * to `me` or `shared` syncs to everyone; everything else stays local.
+ */
+declare function connect<TState extends Record<string, unknown> = never>(opts: ConnectOptions): Promise<Session<TState>>;
+
+export { type ConnectOptions, type PlayerView, type Session, connect };

package/dist/index.js

@@ -0,0 +1,87 @@
+// src/index.ts
+import { Client, getStateCallbacks } from "colyseus.js";
+var RELAY_ROOM_TYPE = "play";
+function parseObject(s) {
+  if (!s) return {};
+  try {
+    const v = JSON.parse(s);
+    return v && typeof v === "object" ? v : {};
+  } catch {
+    return {};
+  }
+}
+function parseValue(s) {
+  if (s == null) return void 0;
+  try {
+    return JSON.parse(s);
+  } catch {
+    return void 0;
+  }
+}
+async function connect(opts) {
+  const client = new Client(opts.url);
+  const room = await client.joinOrCreate(RELAY_ROOM_TYPE, {
+    gameId: opts.room,
+    name: opts.name,
+    ...opts.options
+  });
+  const emitters = /* @__PURE__ */ new Map();
+  const bridged = /* @__PURE__ */ new Set();
+  const reserved = /* @__PURE__ */ new Set(["join", "leave", "change", "shared"]);
+  const emit = (event, ...args) => emitters.get(event)?.forEach((cb) => cb(...args));
+  const $ = getStateCallbacks(room);
+  $(room.state).players.onAdd((player, id) => {
+    emit("join", id, parseObject(player.data));
+    $(player).onChange(() => emit("change", id, parseObject(player.data)));
+  });
+  $(room.state).players.onRemove((_player, id) => emit("leave", 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());
+    set.add(cb);
+    if (!reserved.has(event) && !bridged.has(event)) {
+      bridged.add(event);
+      room.onMessage(event, (msg) => emit(event, msg));
+    }
+    return () => {
+      set?.delete(cb);
+    };
+  });
+  return {
+    id: room.sessionId,
+    get players() {
+      const out = /* @__PURE__ */ new Map();
+      room.state?.players?.forEach(
+        (p, id) => out.set(id, { id, name: p.name, state: parseObject(p.data) })
+      );
+      return out;
+    },
+    me: {
+      set(state) {
+        room.send("state", JSON.stringify(state));
+      }
+    },
+    shared: {
+      get(key) {
+        return parseValue(room.state?.shared?.get(key));
+      },
+      set(key, value) {
+        room.send("shared", { key, value: JSON.stringify(value) });
+      },
+      keys() {
+        return room.state?.shared ? Array.from(room.state.shared.keys()) : [];
+      }
+    },
+    on,
+    send(type, payload) {
+      room.send(type, payload);
+    },
+    leave() {
+      void room.leave();
+    }
+  };
+}
+export {
+  connect
+};

package/dist/schema.d.ts

@@ -0,0 +1,51 @@
+import * as _colyseus_schema from '@colyseus/schema';
+import { SchemaType, MapSchema } from '@colyseus/schema';
+
+declare const PlayerState: _colyseus_schema.SchemaWithExtendsConstructor<{
+    name: "string";
+    data: "string";
+}, _colyseus_schema.AssignableProps<_colyseus_schema.InferSchemaInstanceType<{
+    name: "string";
+    data: "string";
+}>>, typeof _colyseus_schema.Schema>;
+type PlayerState = SchemaType<typeof PlayerState>;
+declare const RoomState: _colyseus_schema.SchemaWithExtendsConstructor<{
+    players: {
+        map: _colyseus_schema.SchemaWithExtendsConstructor<{
+            name: "string";
+            data: "string";
+        }, _colyseus_schema.AssignableProps<_colyseus_schema.InferSchemaInstanceType<{
+            name: "string";
+            data: "string";
+        }>>, typeof _colyseus_schema.Schema>;
+        default: MapSchema<_colyseus_schema.InferSchemaInstanceType<{
+            name: "string";
+            data: "string";
+        }>, string>;
+    };
+    shared: {
+        map: "string";
+        default: MapSchema<string, string>;
+    };
+}, _colyseus_schema.AssignableProps<_colyseus_schema.InferSchemaInstanceType<{
+    players: {
+        map: _colyseus_schema.SchemaWithExtendsConstructor<{
+            name: "string";
+            data: "string";
+        }, _colyseus_schema.AssignableProps<_colyseus_schema.InferSchemaInstanceType<{
+            name: "string";
+            data: "string";
+        }>>, typeof _colyseus_schema.Schema>;
+        default: MapSchema<_colyseus_schema.InferSchemaInstanceType<{
+            name: "string";
+            data: "string";
+        }>, string>;
+    };
+    shared: {
+        map: "string";
+        default: MapSchema<string, string>;
+    };
+}>>, typeof _colyseus_schema.Schema>;
+type RoomState = SchemaType<typeof RoomState>;
+
+export { PlayerState, RoomState };

package/dist/schema.js

@@ -0,0 +1,20 @@
+// src/schema.ts
+import { schema, MapSchema } from "@colyseus/schema";
+var PlayerState = schema(
+  {
+    name: "string",
+    data: "string"
+  },
+  "PlayerState"
+);
+var RoomState = schema(
+  {
+    players: { map: PlayerState, default: new MapSchema() },
+    shared: { map: "string", default: new MapSchema() }
+  },
+  "RoomState"
+);
+export {
+  PlayerState,
+  RoomState
+};

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@genex-ai/multiplayer",
+  "version": "0.1.0",
+  "description": "The multiplayer client wrapper + shared room schema for genex.",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./schema": {
+      "types": "./dist/schema.d.ts",
+      "import": "./dist/schema.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@colyseus/schema": "^3.0.76",
+    "colyseus.js": "^0.16.22"
+  },
+  "peerDependencies": {
+    "three": ">=0.160.0"
+  },
+  "peerDependenciesMeta": {
+    "three": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "tsup": "^8.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/me-ai-org/genex-demo.git",
+    "directory": "packages/multiplayer"
+  },
+  "license": "MIT",
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts"
+}