@genex-ai/cli-demo 0.12.1 → 0.15.0

package/templates/skills/genex-threejs-character-controller/references/wiring.md

@@ -0,0 +1,198 @@
+# Wiring the character controller
+
+The full path from an empty scene to a playable character:
+world → `CharacterController` → `FollowCamera` → `KeyboardInput` /
+`TouchJoystick` → `CharacterAnimations`. Every class and option name below is
+the vendored code's real API — copy from here, not from memory.
+
+## 1. Physics world
+
+```ts
+import { PhysicsWorld } from "./controllers/shared/physics-world.ts";
+
+const physics = await PhysicsWorld.create();      // awaits RAPIER.init() (embedded WASM)
+const world = physics.world;                      // the raw Rapier world controllers consume
+```
+
+Nothing may construct any RAPIER object before `create()` resolves. Options if
+you need them: `gravity` (default `[0, -9.81, 0]`), `timeStep` (default
+`1/60`), `maxDelta`, `interpolate`. `physics.paused` and `physics.timeScale`
+give you pause and slow motion for free.
+
+## 2. Level colliders
+
+Every walkable surface needs a rigid body + collider. For authored boxes:
+
+```ts
+import { cuboidCollider } from "./controllers/shared/colliders.ts";
+
+const ground = new THREE.Mesh(new THREE.BoxGeometry(90, 0.5, 90), groundMat);
+scene.add(ground);
+const groundBody = physics.createBody({ type: "fixed", position: [0, -0.25, 0] }, ground);
+cuboidCollider(world, groundBody, [45, 0.25, 45], { friction: 1 }); // HALF extents
+```
+
+For loaded GLB level pieces, `collidersFromObject(world, body, gltf.scene, "trimesh")`
+auto-generates colliders per mesh (`"hull"` for dynamic props from
+`$genex-ai-model`; `"trimesh"` only on static geometry). `cuboidCollider`
+takes **half** extents — do not halve twice.
+
+## 3. Character
+
+```ts
+import { CharacterController } from "./controllers/character/character-controller.ts";
+import { characterPresets } from "./controllers/character/presets.ts";
+
+const character = new CharacterController(world, camera, {
+  ...characterPresets["default"].options,
+  position: { x: 0, y: 2, z: 0 },
+  userData: { controller: { excludeVehicleRay: true } },
+});
+scene.add(character.root);
+physics.registerBody(character.body, character.root);
+```
+
+- The constructor creates the dynamic body + capsule collider immediately.
+- `character.root` is the visual anchor; `registerBody` makes it follow the
+  body with interpolation. Register scene-root-level groups and add them to the
+  scene **first** — `registerBody` captures the parent's world matrix once and
+  never refreshes it.
+- `userData: { controller: { excludeVehicleRay: true } }` keeps car wheels
+  from treating the on-foot player as drivable ground. Related keys (set on
+  OTHER bodies): `excludeRay` (ignored by all ground queries),
+  `excludeCharacterRay` (ignored by the character's ground query only).
+- The camera argument is how movement becomes camera-relative ("forward" = away
+  from camera). Pass the same camera the `FollowCamera` drives.
+
+### Place the model so its feet touch the ground
+
+The capsule floats: in root space the ground is at
+`-(capsuleHalfHeight + capsuleRadius + floatHeight)` — **-0.8** with the
+defaults (0.3 + 0.3 + 0.2). Normalize any loaded model to ~1.35 units tall and
+drop its bounding-box bottom to that line:
+
+```ts
+const bbox = new THREE.Box3().setFromObject(model);
+const scale = 1.35 / Math.max(bbox.max.y - bbox.min.y, 1e-3);
+model.scale.setScalar(scale);
+model.position.y = -0.8 - bbox.min.y * scale;
+character.root.add(model);
+```
+
+A model hovering above the floor or knee-deep in it means this offset is wrong
+— it is the single most common wiring bug.
+
+## 4. Input
+
+```ts
+import { KeyboardInput } from "./controllers/character/keyboard-input.ts";
+
+const kb = new KeyboardInput(); // WASD/arrows move, Shift run, Space jump, F interact
+```
+
+Event-driven — nothing to poll per frame. Read `kb.getCharacterMovement()`
+inside the before-step callback and pass the **complete** intent object every
+time: the controller merges defined fields, so a stale partial would leave old
+`true`s behind. Merge touch controls caller-side (see the SKILL's mobile
+section). `kb.onInteract(cb)` is the rising-edge F-key hook (for enter/exit).
+It already clears all keys on window blur / tab hide, so no stuck-key handling
+is needed.
+
+## 5. Follow camera
+
+```ts
+import { FollowCamera } from "./controllers/character/follow-camera.ts";
+
+const followCam = new FollowCamera(camera, {
+  domElement: renderer.domElement,
+  colliderMeshes: staticWallMeshes,
+});
+```
+
+Drag orbits, wheel/pinch zooms, and rays pull the camera in front of walls.
+Rules that matter:
+
+- `colliderMeshes` takes static **leaf** meshes only (the ray test is
+  non-recursive) and must never include the character or vehicle meshes — the
+  rays start at the character's head and would hit them every frame. The array
+  is public — mutate it after level loads.
+- `minDistance` defaults to 0.02, so zooming all the way in is effectively
+  first-person; clamp with `minDistance`/`maxDistance` for your scale.
+- Feel: `smoothTime` (0.05 snappy → 0.25 cinematic, default 0.1),
+  `initialDistance` (default 4), `initialAzimuthAngle` (default `Math.PI` —
+  camera starts behind a +Z-facing character).
+- v1 limits (by design): no pointer-lock mode, no truck/pan, and the orbit
+  space assumes the up axis stays roughly world +Y — far-from-Y custom gravity
+  will misbehave.
+
+## 6. The loop — exact order
+
+Per fixed **substep** (inside `physics.onBeforeStep`), in this order:
+
+1. Drive moving platforms (`setNextKinematicTranslation` / `setNextKinematicRotation`).
+2. `EnterExitManager.update(dt)` — only if vehicles exist (vehicle skill).
+3. `character.setMovement(...)` then `character.update()` — skip while
+   `character.isParked`.
+4. (Vehicle/drone `update()` calls, if any.)
+5. `world.step()` happens automatically right after your callback returns.
+
+Per **render** frame (inside `renderer.setAnimationLoop`), in this order:
+
+```ts
+const delta = clock.getDelta();
+physics.step(delta);                               // 1. fixed substeps + mesh sync
+
+pivot.copy(character.currPos).addScaledVector(character.bodyYAxis, 0.5);
+followCam.moveTo(pivot.x, pivot.y, pivot.z, true); // 2. feed the camera
+followCam.setUp(character.upAxis);
+if (physics.stepsLastFrame > 0 && character.isOnPlatform) {
+  followCam.applyPlatformTurn(character.turnOnYQuat);
+}
+followCam.update(delta);                           // 3. damp + place the camera
+
+anims.update(character, delta);                    // 4. animations (render delta)
+renderer.render(scene, camera);                    // 5. draw
+```
+
+Non-negotiables:
+
+- `update()` takes an optional dt **and ignores it** — all controller time
+  terms use the fixed `world.timestep`. Never call controller updates from the
+  render loop directly.
+- `applyPlatformTurn` consumes a per-physics-step yaw delta: gate it on
+  `physics.stepsLastFrame > 0`, or high-refresh displays re-apply a stale delta
+  and the camera over-rotates on platforms.
+- Camera and animation updates take the **render** delta, never
+  `physics.timeStep`.
+
+## 7. Reading state (for game logic)
+
+All getters are live internal objects — `.clone()` if you keep them:
+`currPos`, `currQuat`, `currLinVel`, `isOnGround`, `isFalling`, `isMoving`,
+`isOnPlatform`, `moveSpeed`, `verticalSpeed`, `runActive`, `jumpActive`,
+`slopeAngle`, `actualSlopeAngle`, `standCollider` (the rigid body under the
+character), `standPoint`, `standNormal`, `upAxis`, `bodyZAxis` (facing).
+Useful methods beyond `setMovement`: `setLockForward(true)` for strafe mode,
+`setGroundDetection("rayCast" | "shapeCast")`, `park()` / `unpark(pos, euler)`
+for vehicle boarding, `syncRoot()` if you skip `registerBody`.
+
+## 8. Debug and teardown
+
+- `physics.enableDebug(scene)` draws every collider as wireframe lines
+  (disable in shipped games); `{ debug: true }` + a `debugScene` constructor
+  arg adds per-controller indicators.
+- Teardown: `character.dispose()`, `kb.dispose()`, `followCam.dispose()`,
+  joystick/button `.dispose()`, then `physics.dispose()` last.
+
+## Troubleshooting
+
+- **Character slides down gentle ramps or climbs cliffs** — check
+  `slopeMaxAngle` (default 72°); see the tuning reference.
+- **Stuck bouncing at spawn** — spawn `position.y` too low; the capsule center
+  must start above `capsuleHalfHeight + capsuleRadius + floatHeight`.
+- **Model drifts away from the capsule** — the registered root's parent moved
+  or scaled after `registerBody`; register scene-root groups only.
+- **Movement ignores the camera** — you passed a different camera to the
+  controller than the one being rendered.
+- **`using deprecated parameters for the initialization function` in the
+  console** — harmless one-time Rapier WASM-loader message; ignore it.

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

@@ -1,15 +1,16 @@
 ---
 name: genex-threejs-embed-auth
-description: Wire up player identity for a Genex game via @genex-ai/embed-sdk. Load this UNCONDITIONALLY for every game, multiplayer or not, BEFORE writing any boot code — every player gets an identity (signed-in account or guest); saving progress requires sign-in, and multiplayer requires the SDK's token either way.
+description: Wire up player identity AND durable game state for a Genex game via @genex-ai/embed-sdk. Load this UNCONDITIONALLY for every game, multiplayer or not, BEFORE writing any boot code — every player gets an identity (signed-in account or guest); per-player saves, shared world state, and leaderboards are one-line SDK calls; multiplayer requires the SDK's token either way.
 ---
 
 # Genex Three.js Embed Auth
 
-`@genex-ai/embed-sdk` is how a Genex game learns **who is playing it**. Every
-game needs it. Published games are playable by **guests** (no account — the
-SDK mints a temporary identity like `Guest-1234` automatically), while
-**signing in** unlocks saving/loading progress; multiplayer works for both,
-using the SDK's token. The SDK handles every context with one
+`@genex-ai/embed-sdk` is how a Genex game learns **who is playing it** — and
+how it **saves**. Every game needs it. Published games are playable by
+**guests** (no account — the SDK mints a temporary identity like `Guest-1234`
+automatically), while **signing in** unlocks saving/loading progress (each
+player gets their own save slot) and leaderboard entries; multiplayer works
+for both, using the SDK's token. The SDK handles every context with one
 `initEmbed(...)` call:
 
 - **Embedded in the Genex dashboard (an iframe):** a silent handshake signs
@@ -102,10 +103,10 @@ boot-path gate; `waitForAuth()` guards saves only.
   synchronous.
 - `getUser()` → `{ id, name, image? } | null` — non-null once authenticated OR
   guest. Guest ids are prefixed `guest:`.
-- `getEmbedToken()` → `string | undefined` — for `Authorization: Bearer` on
-  `GET`/`PUT ${GENEX.apiUrl}/api/projects/${GENEX.slug}/state`. Defined for
-  guests too, but `/state` answers guests with `403 { "error": "guest_no_save" }`
-  — that's why saves gate on `waitForAuth()`, not on the token existing.
+- `getEmbedToken()` → `string | undefined` — the raw token, for the RARE
+  advanced case of calling the Genex API by hand. The state/leaderboard
+  helpers below attach it automatically — prefer them; never hand-roll fetch
+  calls to `/state` endpoints.
 - `getColyseusAuth()` → `{ embedToken } | undefined` — pass as `connect()`'s
   `auth` option (REQUIRED — the relay rejects tokenless joins; guest tokens
   are accepted). Read it fresh at every `connect()` call; tokens rotate
@@ -114,6 +115,31 @@ boot-path gate; `waitForAuth()` guards saves only.
   `"blocked"`, `"error"`. A mid-game sign-in fires `"authenticated"` after
   `"guest"` — progress saving can start right then, no reload.
 
+Durable state + leaderboards (all six are safe to call from boot — they wait
+for identity internally, never throw for guests, and reject only when the
+session is blocked):
+
+- `loadPlayerState()` → `Promise<{ data, version, guest? }>` — THIS player's
+  own save (per-player, per-game; other players can never read or overwrite
+  it). `{ data: null, version: 0 }` when they never saved.
+- `savePlayerState(data, { ifVersion? }?)` → `Promise<{ saved, version?,
+  conflict?, guest?, queued? }>` — save any JSON ≤ 256KB to their slot. For
+  guests the value is QUEUED in memory and auto-flushed if they sign in
+  mid-game — no extra code. Small saves survive tab close automatically.
+- `loadWorldState()` / `saveWorldState(data, { ifVersion? }?)` — the game's
+  ONE shared world slot (≤ 1MB, every player reads/writes the same blob) —
+  level layouts, persistent-world object positions. Multiplayer games: only
+  the host writes it (see the multiplayer skill). Always pass `ifVersion`
+  here (shared slot = real races); a losing write resolves
+  `{ conflict: true, version }` — reload, merge, retry.
+- `submitScore(score, { board?, mode? }?)` → `Promise<{ submitted, best?,
+  improved?, guest?, queued? }>` — keep-best leaderboard submit (`mode:
+  "min"` for lap-time boards). Guests: best value queues, flushes on sign-in.
+- `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`).
+
 From `@genex-ai/embed-sdk/sentry` (crash reporting; exactly these two):
 
 - `initGameSentry({ slug, dsn?, environment? })` — call once, BEFORE
