@genex-ai/cli-demo 0.11.0 → 0.14.2

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,24 +1,31 @@
 ---
 name: genex-threejs-embed-auth
-description: Wire up signed-in identity for a Genex game via @genex-ai/embed-sdk. Load this UNCONDITIONALLY for every game, multiplayer or not, BEFORE writing any boot code — identity is required for play, saving progress, and multiplayer; there is no anonymous mode.
+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.
 ---
 
 # Genex Three.js Embed Auth
 
 `@genex-ai/embed-sdk` is how a Genex game learns **who is playing it**. Every
-game needs it — there is **no anonymous play**: without a signed-in identity
-the game is not playable, cannot save progress, and cannot join multiplayer.
-The SDK handles both contexts with one `initEmbed(...)` call:
-
-- **Embedded in the Genex dashboard (an iframe):** a silent handshake with the
-  dashboard signs the player in within a couple of seconds — no login screen.
-- **Standalone (someone opens the game's link directly):** the SDK redirects
-  through Genex sign-in (first-time visitors sign up there) and returns to the
-  game automatically. This is a real page navigation, by design — game code
-  does not need to handle any of it.
-
-While identity is resolving (or missing) the SDK shows its own full-screen
+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
+`initEmbed(...)` call:
+
+- **Embedded in the Genex dashboard (an iframe):** a silent handshake signs
+  the viewer in within a couple of seconds — or drops a signed-out viewer
+  straight into guest play. No login screen either way.
+- **Standalone (someone opens the game's link directly):** the visit bounces
+  once through Genex (at the CDN edge in production, so the game only loads
+  AFTER identity is resolved; the SDK does the same bounce itself in local
+  dev) — signed-in visitors arrive already authenticated on ANY game with
+  zero clicks; everyone else arrives as a guest with a small dismissible
+  "sign in to save progress" popover (rendered by the SDK — don't build your
+  own). Nobody ever hits a login wall on a published game.
+
+While identity is resolving (or blocked) the SDK shows its own full-screen
 overlay over the game, so never build a separate "connecting" screen for auth.
+Guest sessions have **no** overlay — the game just plays.
 
 ## Install
 
@@ -50,42 +57,69 @@ initEmbed({
 });
 ```
 
+Also give `<body>` a dark background in `index.html` (e.g.
+`<body style="margin:0;background:#080a14">`) — it makes the pre-boot frame
+(before any JS runs) match the SDK's own loading overlay instead of flashing
+white, and every Genex surface assumes a dark canvas anyway.
+
 Scene setup and asset loading may continue immediately after this call — auth
-never blocks rendering. Gate the **identity-dependent** parts (multiplayer
-connect, saving/loading progress, showing the player's name) on `waitForAuth()`:
+never blocks rendering. There are **two gates**, and picking the right one
+matters:
 
 ```ts
-import { waitForAuth, getColyseusAuth, getEmbedToken } from "@genex-ai/embed-sdk";
-
-const { user } = await waitForAuth();   // resolves when signed in; rejects if blocked
-// user.id / user.name are the real Genex identity
+import { waitForPlayer, waitForAuth, getColyseusAuth, getEmbedToken } from "@genex-ai/embed-sdk";
+
+// PLAYER gate — resolves for guests AND signed-in players. Use for
+// multiplayer connect() and player-name UI. This is the gate almost
+// everything wants.
+const { user, guest } = await waitForPlayer();
+// user.id / user.name — real account identity, or guest:<id> / "Guest-1234"
+
+// ACCOUNT gate — resolves ONLY for signed-in players (stays pending for
+// guests; resolves later if they sign in mid-game). Use ONLY for /state
+// saving/loading and other account-bound features.
+const { user: account } = await waitForAuth();
 ```
 
+**NEVER gate scene boot or `connect()` on `waitForAuth()`** — for a guest it
+stays pending forever and your game would sit empty. `waitForPlayer()` is the
+boot-path gate; `waitForAuth()` guards saves only.
+
 ## API surface (exact — do not invent methods)
 
 - `initEmbed({ slug, apiUrl, dashboardOrigins })` — call once, first. All three
   fields required (from `genex.config.ts`).
-- `waitForAuth()` → `Promise<{ user }>` — THE gate for `connect()` and `/state`
-  calls. Rejects if the session ends up blocked — catch it and let the SDK's
-  overlay handle the UX (don't build your own sign-in UI).
+- `waitForPlayer()` → `Promise<{ user, guest }>` — THE gate for `connect()`
+  and player-name UI; resolves for guests and accounts alike, rejects only if
+  the session ends up blocked.
+- `waitForAuth()` → `Promise<{ user }>` — the gate for `/state` calls and
+  account-bound features. Stays PENDING for guests (resolves live if they
+  sign in); rejects if blocked. Catch rejections and let the SDK's overlay
+  handle the UX (don't build your own sign-in UI).
 - `isEmbedded()` → `boolean` — structural "is in an iframe" check; NOT the same
   question as "is signed in".
-- `getAuthState()` → `"pending" | "authenticated" | "blocked"` — synchronous.
-- `getUser()` → `{ id, name, image? } | null` — non-null only when authenticated.
+- `getAuthState()` → `"pending" | "authenticated" | "guest" | "blocked"` —
+  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` (both REQUIRE it).
+  `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.
 - `getColyseusAuth()` → `{ embedToken } | undefined` — pass as `connect()`'s
-  `auth` option (REQUIRED — the relay rejects tokenless joins). Read it fresh
-  at every `connect()` call; tokens rotate automatically (~every 10 minutes).
-- `on(event, cb)` → unsubscribe fn. Events: `"authenticated"`, `"blocked"`,
-  `"error"`.
+  `auth` option (REQUIRED — the relay rejects tokenless joins; guest tokens
+  are accepted). Read it fresh at every `connect()` call; tokens rotate
+  automatically (~every 10 minutes).
+- `on(event, cb)` → unsubscribe fn. Events: `"authenticated"`, `"guest"`,
+  `"blocked"`, `"error"`. A mid-game sign-in fires `"authenticated"` after
+  `"guest"` — progress saving can start right then, no reload.
 
 From `@genex-ai/embed-sdk/sentry` (crash reporting; exactly these two):
 
 - `initGameSentry({ slug, dsn?, environment? })` — call once, BEFORE
   `initEmbed()`. Only `slug` is required; the shared Genex Sentry project DSN
-  is built in. Errors, tracing, and session replay all start here; the signed-in
-  user is attached automatically after auth (no code needed).
+  is built in. Errors, tracing, and session replay all start here; the current
+  player (account or guest) is attached automatically (no code needed).
 - `sentryCanvasSnapshot(canvas)` — session replay records the DOM, not the 3D
   canvas; call this once per frame at the END of the render loop so replays
   show actual gameplay. Works for BOTH WebGL and WebGPU renderers; internally
@@ -100,6 +134,31 @@ function animate() {
 }
 ```
 
+## Saving progress with guests around
+
+Guests play but cannot save — design the save path accordingly:
+
+```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),
+  });
+}
+
+// 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 */ });
+```
+
+The SDK already tells guests to sign in (its popover / the dashboard's card) —
+don't add another prompt.
+
 ## Crash reporting rules
 
 - `initGameSentry` has token scrubbing built in (the sign-in return-trip pass
@@ -136,13 +195,17 @@ If `src/genex.config.ts` is somehow missing (e.g. it was deleted), re-run
 
 ## Standalone behavior (what to expect, not something to code)
 
-Opening the game's link directly (not from the dashboard) bounces through the
-Genex sign-in page and back before the game becomes playable — including during
-your own local `npm run dev` checks (sign in once; the bounce is instant after
-that). The return trip carries a one-time pass in the URL that the SDK consumes
-and removes immediately. Don't code around any of this: no `?`/`#` URL params
-of yours will be affected, and `isEmbedded()` / the return-trip handling are
-internal SDK concerns.
+Opening a published game's link directly (not from the dashboard) shows a
+brief "Loading…" overlay while the SDK round-trips through Genex once, then
+the game starts: already-signed-in visitors come back authenticated (zero
+clicks — on every game), everyone else comes back playing as a guest with the
+SDK's own top-right "sign in to save progress" popover. The return trip
+carries a one-time pass (or an inert guest marker) in the URL that the SDK
+consumes and removes immediately. Unpublished drafts are the exception:
+strangers can't play them, so a draft link shows the SDK's sign-in gate
+instead. Don't code around any of this: no `?`/`#` URL params of yours will
+be affected, and `isEmbedded()` / the return-trip handling are internal SDK
+concerns.
 
 ## Checklist
 
@@ -151,24 +214,33 @@ internal SDK concerns.
 - [ ] `sentryCanvasSnapshot(renderer.domElement)` runs after `renderer.render()`
       in the main loop (WebGL and WebGPU alike).
 - [ ] `genex.config.ts` includes `dashboardOrigins` (from `.genex/project.json`).
-- [ ] Everything identity-dependent awaits `waitForAuth()` (multiplayer `connect`,
-      `/state` load/save, player-name UI).
-- [ ] `/state` fetches send `Authorization: Bearer ${getEmbedToken()}`.
+- [ ] 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`).
 - [ ] No token value is ever logged or sent to analytics.
-- [ ] No custom sign-in/anonymous-fallback UI — the SDK overlay + dashboard own that.
+- [ ] No custom sign-in prompt, guest badge, or auth overlay — the SDK popover/
+      overlay and the dashboard own all of that UX.
 
 ## Troubleshooting
 
-- **Game loads then immediately navigates away (standalone/local dev)** — that's
-  the sign-in bounce working as designed. Sign in once in the browser; it
-  returns to the game automatically.
-- **`waitForAuth()` rejects / state is `"blocked"`** — the visitor declined or
-  failed sign-in, or the dashboard session ended. The SDK overlay (or the
-  dashboard, when embedded) shows the sign-in prompt; the game just stays
-  paused behind it. Don't retry in a loop.
+- **Game loads then immediately navigates away (standalone/local dev)** — the
+  identity bounce, working as designed for EVERY standalone visit. It returns
+  to the game automatically (signed-in or as a guest) within a second.
+- **`waitForAuth()` never resolves** — the player is a GUEST; that's the
+  designed behavior. Anything that must run for guests belongs behind
+  `waitForPlayer()` instead.
+- **State is `"blocked"` / `waitForPlayer()` rejects** — an unpublished draft
+  opened by a non-owner, or auth infrastructure was unreachable. The SDK
+  overlay (or the dashboard, when embedded) shows the sign-in prompt; the game
+  just stays paused behind it. Don't retry in a loop.
 - **Multiplayer join rejected with 401** — `connect()` ran before
-  `waitForAuth()` resolved, without `auth: getColyseusAuth()!`, or with a stale
-  cached token on reconnect (read it fresh each call).
-- **`/state` returns 401/403** — missing `Authorization` header (401) or the
-  token belongs to a different game (403): `GENEX.slug` doesn't match this
-  project.
+  `waitForPlayer()` resolved, without `auth: getColyseusAuth()!`, or with a
+  stale cached token on reconnect (read it fresh each call).
+- **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.

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

@@ -44,17 +44,19 @@ npm i @genex-ai/multiplayer
 Pick your own per-player state shape (any JSON). `room` is the **project slug**
 (printed by `genex init`) — same id = same room, different ids are fully isolated.
 
-**Joining requires a signed-in identity — the relay rejects joins without one.**
+**Joining requires the SDK's player identity — the relay rejects tokenless
+joins, but accepts guests** (accountless players named like `Guest-1234`).
 Load the `genex-threejs-embed-auth` skill first (it sets up `initEmbed(...)`),
-then gate `connect()` on `waitForAuth()`:
+then gate `connect()` on `waitForPlayer()` — NOT `waitForAuth()`, which stays
+pending for guests and would keep them out of multiplayer forever:
 
 ```ts
 import { connect } from "@genex-ai/multiplayer";
-import { waitForAuth, getColyseusAuth } from "@genex-ai/embed-sdk";
+import { waitForPlayer, getColyseusAuth } from "@genex-ai/embed-sdk";
 
 type State = { x: number; z: number; q: number[] };  // YOUR per-player state (rotation as quaternion)
 
-const { user } = await waitForAuth();  // identity gate — rejects if the session is blocked
+const { user } = await waitForPlayer();  // player gate (guest OR signed-in) — rejects only if blocked
 const room = await connect<State>({
   url: GENEX.colyseusUrl,     // e.g. "wss://demo-colyseus.glotech.world" — see config wiring below
   room: GENEX.slug,           // the project slug — everyone with this id shares a room
@@ -207,9 +209,11 @@ file layout.
 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 the embed identity** (`Authorization: Bearer` with the token from
-`getEmbedToken()`) — there is no anonymous read or save. Call them only after
-`await waitForAuth()` (see the `genex-threejs-embed-auth` skill):
+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):
 
 ```ts
 import { getEmbedToken } from "@genex-ai/embed-sdk";
@@ -239,8 +243,9 @@ single writer.
 ## Checklist
 
 - [ ] `npm i @genex-ai/multiplayer` (≥ 0.4.0 for objects/host); config wired into the build.
-- [ ] `connect()` runs AFTER `await waitForAuth()` and passes `auth: getColyseusAuth()!`
-      (the relay rejects tokenless joins — see `genex-threejs-embed-auth`).
+- [ ] `connect()` runs AFTER `await waitForPlayer()` (never `waitForAuth()` — guests would
+      hang) and passes `auth: getColyseusAuth()!` (the relay rejects tokenless joins —
+      see `genex-threejs-embed-auth`).
 - [ ] `room` is the **project slug**.
 - [ ] `me.set` on a fixed **10–20 Hz** tick; full object each time.
 - [ ] Skip yourself in `room.players` (`id === room.id`).
@@ -255,6 +260,7 @@ single writer.
 ## Troubleshooting auth
 
 - **`connect()` rejects with 401/403** — 401 "auth required"/"invalid token": you joined
-  without `auth` or before `waitForAuth()` resolved (or the token expired mid-reconnect —
+  without `auth` or before `waitForPlayer()` resolved (or the token expired mid-reconnect —
   read `getColyseusAuth()` fresh at every connect). 403 "wrong game": the `room` value
-  doesn't match this game's own slug.
+  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.

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.