@genex-ai/cli-demo 0.88.0-dev.219 → 0.91.0-dev.228

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

@@ -1,6 +1,6 @@
 ---
 name: genex-threejs-character-controller
-description: Add Genex's tuned ECCTRL-derived physics character controller with `npx genex controller character`: dynamic-capsule movement, follow camera, touch input, personal VRM + UAL animation, or an exact same-rig Meshy character. Use for every on-foot player or third-person movement request.
+description: Add Genex's tuned ECCTRL-derived physics character controller with `npx genex controller character`: dynamic-capsule movement, follow camera, touch input, and one loader that resolves the player's body — the game's own generated character by default, the profile VRM avatar as the fallback. Use for every on-foot player or third-person movement request.
 ---
 
 # Genex Three.js Character Controller
@@ -19,24 +19,47 @@ animation retargeting, capsule auto-fit, foot IK) and the 12-clip core
 ~1.3 MB) into `public/assets/`. Need more — swords, pistols, magic, climbing,
 swimming, emotes? Install exactly what the game uses with
 `npx genex controller anims <tags|clip names…>` (see Animations below). The
-default command also writes a fallback avatar to `public/assets/avatar.vrm` —
-**your** avatar when you're signed in,
-otherwise a bundled CC0 default (attribution in `src/controllers/NOTICE.md`).
-At runtime the character plays as the **visiting player's own** picked avatar
-(`user.avatarUrl` from the embed identity — see the wiring below); the baked
-file is only the fallback for local dev and load failures. The copied files are then owned by the game —
+copied files are then owned by the game —
 edit them freely; re-running skips existing files unless `--force`. Do not write
 a character controller from scratch and do not swap in a kinematic-controller
 tutorial: this one is a real dynamic body that pushes crates, rides moving
 platforms, climbs stairs and slides on too-steep slopes out of the box.
 