@@ -134,30 +160,53 @@ function animate() {
 }
 ```
 
-## Saving progress with guests around
+## Saving progress (per-player — every player has their own slot)
 
-Guests play but cannot save — design the save path accordingly:
+Use the SDK helpers; never hand-roll fetch calls to the state API. Progression,
+inventory, unlocks — anything about ONE player — goes in their player slot:
 
 ```ts
-// Fire-and-forget save that is simply OFF for guests:
-async function saveProgress(data: unknown) {
-  const token = getEmbedToken();
-  if (getAuthState() !== "authenticated" || !token) return; // guest: skip silently
-  await fetch(`${GENEX.apiUrl}/api/projects/${GENEX.slug}/state`, {
-    method: "PUT",
-    headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json" },
-    body: JSON.stringify(data),
-  });
-}
+import { loadPlayerState, savePlayerState } from "@genex-ai/embed-sdk";
+
+// boot: load whatever this player saved last time (fine for guests — resolves
+// { data: null, guest: true } instead of failing)
+const { data } = await loadPlayerState();
+applyProgress(data ?? defaultProgress());
+
+// checkpoints / level-ups: fire-and-forget, DEBOUNCED (not per frame)
+void savePlayerState(progress);
+```
+
+Guests need zero special handling: their saves queue in memory and auto-flush
+the moment they sign in mid-game (so a guest's progress follows them into
+their new account), and `waitForAuth()` resolving is the signal that a real
+account now exists. The SDK already tells guests to sign in (its popover / the
+dashboard's card) — don't add another prompt.
+
+**Per-player vs world:** `savePlayerState` is each player's own progress;
+`saveWorldState` is the game's ONE shared world (persistent-world layouts —
+see the multiplayer skill's persistence section for the host-writes pattern).
+Never store per-player progression in the world slot: every player of the
+game shares that single blob.
+
+## Leaderboards
+
+```ts
+import { submitScore, getLeaderboard } from "@genex-ai/embed-sdk";
+
+// on game over / lap complete — keep-best, so just submit every run
+void submitScore(finalScore);                            // higher is better
+void submitScore(lapMs, { board: "laps", mode: "min" }); // lower is better
 
