@genex-ai/cli-demo 0.17.0 → 0.18.0

package/templates/skills/genex-ai-model/SKILL.md

@@ -58,7 +58,7 @@ Use Three.js `GLTFLoader` (the game serves at the domain root
 `https://<slug>.genex.technology/`, so relative or absolute paths both work):
 
 ```ts
-import { GLTFLoader } from "three/examples/jsm/loaders/GLTFLoader.js";
+import { GLTFLoader } from "three/addons/loaders/GLTFLoader.js";
 
 const loader = new GLTFLoader();
 const gltf = await loader.loadAsync("./assets/models/weathered-wooden-barrel.glb");
@@ -71,6 +71,11 @@ scene.add(model);
 To place many copies, `model.clone()` per instance. For animated GLBs, drive
 `gltf.animations` with a `THREE.AnimationMixer`.
 
+**If the game has physics, give the model a collider** — a GLB added only to the
+scene is a ghost: players and objects pass straight through it.
+`$genex-threejs-physics-rapier` has the decision table
+(`collidersFromObject(model, "hull")` is the default for props).
+
 ## Publish checklist (so players see the model)
 
 - Reference assets with **relative** paths (`./assets/...`); absolute

package/templates/skills/genex-ai-sfx/SKILL.md

@@ -58,8 +58,17 @@ Reuse one loaded `buffer` across many plays; create a fresh `Audio`/`PositionalA
 - Relative path `./assets/sfx/...`; `base: "./"` in `vite.config.ts`; files live under
   `public/assets/` so Vite ships them; `npx genex publish` ships them to R2.
 
+## Options
+
+- `--duration <sec>` — target length 0.5–22 (shown in Run above); omit to let
+  the model pick.
+- `--no-wait` — enqueue and return immediately (the file won't be downloaded;
+  re-run without `--no-wait` to fetch it).
+- `--api-url <url>` — override the API base (local dev).
+
 ## Troubleshooting
 
+- **"Not authorized"** — run `npx @genex-ai/cli-demo@latest init` first (it writes your `GENEX_TOKEN`).
 - **No sound** — the `AudioContext` is suspended until a user gesture; trigger the
   first play from a click/keydown. Confirm the camera has an `AudioListener`.
 - **Too quiet/loud** — `sound.setVolume(0..1)`; for positional, tune

package/templates/skills/genex-ai-skybox/SKILL.md

@@ -56,7 +56,8 @@ const pmrem = new THREE.PMREMGenerator(renderer);
 const envMap = pmrem.fromEquirectangular(texture).texture;
 scene.environment = envMap;
 scene.background = texture; // keep the raw texture for the visible sky
-texture.dispose; // (dispose the PMREM source later if you stop using it)
+// Do NOT dispose `texture` here — it IS the visible background. Dispose it only
+// if you later stop using it as the sky.
 ```
 
 ## Publish checklist
@@ -66,8 +67,15 @@ texture.dispose; // (dispose the PMREM source later if you stop using it)
 - Generated files live under `public/assets/` so Vite ships them; `npx genex publish`
   ships that folder with the game.
 
+## Options
+
+- `--no-wait` — enqueue and return immediately (the file won't be downloaded;
+  re-run without `--no-wait` to fetch it).
+- `--api-url <url>` — override the API base (local dev).
+
 ## Troubleshooting
 
+- **"Not authorized"** — run `npx @genex-ai/cli-demo@latest init` first (it writes your `GENEX_TOKEN`).
 - **Sky looks too dark/bright** — adjust `renderer.toneMappingExposure`, or scale
   `scene.environment` influence via material `envMapIntensity`.
 - **Seam/pole artifacts** — that's inherent to equirect images; keep the camera

package/templates/skills/genex-ai-texture/SKILL.md

@@ -41,8 +41,10 @@ Committed by `npx genex publish`, so it ships with your game.
 ```ts
 import * as THREE from "three";
 
