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

package/templates/controllers/character/player-character.ts

@@ -0,0 +1,217 @@
+// SPDX-License-Identifier: MIT
+// The player's body, resolved once: the game's OWN generated character when
+// this game has one, the visiting player's profile avatar when it does not.
+//
+// WHY THIS EXISTS: before it, the two lanes were different code — different
+// loader, different CharacterAnimations arguments, and a per-frame call that
+// appeared and disappeared. So the boot path written at hour 0 (the avatar,
+// the only lane that works before a character exists) had to be REWRITTEN at
+// hour 2 when the generated character landed, by an agent low on context with
+// ten things half-done. It wasn't, and games shipped wearing the platform's
+// stock avatar instead of the character they were designed around. ONE shape
+// for both lanes means the character arriving later is a file drop, not an
+// edit — `genex controller character --character <id>` writes the manifest and
+// the next reload picks it up.
+//
+// The generated character is the default for any game where a human body
+// appears on screen (first-person included — remotes, a look-down body, a
+// shadow, a menu portrait). The avatar is the FALLBACK: a declared temporary
+// body while the character renders, or the stand-in when generation genuinely
+// could not happen (out of credits, failed, unverified).
+import * as THREE from "three";
+import * as SkeletonUtils from "three/addons/utils/SkeletonUtils.js";
+import { VRMUtils } from "@pixiv/three-vrm";
+import type { LocomotionProfile } from "./character-animations.ts";
+import { loadCharacterClips } from "./animation-packs.ts";
+import {
+  loadMeshyCharacter,
+  type LoadMeshyCharacterOptions,
+  type MeshyCharacter,
+} from "./meshy/meshy-loader.ts";
+import { loadVrm, loadVrmCloneBase } from "./vrm/vrm-loader.ts";
+
+/** "generated" = this game's own themed character; "avatar" = the fallback. */
+export type PlayerCharacterKind = "generated" | "avatar";
+
+export interface PlayerCharacter {
+  kind: PlayerCharacterKind;
+  /** Renderable root — parent it under `character.root`. */
+  scene: THREE.Group;
+  /** Clips for CharacterAnimations (exact-rig generated clips, or retargeted UAL). */
+  clips: THREE.AnimationClip[];
+  /** Present only in the generated lane; pass straight through to CharacterAnimations. */
+  locomotionProfile?: LocomotionProfile;
+  /** Once per RENDER frame, after physics.step(). Ticks the VRM humanoid + spring
+   *  bones in the fallback lane; a no-op for native rigs. Always call it — that
+   *  is the point: the boot code never changes when the lane does. */
+  update(delta: number): void;
+  dispose(): void;
+}
+
+/** A REMOTE player's body: visual only, so no per-frame update and no physics. */
+export interface RemotePlayerCharacter {
+  kind: PlayerCharacterKind;
+  scene: THREE.Group;
+  clips: THREE.AnimationClip[];
+  locomotionProfile?: LocomotionProfile;
+  /** Detach on 'leave'. GPU resources belong to the shared base, never a clone. */
+  dispose(): void;
+}
+
+export interface LoadPlayerCharacterOptions {
+  /** The visiting player's VRM (`user.avatarUrl` from the embed identity). Fallback lane only. */
+  avatarUrl?: string | null;
+  /** Asset base. Default "./assets/". */
+  base?: string;
+  /** Manifest override. Default `${base}meshy-character.json`. */
+  manifestUrl?: string;
+  /** Passed through to the Meshy loader — the quality kit's decoder-wired loader
+   *  and per-tier model rung ladder (`$genex-threejs-adaptive-quality`). */
+  meshy?: LoadMeshyCharacterOptions;
+}
+
+/**
+ * Does this game have a generated character? A dev server answers HTTP 200 with
+ * `index.html` for ANY unknown path, so `res.ok` is not evidence — the JSON
+ * parse plus the manifest's own identity fields are. False is the quiet,
+ * expected answer for a game that has not generated its character yet.
+ *
+ * Exported for tests: this probe is the whole routing decision.
+ */
+export async function probeGeneratedCharacter(url: string): Promise<boolean> {
+  try {
+    const response = await fetch(url, { cache: "no-store" });
+    if (!response.ok) return false;
+    const manifest = (await response.json()) as { schema?: number; rig?: string } | null;
+    return manifest?.schema === 1 && manifest.rig === "meshy-biped";
+  } catch {
+    return false; // absent, or the dev server's index.html — same meaning here
+  }
+}
+
+// One PARSED base per manifest URL — the clone source for remote players, so N
+// remotes cost ~1 character of GPU memory instead of N (the same trade the VRM
+// lane's loadVrmCloneBase makes). Never animated; clones carry their own mixer.
+const generatedBaseCache = new Map<string, Promise<MeshyCharacter>>();
+// Retargeted fallback clips per (avatar URL + asset base) — retargeting is per
+// humanoid rig, and every clone of one URL shares one base rig.
+const fallbackClipsCache = new Map<string, Promise<THREE.AnimationClip[]>>();
+
+function generatedBase(url: string, options?: LoadMeshyCharacterOptions): Promise<MeshyCharacter> {
+  let cached = generatedBaseCache.get(url);
+  if (!cached) {
+    cached = loadMeshyCharacter(url, options);
+    cached.catch(() => generatedBaseCache.delete(url)); // failures retry next call
+    generatedBaseCache.set(url, cached);
+  }
+  return cached;
+}
+
+/**
+ * The LOCAL player's body. Wire it once at boot and never touch it again:
+ *
+ * ```ts
+ * const player = await loadPlayerCharacter({ avatarUrl: user.avatarUrl });
+ * const fit = capsuleFromModel(player.scene);
+ * character.root.add(player.scene);
+ * player.scene.position.y = fit.modelOffsetY;
+ * const anims = new CharacterAnimations(player.scene, player.clips, {
+ *   locomotionProfile: player.locomotionProfile,
+ * });
+ * // per render frame: anims.update(character, delta); player.update(delta);
+ * ```
+ */
+export async function loadPlayerCharacter(
+  options: LoadPlayerCharacterOptions = {},
+): Promise<PlayerCharacter> {
+  const base = options.base ?? "./assets/";
+  const manifestUrl = options.manifestUrl ?? `${base}meshy-character.json`;
+  const fallbackUrl = `${base}avatar.vrm`;
+
+  if (await probeGeneratedCharacter(manifestUrl)) {
+    try {
+      const native = await loadMeshyCharacter(manifestUrl, options.meshy);
+      return {
+        kind: "generated",
+        scene: native.scene,
+        clips: native.clips,
+        locomotionProfile: native.locomotionProfile,
+        update: (delta) => native.update(delta),
+        dispose: () => native.dispose(),
+      };
+    } catch (error) {
+      // LOUD: this game HAS a character and it failed — a dead R2 URL or a rig
+      // mismatch, not the ordinary "no character yet" path above.
+      console.warn(
+        "[player-character] the generated character failed to load — falling back to the avatar",
+        error,
+      );
+    }
+  }
+
+  const { scene, vrm } = await loadVrm(options.avatarUrl || fallbackUrl).catch(() =>
+    loadVrm(fallbackUrl),
+  );
+  const clips = await loadCharacterClips(vrm, { base });
+  return {
+    kind: "avatar",
+    scene,
+    clips,
+    update: (delta) => vrm.update(delta),
+    dispose: () => VRMUtils.deepDispose(scene),
+  };
+}
+
+/**
+ * A REMOTE player's body. In a game with a generated character EVERY player
+ * 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. Without a generated character each remote keeps
+ * their own `avatarUrl`, which is the right look for a game with no themed cast.
+ *
+ * Visual only: no physics body, no controller, no per-frame update. Clones share
+ * the base's geometry/materials/textures, so `dispose()` detaches — it never
+ * disposes GPU resources the base and every other clone still use.
+ */
+export async function loadRemotePlayerCharacter(
+  options: LoadPlayerCharacterOptions = {},
+): Promise<RemotePlayerCharacter> {
+  const base = options.base ?? "./assets/";
+  const manifestUrl = options.manifestUrl ?? `${base}meshy-character.json`;
+  const fallbackUrl = `${base}avatar.vrm`;
+
+  if (await probeGeneratedCharacter(manifestUrl)) {
+    try {
+      const shared = await generatedBase(manifestUrl, options.meshy);
+      const scene = SkeletonUtils.clone(shared.scene) as THREE.Group;
+      return {
+        kind: "generated",
+        scene,
+        clips: shared.clips,
+        locomotionProfile: shared.locomotionProfile,
+        dispose: () => scene.removeFromParent(),
+      };
+    } catch (error) {
+      console.warn(
+        "[player-character] the generated character failed to load for a remote player — falling back to their avatar",
+        error,
+      );
+    }
+  }
+
+  const requested = options.avatarUrl || fallbackUrl;
+  const url = await loadVrmCloneBase(requested).then(
+    () => requested,
+    () => fallbackUrl,
+  );
+  const shared = await loadVrmCloneBase(url);
+  const clipsKey = `${url}${base}`;
+  let clips = fallbackClipsCache.get(clipsKey);
+  if (!clips) {
+    clips = loadCharacterClips(shared.vrm, { base });
+    clips.catch(() => fallbackClipsCache.delete(clipsKey));
+    fallbackClipsCache.set(clipsKey, clips);
+  }
+  const scene = SkeletonUtils.clone(shared.scene) as THREE.Group;
+  return { kind: "avatar", scene, clips: await clips, dispose: () => scene.removeFromParent() };
+}