-// And start loading/saving the moment a guest upgrades mid-game:
-waitForAuth().then(({ user }) => {
-  // signed in (possibly after starting as a guest) — load their save now
-}).catch(() => { /* blocked — SDK overlay owns the UX */ });
+// render a top-10 + the player's own rank
+const { items, me } = await getLeaderboard({ limit: 10 });
 ```
 
-The SDK already tells guests to sign in (its popover / the dashboard's card) —
-don't add another prompt.
+Scores are per-account (one row per player per board, real display names from
+their Genex account) and keep-best — submitting a worse score changes nothing
+(`improved: false`). Guests can READ leaderboards; their submits queue and
+post when they sign in. Send a consistent `mode` per board. Scores are
+client-reported (arcade-style trust) — don't present them as anti-cheat.
 
 ## Crash reporting rules
 
@@ -216,9 +265,13 @@ concerns.
 - [ ] `genex.config.ts` includes `dashboardOrigins` (from `.genex/project.json`).
 - [ ] Multiplayer `connect()` and player-name UI await `waitForPlayer()` —
       NEVER `waitForAuth()` (guests would hang forever).
-- [ ] `/state` load/save gates on `waitForAuth()` / `getAuthState() ===
-      "authenticated"` and sends `Authorization: Bearer ${getEmbedToken()}`;
-      guests skip saves silently (the server answers them `403 guest_no_save`).
+- [ ] Saves/loads use the SDK helpers (`savePlayerState`/`loadPlayerState` for
+      per-player progress, `saveWorldState`/`loadWorldState` for the shared
+      world, `submitScore`/`getLeaderboard` for scores) — no hand-rolled fetch
+      to `/state` endpoints, no manual guest gating (the helpers own it).
+- [ ] Per-player progression lives in the PLAYER slot, never in the shared
+      world slot.
+- [ ] Saves are debounced (checkpoints/level-ups), not per-frame.
 - [ ] No token value is ever logged or sent to analytics.
 - [ ] No custom sign-in prompt, guest badge, or auth overlay — the SDK popover/
       overlay and the dashboard own all of that UX.
@@ -241,6 +294,12 @@ concerns.
 - **Multiplayer join rejected with 403 "guest capacity"** — the room is at its
   guest limit; only signing in gets the player a seat right now. Surface the
   relay's message as-is.
-- **`/state` returns 401/403** — missing `Authorization` header (401), a guest
-  token (403 `guest_no_save` — expected, skip saves for guests), or the token
-  belongs to a different game (403): `GENEX.slug` doesn't match this project.
+- **`/state` returns 401/403 (hand-rolled fetch)** — missing `Authorization`
+  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.
+- **`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
+  constantly, more than one client is acting as the writer — in multiplayer,
+  only the host should save the world.

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