-Use the VRM + UAL lane above by default. When the game needs a custom generated
-humanoid or an action unavailable in UAL, load `$genex-ai-character`, search
-Meshy's library first, and follow the reviewed image-first generation flow.
+## The player's body: the game's own character
+
+**The player wears the character this game generated for itself.** That is the
+default for any game where a human body appears on screen — third-person
+obviously, and first-person too the moment remotes, a look-down body, a shadow,
+a death cam, or a menu portrait shows one. Load `$genex-ai-character` and start
+it EARLY, with your first art actions, so it lands around the v0 preview
+instead of after it.
+
+The profile VRM avatar is the **fallback**, and the command bakes a neutral CC0
+copy to `public/assets/avatar.vrm` (attribution in `src/controllers/NOTICE.md`)
+so a fresh game always has a working body. It is used when:
+
+- the generated character hasn't landed yet — say in one plain line that this
+  body is temporary; or
+- it genuinely could not be made (out of credits, generation failed, email
+  unverified) — say so in one line, record `Player character: VRM — <reason>`
+  in DESIGN.md, and keep building.
+
+At runtime the fallback lane loads the **visiting player's own** picked avatar
+(`user.avatarUrl` from the embed identity); the baked file covers local dev and
+load failures. Games whose player is not a person at all — a car, a ship, an
+RTS cursor, a board — generate that object with `npx genex model` instead and
+never enter this lane.
+
+**You never write two boot paths for this.** `loadPlayerCharacter()` decides at
+runtime from `public/assets/meshy-character.json` and returns one shape either
+way, so the character arriving mid-build is a file drop
+(`npx genex controller character --character <id>`) and not an edit to your
+most load-bearing code. Wire the block under "Minimal wiring" once, at hour 0.
+
 For a full custom LOCOMOTION SET beyond the UAL packs (a weapon-hold 8-way
-shooter kit, a signature gait), see that skill's motion section: `npx genex
-motion install --set rifle` drops the proven rifle set + its own runtime, and
-`genex motion gen` builds new sets from text.
+shooter kit, a signature gait), see `$genex-ai-character`'s motion section:
+`npx genex motion install --set rifle` drops the proven rifle set + its own
+runtime, and `genex motion gen` builds new sets from text.
 
 Before generating a Meshy character, discuss two or three visual directions.
 When the user names a visual reference, inspect references before writing the
@@ -64,12 +87,12 @@ that model in R2. Before rigging, ask the user to approve a separate
 rigged and animated. (For these approvals, use your question tool when you
 have one; if you have none, a short numbered list in chat.)
 
-That is a separate, **same-rig Meshy-native lane**. Its animation-only GLBs are
-accepted only when their skeleton signature matches the active character
-revision; this lane does no runtime retargeting. The shared ECCTRL-derived
-dynamic controller stays authoritative for collision, grounding, facing, and
-world translation. The animation layer poses the visual rig; it never
-translates the visual root.
+The generated character is a **same-rig Meshy-native lane**. Its animation-only
+GLBs are accepted only when their skeleton signature matches the active
+character revision; this lane does no runtime retargeting. The shared
+ECCTRL-derived dynamic controller stays authoritative for collision, grounding,
+facing, and world translation — identical in both lanes. The animation layer
+poses the visual rig; it never translates the visual root.
 
 Meshy manifests bypass browser cache, so newly installed actions must work
 after preview without asking the player to disable cache. `playOneShot()`
@@ -101,10 +124,11 @@ fork as a migration strategy. Install a fresh copy elsewhere and port only the n
 | `character/character-animations.ts` | `CharacterAnimations` | animation state machine, directional profiles, speed-matched cadence, `playOneShot`, procedural fallback |
 | `character/animation-packs.ts` | `loadCharacterClips` | loads the core + installed UAL packs and retargets them to the active VRM |
 | `character/meshy/meshy-loader.ts` | `loadMeshyCharacter` | loads a Meshy manifest, exact-signature model/clips, locomotion slots, and fallbacks |
+| `character/player-character.ts` | `loadPlayerCharacter`, `loadRemotePlayerCharacter` | **the player's body** — the game's generated character when it has one, the avatar fallback when it doesn't, one shape either way |
 | `character/motion-actions.ts` | `MotionActionDriver` | applies only validated planar trajectories through the physics controller, never the visual root |
-| `character/vrm/*` | `loadVrm`, `retargetClips`, `capsuleFromModel`, `FootIK` | load the VRM avatar, retarget library clips onto its humanoid rig, auto-fit the capsule, ground the feet |
+| `character/vrm/*` | `loadVrm`, `retargetClips`, `capsuleFromModel`, `FootIK` | the FALLBACK lane's parts: load a VRM avatar, retarget library clips onto its humanoid rig, auto-fit the capsule (works on both lanes), ground the feet |
 
-## Minimal wiring: personal VRM lane
+## Minimal wiring
 
 ```ts
 import { PhysicsWorld } from "./controllers/shared/physics-world.ts";
@@ -115,25 +139,27 @@ import { characterPresets } from "./controllers/character/presets.ts";
 import { FollowCamera } from "./controllers/character/follow-camera.ts";
 import { createAimCue } from "./controllers/character/aim-cue.ts";
 import { KeyboardInput } from "./controllers/character/keyboard-input.ts";
-import { loadVrm } from "./controllers/character/vrm/vrm-loader.ts";
+import { loadPlayerCharacter } from "./controllers/character/player-character.ts";
 import { capsuleFromModel } from "./controllers/character/vrm/capsule-fit.ts";
 import { waitForPlayer } from "@genex-ai/embed-sdk";
 
 const physics = await PhysicsWorld.create(); // nothing RAPIER-related may run before this resolves
 
-// Load the PLAYING user's avatar — every visitor plays as the avatar THEY
-// picked on their genex profile (guests get a per-session one), not the
-// creator's. `user.avatarUrl` comes from the embed identity
-// ($genex-threejs-embed-auth boots before this); the baked
-// `./assets/avatar.vrm` is the fallback for local dev, old APIs, and load
-// failures. Then load every animation the game has (the bundled core library +
-// any packs installed by `genex controller anims`), retargeted onto the VRM.
+// The player's body — ONE call, both lanes. It plays as the character THIS
+// GAME generated whenever `public/assets/meshy-character.json` is present
+// (with that character's exact-rig clips and locomotion profile), and falls
+// back to the visiting player's own profile avatar when it isn't — retargeting
+// the bundled core library plus any packs installed by `genex controller
+// anims`. `user.avatarUrl` comes from the embed identity
+// ($genex-threejs-embed-auth boots before this) and is used only in that
+// fallback lane; the baked `./assets/avatar.vrm` covers local dev and load
+// failures. WRITE THIS ONCE: when the generated character lands mid-build,
+// `genex controller character --character <id>` drops the manifest in and the
+// next reload swaps the body. Nothing below changes.
 const { user } = await waitForPlayer();          // from "@genex-ai/embed-sdk"
-const { scene: avatar, vrm } = await loadVrm(user.avatarUrl ?? "./assets/avatar.vrm")
-  .catch(() => loadVrm("./assets/avatar.vrm")); // network failure → bundled fallback
-const clips = await loadCharacterClips(vrm);
+const player = await loadPlayerCharacter({ avatarUrl: user.avatarUrl });
 
-const fit = capsuleFromModel(avatar);          // collider fits THIS avatar's bounds
+const fit = capsuleFromModel(player.scene);    // collider fits THIS body's bounds
 const character = new CharacterController(physics.world, camera, {
   ...characterPresets["default"].options,
   ...fit,
@@ -141,11 +167,15 @@ const character = new CharacterController(physics.world, camera, {
   userData: { controller: { excludeVehicleRay: true } }, // car wheels must never drive on the player
 });
 scene.add(character.root);
-character.root.add(avatar);                     // parent the avatar under the character root
-avatar.position.y = fit.modelOffsetY;           // root = capsule CENTER; drop the model so feet touch the floor
+character.root.add(player.scene);               // parent the body under the character root
+player.scene.position.y = fit.modelOffsetY;     // root = capsule CENTER; drop the model so feet touch the floor
 physics.registerBody(character.body, character.root); // root now follows the body, interpolated
 
-const anims = new CharacterAnimations(avatar, clips);
+// locomotionProfile is present in the generated lane and undefined in the
+// fallback — pass it either way; CharacterAnimations handles both.
+const anims = new CharacterAnimations(player.scene, player.clips, {
+  locomotionProfile: player.locomotionProfile,
+});
 addEventListener("pointerdown", () => anims.playOneShot("Punch_Jab")); // punch on click
 
 const kb = new KeyboardInput();
@@ -184,7 +214,10 @@ renderer.setAnimationLoop(() => {
   followCam.update(delta);
 
   anims.update(character, delta); // see the animations reference
-  vrm.update(delta);              // REQUIRED — ticks the humanoid rig + spring bones
+  player.update(delta);           // REQUIRED — ticks the VRM humanoid + spring bones
+                                  // in the fallback lane, a no-op for native rigs.
+                                  // Always call it: that is why the lane can change
+                                  // under you without this loop changing.
   renderer.render(scene, camera);
 });
 ```
@@ -312,20 +345,39 @@ and the style-matching rules live in `$genex-threejs-touch-controls`.
 
 **The local player is physics-authoritative; remote players are interpolated
 visuals only.** Exactly one `CharacterController` exists — yours. For every
-remote player: load **that player's own avatar** —
-`loadVrm(p.avatarUrl || "./assets/avatar.vrm")` (the multiplayer SDK's
-`player.avatarUrl` is their verified profile pick; fall back to the baked file
-when it's empty or fails to load, and `VRMUtils.deepDispose` the model when
-they leave) — move it with the interpolator from `$genex-threejs-multiplayer`,
-and **never** create a rigid body, a `CharacterController`, or any physics for
-it. Simulating remote players' physics locally guarantees divergence — every
-client would compute a different world. Never render every remote with your
-own avatar file: players picked their looks, show them. And a remote player's
-body is **never hand-built primitives** (no capsule-plus-cone "person"): in a
-themed game remotes wear the SAME themed character model the local player
-uses; otherwise they wear their `p.avatarUrl` VRM. First-person games are not
-exempt — the local player may be invisible to themselves
-(`setFirstPersonBody`), but every remote is a full character on screen.
+remote player:
+
+```ts
+import { loadRemotePlayerCharacter } from "./controllers/character/player-character.ts";
+
+const remote = await loadRemotePlayerCharacter({ avatarUrl: p.avatarUrl });
+scene.add(remote.scene);
+const remoteAnims = new CharacterAnimations(remote.scene, remote.clips, {
+  locomotionProfile: remote.locomotionProfile,
+});
+// on 'leave': remote.dispose()
+```
+
+Same rule as the local player, and the same one call: **in a game with its own
+generated character, every remote wears it** — the game should look like the
+game that was designed, and a mixed roster (one themed knight plus three stock
+avatars) is the same incoherence as capsule-and-cone remotes. Only when this
+game has NO generated character does each remote wear their own
+`p.avatarUrl` VRM, which is then the right look. Several generated characters
+(per class, per team, a picker) are fine when the player asks for them — the
+rule is a coherent themed cast, not exactly one model. Name tags distinguish
+players; their bodies don't have to.
+
+The loader shares one parsed base across every remote (N remotes ≈ 1 body of
+GPU memory) and `remote.dispose()` detaches the clone without touching those
+shared resources. Move it with the interpolator from
+`$genex-threejs-multiplayer`, and **never** create a rigid body, a
+`CharacterController`, or any physics for it. Simulating remote players'
+physics locally guarantees divergence — every client would compute a different
+world. And a remote player's body is **never hand-built primitives** (no
+capsule-plus-cone "person"). First-person games are not exempt — the local
+player may be invisible to themselves (`setFirstPersonBody`), but every remote
+is a full character on screen.
 
 - **Publish `character.netState()`** on the fixed 10–20 Hz tick (never per frame):
   `room.me.set(character.netState())`. It bundles the network-safe position, a four-number

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

@@ -8,12 +8,16 @@ clips only on the exact matching generated rig revision.
 
 ## The bundled assets + animation packs
 
-`npx genex controller character` sets the game up to play as a **VRM avatar**:
-
-- `public/assets/avatar.vrm` — the FALLBACK avatar (yours when signed in, else a
-  bundled CC0 default). Always present; always one path. At runtime the game
-  loads the visiting player's own picked avatar instead (`user.avatarUrl` from
-  the embed identity) — this file covers local dev and load failures.
+`npx genex controller character` installs both lanes of the player's body — the
+game's own generated character (the default) and the VRM avatar fallback:
+
+- `public/assets/meshy-character.json` — written by
+  `npx genex controller character --character <id>` once the game's character
+  has been generated. Its presence is what `loadPlayerCharacter` routes on.
+- `public/assets/avatar.vrm` — the FALLBACK body (the bundled CC0 default).
+  Always present; always one path. At runtime the fallback lane loads the
+  visiting player's own picked avatar instead (`user.avatarUrl` from the embed
+  identity) — this file covers local dev and load failures.
 - `public/assets/animation-library.glb` (~1.3 MB) — the 12-clip core
   (idle/walk/jog/sprint, the jump trio, crouch idle+move, hit, death, interact)
   on a shared Quaternius rig (provenance in `src/controllers/NOTICE.md`).
@@ -26,38 +30,39 @@ clips only on the exact matching generated rig revision.
 VRM helpers live in `src/controllers/character/vrm/`. Install three-vrm once:
 `npm i @pixiv/three-vrm`.
 
-Load the avatar, then EVERYTHING the game has via `loadCharacterClips` — core
-library + installed packs, each retargeted onto the avatar's humanoid rig —
-all with **relative** paths so the published game works under its subpath:
+`loadPlayerCharacter` loads the body and everything the game can play on it in
+one call — the generated character's exact-rig clips, or the core library plus
+installed packs retargeted onto the avatar's humanoid rig. All with
+**relative** paths so the published game works under its subpath:
 
 ```ts
-import { loadVrm } from "./controllers/character/vrm/vrm-loader.ts";
-import { loadCharacterClips } from "./controllers/character/animation-packs.ts";
+import { loadPlayerCharacter } from "./controllers/character/player-character.ts";
 import { capsuleFromModel } from "./controllers/character/vrm/capsule-fit.ts";
 import { CharacterController } from "./controllers/character/character-controller.ts";
 import { CharacterAnimations } from "./controllers/character/character-animations.ts";
 import { characterPresets } from "./controllers/character/presets.ts";
 import { waitForPlayer } from "@genex-ai/embed-sdk";
 
-// The playing user's OWN avatar (their profile pick; per-session for guests) —
-// the baked file is only the local-dev / failure fallback.
+// This game's own generated character when it has one; otherwise the playing
+// user's own avatar (their profile pick; per-session for guests), with the
+// baked file as the local-dev / failure fallback.
 const { user } = await waitForPlayer();
-const { scene, vrm } = await loadVrm(user.avatarUrl ?? "./assets/avatar.vrm")
-  .catch(() => loadVrm("./assets/avatar.vrm"));
-const clips = await loadCharacterClips(vrm); // core + every installed pack, retargeted
+const player = await loadPlayerCharacter({ avatarUrl: user.avatarUrl });
 
-// capsuleFromModel derives the collider from the avatar's bounds — no manual
-// per-avatar tuning even as heights/proportions vary across the library.
-const fit = capsuleFromModel(scene);
+// capsuleFromModel derives the collider from the body's bounds — no manual
+// per-model tuning even as heights and proportions vary between lanes.
+const fit = capsuleFromModel(player.scene);
 const character = new CharacterController(physics.world, camera, {
   ...characterPresets["default"].options,
   ...fit,
   position: { x: 0, y: 2, z: 0 },
 });
-character.root.add(scene);
-scene.position.y = fit.modelOffsetY; // root = capsule CENTER; drop the model so feet touch the floor
+character.root.add(player.scene);
+player.scene.position.y = fit.modelOffsetY; // root = capsule CENTER; drop the model so feet touch the floor
 
-const anims = new CharacterAnimations(scene, clips);
+const anims = new CharacterAnimations(player.scene, player.clips, {
+  locomotionProfile: player.locomotionProfile, // undefined in the fallback lane — fine
+});
 ```
 
 (Advanced: to load a single GLB by hand, `retargetClips(vrm, gltf.scene,
@@ -68,12 +73,15 @@ Per render frame, **after** `physics.step(delta)`:
 
 ```ts
 anims.update(character, delta); // the controller itself satisfies the snapshot type
-vrm.update(delta);              // REQUIRED — ticks the humanoid rig + spring bones
+player.update(delta);           // REQUIRED — ticks the humanoid rig + spring bones
 ```
 
-`vrm.update(delta)` MUST run every frame, AFTER `anims.update`: it applies the
-animated normalized pose onto the render mesh and advances spring bones (hair,
-cloth). `anims.update` takes the RAW render delta — pause/slow-motion go through
+`player.update(delta)` MUST run every frame, AFTER `anims.update`. In the
+fallback (VRM) lane it applies the animated normalized pose onto the render
+mesh and advances spring bones (hair, cloth); native generated rigs need no
+such pass, so it costs nothing there. Call it unconditionally — that is what
+lets the body change lanes without this loop changing.
+`anims.update` takes the RAW render delta — pause/slow-motion go through
 `anims.setPaused(true)` / `anims.setTimeScale(0.5)` (fade durations stretch with
 the time scale so slow motion doesn't pop).
 
@@ -107,26 +115,25 @@ estimated cost. Use a returned ID; do not guess from a name. Search is free and
 local. Character and animation generation print a Genex-credit quote before
 enqueueing, and successful outputs are copied to permanent R2 URLs.
 
-The install command writes `public/assets/meshy-character.json`. Wire that
-manifest through the **same** physics controller and camera:
+The install command writes `public/assets/meshy-character.json`. **There is
+nothing to wire** — the boot block above already routes on that file, so the
+next reload plays the generated character with its exact-rig clips and
+locomotion profile, through the same physics controller and camera.
+
+`loadMeshyCharacter` is the direct handle underneath, for the rare case that
+needs the manifest itself (reading `rigSignature`, a second character in the
+scene):
 
 ```ts
 import { loadMeshyCharacter } from "./controllers/character/meshy/meshy-loader.ts";
 
 const native = await loadMeshyCharacter("./assets/meshy-character.json");
-const fit = capsuleFromModel(native.scene);
-const character = new CharacterController(physics.world, camera, {
-  ...characterPresets["default"].options,
-  ...fit,
-  position: { x: 0, y: 2, z: 0 },
-});
-character.root.add(native.scene);
-native.scene.position.y = fit.modelOffsetY;
-const anims = new CharacterAnimations(native.scene, native.clips, {
-  locomotionProfile: native.locomotionProfile,
-});
+// native.scene / native.clips / native.locomotionProfile / native.manifest
 ```
 
+Never make it the player's boot path: that is the two-lane split
+`loadPlayerCharacter` exists to remove.
+
 During Meshy validation, record the action ID actually bound to every slot.
 A public preview is not evidence when the game is playing a different clip or
 a rig-basic fallback. Meshy limb rotations play unchanged. Never freeze hand
@@ -210,15 +217,19 @@ const footIK = new FootIK(vrm, (foot) => {
 });
 ```
 
-ORDER IS LOAD-BEARING — foot IK poses the VRM's *normalized* bones, which
-`vrm.update()` then copies onto the render mesh. Run it BETWEEN the two (after
-`vrm.update` it has no visible effect at all — the next frame's mixer tick
+Foot IK is a VRM-lane feature (it poses a VRM's normalized bones), so it
+applies only when the player is on the fallback body — check
+`player.kind === "avatar"` before creating it.
+
+ORDER IS LOAD-BEARING — foot IK poses the VRM's *normalized* bones, which the
+VRM's own update then copies onto the render mesh. Run it BETWEEN the two
+(after that copy it has no visible effect at all — the next frame's mixer tick
 overwrites it before the copy):
 
 ```ts
 anims.update(character, delta); // 1. mixer poses the normalized rig
-footIK.update(delta);           // 2. plant the feet on that pose
-vrm.update(delta);              // 3. copy normalized -> render mesh + spring bones
+footIK?.update(delta);          // 2. plant the feet on that pose (fallback lane only)
+player.update(delta);           // 3. copy normalized -> render mesh + spring bones
 ```
 
 ## States and default clips
@@ -409,12 +420,13 @@ remoteAnims.update(remoteState.flags, delta);
 resolves correctly (a missing flag reads as not-crouched).
 
 The mixer crossfades exactly as it does locally, so remote players animate
-correctly without simulating anything. Use the same visual lane as the owner:
-for a VRM game load **that remote player's own avatar** —
-`loadVrm(p.avatarUrl || "./assets/avatar.vrm")` (the multiplayer SDK's verified
-per-player field; empty means fall back) + retargeted UAL clips, call
-`vrm.update(delta)` per remote, and `VRMUtils.deepDispose` the model on leave —
-or `loadMeshyCharacter` for a Meshy game. Relay one-shot events (punch,
+correctly without simulating anything. Build every remote's body with
+`loadRemotePlayerCharacter({ avatarUrl: p.avatarUrl })` — the same routing the
+local player gets, so in a game with a generated character everyone wears it,
+and only a game without one falls back to per-player avatars (`p.avatarUrl` is
+the multiplayer SDK's verified per-player field; empty means fall back). It
+clones a shared parsed base, so N remotes cost about one body of GPU memory;
+call `remote.dispose()` on leave. Relay one-shot events (punch,
 hit, validated planar-action start) alongside the flags and call the matching
 `remoteAnims.playOneShot(...)` on receipt. Never run `MotionActionDriver` for a
 remote: its smoothed owner-authored transform is the sole movement authority.

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

@@ -72,9 +72,11 @@ import { waitForPlayer, waitForAuth, getColyseusAuth, getEmbedToken } from "@gen
 const { user, guest } = await waitForPlayer();
 // user.id / user.name — real account identity, or guest:<id> / "Guest-1234"
 // user.avatarUrl — the player's OWN VRM avatar (profile pick; per-session for
-// guests). Load it for the local player's visual in a VRM-lane game, with the
-// baked ./assets/avatar.vrm as the fallback (absent on old APIs / local test
-// mode). Peers see each other's via the multiplayer SDK's player.avatarUrl.
+// guests). It is the FALLBACK body, not the game's character: pass it to
+// loadPlayerCharacter({ avatarUrl: user.avatarUrl }) and it is used only when
+// this game has no generated character of its own, with the baked
+// ./assets/avatar.vrm behind it (absent on old APIs / local test mode).
+// Peers resolve the same way via the multiplayer SDK's player.avatarUrl.
 
 // ACCOUNT gate — resolves ONLY for signed-in players (stays pending for
 // guests; resolves later if they sign in mid-game). Use ONLY for /state

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

@@ -537,14 +537,16 @@ fights (many writers). A ball on `objects` glides and has one owner. That's the
   `{ id, name, avatarUrl, connected, state, stateRaw }`: `state` is auto-smoothed (remotes) / live (you);
   `stateRaw` is the raw latest (hit-tests, discrete values). A reconnect-grace seat remains in this
   map with `connected: false`. `avatarUrl` is that player's verified VRM pick (server-set, `''`
-  when unknown) — in a VRM-lane game render each remote with
-  `loadVrmClone(p.avatarUrl || "./assets/avatar.vrm")` (the vendored loader's shared-GPU clone:
-  N remotes share one set of geometry/textures instead of re-parsing per player — retarget
-  clips once on `loadVrmClone.base(url)` and play them on each clone's own mixer); never
-  publish avatar URLs through `me.set`. **A remote player's body is NEVER hand-built
-  primitives** (no capsule + cone "person" — the single most common shipped co-op defect):
-  a themed game renders remotes with the SAME themed character model the local player
-  uses; everything else renders `p.avatarUrl` VRMs. This applies with full force to
+  when unknown) — render each remote with
+  `loadRemotePlayerCharacter({ avatarUrl: p.avatarUrl })` (the vendored controller kit's
+  loader) and `remote.dispose()` on leave; never publish avatar URLs through `me.set`.
+  That one call carries the whole rule: **in a game with its own generated character,
+  every remote wears it** — `p.avatarUrl` is used only when this game has no generated
+  character, which is exactly when per-player looks are the right answer. It shares one
+  parsed base across remotes (N remotes ≈ 1 body of geometry/textures instead of a parse
+  per player) and clips are retargeted once on that base. **A remote player's body is
+  NEVER hand-built primitives** (no capsule + cone "person" — the single most common
+  shipped co-op defect). This applies with full force to
   first-person games — the local player may be invisible to themselves, but every
   remote hunter/partner is a full character on screen. On phone tiers, animate and fully draw only the
   nearest `tier.remoteAvatarCap` remotes (`$genex-threejs-adaptive-quality`) — freeze the

package/templates/skills/genex-threejs-multiplayer/references/host-physics.md

@@ -273,13 +273,14 @@ room.me.set({
   r: character.runActive,  j: character.jumpActive, c: character.crouchActive,
 });
 
-// Remote players: a VISUAL-ONLY avatar — NO Rapier body, NO controller instance for remotes.
-// Build each remote's visual from THEIR OWN model: in a VRM-lane game that is
-// loadVrmClone(pl.avatarUrl || "./assets/avatar.vrm") — the verified per-player pick the
-// relay replicates ('' = unknown → fall back; deepDispose the clone on 'leave'). The clone
-// shares parsed GPU geometry/textures across remotes with the same file (most rooms: all of
-// them) — retarget clips once against loadVrmClone.base(url).vrm and drive each clone's own
-// AnimationMixer. Never reuse your own avatar OBJECT for a remote (clones, not references).
+// Remote players: a VISUAL-ONLY body — NO Rapier body, NO controller instance for remotes.
+// Build each remote with loadRemotePlayerCharacter({ avatarUrl: pl.avatarUrl }) — in a game
+// with its own generated character everyone wears it, and pl.avatarUrl (the verified
+// per-player pick the relay replicates; '' = unknown → fall back) is used only when this
+// game has no generated character. It clones a shared parsed base, so remotes share GPU
+// geometry/textures instead of re-parsing per player, and retargets clips once on that
+// base; drive each clone's own AnimationMixer and call remote.dispose() on 'leave'.
+// Never reuse your own body OBJECT for a remote (clones, not references).
 // Phone tiers animate only the nearest tier.remoteAvatarCap remotes (adaptive-quality skill). Position/rotation from smoothed state; animation from the
 // synced flags via the avatar's own update(flags, dt). The character-controller skill's
 // animations reference owns the flag set.