package/templates/skills/genex-ai-character/SKILL.md

@@ -1,16 +1,39 @@
 ---
 name: genex-ai-character
-description: Generate a controller-ready Meshy humanoid with Genex, search the committed Meshy animation catalog by gameplay intent, add exact same-rig actions, and install the shared physics controller's Meshy-native adapter. Use for the game's themed character — the default whenever the protagonist is visible — or for motion not covered by the VRM + UAL lane.
+description: Generate a controller-ready Meshy humanoid with Genex, search the committed Meshy animation catalog by gameplay intent, add exact same-rig actions, and install the shared physics controller's Meshy-native adapter. Use for the game's own character — the player's body in every game where a human body appears on screen — and for motion the bundled UAL library doesn't cover.
 ---
 
 # Genex AI Character
 
-A themed Meshy character is the DEFAULT for any game whose protagonist is
-visible (third-person, or first-person with co-op/remote players); the
-VRM + UAL controller is the instant placeholder while it builds, and the
-final character only for games with no themed protagonist. Both lanes use
-the same ECCTRL-derived Rapier controller, camera, inputs, crossfades,
-transition rules, and multiplayer authority contract.
+**The game's own generated character IS the player's body.** Not the platform's
+profile avatar — that is the fallback. The rule applies wherever a human body
+appears on screen: third-person obviously, and first-person too, the moment
+co-op or versus remotes, a look-down body, a shadow, a death or spectator
+camera, or a menu portrait shows one. "The camera is in the head" is not an
+exemption; **"no human body ever appears in this game" is.** A game whose
+player is genuinely not a person — a car, a ship, an RTS cursor, a puzzle
+board — generates that object with `npx genex model` instead.
+
+**Start it EARLY** — enqueue the character right after the design interview,
+alongside the Stage-1 HUD concept, not as an afterthought once the world is
+built. Its concept candidates ride the same review beat as the HUD concept, and
+firing at minute 0 means it lands around the v0 preview instead of long after
+it.
+
+Until it lands, the player's body is the profile VRM avatar. That is a fallback
+in two shapes and both are spoken aloud: a **temporary** body while the
+character renders (say so in one plain line — the avatar is fully textured and
+animated, so nothing on screen will look unfinished enough to remind you), or
+the **stand-in** when generation genuinely could not happen (out of credits,
+failed, email unverified) — then record `Player character: VRM — <reason>` in
+DESIGN.md. Never let it become the game's character by default.
+
+Both lanes use the same ECCTRL-derived Rapier controller, camera, inputs,
+crossfades, transition rules, and multiplayer authority contract — and the
+same one-call boot path (`loadPlayerCharacter`, in
+`$genex-threejs-character-controller`), so when the character lands mid-build,
+`npx genex controller character --character <id>` is the whole switch. There is
+no code to rewrite, which is exactly why there is no excuse to skip it.
 
 **Two lanes, two approval shapes:**
 
