@genex-ai/cli-demo 0.62.0-dev.143 → 0.63.0-dev.146

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@genex-ai/cli-demo",
-  "version": "0.62.0-dev.143",
+  "version": "0.63.0-dev.146",
   "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-ai-menu/SKILL.md

@@ -126,6 +126,19 @@ after the UI plan gate, enqueue the video with `--no-wait`, ship the CSS menu
 (R2) — permanent, public, CORS-open; you load them straight from the printed
 URLs, nothing is downloaded or committed.
 
+**Two failed video attempts = ship the still. Hard stop.** Video is the one
+generation that fails server-side with real frequency (render timeouts), and
+every attempt costs minutes of waiting. One retry is fair — shorten the clip
+(4–6 s) and simplify the motion prompt. After a SECOND failure, stop
+generating: keep the key-art still as the menu background and give it life
+for free with a slow CSS pan/zoom (`transform: scale(1.06)` over ~20 s,
+alternating), tell the user in one plain line ("the animated menu backdrop
+kept failing, so your menu uses the key art — looks great, costs nothing"),
+and spend those minutes in the game. A third attempt is how half an hour
+disappears into chrome — the CLI counts failures and reminds you at the
+second one. The still-image menu is a real menu: this rule is the built-in
+fallback, not a downgrade to apologize for.
+
 ## Wire it as a phase screen
 
 The menu is one `data-phase` screen in the `$genex-threejs-game-ui`

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

@@ -0,0 +1,189 @@
+---
+name: genex-threejs-game-content
+description: Turn a content-shaped request — quests, NPCs, dialogue, shops, loot, XP — into a countable content contract and the data-driven systems that ship it. Use when the ask names game content in the plural or a content genre (RPG, adventure, story, open world), BEFORE the asset batch, and before calling such a game done.
+---
+
+# Genex Three.js Game Content
+
+The most common way a content-shaped request fails is not bad code — it is the
+ask silently shrinking: "quests" ships as one hardcoded integer, "NPCs" as
+empty textured huts, "a big world" as one small fogged plane, while every
+visual floor passes, because content is invisible to a screenshot. This skill
+gives content the same teeth the look has: a countable contract written up
+front, data-driven systems that make each contract line cheap to ship, and a
+floor that gates publish.
+
+## The content contract — write it before the asset batch
+
+Run this the moment the game concept is locked, in the SAME plan message as
+`$genex-threejs-game-ui`'s UI gate, whenever the request names content in the
+plural (quests, enemies, bosses, locations, spells, items, factions…) or a
+content genre (an RPG, an adventure, an open world, a story game, a survival
+game). **Walk every plural noun of the request and make each one a countable
+line.** The template:
+
+```
+CONTENT CONTRACT — <game>
+world:       <size class, as a number: one arena | a district (~500 m) | open world (km-class — $genex-threejs-open-world)>
+locations:   <N, named: village, crypt, bandit camp, watchtower, boss lair…>
+quests:      <N total — a main chain of M gated steps + side quests; each giver named>
+NPCs:        <N speaking (quest givers, merchants) + M flavor villagers>
+enemies:     <N types + where they spawn; which are bosses and what makes each boss FIGHT differently>
+progression: <what grows: XP/levels, gear tiers, learnable abilities — the numbers and their rewards>
+economy:     <currency sources AND sinks — what the player earns and what they spend it on>
+minute ten:  <one sentence: what is the player DOING ten minutes in, and why is it different from minute one?>
+```
+
+Rules that make the contract real:
+
+- **It comes before the asset batch.** The asset set derives from the
+  contract — a world with six locations and four enemy types needs a
+  different `npx genex model` list than one arena, and finding that out after
+  the batch means the world gets shaped around the wrong assets.
+- **Every line is a floor.** Publish and the final handoff wait for the
+  contract's countables exactly the way they wait for the sprite HUD: a
+  request that said "quests" is not done with one; a request that said "big
+  world" is not done with an arena.
+- **Scope belongs to the user.** Building a small first slice is the right
+  ORDER (`$genex-threejs-game-ui`'s v0 beat still applies) — but the slice is
+  a milestone on the way to the contract, never a quiet replacement for it.
+  If the full ask genuinely doesn't fit, shrinking any line is a structured
+  question to the user with real options — never a silent cut justified as
+  "standard practice".
+- **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.
+
+## Data-driven, or you won't finish in one session
+
+The reason a solo agent can ship seven quests and seventeen items in an
+afternoon is architecture, not typing speed:
+
+- **Systems read tables; content lives in tables.** The quest engine, the
+  dialogue walker, the merchant screen, and the spawner are each written
+  ONCE; quest #5, item #12, and enemy #4 are table rows. If adding a quest
+  means touching engine code, the engine is wrong.
+- **Hand-author the beats, table-drive the bulk, seed the placement.** Quest
+  prose, boss mechanics, and location identities deserve human-quality
+  authoring; stats, stocks, and rewards are data; trees, rocks, and chest
+  scatter come from a seeded RNG so "more world" costs zero authoring.
+- **One event bus.** Quests advance on events the game already emits
+  (`enemy:died`, `item:pickup`, `chest:opened`, `npc:talked`, `zone:entered`)
+  — the quest system subscribes; combat and loot never know quests exist.
+  This is also what makes quest logic testable in isolation.
+
+The full engine — quest defs + state machine, dialogue trees with quest
+hooks, merchant stocks, XP curve — is in
+[references/content-tables.md](references/content-tables.md) as copy-paste
+modules. Copy them and fill the tables; don't re-derive the shape.
+
+## Quests: defs + events, never an integer
+
+The minimum honest quest system is a table of defs and an event-driven state
+machine (`locked → available → active → ready → done`), with prereq gating for
+the main chain:
+
+```ts
+type Objective =
+  | { kind: "kill"; target: string; count: number }
+  | { kind: "collect"; item: string; count: number }
+  | { kind: "reach"; location: string }
+  | { kind: "talk"; npc: string };
+
+type QuestDef = {
+  id: string;
+  giver: string;            // NPC id — every quest has a face, not a board
+  prereq?: string;          // quest id that must be done first (main chain)
+  title: string;
+  brief: string;            // 2–3 sentences of authored prose, not filler
+  objective: Objective;
+  rewards: { gold?: number; xp?: number; items?: string[] };
+};
+```
+
+Progress comes only from the event bus (see the reference for the ~60-line
+engine). A tracked quest gets a compass/journal marker
+(`$genex-threejs-game-ui` inventories the journal as a screen element), and
+turn-in happens in dialogue — handing in a quest should feel like talking to
+a person, not watching a counter flip.
+
+## Dialogue: trees with quest hooks
+
+Quest givers and merchants speak. The walker is a dozen lines (reference file)
+over nodes of `{ text, options: [{ label, next | action }] }`; what makes it a
+QUEST system is three dynamic option states injected per NPC: **offer** (quest
+available → "I might have work for you"), **remind** (active → restate the
+objective), **turn-in** (ready → hand rewards, open the next chain link). Add
+a couple of lore branches per named NPC — three authored lines is the
+difference between a person and a signpost. A quest board is an acceptable
+extra for arcade-shaped games; it is never the replacement for speaking
+NPCs when the ask said "NPCs".
+
+## Items, shops, and an economy that closes
+
+An item catalog (id, kind, price, stats), stack-based inventory, and merchant
+stock tables per vendor NPC — all data (reference file). The rule that keeps
+it a game: **currency needs sinks.** Gold the player can only accumulate is a
+score with a coin icon; gold that buys potions, a better sword, and a spell
+tome is an economy. Price the first upgrade to be affordable after the first
+quest, and let drops + chest loot + quest rewards all feed the same wallet.
+
+## Progression: something must grow
+
+Pick at least one growth axis and wire its rewards into the quest/enemy
+tables: an XP curve (`xpNext = 100 * level ** 1.4` is a fine default) with
+flat stat gains per level, gear tiers on the merchant, or learnable abilities
+gated behind tomes/trainers. The contract names which; "nothing grows" is what
+makes minute ten feel like minute one.
+
+## NPCs: the minimum that reads as alive
+
+A named NPC with a role, a home spot, an idle bob, a face-the-player turn
+within a few meters, and dialogue reads as a person — schedules and pathing
+are optional upgrades, speech is not. Place speaking NPCs (givers, merchants)
+by hand at their locations; scatter flavor villagers with one-line barks from
+a table. An empty textured hut village fails the "NPCs" line of any contract.
+For host-simulated NPCs/enemies in multiplayer, `$genex-threejs-multiplayer`
+owns the authority rules.
+
+## Content that can't dead-end — check before shipping
+
+- A kill/collect quest counts progress made BEFORE acceptance (or the brief
+  says why not) — "kill 5 bandits" accepted after clearing the camp must not
+  strand at 0/5.
+- A quest item from a unique source (a boss drop, a one-time chest) must
+  persist until picked up — the source never respawns, so expiring the drop
+  dead-ends the chain.
+- The main chain gates on prereqs, not on geography alone — reaching the
+  final lair early should show a locked door or a warning, not a sequence
+  break that skips the story.
+- The turn-in NPC is reachable after the objective (didn't die in the wave,
+  isn't locked behind the boss arena).
+- Saves restore quest state AND its world side-effects — the opened chest
+  stays open, the armed boss stays armed. Quest stages, inventory, XP, and
+  gold go in the per-player slot via `$genex-threejs-embed-auth`.
+
+## Wiring into the rest of the pack
+
+- World layout, terrain, and location placement at scale:
+  `$genex-threejs-open-world` (the contract's `world:` line decides whether
+  it loads).
+- Quest journal, tracker, toasts, vendor screens: inventory them at
+  `$genex-threejs-game-ui`'s gate — they are screen elements like any other.
+- Level-ups, quest completion, and boss kills are exactly the "moments" the
+  feel pass layers feedback on: `$genex-threejs-game-feel` + a real
+  `npx genex sfx` fanfare (`$genex-ai-sfx`).
+- Location set pieces and speaking-NPC meshes: `$genex-ai-model` /
+  `$genex-ai-character` — generated assets decorate the contract's landmarks;
+  they never decide how many exist.
+
+## Failure modes to catch
+
+- "Quests" (plural, in the ask) shipped as one quest — a stage integer with
+  hardcoded strings and no giver.
+- A village of textured huts where nobody speaks.
+- A gold counter with nothing to spend it on.
+- No growth axis: the player at minute thirty plays exactly like minute one.
+- The contract posted, then quietly abandoned when the first slice previewed
+  well — the slice is a milestone, not the destination.
+- Contract lines silently shrunk without a structured question to the user.

package/templates/skills/genex-threejs-game-content/references/content-tables.md

@@ -0,0 +1,269 @@
+# Genex game content — copy-paste systems
+
+Four small modules that turn contract lines into shipped content: an event
+bus, a quest engine, a dialogue walker with quest hooks, and items/economy +
+XP. Copy them, fill the tables, and keep content OUT of engine code — adding
+a quest, an item, or a vendor must always be a table edit.
+
+All snippets are plain vanilla-ts (no enums, no decorators) and assume a
+single shared game-state object `G` you already have (player stats, wallet,
+the scene). Adapt names, not shapes.
+
+## 1. Event bus — the only coupling
+
+```ts
+// events.ts — combat, loot, and movement EMIT; quests and UI SUBSCRIBE.
+type GameEvent =
+  | { type: "enemy:died"; enemyKind: string }
+  | { type: "item:pickup"; item: string; count: number }
+  | { type: "chest:opened"; chestId: string }
+  | { type: "npc:talked"; npc: string }
+  | { type: "zone:entered"; location: string };
+
+type Handler = (e: GameEvent) => void;
+const handlers: Handler[] = [];
+
+export function onEvent(h: Handler): void {
+  handlers.push(h);
+}
+export function emit(e: GameEvent): void {
+  for (const h of handlers) h(e);
+}
+```
+
+## 2. Quest engine — defs are data, progress is events
+
+```ts
+// quests.ts
+import { onEvent } from "./events.ts";
+
+type Objective =
+  | { kind: "kill"; target: string; count: number }
+  | { kind: "collect"; item: string; count: number }
+  | { kind: "reach"; location: string }
+  | { kind: "talk"; npc: string };
+
+type QuestDef = {
+  id: string;
+  giver: string;
+  prereq?: string;
+  title: string;
+  brief: string;
+  turnIn: string; // authored prose for the hand-in moment
+  objective: Objective;
+  rewards: { gold?: number; xp?: number; items?: string[] };
+};
+
+// CONTENT — the whole quest list lives here. Main chain via prereq; the
+// prose is authored, not generated filler. Counts must match the contract.
+export const QUESTS: QuestDef[] = [
+  {
+    id: "q_wolves",
+    giver: "elder",
+    title: "Teeth in the Tall Grass",
+    brief:
+      "Wolves have taken the shepherd's flock and now they circle the palisade at dusk. Thin the pack before someone's child is next.",
+    turnIn: "Five pelts. The flock sleeps easy tonight — and so do we. Take this.",
+    objective: { kind: "kill", target: "wolf", count: 5 },
+    rewards: { gold: 40, xp: 60 },
+  },
+  {
+    id: "q_amulet",
+    giver: "elder",
+    prereq: "q_wolves",
+    title: "What the Crypt Keeps",
+    brief:
+      "Our founder's amulet lies in the old crypt east of the fields. The dead have grown restless around it — bring it back, and mind the narrow dark.",
+    turnIn: "The amulet… after all these years. You have the village's gratitude, and its coin.",
+    objective: { kind: "collect", item: "founder_amulet", count: 1 },
+    rewards: { gold: 80, xp: 120, items: ["potion_health"] },
+  },
+  // …side quests: no prereq, different givers, different objective kinds.
+];
+
+type QuestStatus = "locked" | "available" | "active" | "ready" | "done";
+type QuestState = { status: QuestStatus; progress: number };
+
+export const questState = new Map<string, QuestState>();
+for (const q of QUESTS) {
+  questState.set(q.id, { status: q.prereq ? "locked" : "available", progress: 0 });
+}
+
+const def = (id: string): QuestDef => QUESTS.find((q) => q.id === id)!;
+
+export function accept(id: string): void {
+  const s = questState.get(id)!;
+  if (s.status !== "available") return;
+  s.status = "active";
+  // Contract check "can't dead-end": count pre-acceptance progress where the
+  // fiction allows it (kills already made), or reset knowingly.
+}
+
+export function turnIn(id: string): { gold: number; xp: number; items: string[] } | null {
+  const s = questState.get(id)!;
+  if (s.status !== "ready") return null;
+  s.status = "done";
+  for (const q of QUESTS) {
+    if (q.prereq === id && questState.get(q.id)!.status === "locked") {
+      questState.get(q.id)!.status = "available"; // next chain link opens
+    }
+  }
+  const r = def(id).rewards;
+  return { gold: r.gold ?? 0, xp: r.xp ?? 0, items: r.items ?? [] };
+}
+
+function bump(q: QuestDef, s: QuestState, amount = 1): void {
+  const needed = "count" in q.objective ? q.objective.count : 1;
+  s.progress = Math.min(needed, s.progress + amount);
+  if (s.progress >= needed) s.status = "ready"; // journal + marker flip to "return"
+}
+
+onEvent((e) => {
+  for (const q of QUESTS) {
+    const s = questState.get(q.id)!;
+    if (s.status !== "active") continue;
+    const o = q.objective;
+    if (o.kind === "kill" && e.type === "enemy:died" && e.enemyKind === o.target) bump(q, s);
+    if (o.kind === "collect" && e.type === "item:pickup" && e.item === o.item) bump(q, s, e.count);
+    if (o.kind === "reach" && e.type === "zone:entered" && e.location === o.location) bump(q, s);
+    if (o.kind === "talk" && e.type === "npc:talked" && e.npc === o.npc) bump(q, s);
+  }
+});
+```
+
+Journal UI, the tracked-quest compass marker, and toasts subscribe to the
+same state — inventory them as screen elements at `$genex-threejs-game-ui`'s
+gate. Persist `[...questState]` (plus world side-effects like opened chests)
+in the per-player slot via `$genex-threejs-embed-auth`.
+
+## 3. Dialogue walker — quest states become options
+
+```ts
+// dialogue.ts
+import { QUESTS, questState, accept, turnIn } from "./quests.ts";
+
+type DialogueOption = { label: string; next?: DialogueNode; action?: () => void };
+type DialogueNode = { text: string; options: DialogueOption[] };
+
+// CONTENT — per-NPC roots: greeting + a couple of authored lore branches.
+// Three real lines is the difference between a person and a signpost.
+const ROOTS: Record<string, DialogueNode> = {
+  elder: {
+    text: "Maren watches the road as she talks. “Strangers used to mean trade. Lately they mean trouble.”",
+    options: [
+      {
+        label: "Tell me about this village.",
+        next: {
+          text: "“Three generations behind this palisade. The crypt east of here is older than all of it — and lately, louder.”",
+          options: [],
+        },
+      },
+    ],
+  },
+  // blacksmith, herbalist… — every giver and merchant has a root.
+};
+
+// The whole walker: render node.text + numbered options; a click (or the
+// 1–9 key) runs option.action?.(), then shows option.next or closes. Emit
+// { type: "npc:talked", npc } when a conversation OPENS — that's what "talk"
+// objectives listen for.
+export function pickOption(node: DialogueNode, index: number): DialogueNode | null {
+  const opt = node.options[index];
+  if (!opt) return node;
+  opt.action?.();
+  return opt.next ?? null; // null = close the dialogue panel
+}
+
+export function openDialogue(npc: string): DialogueNode {
+  const root = ROOTS[npc];
+  const options = [...root.options];
+  for (const q of QUESTS) {
+    if (q.giver !== npc) continue;
+    const s = questState.get(q.id)!;
+    if (s.status === "available") {
+      options.unshift({
+        label: `[Quest] ${q.title}`,
+        next: {
+          text: q.brief,
+          options: [
+            { label: "I'll do it.", action: () => accept(q.id) },
+            { label: "Not now." },
+          ],
+        },
+      });
+    } else if (s.status === "active") {
+      options.unshift({ label: `[${q.title}] Remind me.`, next: { text: q.brief, options: [] } });
+    } else if (s.status === "ready") {
+      options.unshift({
+        label: `[Complete] ${q.title}`,
+        next: { text: q.turnIn, options: [] },
+        action: () => {
+          const r = turnIn(q.id);
+          // …grant r.gold / r.xp / r.items through your wallet + inventory.
+        },
+      });
+    }
+  }
+  return { text: root.text, options };
+}
+```
+
+## 4. Items, merchants, XP — the economy that closes
+
+```ts
+// items.ts
+type ItemDef = {
+  id: string;
+  kind: "weapon" | "armor" | "potion" | "quest" | "tome";
+  name: string;
+  price: number; // what merchants charge — the SINK side of the economy
+  stats?: { dmg?: number; armor?: number; heal?: number };
+};
+
+export const ITEMS: ItemDef[] = [
+  { id: "sword_iron", kind: "weapon", name: "Iron Sword", price: 120, stats: { dmg: 18 } },
+  { id: "potion_health", kind: "potion", name: "Health Draught", price: 25, stats: { heal: 40 } },
+  { id: "founder_amulet", kind: "quest", name: "Founder's Amulet", price: 0 },
+  // …the catalog. Price the first upgrade to land right after the first quest's gold.
+];
+
+// Merchant stock is per-NPC data — a second vendor is one more entry.
+export const STOCKS: Record<string, string[]> = {
+  blacksmith: ["sword_iron", "armor_leather"],
+  herbalist: ["potion_health", "potion_mana"],
+};
+
+// XP curve + level rewards: one growth axis, wired to quest/enemy rewards.
+export const xpNext = (level: number): number => Math.round(100 * level ** 1.4);
+export function addXp(player: { level: number; xp: number; maxHp: number; hp: number }, amount: number): void {
+  player.xp += amount;
+  while (player.xp >= xpNext(player.level)) {
+    player.xp -= xpNext(player.level);
+    player.level += 1;
+    player.maxHp += 12;
+    player.hp = player.maxHp; // level-up heals — a reward the player FEELS
+  }
+}
+```
+
+## Seeded placement — bulk content for free
+
+Scatter the non-authored bulk (chests, camps, flavor spawns) with a seeded
+RNG so the world is deterministic across loads and machines:
+
+```ts
+export function seededRng(seed: number): () => number {
+  let s = seed >>> 0;
+  return () => {
+    s = (s * 1664525 + 1013904223) >>> 0;
+    return s / 0xffffffff;
+  };
+}
+// const rng = seededRng(1337): place 10 chests at rng()-driven offsets around
+// locations, skip water/steep slopes via the world's height/biome lookups
+// ($genex-threejs-open-world), and hand-place only the authored few.
+```
+
+Hand-authored where it matters (quest prose, boss mechanics, unique loot),
+tables for the bulk, seeds for the scatter — that split is what lets one
+session ship the whole contract.

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);