@@ -207,38 +207,42 @@ file layout.
 ## Persistent worlds (optional — survives restarts)
 
 The relay is in-memory: room state is gone when everyone leaves or the server restarts. For a world
-that persists, save/load one JSON blob keyed by the project slug, from **one authority** (the host):
-
-Both calls **require a signed-in identity** (`Authorization: Bearer` with the token
-from `getEmbedToken()`) — guests play multiplayer but cannot read or write saves
-(the server answers their token `403 guest_no_save`). Gate them on
-`await waitForAuth()` — the ACCOUNT gate, deliberately stricter than the
-`waitForPlayer()` gate `connect()` uses (see the `genex-threejs-embed-auth` skill):
+that persists (a driven car stays where it was parked, built structures survive), save/load the
+game's shared world slot via the embed SDK, from **one authority** (the host):
 
 ```ts
-import { getEmbedToken } from "@genex-ai/embed-sdk";
+import { loadWorldState, saveWorldState } from "@genex-ai/embed-sdk";
 
-// load on boot (after waitForAuth() has resolved)
-const { data } = await fetch(`${GENEX.apiUrl}/api/projects/${GENEX.slug}/state`, {
-  headers: { Authorization: `Bearer ${getEmbedToken()}` },
-}).then(r => r.json());
+// load on boot (safe to call immediately — waits for identity internally;
+// guests resolve { data: null, guest: true } and receive the live world
+// through the room instead)
+const { data, version } = await loadWorldState();
 initWorld(data ?? defaultWorld());
-
-// save from ONE authority — the elected host — to avoid races; max 1 MB, last-write-wins
-if (room.isHost) fetch(`${GENEX.apiUrl}/api/projects/${GENEX.slug}/state`, {
-  method: "PUT",
-  headers: {
-    "Content-Type": "application/json",
-    Authorization: `Bearer ${getEmbedToken()}`,
-  },
-  body: JSON.stringify(world),
-});
+let worldVersion = version;
+
+// save from ONE authority — the elected host — debounced, WITH ifVersion so a
+// stale host handoff loses loudly instead of silently clobbering:
+async function persistWorld(world: unknown) {
+  if (!room.isHost) return;
+  const res = await saveWorldState(world, { ifVersion: worldVersion });
+  if (res.saved) worldVersion = res.version!;
+  else if (res.conflict) {
+    // someone else wrote since our read (host migration race) — resync
+    const fresh = await loadWorldState();
+    worldVersion = fresh.version;
+    mergeWorld(fresh.data);
+  }
+  // res.guest: this host is a guest (guest-only room) — saving is off until a
+  // signed-in player joins; the relay prefers signed-in hosts automatically.
+}
 ```
 