+// The extension varies by provider (production emits .png) — use the EXACT
+// path the CLI printed when generation finished, don't assume .jpg.
 const map = await new THREE.TextureLoader().loadAsync(
-  "./assets/textures/lush-green-grass/basecolor.jpg",
+  "./assets/textures/lush-green-grass/basecolor.png",
 );
 map.colorSpace = THREE.SRGBColorSpace;
 map.wrapS = map.wrapT = THREE.RepeatWrapping;
@@ -70,8 +72,16 @@ scene.add(ground);
 - Relative path `./assets/textures/...`; `base: "./"` in `vite.config.ts`; files live under
   `public/assets/` so Vite ships them; `npx genex publish` ships them to R2.
 
+## Options
+
+- `--terrain` — seamless tiling tuned for ground/terrain (shown in Run above).
+- `--no-wait` — enqueue and return immediately (the file won't be downloaded;
+  re-run without `--no-wait` to fetch it).
+- `--api-url <url>` — override the API base (local dev).
+
 ## Troubleshooting
 
+- **"Not authorized"** — run `npx @genex-ai/cli-demo@latest init` first (it writes your `GENEX_TOKEN`).
 - **Visible tiling seams** — use `--terrain` (tuned for seamless edges), lower the
   `repeat`, or blend two textures. Perfect seamlessness is a known v1 limitation.
 - **Colors look washed/dark** — ensure `map.colorSpace = THREE.SRGBColorSpace`.

package/templates/skills/genex-getting-started/SKILL.md

@@ -45,6 +45,30 @@ npx genex texture "mossy cobblestone" --terrain # a tiling surface texture
 Each has a focused skill with the exact loader code — `$genex-ai-model`,
 `$genex-ai-skybox`, `$genex-ai-sfx`, `$genex-ai-texture`.
 
+## Identity & saves (every game)
+
+Every Genex game ships with built-in player identity: sign-in, guests, per-player
+saves, a shared world slot, and leaderboards — all through `@genex-ai/embed-sdk`.
+Load `$genex-threejs-embed-auth` before writing boot code; it wires the one-call
+setup (`initEmbed` + `waitForPlayer`) and is also where multiplayer gets its
+connection auth. A game without it loses all progress on refresh.
+
+## Loading screens (recommendation)
+
+Generated assets take a moment to fetch at runtime. Show a simple loading
+screen or progress hint while models/textures/sounds load, and remove it when
+the game is ready — players should never stare at a black screen. This is a
+recommendation, not a rule: even a one-line "Loading…" overlay over the dark
+page background is enough.
+
+## Remixing an existing game
+
+If the project folder already contains a game (a remix or any existing
+project), don't scaffold a new app over it: read the existing code first and
+keep its renderer, structure, and conventions — extend, don't rebuild.
+Running `genex init` in such a folder only wires identity/publishing and
+refreshes the genex-owned skills; the game's own files are never touched.
+
 ## Publishing
 
 Before your first `genex preview`, the play URL (`https://<slug>.genex.technology/`)
@@ -66,6 +90,26 @@ If unsure, use `games` (also the server's fallback for anything unrecognized).
 Your own files were left untouched. `genex init` only adds missing files and
 refreshes the genex-owned ones.
 
+## Reconnecting an existing game (`genex link`)
+
+Each game's connection to its live page is folder-local (`.genex/project.json`
++ the `genex_key` deploy key). If that folder is gone — deleted, or the game
+was built on another machine — **don't run `init` to "recover" it**: that
+creates a brand-new game at a new URL. Instead, clone the game's source repo
+and re-link the clone to the same live game:
+
+```bash
+git clone <the game's repo url> my-game && cd my-game
+npm install
+npx @genex-ai/cli-demo@latest link <slug>   # slug = the name in the play URL
+```
+
+`link` never creates a project: it signs in if needed (the browser opens once),
+registers a fresh deploy key for this folder, and rewrites the local link.
+After it, `npx genex preview` / `npx genex publish` update the **same live
+game** — plays, likes, and comments stay. It also fixes a folder whose
+authorization went stale ("Not authorized" from `preview`/`publish`).
+
 ## Re-running setup
 
 Safe to run any time — genex-owned skills are refreshed to the latest version,

