@genex-ai/cli-demo 0.62.0-dev.144 → 0.63.0-dev.149

package/dist/index.js

@@ -12357,15 +12357,19 @@ var CONTROLLER_FILE_SETS = {
       ...INPUT_AND_CAMERA,
       NOTICE
     ],
-    // The player's VRM is written to public/assets/avatar.vrm at install time by
+    // The FALLBACK VRM is written to public/assets/avatar.vrm at install time by
     // installOwnerAvatar (owner's avatar, or the bundled default) — so it is NOT
-    // a static manifest asset. animation-library.glb (the 12-clip core) still is;
-    // extra clips arrive via `genex controller anims` into public/assets/anims/.
+    // a static manifest asset; at runtime the game loads the playing user's own
+    // avatar (user.avatarUrl from the embed identity, AG-804) and this file
+    // covers local dev + load failures. animation-library.glb (the 12-clip core)
+    // still is a manifest asset; extra clips arrive via `genex controller anims`
+    // into public/assets/anims/.
     assets: ["assets/animation-library.glb"],
     skill: "genex-threejs-character-controller",
     sketch: [
       `const physics = await PhysicsWorld.create();`,
-      `const { scene, vrm } = await loadVrm("./assets/avatar.vrm");`,
+      `const { user } = await waitForPlayer(); // @genex-ai/embed-sdk \u2014 the player's own avatar`,
+      `const { scene, vrm } = await loadVrm(user.avatarUrl ?? "./assets/avatar.vrm").catch(() => loadVrm("./assets/avatar.vrm"));`,
       `const clips = await loadCharacterClips(vrm); // core library + every genex-controller-anims pack`,
       `const character = new CharacterController(physics.world, camera, { ...characterPresets["default"].options, ...capsuleFromModel(scene), position: { x: 0, y: 2, z: 0 } });`,
       `character.root.add(scene); const anims = new CharacterAnimations(scene, clips);`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@genex-ai/cli-demo",
-  "version": "0.62.0-dev.144",
+  "version": "0.63.0-dev.149",
   "description": "Set up your project's agent workspace (.claude/.codex/.cursor in the game folder), authorize, create a game project, generate AI assets, and publish (genex CLI).",
   "type": "module",
   "bin": {

package/templates/skills/genex-explore/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: genex-explore
-description: Search the curated Genex community gallery with `npx genex explore` before hand-writing hard visual or physics systems. Use when the game needs terrain, grass, water, vehicles, buildings, dungeons, flocking/boids, or advanced shader work — proven open-source Three.js implementations you can clone as a starting point or borrow parts from, credits included.
+description: Search the curated Genex community gallery with `npx genex explore` — once at the planning stage (the plan sweep, browse the catalog against the game plan and state reuse decisions) and again before hand-writing any hard system. Use when planning a new game, or when it needs terrain, grass, water, vehicles, buildings, dungeons, flocking, or advanced shaders — proven open-source Three.js implementations to clone or borrow from, credits included.
 ---
 
 # Genex Explore — proven building blocks from the community gallery
@@ -11,9 +11,29 @@ advanced shader effects. The curated community gallery holds **faithful ports of
 proven open-source Three.js projects** — playable, cloneable, and licensed for
 reuse. Search it before hand-writing one of those systems.
 
-## When to use
+## The plan sweep — once per game, right after the plan is written
 
-Before building a hard visual/physics system by hand, run:
+The moment the game contract (and the content contract, when there is one) is
+on the table, run the catalog against it ONCE:
+
+```bash
+npx genex explore
+```
+
+No query — the catalog is small and every entry is proven, so one browse
+covers the whole plan at once. Then walk the plan's systems (terrain, grass,
+water, vehicles, combat feel, buildings, dungeons…) and for each one that a
+catalog entry serves, state a reuse decision in the plan, one line each:
+**clone as the base** / **borrow parts** (see below) / **build fresh, because
+X**. Not deciding is the failure — a session that hand-builds a grass field
+while a proven grass system sits in the catalog wasted its minutes on a
+solved problem. If the catalog comes back empty on this stand, say so in one
+line and move on — the sweep costs one command either way.
+
+## When to use again — before any hard system
+
+Later in the build, before hand-writing a hard visual/physics system the plan
+didn't foresee, run:
 
 ```bash
 npx genex explore "<what you need>"

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

@@ -19,10 +19,12 @@ 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 the player's avatar to `public/assets/avatar.vrm` —
+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`).
-By default, the character plays as that VRM. The copied files are then owned by the game —
+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 —
 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