@@ -231,4 +254,27 @@ durations, nominal speeds, trajectories, and gameplay requirements.
 For multiplayer, only the owning client advances the dynamic body and publishes
 its pose plus compact animation state. Remote characters are visual-only: they
 interpolate the owner's transform and replay the matching clip progress. Never
-run a motion driver or a second physics controller for a remote player.
+run a motion driver or a second physics controller for a remote player. In a
+game with a generated character, every remote wears it — one
+`loadRemotePlayerCharacter` call, one shared parsed base, N cheap clones.
+
+## Troubleshooting
+
+- **"Not authorized"** — run `npx genex init` first (in the project — it resolves this project's own CLI) (it writes your `GENEX_TOKEN`).
+- **"Out of credits" (`insufficient_credits`)** — the account has no credits left for
+  this character stage. Tell the user the facts the CLI printed: their balance, this
+  stage's cost, and when their credits refill. Then keep the player on the profile
+  VRM avatar (the fallback lane — no code change, it is already what the game
+  loads), tell them in one plain line that the game is wearing the platform avatar
+  because the character couldn't be generated, record
+  `Player character: VRM — out of credits` in DESIGN.md, and mark the spot with
+  `// TODO(genex): regenerate when credits refill`. Do not stop the session over
+  this, and do not hand-build a stand-in humanoid.
+- **"Email not verified" (`email_verification_required`)** — generation credits
+  unlock after the account's email is verified. Give the user the verify link the
+  CLI printed, wait for them to confirm, then re-run the command.
+- **The character is stuck mid-lane** — each stage is a separate generation. `npx
+  genex wait --all` prints one line per job; a failed `preview` or `finalize` is
+  re-run from the id of the stage before it, never from the beginning.
+- **The rig or a pose is bad** — reject and regenerate. Never repair limbs at
+  runtime; validation never rewrites limb animation.

package/templates/skills/genex-ai-image/SKILL.md

@@ -213,7 +213,11 @@ See `$genex-threejs-multiplayer` for the `shared` channel rules and the room API
   still re-renders and alpha is destroyed either way: after any masked edit,
   re-run `--clean`/re-extraction downstream. A targeting scope, not a pixel
   freeze.
-- `--clean <url>` — ML background removal of THAT image only (prompt recorded, unused).
+- `--clean <url>` — ML background removal of THAT image only (prompt recorded,
+  unused). **For an image that HAS a background.** Running it over a
+  `--transparent` result re-keys edges that were already correct and can spray
+  colour speckle across the rim and into the art — `ui trim`/`extract`/`audit`
+  refuse that output, and nothing repairs it but going back to the original.
 - `--upscale <url>` — 2x utility upscale of THAT image (prompt recorded,
   unused; ~2-credit class). Use before printing/large billboards, not by
   default.

package/templates/skills/genex-ai-menu/SKILL.md

@@ -373,12 +373,20 @@ not):
 - **Logotype (default yes):**
   `npx genex image "the word 'EMBERFALL' as an ornate engraved game logo, <style brief>" --transparent`
   — the wordmark alone on a transparent background, in the brief's display