package/templates/skills/genex-threejs-atmosphere-aerial-perspective/SKILL.md

@@ -5,6 +5,10 @@ description: Implement sky and aerial perspective for Genex Three.js games. Use
 
 # Genex Three.js Atmosphere And Aerial Perspective
 
+**Static sky at a fixed time of day → `$genex-ai-skybox` instead** (one command,
+a real 360° image + lighting). This skill is for dynamic, animated, or
+scale-transitioning skies (time-of-day, ground-to-space).
+
 Treat sky rendering and aerial perspective as two views of the same scattering model. They must share radii, density profiles, coefficients, sun direction, exposure scale, and coordinate transforms.
 
 ## Choose the implementation tier

package/templates/skills/genex-threejs-bloom/references/bloom.md

@@ -2,6 +2,8 @@
 
 Use this reference to choose bloom ownership, signal order, selective contribution, and scene-relative emissive ranges without making bloom responsible for the underlying form.
 
+> **Renderer note:** this reference assumes `WebGPURenderer` + TSL node materials. Check the project's actual renderer first — the Genex scaffold ships vanilla WebGL three.js. On WebGL, adapt the technique with standard materials / `EffectComposer` passes or pick a simpler alternative; never switch renderers mid-project.
+
 ## Contents
 
 - production WebGPU pipeline signal order
@@ -119,7 +121,7 @@ Composer order:
 scene -> SSAO -> volumetrics -> bloom -> lens flare -> fog/color
 ```
 
-This is a useful comparison, not the quality target. The threshold is very low
+This is a useful comparison, not the quality target — note its fog/color stage runs AFTER bloom, deviating from the canonical order in $genex-threejs-image-pipeline (fog belongs before bloom so bright fog does not glow). The threshold is very low
 and can bloom ordinary bright surfaces. The wrapper exposes only enabled,
 strength, and threshold, while radius stays at its constructor value.
 

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

@@ -5,6 +5,12 @@ description: Design advanced Three.js camera systems for Genex browser games. Us
 
 # Genex Three.js Camera Direction
 
+**Boundary:** the pack's default third-person camera is the bundled
+`FollowCamera` (see `$genex-threejs-character-controller` — the vehicle
+controllers hand off to it too). Extend and tune that first; load this skill
+for rigs beyond it — top-down/side views, authored shots, cinematics, pointer
+look, and camera handoffs.
+
 Treat the camera as an authored visual system, not a passive viewport. Compose
 the subject, establish scale, choose a stable up frame, and make every mode
 handoff explicit.

package/templates/skills/genex-threejs-camera-direction/references/camera-rigs.md

@@ -289,8 +289,8 @@ Keys are cleared on:
 
 Scene-specific constraints then run after controls:
 
-- NASA room clamps X/Y/Z with floor, ceiling, and wall clearance.
-- Mann’s Planet clamps camera Y above sampled terrain plus `0.2`.
+- an interior room scene clamps X/Y/Z with floor, ceiling, and wall clearance.
+- a terrain scene clamps camera Y above sampled terrain plus `0.2`.
 - cinematic scenes block movement keys while retaining their authored camera.
 
 Input control and spatial constraint are separate layers.

package/templates/skills/genex-threejs-character-controller/SKILL.md

@@ -139,7 +139,12 @@ when done (punch-on-click is the default). Read
 wiring, the **full 46-clip catalog** with genre hints, `playOneShot` options,
 overrides, foot IK, and remote-player animation.
 
-## Mobile: TouchJoystick + VirtualButton
+## Mobile: TouchJoystick + VirtualButton (wire by default)
+
+**Wire these whenever this controller is installed — not only when asked.**
+Published games get opened on phones from shared links; the bundled touch
+controls are ~6 lines and invisible on desktop. (Designing phone-specific
+layouts or testing mobile viewports stays ask-only.)
 
 ```ts
 import { TouchJoystick, VirtualButton } from "./controllers/character/touch-joystick.ts";

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

