@genex-ai/cli-demo 0.17.0 → 0.20.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,7 +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).
+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)
 
@@ -60,11 +60,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 +75,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": {
@@ -188,7 +191,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

package/templates/skills/genex-threejs-multiplayer/references/realtime-patterns.md

@@ -18,13 +18,20 @@ already did, and stacking two smoothers adds visible lag.
 ```ts
 import * as THREE from "three";
 import { connect } from "@genex-ai/multiplayer";
+import { waitForPlayer, getColyseusAuth } from "@genex-ai/embed-sdk";
 import { GENEX } from "./genex.config";
 
 // Your published state — EVERY synced field, including discrete ones like hp. `me.set`
 // replaces your state wholesale, so the tick must send all of these every time (below).
 type S = { x: number; z: number; q: number[]; hp: number };
 
-const room = await connect<S>({ url: GENEX.colyseusUrl, room: GENEX.slug });
+const { user } = await waitForPlayer();  // player gate (guest OR signed-in) — never waitForAuth()
+const room = await connect<S>({
+  url: GENEX.colyseusUrl,
+  room: GENEX.slug,
+  name: user.name,
+  auth: getColyseusAuth()!,  // REQUIRED — tokenless joins are rejected. Read fresh each connect; NEVER log it.
+});
 
 // --- local player: input mutates this; we render yourself from it (zero latency) ---
 // This ONE object holds everything you sync. Keep hp/ammo/etc. here too — see the warning below.
@@ -132,8 +139,11 @@ Rules that keep it correct:
 
 ## Host authority (scores, rounds, world)
 
-One client is `room.host` (the first joiner, re-elected on leave). Let only the host write agreed
-state, so there's a single source of truth — no "who increments the score" races:
+One client is `room.host` — the earliest **signed-in** player (guests host only while no account
+is present), and the host can change on **join** as well as leave: the first account entering a
+guest-hosted room takes over. Always react to `on('host')` / read `isHost` in your loop, never
+once at startup. Let only the host write agreed state, so there's a single source of truth — no
+"who increments the score" races:
 
 ```ts
 function updateHud() {
@@ -147,8 +157,9 @@ function goal(team: "a" | "b") {
 room.on("host", () => {/* host migrated — the new host takes over writing */});
 ```
 
-`room.on('shared', …)` fires when a key is **first set**, not on every change — for a live value,
-read `room.shared.get(...)` in your loop (as `updateHud` does) rather than relying on the event.
+`room.on('shared', …)` fires on every **distinct** change of a key (a set to the same value is
+de-duped) — but for a value you render every frame, read `room.shared.get(...)` in your loop (as
+`updateHud` does) rather than wiring render state through the event.
 
 ## Custom events (shots, emotes, chat)
 

package/templates/skills/genex-threejs-physics-rapier/SKILL.md

@@ -62,7 +62,8 @@ physics.onBeforeStep(() => {
 const clock = new THREE.Clock();
 renderer.setAnimationLoop(() => {
   physics.step(clock.getDelta()); // fixed substeps + mesh sync + events
-  // camera follow, animation mixers — render-delta work stays OUT here
+  // camera follow, mixers, HUD go HERE (render-delta work, after the step) —
+  // never inside onBeforeStep above
   renderer.render(scene, camera);
 });
 ```

package/templates/skills/genex-threejs-physics-rapier/references/colliders-from-assets.md

@@ -179,7 +179,7 @@ reference).
 ## End-to-end: a genex model prop
 
 ```ts
-import { GLTFLoader } from "three/examples/jsm/loaders/GLTFLoader.js";
+import { GLTFLoader } from "three/addons/loaders/GLTFLoader.js";
 import { collidersFromObject } from "./controllers/shared/colliders.ts";
 
 const loader = new GLTFLoader();