-  register, no extra text or scenery. Clean with `--bg-mode glyph` if letter
-  counters get eaten, trim with `npx genex ui trim`. Then VERIFY it is
-  actually transparent — view the trimmed PNG over a bright test background;
-  background removal sometimes leaves an opaque disc or plate behind the
-  mark, and that plate ships as a hole punched in your key art. If any
-  background remains, re-run the clean. Short names (one or two
+  register, no extra text or scenery. Then trim with `npx genex ui trim`.
+  **`--transparent` already returns a finished cutout — a `--clean` pass is a
+  REPAIR for a defect you can see, never routine polish.** Re-clean ONLY if
+  the letter counters came out filled: `--bg-mode glyph` for hard flat
+  shapes, `--bg-mode matte` for soft metallic, chromed, or glowing edges
+  (most ornate wordmarks are soft edges — `glyph` is the wrong cutter for
+  them). Then VERIFY over a bright test background, looking for BOTH
+  failures: **(1)** an opaque disc or plate behind the mark — that plate
+  ships as a hole punched in your key art; **(2)** coloured speckle or a
+  rainbow rim along the letter edges — that means the clean pass DAMAGED the
+  art, so go back to the `--transparent` original and ship that. Running a
+  background remover over an image that was already transparent re-keys every
+  edge it should have left alone; `ui trim`/`extract`/`audit` now refuse that
+  output outright, and nothing downstream repairs it. Short names (one or two
   words) come out best. Wire it as the menu title AND the loader mark; the
   DOM keeps an accessible text fallback (`aria-label` or visually-hidden
   text).

package/templates/skills/genex-ai-skybox/SKILL.md

@@ -23,12 +23,25 @@ towers, or any object painted into the sky render at infinite distance: they
 never get closer as the player moves, they sit at the wrong parallax against
 the real 3D world, and they read as broken the moment the camera strafes.
 Structures belong in the scene as geometry (`npx genex model`); the sky
-carries atmosphere — light, weather, clouds, haze, stars. The CLI enforces
-this: every skybox prompt gets an environment-only suffix appended (you'll
-see `↳ environment-only guard applied` and the full final prompt is stored
-with the generation). If you genuinely need content baked into the sky —
-e.g. a space station panorama for a scene with no world geometry — pass
-`--raw` to send your prompt exactly as written.
+carries atmosphere — light, weather, clouds, haze, stars.
+
+**Writing "no cathedral" does not rescue a prompt that also says "cathedral".**
+Image models are steered by the nouns they ARE given; a ban loses to any
+positive mention of the same thing in the same prompt. A real pilot asked for
+a *"cinematic dark anime gothic atmosphere, ruined cathedral courtyard mood,
+**no buildings or structures**"* — and got a full gothic cathedral with a
+courtyard balustrade and a baked ground plane. Five negations in that prompt,
+zero effect. So never name a structure in a skybox prompt **even to exclude
+it**: describe only light, colour, cloud, weather and time of day.
+
+The CLI enforces this both ways. It appends a closed-positive environment
+clause to every prompt (you'll see `↳ environment-only guard applied`; the
+full final prompt is stored with the generation), and it **refuses outright,
+before spending any credits**, when the prompt itself names a structure or
+object. Landforms are fine — "golden hour over misty mountains", "a distant
+sea horizon", "towering cumulonimbus" all pass. If you genuinely need content
+baked into the sky — e.g. a space station panorama for a scene with no world
+geometry — pass `--raw` to send your prompt exactly as written.
 
 ## Run
 

package/templates/skills/genex-game-director/SKILL.md

@@ -318,17 +318,35 @@ way this skill is worn by the main agent: you stay the director.
   holding the only free slot"). The table is accountability, not ceremony —
   inline can be the right call.
 
-## 7. The game's character (Meshy) — themed by default
-
-**A themed character is the DEFAULT for any game whose protagonist is
-VISIBLE** — third-person, or first-person with co-op/remote players who see
-each other. Put its row in the Assets table up front and install the
-VRM + UAL controller (`npx genex controller character`) as the instant
-placeholder. The VRM stays the FINAL character only for games with no
-themed protagonist to sell (a generic exploration toy, a faceless solo
-first-person game — say which in one line). A capsule or hand-built
-primitive standing in for a person is never a shipped state, for the local
-player or a remote one.
+## 7. The game's character (Meshy) — the player's body
+
+**The game's own generated character IS the player's body**, wherever a
+human body appears on screen. Third-person obviously; first-person too, the
+moment remotes, a look-down body, a shadow, a death or spectator camera, or
+a menu portrait shows one. "The camera is in the head" is not an exemption —
+**"no human body ever appears in this game" is**, and a game whose player is
+genuinely not a person (a car, a ship, an RTS cursor, a board) generates
+that object with `npx genex model` instead.
+
+Put its row in the Assets table up front and **enqueue it with your first
+art actions** — its concepts ride the same review beat as the Stage-1 HUD
+concept, so firing at minute 0 lands it around the v0 preview instead of
+after it. `npx genex controller character` installs the controller and the
+fallback body in one command; the boot path is written once and never
+rewritten (`loadPlayerCharacter` — see
+`$genex-threejs-character-controller`), so when the character lands,
+`npx genex controller character --character <id>` is the entire switch.
+
+The profile VRM avatar is the FALLBACK, in two shapes and both spoken
+aloud: a temporary body while the character renders (say so plainly — it's
+a fully textured animated humanoid, so nothing on screen will look
+unfinished enough to remind you), or the stand-in when generation genuinely
+could not happen (out of credits, failed, unverified), recorded in DESIGN.md
+as `Player character: VRM — <reason>`. A capsule or hand-built primitive
+standing in for a person is never a shipped state, for the local player or a
+remote one. In a game with a generated character, every remote wears it —
+a mixed roster of one themed hero plus stock avatars is the same incoherence
+as capsule-and-cone remotes.
 
 **The default lane has ONE user stop, and it rides the concept review.**
 When the user names a visual reference, inspect references before writing

package/templates/skills/genex-game-director/references/routing-map.md

@@ -20,9 +20,9 @@ Three.js release or branch, and do not blindly copy demo architecture.
 | Work needed | Load |
 | --- | --- |
 | shot composition, chase/side/orbit rigs, camera handoffs, projection ownership, pointer look, mouse-aimed action (shooter, FPS/first-person, sniper, turret, crosshair/reticle), mouse-look, hand-rolled steering/pan/look input signs (screen-direction contract), floating origins | `$genex-threejs-camera-direction` |
-| on-foot player movement: walk/run/jump/crouch, third-person character, slopes, stairs, moving platforms, personal VRM animation, directional locomotion, transitions, action motion | `$genex-threejs-character-controller` |
-| the game's themed character — the DEFAULT whenever the protagonist is visible (third-person, or first-person with co-op/remote players); one user stop riding the concept review, owner-ratified auto-pick on silence (director §7) — or Meshy animation coverage beyond UAL: reference-informed A-pose concepts, exact action IDs, same-rig adapter | `$genex-ai-character` + `$genex-threejs-character-controller` |
-| remote player bodies in multiplayer — NEVER hand-built primitives: the themed character model in themed games, the player's `p.avatarUrl` VRM otherwise | `$genex-threejs-multiplayer` + `$genex-threejs-character-controller` |
+| on-foot player movement: walk/run/jump/crouch, third-person character, slopes, stairs, moving platforms, the player's body loader, directional locomotion, transitions, action motion | `$genex-threejs-character-controller` |
+| the game's own generated character — the player's BODY wherever a human body appears on screen (first-person included; the exemption is "no human body ever appears", not "the camera is in the head"), enqueued with the first art actions; one user stop riding the concept review, owner-ratified auto-pick on silence (director §7) — or Meshy animation coverage beyond UAL: reference-informed A-pose concepts, exact action IDs, same-rig adapter | `$genex-ai-character` + `$genex-threejs-character-controller` |
+| remote player bodies in multiplayer — NEVER hand-built primitives: the game's generated character when it has one (everyone wears it), the player's `p.avatarUrl` VRM only when it doesn't | `$genex-threejs-multiplayer` + `$genex-threejs-character-controller` |
 | the game has enemies, NPCs, or creatures — **load whenever an enemy roster exists**: rigged bipeds via `npx genex creature`, static + procedural motion for other body shapes, plus the mechanical floor every enemy owes (collider, verified facing, hit reaction, death moment) | `$genex-threejs-creatures` |
 | the player drives or flies something: cars, drones, vehicle physics, gearbox, enter/exit between character and vehicle | `$genex-threejs-vehicle-controllers` |
 | playable on phones: touch/mobile input for any game — joystick, virtual buttons, drag zones, per-genre touch recipes, rotate-device overlay — wired by default for every NEW game when a recipe fits (skip with a one-line reason) | `$genex-threejs-touch-controls` |