@@ -138,7 +138,11 @@ session is blocked):
 - `getLeaderboard({ board?, limit?, order? }?)` → `Promise<{ items, me }>` —
   top entries (verified display names — never trust client-side name input
   for this) + the signed-in player's own `{ rank, score }`. Works for guests
-  too (`me: null`).
+  too (`me: null`). `limit` caps at 100 server-side.
+
+Server write limits (per player, per minute): **60 player-saves, 120
+world-saves, 30 score submits**. A debounced ~1/sec checkpoint never gets near
+them — only a save-per-frame loop does (it surfaces as HTTP 429).
 
 From `@genex-ai/embed-sdk/sentry` (crash reporting; exactly these two):
 
@@ -298,6 +302,10 @@ concerns.
   header (401), a guest token (403 `guest_no_save`), or the token belongs to a
   different game (403). All three mean the code bypassed the SDK helpers —
   switch to `savePlayerState`/`saveWorldState`, which handle every case.
+- **Saves or score submits return 429** — writing too often (per-player limits:
+  60 player-saves/min, 120 world-saves/min, 30 score submits/min). Debounce to
+  ~1 write/sec at checkpoints and never save in the render loop; back off a
+  second and retry.
 - **`saveWorldState` resolves `{ conflict: true }`** — another player wrote the
   shared slot since your last read. Expected under concurrency: reload with
   `loadWorldState()`, merge, retry with the fresh `version`. If it happens

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

