@genex-ai/cli-demo 0.18.0 → 0.21.0

package/dist/index.js

@@ -1064,7 +1064,7 @@ async function deployGame(ctx, opts, log) {
   }
   if (!await pushSource(cwd, ctx.sshUrl, keyPath, log)) return false;
   log.step("Publishing\u2026");
-  if (!await callPublish(ctx, commit, opts.matchmaking ?? null, log)) return false;
+  if (!await callPublish(ctx, commit, opts, log)) return false;
   const index = files.find((f) => f.relPath === "index.html");
   await waitUntilLive(grant.playUrl, fingerprintOf(index.bytes.toString("utf8")), opts.liveTimeoutMs ?? 2e4, log);
   return true;
@@ -1148,15 +1148,21 @@ async function uploadAll(uploadUrl, uploadToken, files, log) {
   await Promise.all(Array.from({ length: Math.min(8, files.length) }, () => worker()));
   return !failed;
 }
-async function callPublish(ctx, commit, matchmaking, log) {
+async function callPublish(ctx, commit, opts, log) {
   let res;
   try {
     res = await fetch(`${ctx.apiUrl}/api/games/${ctx.projectId}/publish`, {
       method: "POST",
       headers: { "Content-Type": "application/json", Authorization: `Bearer ${ctx.token}` },
-      // matchmaking rides every go-live (preview AND publish): object = upsert,
-      // null = clear — so a draft's declared preset reaches the relay immediately.
-      body: JSON.stringify({ commit, matchmaking: matchmaking ?? null })
+      // Detections ride every go-live (preview AND publish): matchmaking is
+      // tri-state (object = upsert, null = clear); embedSdkVersion/multiplayer
+      // are sent only when detected (absent = server keeps the stored value).
+      body: JSON.stringify({
+        commit,
+        matchmaking: opts.matchmaking ?? null,
+        ...opts.embedSdkVersion ? { embedSdkVersion: opts.embedSdkVersion } : {},
+        ...opts.multiplayer !== void 0 ? { multiplayer: opts.multiplayer } : {}
+      })
     });
   } catch (err) {
     log.error(`Couldn't reach the API at ${ctx.apiUrl}: ${String(err)}`);
@@ -1370,7 +1376,12 @@ async function runPublish(opts) {
   if (!opts.noPush) {
     const ok = await deployGame(
       { projectId: meta.id, sshUrl: meta.sshUrl, apiUrl, token },
-      { noBuild: opts.noBuild, matchmaking: detections.matchmaking },
+      {
+        noBuild: opts.noBuild,
+        matchmaking: detections.matchmaking,
+        embedSdkVersion: detections.embedSdkVersion,
+        multiplayer: detections.multiplayer
+      },
       log
     );
     if (!ok) {
@@ -1388,6 +1399,9 @@ async function runPublish(opts) {
     if (opts.description) body.description = opts.description;
     if (opts.regenerateCover) body.regenerateCover = true;
     if (opts.categories?.length) body.categories = opts.categories;
+    if (opts.sourceRepoUrl) body.sourceRepoUrl = opts.sourceRepoUrl;
+    if (opts.sourceAuthor) body.sourceAuthor = opts.sourceAuthor;
+    if (opts.license) body.license = opts.license;
     if (detections.embedSdkVersion) body.embedSdkVersion = detections.embedSdkVersion;
     body.multiplayer = detections.multiplayer;
     body.matchmaking = detections.matchmaking ?? null;
@@ -1434,9 +1448,16 @@ async function runPreview(opts) {
   const apiUrl = getApiUrl(meta.apiUrl);
   const ok = await deployGame(
     { projectId: meta.id, sshUrl: meta.sshUrl, apiUrl, token },
-    // matchmaking reaches the server on every preview too — a draft with a declared
-    // preset must not silently run the default one (null clears a removed config).
-    { noBuild: opts.noBuild, matchmaking: detections.matchmaking },
+    // Detections reach the server on every preview too: matchmaking so a draft's
+    // declared preset doesn't silently run the default (null clears a removed
+    // config), embedSdkVersion/multiplayer so the dashboard's Publish button can
+    // list the draft without wrongly treating it as a pre-embed-auth bundle.
+    {
+      noBuild: opts.noBuild,
+      matchmaking: detections.matchmaking,
+      embedSdkVersion: detections.embedSdkVersion,
+      multiplayer: detections.multiplayer
+    },
     log
   );
   if (!ok) {
@@ -1888,6 +1909,72 @@ async function exists2(p) {
   }
 }
 
+// src/commands/explore.ts
+async function runExplore(opts) {
+  const log = createLogger({ quiet: opts.quiet });
+  const query = opts.query?.trim();
+  if (!query) {
+    log.error('Missing query. Usage: genex explore "<what you need>"');
+    process.exitCode = 1;
+    return;
+  }
+  const apiUrl = getApiUrl(opts.apiUrl);
+  let res;
+  try {
+    res = await fetch(`${apiUrl}/api/gallery/search-corpus?curated=1`);
+  } catch {
+    log.error("Couldn't reach Genex \u2014 please try again.");
+    process.exitCode = 1;
+    return;
+  }
+  if (!res.ok) {
+    log.error(`explore: API returned ${res.status} \u2014 please try again.`);
+    process.exitCode = 1;
+    return;
+  }
+  const { items } = await res.json();
+  const ranked = rank(items, query).slice(0, 5);
+  if (opts.json) {
+    console.log(JSON.stringify(ranked, null, 2));
+    return;
+  }
+  if (ranked.length === 0) {
+    log.plain(
+      `No curated projects matched "${query}". Try a broader term (terrain, grass, vehicle, water, building, dungeon, fish, shader).`
+    );
+    return;
+  }
+  for (const [i, p] of ranked.entries()) {
+    const meta = [
+      p.categories.join(", "),
+      p.license ?? "",
+      p.sourceAuthor ? `originally by ${p.sourceAuthor}` : ""
+    ].filter(Boolean).join(" \xB7 ");
+    log.plain(`${c.bold(`${i + 1}. ${p.title}`)} \u2014 ${meta}`);
+    if (p.description) log.plain(`   ${p.description.slice(0, 160)}`);
+    if (p.playUrl) log.plain(`   play:  ${p.playUrl}`);
+    if (p.cloneUrl) log.plain(`   clone: ${p.cloneUrl}   (editable source on main)`);
+    if (p.sourceRepoUrl) log.plain(`   upstream: ${p.sourceRepoUrl}`);
+  }
+  log.plain("");
+  log.plain(
+    `To use one: clone it as a starting template, or borrow parts into your current game \u2014 the genex-explore skill has the exact steps. Keep the credits.`
+  );
+}
+function rank(items, query) {
+  const terms = query.toLowerCase().split(/\s+/).filter(Boolean);
+  return items.map((p) => {
+    const hay = `${p.title} ${p.description} ${p.categories.join(" ")}`.toLowerCase();
+    let score = 0;
+    for (const t of terms) {
+      if (p.title.toLowerCase().includes(t)) score += 3;
+      if (p.categories.some((cat) => cat.includes(t))) score += 2;
+      if (hay.includes(t)) score += 1;
+    }
+    return { p, score };
+  }).filter((x) => x.score > 0).sort((a, b) => b.score - a.score || b.p.playsCount - a.p.playsCount).map((x) => x.p);
+}
+
 // src/index.ts
 var GEN_KINDS = /* @__PURE__ */ new Set(["model", "skybox", "sfx", "texture"]);
 function getVersion() {
@@ -1916,6 +2003,8 @@ ${c.bold("Usage")}
   genex texture "<prompt>" [options] Generate a PBR texture into public/assets/textures.
   genex controller <type> [--force]  Install a physics controller (character|car|drone)
                                      into src/controllers (+ assets into public/assets).
+  genex explore "<query>" [options]  Search the curated community gallery \u2014 proven
+                                     Three.js systems you can clone or borrow parts from.
 
 ${c.bold("Options for the generators (`model` `skybox` `sfx` `texture`)")}
   --terrain            (texture) seamless tiling surface for terrain/ground.
@@ -1954,9 +2043,17 @@ ${c.bold("Options for `preview` / `publish`")}
   --categories <list>  (publish) 1-3 gallery categories, comma-separated.
                        Valid: games, assets, physics, terrain, lighting, vfx.
   --regenerate-cover   (publish) Re-mint the disc cover (concept changed).
+  --source-repo-url <url>  (publish) Upstream repo this game is a port of \u2014
+                       shown as "Ported from \u2026" credit on the game page.
+  --source-author <name>   (publish) Upstream author to credit.
+  --license <label>        (publish) Upstream license label (e.g. MIT).
   --api-url <url>      (publish) Override the API base URL.
   --env <path>         Token env file (default: ~/.genex/env).
 
+${c.bold("Options for `explore`")}
+  --json               Print the top matches as JSON (for tools/agents).
+  --api-url <url>      Override the API base URL.
+
 ${c.bold("Global")}
   --quiet              Reduce output.
   -h, --help           Show this help.
@@ -1981,6 +2078,7 @@ ${c.bold("Examples")}
   genex sfx "punchy laser zap" --duration 2
   genex texture "mossy cracked cobblestone" --terrain
   genex controller character
+  genex explore "grass"
 `;
 function parseArgs(argv) {
   const parsed = {
@@ -2001,7 +2099,10 @@ function parseArgs(argv) {
     "--description",
     "--categories",
     "--timeout",
-    "--duration"
+    "--duration",
+    "--source-repo-url",
+    "--source-author",
+    "--license"
   ]);
   let i = 0;
   while (i < argv.length) {
@@ -2040,6 +2141,9 @@ function parseArgs(argv) {
       case "--quiet":
         parsed.options.quiet = true;
         break;
+      case "--json":
+        parsed.options.json = true;
+        break;
       default: {
         if (needsValue.has(arg)) {
           const value = argv[i++];
@@ -2055,6 +2159,8 @@ function parseArgs(argv) {
           parsed.command = arg;
         } else if (parsed.options.name === void 0) {
           parsed.options.name = arg;
+        } else if (parsed.command === "explore") {
+          parsed.options.name = `${parsed.options.name} ${arg}`;
         } else {
           parsed.error = `Unexpected argument: ${arg}`;
           return parsed;
@@ -2097,6 +2203,15 @@ function applyValueFlag(options, flag, value) {
     case "--categories":
       options.categories = value.split(",").map((s) => s.trim().toLowerCase()).filter(Boolean);
       break;
+    case "--source-repo-url":
+      options.sourceRepoUrl = value;
+      break;
+    case "--source-author":
+      options.sourceAuthor = value;
+      break;
+    case "--license":
+      options.license = value;
+      break;
     case "--timeout": {
       const n = Number(value);
       if (!Number.isFinite(n) || n <= 0) {
@@ -2162,6 +2277,9 @@ async function main() {
     case "publish":
       await runPublish(parsed.options);
       break;
+    case "explore":
+      await runExplore({ ...parsed.options, query: parsed.options.name });
+      break;
     default:
       log.error(`Unknown command: ${parsed.command}`);
       log.plain(`Run ${c.cyan("genex --help")} for usage.`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@genex-ai/cli-demo",
-  "version": "0.18.0",
+  "version": "0.21.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-ai-model/SKILL.md

@@ -32,25 +32,33 @@ lives under `public/` so Vite ships it in the build (load it as `./assets/models
 the `public/` prefix is stripped when served). It is **committed by `npx genex publish`**,
 so it ships inside your published game.
 
-## Hero models must face forward
-
-For the model the player controls (a ship, car, character — the "hero"), the mesh should
-**face forward**: its front pointing down the direction of travel (conventionally `+Z`,
-i.e. "looking forward"). A hero whose nose points sideways reads as broken at a glance.
-
-- **In the prompt:** when it's the player's craft, ask for it facing forward — e.g.
-  `"...game-ready, facing forward, front toward +Z"`.
-- **On load (fallback):** if the imported GLB still isn't forward, rotate it once so its
-  nose aligns with travel. Wrap the model in a parent `Object3D` and apply the correction
-  to the child, so your movement code can rotate the parent cleanly:
+## Models that point somewhere must face forward
+
+Any model with a "front" the game aims — the hero the player controls, an **NPC that
+walks toward or looks at players**, a turret, a vehicle — should face **forward**: its
+front toward `+Z` (glTF's "looking forward"), so yaw/`lookAt` code points it correctly.
+A hero whose nose points sideways — or an enemy that chases you while staring off to the
+side — reads as broken at a glance.
+
+- **In the prompt:** ask for it — e.g. `"...game-ready, facing forward, front toward +Z"`.
+  Treat this as a hint, not a guarantee: generated meshes regularly come back rotated
+  anyway, so the check below is never optional.
+- **On load (always check — hero AND NPC):** if the GLB isn't `+Z`-forward, rotate it
+  once. Wrap the model in a parent `Object3D` and put the correction on the child, so
+  game code rotates the parent cleanly:
   ```ts
-  const hero = new THREE.Object3D();
+  const rig = new THREE.Object3D();
   gltf.scene.rotation.y = Math.PI / 2; // one-time facing correction — tune per model
-  hero.add(gltf.scene);
-  scene.add(hero); // move/rotate `hero`, not gltf.scene
+  rig.add(gltf.scene);
+  scene.add(rig); // move/rotate/lookAt `rig`, not gltf.scene
   ```
-- Orientation **is** visible in a still — confirm the hero faces forward in your
-  self-check screenshot before moving on.
+  Clones inherit the fix only if you clone the corrected child (or the whole rig) —
+  never the raw `gltf.scene`.
+- **Verify it, don't assume it.** Orientation **is** visible in a still — in your
+  self-check screenshot confirm the hero faces its travel direction AND that NPCs driven
+  by chase/aim code face their target (an enemy rotated 90° from its victim is this
+  pipeline's most common visible bug). If you can't capture real gameplay (a draft's
+  sign-in gate is up), say so plainly instead of skipping the check silently.
 
 ## Load it into the scene
 

package/templates/skills/genex-explore/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: genex-explore
+description: Search the curated Genex community gallery with `npx genex explore` before hand-writing hard visual or physics systems. Use when the game needs terrain, grass, water, vehicles, buildings, dungeons, flocking/boids, or advanced shader work — proven open-source Three.js implementations you can clone as a starting point or borrow parts from, credits included.
+---
+
+# Genex Explore — proven building blocks from the community gallery
+
+Some systems are notoriously hard to get right from scratch: believable grass,
+vehicle physics, procedural buildings and dungeons, fish/boid flocking, water,
+advanced shader effects. The curated community gallery holds **faithful ports of
+proven open-source Three.js projects** — playable, cloneable, and licensed for
+reuse. Search it before hand-writing one of those systems.
+
+## When to use
+
+Before building a hard visual/physics system by hand, run:
+
+```bash
+npx genex explore "<what you need>"
+```
+
+Examples: `npx genex explore "grass"`, `npx genex explore "vehicle physics"`,
+`npx genex explore "procedural building"`. No sign-in needed — this works even
+before `genex init`.
+
+Each result prints everything you need to act on it:
+
+- `play:` — open it in the browser to judge whether it fits.
+- `clone:` — the public repo with **editable source on `main`**.
+- `upstream:` — the original source repo, with its author and license.
+
+Add `--json` for machine-readable output.
+
+## How to integrate a result
+
+**As a NEW game (start from the whole project):**
+
+1. `git clone <clone URL from the output> <name>` — pick a short one-word name.
+2. `cd <name>`, then `npx @genex-ai/cli-demo@latest init <name>` — choose
+   "Ignore files and continue" if it warns the folder isn't empty; never use
+   `--force`. This creates your own project; the original is untouched.
+3. `npm install`, keep `base: './'` in `vite.config`, then build your changes
+   and ship with `npx genex preview`.
+
+**To BORROW parts into the current project:**
+
+1. Clone the result somewhere temporary, separate from your project
+   (e.g. `/tmp/genex-explore-src`).
+2. Study how it implements the part you need, then bring **just that** over —
+   real code and assets, adapted to your file paths. Don't wholesale-overwrite
+   your game.
+3. Reused assets must live under `public/assets/` to ship. New assets are
+   generated as usual with `$genex-ai-model`, `$genex-ai-skybox`,
+   `$genex-ai-sfx`, or `$genex-ai-texture`.
+
+## Credits rule (non-negotiable)
+
+Every curated result carries an upstream link, author, and license — that
+credit is part of the deal that makes these projects reusable. Whatever you
+build from one:
+
+- keep the attribution block in the README (upstream source repo URL, author,
+  license) exactly as the port carries it;
+- keep any in-game credits screens or notices in place;
+- carry the credit into anything you publish or remix from it.
+
+If nothing matches your query, try a broader term (terrain, grass, vehicle,
+water, building, dungeon, fish, shader) — or build it with the regular
+`genex-threejs-*` skills instead.

package/templates/skills/genex-threejs-camera-direction/SKILL.md

@@ -33,6 +33,18 @@ Read [references/camera-rigs.md](references/camera-rigs.md)
 for exact chase/side/orbit rigs, projection values, transition
 rules, floating-origin shot, pointer controls, and implementation limits.
 
+## Aiming and pointer lock
+
+Camera-aimed action — a third-person shooter reticle, first-person look —
+wants **pointer lock**, not drag-orbit: request it on canvas click
+(`canvas.requestPointerLock()`), drive yaw/pitch from `mousemove` deltas while
+locked, and treat lock loss (Esc) as aim-paused — show a small "click to aim"
+hint whenever unlocked. Keep drag-orbit for non-combat cameras (exploration,
+building, spectating). Pointer lock works everywhere a Genex game runs:
+standalone the game is the top-level page, and the platform's game frame
+already grants the pointer-lock permission — no setup needed. Re-sync
+yaw/pitch from the camera whenever lock is acquired (rule below).
+
 ## Non-negotiable rules
 
 - Use subject dimensions to derive offsets; do not tune one fixed distance for

package/templates/skills/genex-threejs-embed-auth/SKILL.md

@@ -260,6 +260,24 @@ instead. Don't code around any of this: no `?`/`#` URL params of yours will
 be affected, and `isEmbedded()` / the return-trip handling are internal SDK
 concerns.
 
+### Validating a draft (read before self-testing)
+
+An unpublished draft shows the sign-in gate to any browser that isn't signed
+in as the owner — **including your own test browser** (Playwright, headless
+Chrome). The game still boots behind the overlay: console logs, DOM snapshots,
+and key events all work — but every screenshot shows the gate, not the game,
+and a gate capture is NOT visual evidence.
+
+- Validate what the gate can't hide: a clean console, the canvas booting, the
+  HUD present in a DOM snapshot, controls registering.
+- Do NOT work around the gate: don't dig through the SDK's internals for
+  undocumented URL fragments, and don't drive the user's own signed-in
+  browser.
+- For the visual pass on a draft, hand it off plainly: "open your draft page
+  and tell me what you see" — the owner's view is the real check. Once the
+  game is **published**, any fresh browser gets in as a guest, so your own
+  test browser works again for full visual validation.
+
 ## Checklist
 
 - [ ] `initGameSentry({ slug: GENEX.slug })` is the very first call in `main.ts`.

package/templates/skills/genex-threejs-game-feel/SKILL.md

@@ -33,6 +33,10 @@ no matter how good it looks.
   itself, or apply them only to hand-rolled movement.)
 - If an action can't fire (cooldown, no ammo), say so instantly — a click, a
   dimmed icon — silence reads as broken input.
+- Camera-aimed shooting wants **pointer lock** (click to aim, Esc releases —
+  `$genex-threejs-camera-direction` has the rig rules); firing at a reticle
+  with an unlocked drag-to-turn camera feels imprecise no matter how tight
+  the numbers are.
 
 ## Movement: snappy beats realistic
 

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.1** (`objects`/`host` since 0.4; `matchmake()` since 0.5; presets + `score()`/`finish()` since 0.6; `createPrivate()`/`joinPrivate()` since 0.7; matchmake auto-retry + `retry()` since 0.7.1).
+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; matchmake auto-retry + `retry()` since 0.7.1; 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)
 
@@ -123,6 +132,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
@@ -165,13 +204,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'`.
@@ -223,6 +270,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
@@ -306,7 +364,10 @@ host-driven saving works as long as ANY account is in the room.
 
 ## Checklist
 
-- [ ] `npm i @genex-ai/multiplayer` (≥ 0.7.1); 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`).
@@ -328,3 +389,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

@@ -86,4 +86,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.

package/templates/skills/genex-threejs-visual-validation/SKILL.md

@@ -32,7 +32,15 @@ this is the whole acceptance gate, and it is also the minimum for every game:
 2. Press each documented control once (keys, pointer); assert a **visible
    response** to every one — the player moves, the camera turns, the button
    fires.
-3. Capture one screenshot of live gameplay.
+3. Capture one screenshot of live gameplay — of the **game**, not a sign-in
+   gate or loading screen. A capture of the SDK's "Sign in to play" overlay is
+   NOT gameplay evidence; if a draft's gate blocks the view, say so plainly
+   (see the embed-auth skill's "Validating a draft" note) instead of passing
+   the capture off as validation.
+4. In that screenshot, check oriented models: the hero faces its travel
+   direction, and NPCs driven by chase/aim code face their target. A model
+   rotated 90° reads as broken — `$genex-ai-model` has the one-time facing
+   fix.
 
 Everything deeper (baselines, seed sweeps, mosaics, budgets) belongs to
 visual-system work — the sequence above.