-`GET` returns `{ data }` (or `{ data: null }` if never saved). It requires a valid embed
-token for this exact game (401 without one, 403 with another game's token) and is
-size-capped at 1 MB. Don't save every frame — debounce, and let `room.isHost` pick the
-single writer.
+The slot is one JSON blob per game (≤ 1 MB) shared by every player — world layout only,
+NEVER per-player progression (that belongs in each player's own `savePlayerState()` slot —
+see the embed-auth skill). Don't save every frame: debounce (~1/sec), and also flush on
+`document.visibilitychange === "hidden"` so the last edits survive the host closing the tab.
+Guests can't write it, but the relay elects a signed-in host whenever one is present, so
+host-driven saving works as long as ANY account is in the room.
 
 ## Checklist
 

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

@@ -183,35 +183,50 @@ const px = t.stateRaw.x, pz = t.stateRaw.z;   // test against the raw latest
 ## Persistence helper
 
 ```ts
-// persistence.ts — /state requires the embed identity: call only after
-// `await waitForAuth()` has resolved (see the genex-threejs-embed-auth skill).
-import { getEmbedToken } from "@genex-ai/embed-sdk";
+// persistence.ts — the embed SDK owns tokens, guest handling, and conflict
+// decoding (see the genex-threejs-embed-auth skill). World slot = shared
+// layout only; per-player progression goes in savePlayerState() instead.
+import { loadWorldState, saveWorldState } from "@genex-ai/embed-sdk";
+
+let worldVersion = 0;
 
 export async function loadWorld<T>(fallback: T): Promise<T> {
   try {
-    const { data } = await fetch(`${GENEX.apiUrl}/api/projects/${GENEX.slug}/state`, {
-      headers: { Authorization: `Bearer ${getEmbedToken()}` },
-    }).then(r => r.json());
+    const { data, version } = await loadWorldState(); // waits for identity itself
+    worldVersion = version;
     return (data as T) ?? fallback;
   } catch { return fallback; }
 }
 
 let saveTimer: ReturnType<typeof setTimeout> | null = null;
+let latest: unknown;
 export function saveWorld(world: unknown) {
-  if (saveTimer) return;                     // debounce: at most one PUT/sec, from the host only
-  saveTimer = setTimeout(() => {
-    saveTimer = null;
-    fetch(`${GENEX.apiUrl}/api/projects/${GENEX.slug}/state`, {
-      method: "PUT",
-      headers: {
-        "Content-Type": "application/json",
-        Authorization: `Bearer ${getEmbedToken()}`,
-      },
-      body: JSON.stringify(world),
-    }).catch(() => {});
-  }, 1000);
+  latest = world;                            // debounce: at most one write/sec, host only
+  if (saveTimer) return;
+  saveTimer = setTimeout(() => { saveTimer = null; void flushWorld(); }, 1000);
+}
+
+async function flushWorld() {
+  const res = await saveWorldState(latest, { ifVersion: worldVersion }).catch(() => null);
+  if (!res) return;
+  if (res.saved) worldVersion = res.version!;
+  else if (res.conflict) worldVersion = res.version!; // stale after a host race — next save wins
 }
+
+// The host closing their tab must not lose the last edits: flush immediately
+// when the page goes hidden (savePlayerState/saveWorldState small writes ride
+// fetch keepalive, so this completes even mid-unload).
+document.addEventListener("visibilitychange", () => {
+  if (document.visibilityState === "hidden" && saveTimer) {
+    clearTimeout(saveTimer);
+    saveTimer = null;
+    void flushWorld();
+  }
+});
 ```
 
-State is one JSON blob per project, max 1 MB, last-write-wins. Save from a single authority
-(`room.isHost`) so concurrent writers don't clobber each other.
+State is one JSON blob per project, max 1 MB, shared by every player. Save from a single
+authority (`room.isHost`) so concurrent writers don't clobber each other; `ifVersion` turns
+any remaining race into a visible `conflict` instead of silent data loss. Guests can't
+write it — the relay prefers signed-in players as host, so saving works whenever any
+account is in the room (guest-only rooms simply don't persist until one joins).

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

@@ -0,0 +1,128 @@
+---
+name: genex-threejs-physics-rapier
+description: Set up Rapier physics for Genex Three.js games with the vendored PhysicsWorld glue — async WASM init, fixed-timestep world, body-to-mesh sync, collision events — and pick the right collider per asset (cuboid, hull, trimesh, including genex model GLBs). Use whenever anything falls, collides, gets pushed, or stands on moving ground; load before writing any physics code.
+---
+
+# Genex Three.js Physics (Rapier)
+
+Genex games run physics on Rapier (`@dimforge/rapier3d-compat`) through a small
+vendored glue layer: `PhysicsWorld` owns the world, the fixed-timestep loop,
+the rigid-body ↔ `Object3D` sync, and collision events; `shared/colliders.ts`
+turns meshes and GLBs into colliders. You do not install this from a skill —
+a CLI command drops the code into the game.
+
+## Get the code (one command, not hand-rolled)
+
+```bash
+npx genex controller character   # or car / drone — every kind installs shared/
+npm i @dimforge/rapier3d-compat
+```
+
+The command copies `src/controllers/shared/physics-world.ts`,
+`shared/colliders.ts`, and `shared/math.ts` into the game (plus the controller
+you picked). Even a game that only needs loose physics — falling crates, a
+rolling ball — should run it once for the `shared/` layer; existing files are
+never overwritten without `--force`.
+
+**Never hand-write character or vehicle physics.** A capsule you push around
+with raw impulses will clip slopes, stutter on stairs, and slide off moving
+platforms — this is the single most common way physics games go wrong. Tuned,
+tested controllers already exist: load `$genex-threejs-character-controller`
+for walking/running/jumping and `$genex-threejs-vehicle-controllers` for cars
+and drones, each installed by the same `npx genex controller` command.
+
+## Minimal working setup
+
+```ts
+import * as THREE from "three";
+import { PhysicsWorld } from "./controllers/shared/physics-world.ts";
+import { cuboidCollider } from "./controllers/shared/colliders.ts";
+
+const physics = await PhysicsWorld.create(); // awaits RAPIER.init() (embedded WASM)
+const world = physics.world;                 // the raw Rapier world
+
+// Static ground: a box whose top face is at y = 0.
+const ground = new THREE.Mesh(new THREE.BoxGeometry(100, 0.5, 100), groundMat);
+scene.add(ground);
+const groundBody = physics.createBody({ type: "fixed", position: [0, -0.25, 0] }, ground);
+cuboidCollider(world, groundBody, [50, 0.25, 50], { friction: 1 });
+
+// Dynamic crate: passing the mesh to createBody registers it — the mesh
+// follows the body automatically every frame, interpolated between steps.
+const crate = new THREE.Mesh(new THREE.BoxGeometry(1, 1, 1), crateMat);
+scene.add(crate);
+const crateBody = physics.createBody({ type: "dynamic", position: [0, 3, 0] }, crate);
+cuboidCollider(world, crateBody, [0.5, 0.5, 0.5], { friction: 0.6, density: 1 });
+
+// Anything that pushes bodies runs once per fixed substep, before the step:
+physics.onBeforeStep(() => {
+  // controller.update(), impulses, kinematic platform poses ...
+});
+
+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
+  renderer.render(scene, camera);
+});
+```
+
+Note `cuboidCollider` takes **half** extents: `[0.5, 0.5, 0.5]` is a 1×1×1 box.
+
+## The update ordering contract
+
+Physics code never sees the render framerate. Keep this order or controllers
+misbehave in ways that look like tuning problems:
+
+1. **Inside `physics.onBeforeStep(...)`** — runs once per fixed substep, in
+   this order: kinematic platform poses (`setNextKinematicTranslation` /
+   `setNextKinematicRotation`), then `EnterExitManager.update(dt)` if the game
+   has enter/exit vehicles, then each controller's `update()`. Controllers
+   ignore any dt argument and read `world.timestep` internally — never feed
+   them the render delta.
+2. **`physics.step(delta)`** — once per `requestAnimationFrame`, with the
+   render clock delta in **seconds**. It runs zero or more fixed substeps,
+   syncs registered meshes (interpolated), and drains collision events.
+3. **After `step`** — cameras, animation mixers, HUD: render-delta work. Gate
+   once-per-physics-step camera corrections on `physics.stepsLastFrame > 0`.
+
+Read [references/physics-setup.md](references/physics-setup.md) for world
+options, the body registry and its caveats, kinematic platforms, collision and
+sensor events, sleeping bodies, CCD/tunneling, pause/slow-mo, and debug
+rendering.
+
+Read [references/colliders-from-assets.md](references/colliders-from-assets.md)
+for the collider decision table per asset type — `genex model` GLBs, level
+geometry, primitives — hull vs trimesh tradeoffs, and the scale pitfalls.
+
+## Benign boot warning — do not chase it
+
+`@dimforge/rapier3d-compat` 0.19.3 logs once at startup:
+
+```text
+using deprecated parameters for the initialization function; pass a single object instead
+```
+
+This comes from the library's own embedded WASM loader, cannot be fixed from
+game code, and is harmless. Ignore it; do not refactor init code trying to
+silence it.
+
+## Failure conditions
+
+- physics stepped with the raw render delta instead of `physics.step`'s fixed
+  accumulator (speed varies with framerate);
+- a controller updated outside `onBeforeStep`, or fed the render delta;
+- a dynamic body repositioned with `setTranslation` every frame instead of
+  being kinematic;
+- a trimesh collider on a fast dynamic body (falls through the floor);
+- colliders built from a model whose scale changes afterwards;
+- a mesh registered to a body after its parent moved or scaled (silent desync);
+- hand-written character/vehicle physics instead of `npx genex controller`.
+
+## Routing boundary
+
+Player movement, jumping, slopes, and animation state belong to
+`$genex-threejs-character-controller`. Cars, drones, and enter/exit flow belong
+to `$genex-threejs-vehicle-controllers`. Chase/orbit camera design beyond the
+bundled follow camera is `$genex-threejs-camera-direction`. Meshes for props
+come from `$genex-ai-model`; this skill only decides how they collide.