@genex-ai/cli-demo 0.16.0 → 0.17.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@genex-ai/cli-demo",
-  "version": "0.16.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,16 @@ example, the shared-object/ball code, rotation, and host usage. Read
 npm i @genex-ai/multiplayer
 ```
 
-This skill targets `@genex-ai/multiplayer` **≥ 0.7.0** (`objects`/`host` since 0.4; `matchmake()` since 0.5; presets + `score()`/`finish()` since 0.6; `createPrivate()`/`joinPrivate()` since 0.7).
+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)
 
@@ -120,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
@@ -160,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'`.
@@ -218,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
@@ -301,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`).
@@ -323,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.