@@ -89,12 +91,20 @@ import { FollowCamera } from "./controllers/character/follow-camera.ts";
 import { KeyboardInput } from "./controllers/character/keyboard-input.ts";
 import { loadVrm } from "./controllers/character/vrm/vrm-loader.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 player's avatar, then every animation the game has (the bundled core
-// library + any packs installed by `genex controller anims`), retargeted onto the VRM.
-const { scene: avatar, vrm } = await loadVrm("./assets/avatar.vrm");
+// 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.
+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 fit = capsuleFromModel(avatar);          // collider fits THIS avatar's bounds
@@ -266,11 +276,15 @@ 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: create a plain mesh (or the same GLB), 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.
+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.
 
 - Publish your own `currPos` + `currQuat` as a four-number quaternion on the fixed 10–20 Hz tick,
   not per frame. Never reduce multiplayer rotation to scalar yaw.

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

@@ -10,8 +10,10 @@ clips only on the exact matching generated rig revision.
 
 `npx genex controller character` sets the game up to play as a **VRM avatar**:
 
-- `public/assets/avatar.vrm` — the player's avatar (yours when signed in, else a
-  bundled CC0 default). Always present; always one path.
+- `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.
 - `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`).
@@ -35,8 +37,13 @@ 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";
 
-const { scene, vrm } = await loadVrm("./assets/avatar.vrm");
+// The playing user's OWN avatar (their profile pick; per-session for guests) —
+// the baked file is only 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
 
 // capsuleFromModel derives the collider from the avatar's bounds — no manual
@@ -365,8 +372,11 @@ 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:
-`loadVrm` + retargeted UAL clips for a VRM game (and call `vrm.update(delta)`
-per remote), or `loadMeshyCharacter` for a Meshy game. Relay one-shot events (punch,
+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,
 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

@@ -78,6 +78,10 @@ import { waitForPlayer, waitForAuth, getColyseusAuth, getEmbedToken } from "@gen
 // everything wants.
 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.
 
 // 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-game-content/SKILL.md

@@ -53,6 +53,11 @@ Rules that make the contract real:
 - **Minute ten is the design test.** If the honest answer is "the same sixty
   seconds, again", the contract needs another beat (a new area unlocks, a
   quest chain escalates, a build comes online) before any polish work.
+- **Close it with the reuse sweep.** Run `npx genex explore` once (no query)
+  and map the contract's systems against the curated catalog — proven ports
+  of terrain, grass, water, vehicles, combat feel, buildings, dungeons exist
+  there to clone or borrow with credits (`$genex-explore` has the steps). One
+  reuse line per matched system; an empty catalog is a one-line note.
 
 ## Data-driven, or you won't finish in one session
 

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

@@ -46,7 +46,7 @@ npm i @genex-ai/multiplayer@^0.11.0
 > landed in 0.10; confirmed object controls, snaps, host-tick teardown, and reconnect rebasing
 > in 0.9. An older resolve does not have those.
 
-This skill targets `@genex-ai/multiplayer` **≥ 0.11.0** (`objects`/`host` since 0.4;
+This skill targets `@genex-ai/multiplayer` **≥ 0.12.0** (`objects`/`host` since 0.4; verified per-player `avatarUrl` since 0.12;
 `matchmake()` since 0.5; private lobbies since 0.7; auto-reconnect + `inputs`/`onHostTick`
 since 0.8; soft ownership handoff since 0.8.4; confirmed controls, snap epochs, and host-tick
 lifecycle guarantees since 0.9; regional relay selection via `getColyseusUrls()` since 0.10;
@@ -519,6 +519,7 @@ of five kinds — put each on its channel and the game just works:
 | Slow agreed facts (score, round, wave, seed) | `shared` | the **host** (`isHost`) |
 | One-off actions (shot, emote, hit, chat) | `send` + `on` | whoever did it |
 | Discrete per-player values (hp, ammo, flags) | in `me.set`, read via `stateRaw` | you |
+| Which avatar MODEL a player is (VRM look) | already on `players` as `p.avatarUrl` — sync nothing | the **relay** (verified identity) |
 
 Getting the channel right is the whole game. A ball on `shared` stutters (not smoothed) and
 fights (many writers). A ball on `objects` glides and has one owner. That's the difference.
@@ -531,9 +532,11 @@ fights (many writers). A ball on `objects` glides and has one owner. That's the
 - `room.me.snap(state)` — respawn/teleport/mode edge. Publishes a discontinuity epoch so remotes
   hard-reseed instead of interpolating from the old pose. Never use for ordinary movement.
 - `room.players` — fresh `Map` each read, **includes you** (skip `id === room.id`). Each value is
-  `{ id, name, connected, state, stateRaw }`: `state` is auto-smoothed (remotes) / live (you);
+  `{ 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`.
+  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
+  `loadVrm(p.avatarUrl || "./assets/avatar.vrm")`; never publish avatar URLs through `me.set`.
 - `room.activePlayers` — the connected-only subset of `room.players`; use its size for live quorum.
 - `room.objects` — shared objects nobody owns until claimed (a ball, an NPC):
   - `claim(id)` — **legacy** optimistic request. It flips local ownership immediately and is corrected

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

@@ -274,8 +274,12 @@ room.me.set({
 });
 
 // Remote players: a VISUAL-ONLY avatar — NO Rapier body, NO controller instance for remotes.
-// 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.
+// Build each remote's visual from THEIR OWN model: in a VRM-lane game that is
+// loadVrm(pl.avatarUrl || "./assets/avatar.vrm") — the verified per-player pick the relay
+// replicates ('' = unknown → fall back; deepDispose the model on 'leave'). Never reuse your
+// own avatar file for every remote. 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.
 const pl = room.players.get(id)!;
 remoteAvatar.group.position.set(pl.state.x, pl.state.y, pl.state.z);
 remoteAvatar.group.quaternion.fromArray(pl.state.q);

package/templates/skills/genex-threejs-skill-router/references/routing-map.md

@@ -31,7 +31,14 @@ Three.js release or branch, and do not blindly copy demo architecture.
    fogged plane. Scope belongs to the user: shipping fewer or smaller than
    the ask requires their explicit OK through a structured question — a
    "vertical slice first" is a build order, never a license to shrink the
-   destination silently.
+   destination silently. **Close the contract with the reuse sweep:** run
+   `npx genex explore` once (no query) and map the plan's systems against the
+   curated catalog — proven ports of terrain, grass, water, vehicles, combat
+   feel, buildings, dungeons exist there to clone or borrow (credits carried,
+   `$genex-explore` has the integration steps). One reuse line per matched
+   system in the plan (clone as base / borrow parts / build fresh because X);
+   hand-building a system the catalog already proves is the waste this sweep
+   exists to prevent. An empty catalog is a one-line note, not a blocker.
 2. Wire player identity before any boot code: `$genex-threejs-embed-auth` is
    mandatory for every game (`initEmbed(...)` + the `waitForPlayer()` gate) —
    saves, leaderboards, and multiplayer auth all come from it.