@genex-ai/cli-demo 0.15.0 → 0.17.0

package/dist/index.js

@@ -1110,6 +1110,24 @@ async function detectMultiplayer(cwd = process.cwd()) {
     return false;
   }
 }
+async function detectMatchmaking(log, cwd = process.cwd()) {
+  let pkg;
+  try {
+    pkg = JSON.parse(await fs8.readFile(path9.join(cwd, "package.json"), "utf8"));
+  } catch (err) {
+    log.dim(`  (skipping matchmaking \u2014 couldn't read package.json: ${String(err)})`);
+    return null;
+  }
+  const mm = pkg.genex?.matchmaking;
+  if (mm && typeof mm.preset === "string" && mm.preset) {
+    return {
+      preset: mm.preset,
+      ...mm.winCondition ? { winCondition: mm.winCondition } : {},
+      ...mm.config ? { config: mm.config } : {}
+    };
+  }
+  return null;
+}
 async function runPublish(opts) {
   const log = createLogger({ quiet: opts.quiet });
   log.plain(c.bold("genex publish"));
@@ -1151,6 +1169,8 @@ async function runPublish(opts) {
     const embedSdkVersion = await detectEmbedSdkVersion();
     if (embedSdkVersion) body.embedSdkVersion = embedSdkVersion;
     body.multiplayer = await detectMultiplayer();
+    const matchmaking = await detectMatchmaking(log);
+    if (matchmaking) body.matchmaking = matchmaking;
     res = await fetch(`${apiUrl}/api/projects/${meta.id}/publish`, {
       method: "POST",
       headers: { "Content-Type": "application/json", Authorization: `Bearer ${token}` },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@genex-ai/cli-demo",
-  "version": "0.15.0",
+  "version": "0.17.0",
   "description": "Set up your ~/.claude workspace, authorize, create a game project, generate AI assets, and publish (genex CLI).",
   "type": "module",
   "bin": {

package/templates/controllers/shared/NETWORKING.md

@@ -0,0 +1,11 @@
+# Networking these controllers
+
+These controllers simulate **your own player only** (self-authoritative, zero input
+latency). To show OTHER players' rigs in a multiplayer game, publish a small flat state on
+a fixed tick and play it back on a visual-only remote rig — never instantiate a controller
+or a Rapier body for a remote player.
+
+The complete recipe (what to publish per controller, remote playback, contested-contact
+physics via the host) lives in the multiplayer skill:
+`genex-threejs-multiplayer` → `references/host-physics.md`. Load that skill before writing
+any networking code.

package/templates/skills/genex-threejs-multiplayer/SKILL.md

@@ -37,7 +37,71 @@ example, the shared-object/ball code, rotation, and host usage. Read
 npm i @genex-ai/multiplayer
 ```
 
-`objects` and `host` need `@genex-ai/multiplayer` **≥ 0.4.0**.
+This skill targets `@genex-ai/multiplayer` **≥ 0.8.0** (`objects`/`host` since 0.4; `matchmake()` since 0.5; presets + `score()`/`finish()` since 0.6; `createPrivate()`/`joinPrivate()` since 0.7; auto-reconnect + `inputs`/`onHostTick` since 0.8).
+
+## Trust model (say it plainly in your game's copy)
+
+This is **casual, favor-the-player multiplayer** (Haxball, not Rocket League): you are
+authoritative over yourself, match outcomes are self-reported, and there is no server-side
+simulation or anti-cheat. The server DOES enforce identity (verified tokens), object
+ownership, match seating/adjudication, and rate/size caps — but a modified client can still
+lie about its own position or score. Great for friends and casual lobbies; don't promise
+ranked-grade fairness.
+
+## Matchmaking (competitive presets — server-owned)
+
+When players should be **matched into separate capped rooms** rather than share one big room (a 1v1
+duel, an FFA arena, N-v-N teams, an invite lobby), use `matchmake()` instead of `connect()`. It
+returns a handle whose **`session` is `null` while searching** — render your OWN "finding a match…"
+HUD from `mm.matchmaking` (its `status`, `queue.position`, `players`/`opponents`, `teams`, `scores`,
+`winCondition`), and switch to the game once `session` goes live:
+
+```ts
+// Pass auth as a FUNCTION — one matchmake() handle re-joins the queue/match many times (re-search,
+// requeue) over a session, and embed tokens rotate (~10 min). A function is read fresh each (re)join;
+// a static object goes stale and gets rejected mid-session.
+const mm = await matchmake<MyState>({ url, room: slug, auth: () => getColyseusAuth() });
+mm.on('matched', () => {/* session is live — start the game */});
+// each frame: if (mm.session) renderGame(mm.session); else renderSearchingHud(mm.matchmaking);
+mm.on('matchEnded', ({ winnerId, scores, draw }) => {/* result screen */});
+mm.on('error', (e) => {/* a (re)join failed, e.g. auth — usually transient; the handle keeps searching */});
+
+// Report ONLY your own outcome — the server adjudicates. Which call fits depends on the win condition:
+mm.eliminated();   // I'm out              (lastStanding)
+mm.score(1);       // I scored             (firstToScore / highScoreInTime)
+mm.finish();       // I finished the race  (firstToFinish)
+```
+
+Everything is **server-owned** — set once in `package.json` under `genex.matchmaking`, reported at
+publish; the client declares nothing. You never run matchmaking logic: the server owns the queue,
+roles, winner-stays, forfeit, timeout, and the win condition.
+
+```jsonc
+"genex": {
+  "matchmaking": {
+    "preset": "arena",                 // duel | arena | teams | private
+    "winCondition": "firstToScore",    // lastStanding | firstToScore | highScoreInTime | firstToFinish
+    "config": { "scoreTarget": 20, "maxPlayers": 8 }   // numeric knobs, optional
+  }
+}
+```
+
+Presets: **duel** (1v1 winner-stays), **arena** (N-player FFA, join-anytime), **teams** (balanced
+N-v-N), **private** (invite-code lobby). Win conditions: **lastStanding** (last one alive),
+**firstToScore** (first to the score target), **highScoreInTime** (top score at the time cap),
+**firstToFinish** (first to finish). A round that hits the time cap undecided is a draw.
+
+**Private lobbies** (for `preset: 'private'`) don't use `matchmake()` — a host makes an invite code
+and friends join it; the lobby is persistent (rounds replay, nobody is evicted):
+
+```ts
+import { createPrivate, joinPrivate } from "@genex-ai/multiplayer";
+const lobby = await createPrivate<MyState>({ url, room: slug, auth: () => getColyseusAuth() });  // live NOW
+showCode(lobby.code);                                                   // share this
+// a friend, elsewhere:
+const lobby = await joinPrivate<MyState>(code, { url, room: slug, auth: () => getColyseusAuth() });
+// same handle API as matchmake(): lobby.session, lobby.matchmaking, eliminated()/score()/finish(), cancel()
+```
 
 ## Connect
 
@@ -65,6 +129,36 @@ const room = await connect<State>({
 });
 ```
 
+**Capacity:** a room holds up to **64 players** (up to 48 of them guests). Above that, the
+relay opens a **second room for the same game** — two parallel worlds, no error. If your
+game needs seated, one-world competition, use the matchmaking presets instead of one big
+`connect()` room.
+
+## Disconnects & reconnection (built in — render it, don't rebuild it)
+
+The SDK auto-reconnects after a network blip or brief signal loss: the relay holds your seat
+for a grace window (~30 s), and on recovery **nothing changed** — same session id, objects
+still yours, host unchanged, and in a match **a blip is not a forfeit**. Your only job is UI:
+
+```ts
+room.on("reconnecting", ({ attempt }) => showOverlay(`Reconnecting… (${attempt})`));
+room.on("reconnected", () => hideOverlay());
+room.on("disconnect", (code) => {
+  // Terminal: server restart, revoked session, or the link never came back.
+  // To play again, read a FRESH token and connect() anew — never reuse the old auth object.
+  showMenu("Connection lost");
+});
+room.on("server:restart", () => flushSaves()); // the relay warns before a deploy — save now
+```
+
+Keep your render loop running during `reconnecting` — remote players freeze briefly and then
+glide on; don't tear the scene down. A deliberate `room.leave()` never auto-reconnects.
+
+**One seat per player (enforced server-side):** joining the same game again — a second tab,
+another device, or a page reload — instantly evicts the previous session (it gets
+`disconnect`, code 4409). You never need to handle "the same player twice" and a reload
+never leaves a ghost avatar behind.
+
 ## Which channel for which data
 
 **This table is the most important thing in this skill.** Every piece of networked state is one
@@ -105,13 +199,21 @@ fights (many writers). A ball on `objects` glides and has one owner. That's the
   `'host'` `(id)`, and any custom `send` name.
 - `room.send(type, payload)` — fire-and-forget to all **other** clients. **It never echoes to
   you**, so apply your own action's local effect directly (draw your own tracer at fire time),
-  not inside `on(...)`. `room.leave()`.
+  not inside `on(...)`. Relay-internal names (`state`, `shared`, `claim`, `obj`, `release`,
+  `destroy`, `match:*`, `__*`) are refused — pick your own event names. `room.leave()`.
+- `room.inputs.send(payload)` / `room.inputs.on((fromId, payload) => …)` — the host-routed
+  input channel for host-authoritative physics: anyone sends, ONLY the current host receives.
+  See [references/host-physics.md](references/host-physics.md).
+- `room.onHostTick(hz, cb)` — run a fixed simulation tick only while you are the host
+  (auto-starts/stops across host migration). Returns a disposer.
 
 ## The loop you must build (input → local → tick → render)
 
 1. **Input mutates a local object only** (`me.x += …`). Never network on keypress.
 2. **A fixed tick publishes it:** `setInterval(() => room.me.set(me), 66)` (~15 Hz). If you own an
-   object, `objects.set` it in the same tick.
+   object, `objects.set` it in the same tick. **Round numbers before publishing** —
+   `Math.round(v * 100) / 100` (2 decimals ≈ cm precision) — raw floats serialize as 17-digit
+   JSON and are the #1 bandwidth waste; nobody can see a 0.001-unit difference.
 3. **Render at your own framerate:** yourself from your *local* object; every other player from
    `players.get(id).state` directly (already smoothed); every object from `objects.get(id).state`.
 4. **Create-or-reuse one mesh per id**; remove a player's mesh on `'leave'`.
@@ -163,6 +265,17 @@ For host-simulated NPCs, the host claims and drives each enemy as an `object`; w
 leaves, its enemies are reassigned to the new host, which reads their `stateRaw` and keeps
 simulating. See the co-op recipe in [references/genre-recipes.md](references/genre-recipes.md).
 
+### Contested physics (two players pushing ONE thing) — host-authoritative
+
+Claim-on-touch is perfect for one-touch objects (kick a ball). It **breaks down under
+sustained contact** — two players pushing the same crate steal ownership back and forth and
+the crate judders. For contested objects, ONE simulation must own the contest: the **host**
+runs the physics for those objects; everyone else sends **inputs**
+(`room.inputs.send({ push })`), which the relay routes to the host only; the host applies
+them on `room.onHostTick(...)` and publishes results via `objects` (smooth for everyone).
+Full recipe — including surviving host migration and wiring the Rapier controllers —
+in [references/host-physics.md](references/host-physics.md).
+
 ## Smoothness is felt, not seen — hand the feel to a human
 
 Lag and stutter are *motion over time*. A screenshot is one frozen instant, so **you cannot tell
@@ -246,7 +359,10 @@ host-driven saving works as long as ANY account is in the room.
 
 ## Checklist
 
-- [ ] `npm i @genex-ai/multiplayer` (≥ 0.4.0 for objects/host); config wired into the build.
+- [ ] `npm i @genex-ai/multiplayer` (≥ 0.8.0 — auto-reconnect, `inputs`, `onHostTick`); config wired into the build.
+- [ ] `reconnecting`/`reconnected`/`disconnect` render an overlay (don't tear the scene down).
+- [ ] Numbers rounded (~2 decimals) before `me.set`/`objects.set`.
+- [ ] Contested (sustained-contact) objects use the host-physics pattern, not claim-on-touch.
 - [ ] `connect()` runs AFTER `await waitForPlayer()` (never `waitForAuth()` — guests would
       hang) and passes `auth: getColyseusAuth()!` (the relay rejects tokenless joins —
       see `genex-threejs-embed-auth`).
@@ -268,3 +384,6 @@ host-driven saving works as long as ANY account is in the room.
   read `getColyseusAuth()` fresh at every connect). 403 "wrong game": the `room` value
   doesn't match this game's own slug. 403 "guest capacity": the room is at its guest
   limit — signing in gets the player a seat; surface the message as-is.
+- **`disconnect` fired and the player wants back in** — the old session is dead; run your
+  connect flow again from the top with a FRESH `getColyseusAuth()` (a cached auth object is
+  the usual cause of a rejoin failing 401).

package/templates/skills/genex-threejs-multiplayer/references/host-physics.md

@@ -0,0 +1,111 @@
+# Host-authoritative physics — contested objects + networked controllers
+
+Two networking tiers exist for moving things, and picking the right one per object is the
+whole trick:
+
+| Object kind | Tier | Why |
+| --- | --- | --- |
+| One-touch (kick a ball, throw a crate once) | **claim-on-touch** (`objects.claim` on contact, owner simulates) | lowest latency — your kick lands instantly |
+| Sustained contact / contested (two players pushing one crate, tug-of-war, sumo, shared vehicles) | **host-authoritative** (this doc) | one simulation owns the contest — no ownership ping-pong, physics stays consistent |
+
+Claim-on-touch under sustained contact means every contact steals ownership, resets the
+simulation, and the object judders between two owners' views. Host-authoritative kills that
+by construction: **the host runs the ONE Rapier world for contested objects; everyone else
+sends inputs.**
+
+## The pattern (complete)
+
+Every client runs this same code — `onHostTick` only fires on the current host, so there is
+no "am I host?" bookkeeping and host migration is automatic:
+
+```ts
+// ---- inputs: NON-hosts (and the host itself) report intent, ~10-15Hz or on action ----
+// Routed by the relay to the CURRENT HOST ONLY — never broadcast, cheap.
+if (pushingCrate) room.inputs.send({ obj: "crate", push: dir.toArray() });
+
+// ---- simulation: runs ONLY on the host, survives migration ----
+const pending: { obj: string; push: number[] }[] = [];
+room.inputs.on((fromId, payload) => {
+  const p = payload as { obj?: string; push?: number[] };
+  if (p?.obj && Array.isArray(p.push)) pending.push(p as { obj: string; push: number[] });
+});
+
+room.onHostTick(30, (dtMs) => {
+  // 1) First tick after election: adopt the objects + seed the physics world from the
+  //    last published truth (stateRaw) — NEVER from zero, or the world teleports.
+  for (const id of CONTESTED_IDS) {
+    const view = room.objects.get(id);
+    if (!view || !view.isMine) {
+      room.objects.claim(id);
+      seedRapierBody(id, view?.stateRaw); // position/rotation/velocity from the wire
+    }
+  }
+  // 2) Apply everyone's inputs to the ONE authoritative Rapier world.
+  for (const { obj, push } of pending.splice(0)) applyImpulse(obj, push);
+  // 3) Step and publish (flat state: numbers + one [x,y,z,w] quaternion).
+  rapierWorld.step();
+  for (const id of CONTESTED_IDS) {
+    const b = bodyOf(id);
+    room.objects.set(id, {
+      x: r2(b.translation().x), y: r2(b.translation().y), z: r2(b.translation().z),
+      q: quatArray(b.rotation()),
+    });
+  }
+});
+const r2 = (v: number) => Math.round(v * 100) / 100; // quantize — floats are JSON bloat
+
+// ---- rendering: identical on every client, host included ----
+for (const id of CONTESTED_IDS) {
+  const view = room.objects.get(id);
+  if (view) meshOf(id).position.set(view.state.x, view.state.y, view.state.z); // auto-smoothed
+}
+```
+
+Rules that make it correct:
+
+- **Sim internals that must survive migration** (velocities, cooldowns, aggro) either live in
+  the published object state or get mirrored at low rate into a dedicated object
+  (`objects.set("sim", …)`) the next host reads on adoption. Positions/rotations come free
+  via `stateRaw`.
+- **Latency honesty:** a non-host's push lands after ~RTT to the relay. At casual scale that
+  reads as weight, not lag. The host's own pushes are instant — that asymmetry is the tier's
+  price; don't fight it with client-side guessing.
+- **Rate budget:** the host publishes N contested objects at 20–30 Hz; keep N modest (≤ ~10)
+  and state flat + quantized. Inputs are single-receiver and cheap.
+- **Do not** run a second Rapier body for a contested object on non-hosts "for prediction" —
+  that's the double-simulation version of double-smoothing. Draw `state`.
+
+## Networked controllers (the vendored character / vehicle / drone)
+
+The `genex controller` controllers are **local-only physics** — each player simulates their
+OWN rig (self-authoritative, zero latency). Networking them is publish-and-playback, never
+remote simulation:
+
+```ts
+// You: after your controller's update, on the fixed tick (~15Hz)
+room.me.set({
+  x: r2(rig.position.x), y: r2(rig.position.y), z: r2(rig.position.z),
+  q: rig.quaternion.toArray().map(r2),      // quaternion — never a scalar yaw
+  anim: rig.animState,                       // discrete → remotes read via stateRaw
+  // vehicle extras: steer: r2(steerAngle), wheel: r2(wheelSpinPhase)
+});
+
+// Remote players: drive a VISUAL-ONLY rig from smoothed state — no Rapier body, no
+// controller instance for remotes. Wheels/limbs animate from the published params.
+const p = room.players.get(id)!;
+remoteMesh.position.set(p.state.x, p.state.y, p.state.z);
+remoteMesh.quaternion.fromArray(p.state.q);
+remoteAnimator.play(p.stateRaw.anim);        // discrete values from stateRaw
+```
+
+What to publish per controller:
+
+- **character**: `x/y/z`, `q`, `anim` (state-machine id), optionally `speed` for blend trees.
+- **vehicle**: body `x/y/z` + `q`, `steer` angle, a `wheel` spin phase (remotes spin wheels
+  procedurally — never sync per-wheel transforms).
+- **drone**: `x/y/z`, `q`, rotor throttle if the visual needs it.
+
+Player-vs-player physical contact (bumping cars) stays approximate at this tier — each
+client is authoritative over itself, so contacts are cosmetic. If a game's core loop IS
+contested vehicle contact, that's the host-authoritative tier above, with the vehicles as
+host-simulated objects and player inputs over `inputs.send`.

package/templates/skills/genex-threejs-skill-router/references/routing-map.md

@@ -69,4 +69,8 @@ NPC, claimed on contact) and a room `host` (single writer of scores, single simu
 enemies). That skill covers the rules that keep it smooth (draw `state` directly, render
 yourself and objects you own from a local object, quaternion rotation, `stateRaw` for
 hit-tests), the per-genre recipes (sports/ball, shooter, co-op), config wiring, and the
-persistent-world API. Use only the APIs that skill documents — do not invent transport methods.
+persistent-world API. Reconnection is built into the SDK (render `reconnecting`/
+`reconnected`, never rebuild it), and **contested physics** (two players pushing one
+object — sumo, tug-of-war, shared crates) routes to its host-authoritative pattern
+(`inputs` + `onHostTick`, see that skill's host-physics reference) — never claim-on-touch.
+Use only the APIs that skill documents — do not invent transport methods.