@@ -0,0 +1,97 @@
+---
+name: genex-threejs-game-feel
+description: Make a Genex Three.js game feel alive — instant input response, acceleration curves, camera follow and impact shake, layered hit feedback, hitstop, readable cooldowns, difficulty ramp, and a fast fail/retry loop. Use when a game technically works but feels flat, floaty, or boring, and before calling any playable loop done.
+---
+
+# Genex Three.js Game Feel
+
+"Works" and "feels good" are different finish lines. This skill is the second
+one: the tuning pass that turns a functioning loop into a game people replay.
+Run it once the mechanics exist — feel tuning before mechanics is polish on
+nothing.
+
+## The loop test (run this first)
+
+A playable loop has four parts. If any is missing, fix that before tuning:
+
+1. **Verb** — something the player does (move, jump, shoot, grab).
+2. **Objective** — something to chase (score, survive, reach, beat).
+3. **Feedback** — success and damage are unmistakable the moment they happen.
+4. **Fail / retry** — the game can be lost, and restarting is instant.
+
+A game that can't be lost — or takes more than a second to retry — gets boring
+no matter how good it looks.
+
+## Input: respond this frame
+
+- Act on input the **same frame** it arrives. Animation follows the action; it
+  never gates it (the character moves now, the run cycle catches up).
+- Add forgiveness windows: buffer a jump pressed ~100 ms early, allow a jump
+  ~100 ms after walking off a ledge. Players read forgiveness as "tight
+  controls", not as cheating. (The bundled `CharacterController` ships with
+  NO input buffer or coyote time — add these in `character-controller.ts`
+  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.
+
+## Movement: snappy beats realistic
+
+- Reach max speed fast; stop even faster (deceleration stronger than
+  acceleration). Long ease-in reads as "floaty" — the most common complaint.
+- Tune with live numbers, not rebuilds: keep the constants (accel, decel, max
+  speed, jump impulse) in one place and tweak while replaying the same ten
+  seconds.
+- On-foot and vehicle movement ship pre-tuned in
+  `$genex-threejs-character-controller` and
+  `$genex-threejs-vehicle-controllers` — retune their exposed knobs before
+  writing new movement math.
+
+## Camera: the invisible half of feel
+
+- Smooth follow with **lookahead** — bias the camera toward where the player
+  is going, never behind the action hiding the next decision.
+- FOV kick on speed/boost (a few degrees, eased) sells acceleration better
+  than particles.
+- Impact shake: short (< 0.2 s), small, decaying, and always **caused** —
+  shake per event, never ambient. Rigs and handoffs live in
+  `$genex-threejs-camera-direction`.
+- Feel work (shake, FOV kick, hitstop triggers) runs in the **render phase,
+  after `physics.step(...)`** — never inside `onBeforeStep` (that's fixed-step
+  physics territory; see the physics skill's ordering contract).
+
+## Impact: layer the feedback
+
+Every meaningful event the player caused should be **seen and heard**. For big
+hits, layer two or three of:
+
+- a flash or scale pop on the thing that was hit;
+- a particle burst — `$genex-threejs-procedural-vfx`;
+- a sound — generate real ones with `npx genex sfx` (`$genex-ai-sfx`);
+- **hitstop**: freeze the simulation 30–80 ms on heavy impacts (skip rendering
+  pauses — just hold the physics/game clock). Longer than ~100 ms feels like lag.
+  With the bundled physics pack this is built in — `physics.paused = true` /
+  `physics.timeScale = 0.2` (see the physics skill's pause/slow-mo section) plus
+  `anims.setPaused(true)` / `anims.setTimeScale(0.2)` for the character's
+  animations. Don't hand-roll a second clock.
+
+One layer per small event, three for the biggest — uniform intensity flattens
+everything back out.
+
+## Pacing and fail/retry
+
+- Show cooldowns and charges visibly (a refilling ring beats a hidden timer).
+- Ramp difficulty measurably (speed, spawn rate, tighter windows) so the
+  player feels progress; reward near-misses where the design allows.
+- Death should teach: show what killed you, keep the score/best visible, and
+  restart on ONE key without a page reload. The faster the retry, the more
+  "one more try" the game becomes.
+
+## Failure modes to catch
+
+- A mechanic fires with zero feedback — it might as well not have happened.
+- The camera hides what the player needs to react to next.
+- The game cannot be lost, or losing dumps you to a dead screen.
+- Restart requires reloading the page (kills the retry loop — and reloads
+  re-run auth and asset loading).
+- Shake/flash spam with no cause — feedback inflation reads as noise.
+- Feel constants scattered through the code where nobody dares touch them.

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

@@ -0,0 +1,119 @@
+---
+name: genex-threejs-game-ui
+description: Design the 2D interface of a Genex Three.js game — HUD, menus, pause/win/lose screens, score and health displays, overlays, loading screens, and UI state flow. Use whenever the game needs on-screen text, meters, buttons, or menus, or when the interface reads as a generic dashboard, covers the action, or shifts around as numbers change.
+---
+
+# Genex Three.js Game UI
+
+The interface is part of the game, not chrome around it. A strong HUD tells the
+player what to protect, what to chase, and what just happened — without ever
+stealing attention from the scene. This skill covers the 2D layer of a vanilla
+Three.js game: architecture, the states every game needs, readability rules,
+and wiring UI to game state.
+
+## Architecture: DOM overlay by default
+
+Genex games are plain Vite + Three.js apps, so the default UI layer is a DOM
+overlay — HTML/CSS on top of the canvas, not text sprites inside the scene:
+
+```html
+<div id="ui">          <!-- fixed, full-screen, pointer-events: none -->
+  <div id="hud">…</div>
+  <!-- data-phase must exactly match a phase name in setPhase() below — that's how
+       screens toggle. A phase with no screen (e.g. "playing") just hides them all. -->
+  <div id="screen-loading" class="screen" data-phase="loading">…</div>
+  <div id="screen-pause" class="screen" data-phase="paused" hidden>…</div>
+  <div id="screen-over"  class="screen" data-phase="over" hidden>…</div>
+</div>
+```
+
+```css
+#ui { position: fixed; inset: 0; pointer-events: none; font-variant-numeric: tabular-nums; }
+#ui button, #ui .screen { pointer-events: auto; }
+```
+
+`pointer-events: none` on the root keeps the canvas playable; re-enable it only
+on elements that are actually clickable. Keep ALL layout in CSS — never
+position UI by mutating inline pixel styles per frame. In-world (diegetic) UI —
+a health bar floating over an enemy, a scoreboard mesh in a stadium — is the
+exception for things that belong to the world, not the default.
+
+## The states every game needs
+
+Build these as show/hide layers over one state machine, not as ad-hoc DOM
+edits scattered through the code:
+
+1. **Loading** — visible until assets are ready; players must never stare at a
+   black screen. Even "Loading… 3/5" over the dark background is enough.
+2. **Playing HUD** — the minimal always-on layer (see hierarchy below).
+3. **Pause** — freeze the loop, dim the scene, show resume/restart. (With the
+   bundled physics pack, freezing is built in: `physics.paused = true` plus
+   `anims.setPaused(true)` — don't hand-roll a second clock.)
+4. **Fail / retry** — what happened, the score, and a ONE-KEY instant restart
+   (show which key). Restart must not reload the page.
+5. **Win / next** — celebrate, then offer the next thing to do.
+6. **Identity moments** — the player's name/guest identity comes from
+   `$genex-threejs-embed-auth` (`waitForPlayer()`); leaderboards render from
+   `getLeaderboard()`. Never invent your own login UI.
+7. **Multiplayer lobby/points** — matchmaking status, countdowns, and match
+   HUD state come from `$genex-threejs-multiplayer`; render what the SDK
+   reports, don't guess at it.
+
+## Hierarchy: if everything shouts, nothing reads
+
+Order the HUD by what the player loses the game for ignoring:
+
+1. **Survival/status** — health, time, fuel: biggest, most stable, edge/corner.
+2. **Objective** — score, laps, wave: prominent but calmer.
+3. **Moment feedback** — "+100" popups, damage flashes: transient, near the
+   action, gone in under a second.
+4. **Flavor** — combo names, taunts: smallest, skippable.
+
+## Readability rules
+
+- **Never cover the player or incoming threats.** Corners and edges belong to
+  UI; the center of the screen belongs to the game.
+- **Stable layout.** A score ticking 9 → 10 → 100 must not reflow anything:
+  tabular numerals (`font-variant-numeric: tabular-nums`), fixed-width slots,
+  meters that change fill — not size.
+- **Contrast against the real scene.** Test text over the brightest AND
+  darkest areas of actual gameplay; a soft dark plate or text-shadow beats
+  restyling per level.
+- **Desktop first.** Verify at desktop sizes and survive window resizes
+  without clipping; don't design phone layouts or test mobile viewports unless
+  the user asks. Exception: when a bundled controller (character/car/drone) is
+  installed, DO wire its ready-made touch controls behind
+  `navigator.maxTouchPoints > 0` — invisible on desktop, and the shared link
+  isn't dead on a phone (the controller skill has the wiring).
+
+## Wire UI to game state, never the reverse
+
+The game state machine is the single source of truth; the UI renders it.
+Don't keep a second copy of rules in the UI layer (a timer in the HUD and a
+timer in the game WILL drift apart). Buttons and menu keys emit the same
+intents the gameplay input path uses — a "Restart" button and the R key must
+run identical code.
+
+```ts
+// Each .screen carries data-phase (see the HTML block above); the names must match exactly.
+function setPhase(phase: "loading" | "playing" | "paused" | "over" | "won") {
+  for (const s of document.querySelectorAll<HTMLElement>("#ui .screen"))
+    s.hidden = s.dataset.phase !== phase;
+}
+```
+
+UI sounds (clicks, confirms, win stingers) are one `npx genex sfx` away — see
+`$genex-ai-sfx`.
+
+## Failure modes to catch before the player does
+
+- A generic stat dashboard (rows of labels + numbers) instead of a designed
+  HUD — pick the 2–3 numbers that matter and style them by hierarchy.
+- UI panels covering the player or the thing about to kill them.
+- Layout shifting as numbers grow.
+- A fail state with no visible restart key, or a restart that reloads the page.
+- Buttons that render but don't emit the game's real input intents.
+- UI logic duplicating game rules and drifting out of sync.
+
+Before calling UI done, check it over real gameplay footage at desktop size —
+`$genex-threejs-visual-validation` has the capture discipline.

package/templates/skills/genex-threejs-image-pipeline/references/image-pipeline.md

@@ -2,6 +2,8 @@
 
 Use this reference to compose shared scene buffers, lighting effects, atmosphere, bloom, exposure, tone mapping, grading, and feature-local render targets with explicit ownership.
 
+> **Renderer note:** this reference assumes `WebGPURenderer` + TSL node materials. Check the project's actual renderer first — the Genex scaffold ships vanilla WebGL three.js. On WebGL, adapt the technique with standard materials / `EffectComposer` passes or pick a simpler alternative; never switch renderers mid-project.
+
 ## Contents
 
 - production WebGPU pipeline WebGPU graph

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

@@ -37,16 +37,7 @@ example, the shared-object/ball code, rotation, and host usage. Read
 npm i @genex-ai/multiplayer
 ```
 
-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.
+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).
 
 ## Matchmaking (competitive presets — server-owned)
 
@@ -60,11 +51,13 @@ HUD from `mm.matchmaking` (its `status`, `queue.position`, `players`/`opponents`
 // 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.
+await waitForPlayer();  // identity gate first (guest OR signed-in) — same rule as connect()
 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 */});
+mm.on('error', (e) => {/* queue join failed even after the SDK's automatic retries (backoff, ~10s)
+                          — persistent, e.g. broken auth. Fix the cause, then call mm.retry(). */});
 
 // Report ONLY your own outcome — the server adjudicates. Which call fits depends on the win condition:
 mm.eliminated();   // I'm out              (lastStanding)
@@ -73,8 +66,9 @@ 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.
+`genex preview` AND `genex publish` (removing it from package.json clears the stored config on the
+next preview/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": {
@@ -129,36 +123,6 @@ 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
@@ -188,7 +152,9 @@ fights (many writers). A ball on `objects` glides and has one owner. That's the
   - `set(id, state)` — publish it (only lands while you own it; full flat object each call).
   - `get(id)` → `{ id, owner, isMine, state, stateRaw }` or `undefined`. `state` is auto-smoothed
     (or live if `isMine`); `stateRaw` is the raw latest.
-  - `release(id)` — give up ownership. `remove(id)` — destroy it (for transient bullets/pickups).
+  - `release(id)` — give up ownership. `remove(id)` — destroy it (for transient bullets/pickups);
+    **owner-only** — claim it first, or let the current owner remove it (the relay rejects a
+    non-owner's destroy).
   - `ids()` — all object ids seen.
 - `room.isHost` / `room.host` — you are (or who is) the elected authority. Use to pick the single
   writer of `shared` scores/rounds and the single simulator of host-owned objects. Settles within
@@ -199,21 +165,13 @@ 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(...)`. 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.
+  not inside `on(...)`. `room.leave()`.
 
 ## 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. **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.
+   object, `objects.set` it in the same tick.
 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'`.
@@ -265,17 +223,6 @@ 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
@@ -359,10 +306,7 @@ host-driven saving works as long as ANY account is in the room.
 
 ## Checklist
 
-- [ ] `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.
+- [ ] `npm i @genex-ai/multiplayer` (≥ 0.7.1); config wired into the build.
 - [ ] `connect()` runs AFTER `await waitForPlayer()` (never `waitForAuth()` — guests would
       hang) and passes `auth: getColyseusAuth()!` (the relay rejects tokenless joins —
       see `genex-threejs-embed-auth`).
@@ -384,6 +328,3 @@ 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).