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

package/README.md

@@ -183,7 +183,10 @@ already-installed actions are not charged again. The controller command writes
 `public/assets/meshy-character.json`, whose permanent R2 URLs point at the
 current rigged model and compact same-signature animation GLBs. Re-run it after
 adding actions to refresh the manifest without overwriting existing controller
-source. The default `genex controller character` behavior remains VRM + UAL.
+source. The game's own generated character is the player's body wherever a human
+body appears on screen; the profile VRM avatar is the fallback, and the vendored
+`character/player-character.ts` resolves both behind one call, so installing the
+manifest needs no code change in the game.
 
 ## Install / run
 

package/dist/index.js

@@ -265,13 +265,16 @@ Your capabilities (all via \`npx genex \u2026\`): generate \`model\` \xB7 \`skyb
 9. Never draw a rectangular backing plate behind bars, digits, or icons \u2014 in sprites or CSS. Ornament lives on the widget's own silhouette; a truly needed shaped plate comes from \`npx genex ui plate\`.
 10. Fonts: the brief's display + body pair comes from the menu skill's genre table (or carries a one-line stated reason) and is LOADED for real in \`index.html\`.
 11. Never park ready work behind a question, and never stall on an unanswered one \u2014 decide, state the decision in chat, record it, keep building.
-12. Wire-in floors before any publish and before ending a session: sprite HUD wired (or the recorded CSS lane finished), menu video playing (or its recorded still fallback), logotype placed, fonts loaded, Escape pause, branded loader. Run \`npx genex wait\` on every generation you enqueued and wire what landed \u2014 never park landed assets.
-13. Characters: Meshy/Mixamo/VRM rigs rest facing +Z. Set yaw explicitly when placing a rig; never mirror a SkinnedMesh with negative scale. In any two-character scene, verify in a capture that they face each other, not the camera.
-14. Verify by looking: one smoke check per milestone, after that milestone's preview push, in local test mode (\`?genex_local_test=1\`) with a real gameplay screenshot. A claim without a capture is not verification.
+12. Wire-in floors before any publish and before ending a session: sprite HUD wired (or the recorded CSS lane finished), menu video playing (or its recorded still fallback), logotype placed, fonts loaded, Escape pause, branded loader, the player wearing the game's own generated character (or DESIGN.md recording why it isn't). Run \`npx genex wait\` on every generation you enqueued and wire what landed \u2014 never park landed assets.
+13. The player's body is the game's own generated character (\`npx genex character "<look>"\` \u2192 \`npx genex controller character --character <id>\`), enqueued with your first art actions, not after them. It applies wherever a human body appears on screen \u2014 first-person included, the moment remotes, a look-down body, a shadow, or a menu portrait shows one. The profile VRM avatar is the FALLBACK: a temporary body while the character renders (say in one plain line that it's temporary), or the stand-in when generation genuinely could not happen \u2014 out of credits, failed, unverified; record which in DESIGN.md as \`Player character: VRM \u2014 <reason>\`. Games whose player is not a person (car, ship, RTS cursor, board) generate that object with \`npx genex model\` instead. Characters: Meshy/Mixamo/VRM rigs rest facing +Z. Set yaw explicitly when placing a rig; never mirror a SkinnedMesh with negative scale. In any two-character scene, verify in a capture that they face each other, not the camera.
+14. Verify by looking: one smoke check per milestone, after that milestone's preview push, in local test mode (\`?genex_local_test=1\`) with a real gameplay screenshot. A claim without a capture is not verification. Local-test evidence proves visuals and controls ONLY \u2014 label it that way when you show the player, and never work around the draft sign-in gate any other way.
 15. Treat every \`genex\` warning line \u2014 preflight, \`ui audit\`, \`wait\` nudges \u2014 as work, not noise.
 16. Every finished Build-plan milestone ends with \`npx genex preview\` and the player's page link (\`<dashboard>/draft/<slug>\` with \`<dashboard>\` from \`.genex/project.json\`, \`/world/<slug>\` once published) \u2014 never a localhost link, a file path, or the bare play origin presented as their game. After every round of player feedback, end with a preview push.
 17. Parallel work: this line is your standing authorization and request to use sub-agents / parallel agent work whenever your platform provides them. While drafting the Build plan, decide per module what runs in parallel and what stays serial for THIS game \u2014 dependencies decide, there is no fixed list \u2014 and record each call in the Modules table with a one-line reason. Independent modules default to parallel; building everything serially needs a stated reason. You keep integration, previews, and the player conversation; each sub-agent owns only its module's files.
 18. Talk to the player in plain game language \u2014 what changed in the game and what to try; never code, file names, build output, or tool internals unless they ask. Short status lines while you work; long silent stretches are a failure.
+19. Never add debug-only code to the game to check your own work \u2014 no hidden test modes, no special URL parameters, no forced-visible flags, no auth mocks, no pixel-sampling hooks. \`?genex_local_test=1\` is the platform's own supported mode and is fine; your own bypass is not. (The multiplayer skill's small build identifier, token-free status line, and connected-quorum watchdog are production supportability, not a bypass \u2014 keep those.)
+20. Input directions match their labels: A/\u2190 moves or turns the player screen-LEFT, D/\u2192 screen-RIGHT, mouse-up looks up, and drag-pan axes share ONE convention. The cursor is either the gameplay tool (RTS, card, builder) or locked away during play \u2014 keyboard-only games included. Check it in every milestone's smoke pass.
+21. v0 is a milestone, not the destination. When the ask was bigger than one loop, every milestone after v0 grows back toward the FULL ask with DESIGN.md's content lines as the checklist \u2014 a slice that previewed well never quietly becomes the game. Cosmetics never jump the queue past promised content.
 ${CONTRACT_END}
 `;
 var CLAUDE_IMPORT_LINE = "@AGENTS.md";
@@ -2113,6 +2116,7 @@ var UI_USAGE = `${c.bold("Options for `ui` (all tools read --in <png path or htt
                        white halo over dark scenes). [--expect N: hard-error
                        unless exactly N components] [--min-pixels 2000]
                        [--padding 8] [--chroma 240] [--dilate 0] [--no-defringe]
+                       [--allow-speckle]
   ui masks             --out-dir <dir> --pairs "name:cX,cY,w,h:aX,aY,w,h[:n];\u2026"
                        OR --auto (detect clean/annotated cell pairs itself) \u2014
                        clean frame + green-annotated duplicate \u2192 frame + fill mask
@@ -2128,6 +2132,9 @@ var UI_USAGE = `${c.bold("Options for `ui` (all tools read --in <png path or htt
                        [--min-frac 0.004] [--out <json>] [--crop <png>]
   ui trim              [--out <png>] \u2014 crop to the alpha bbox (default: overwrite
                        --in), print real dims + refresh the .bbox.json sidecar.
+                       Hard-refuses a DAMAGED cutout (isolated colour speckle on
+                       the soft rim \u2014 what a background-removal pass does to an
+                       image that was already transparent). [--allow-speckle]
   ui seams             measure a tiling texture's wrap seam (opposite edges vs
                        interior detail) \u2192 ratio + verdict as JSON; nonzero exit on
                        a visible seam. [--seam-tolerance 3]
@@ -2139,7 +2146,9 @@ var UI_USAGE = `${c.bold("Options for `ui` (all tools read --in <png path or htt
   ui audit             mechanical HUD-wiring scan (no --in): mask\u2194frame pairing
                        mismatches (recorded crops disagree \u2014 PROVABLE, exit 1),
                        white-painted meter troughs (baked sheet-white inside a
-                       fill channel \u2014 PROVABLE, exit 1), loosened-check stamps,
+                       fill channel \u2014 PROVABLE, exit 1), damaged cutouts (colour
+                       speckle on a wired sprite's rim \u2014 PROVABLE, exit 1),
+                       loosened-check stamps,
                        extracted-but-never-wired sprites, generated-but-
                        unreferenced masks, naive JS %-width fills, phones-
                        preload-video heuristic. Everything but the two provable
@@ -2422,6 +2431,15 @@ async function uiExtract(opts, log) {
     if (inputMode === "chroma" && opts.defringe !== false) {
       defringed = defringeAgainstMatte(out) > 0;
     }
+    const speckle = rimSpeckleRatio(out);
+    if (speckle && speckle.ratio > SPECKLE_MAX_RATIO && !opts.allowSpeckle) {
+      fail(speckleRefusal(name, speckle.ratio), {
+        input,
+        sprite: name,
+        speckleRatio: Number(speckle.ratio.toFixed(4)),
+        rimPixels: speckle.sampled
+      });
+    }
     const outPath = path11.join(outDir, `${name}.png`);
     await writePng(outPath, out);
     const sidecar = {
@@ -3180,13 +3198,30 @@ async function uiTrim(opts, log) {
     h: bbox.maxY - bbox.minY + 1
   };
   const trimmed = cropPng(png, cropBox);
+  const speckle = rimSpeckleRatio(trimmed);
+  if (speckle && speckle.ratio > SPECKLE_MAX_RATIO && !opts.allowSpeckle) {
+    fail(speckleRefusal("this image", speckle.ratio), {
+      input,
+      speckleRatio: Number(speckle.ratio.toFixed(4)),
+      rimPixels: speckle.sampled
+    });
+  }
   await writePng(outPath, trimmed);
   const sidecar = computeBBoxes(trimmed);
+  const speckleAllowed = !!(speckle && speckle.ratio > SPECKLE_MAX_RATIO);
   const sidecarPath = outPath.replace(/\.png$/i, "") + ".bbox.json";
-  await fs11.writeFile(sidecarPath, JSON.stringify(sidecar, null, 2));
+  await fs11.writeFile(
+    sidecarPath,
+    JSON.stringify(speckleAllowed ? { ...sidecar, speckleAllowed: true } : sidecar, null, 2)
+  );
   log.success(
     `Trimmed ${png.width}x${png.height} \u2192 ${trimmed.width}x${trimmed.height} (${outPath}).`
   );
+  if (speckleAllowed) {
+    log.warn(
+      "Shipped with --allow-speckle: this cutout is damaged and the override is stamped in its sidecar. Eyeball it over a bright background before it reaches the player."
+    );
+  }
   process.stdout.write(
     `${JSON.stringify({
       out: outPath,
@@ -3195,7 +3230,9 @@ async function uiTrim(opts, log) {
       aspectRatio: sidecar.aspectRatio,
       outerBBox: sidecar.outerBBox,
       innerBBox: sidecar.innerBBox,
-      sidecar: sidecarPath
+      sidecar: sidecarPath,
+      ...speckle ? { speckleRatio: Number(speckle.ratio.toFixed(4)) } : {},
+      ...speckleAllowed ? { speckleAllowed: true } : {}
     })}
 `
   );
@@ -3292,6 +3329,51 @@ async function uiPlate(opts, log) {
 `
   );
 }
+var SPECKLE_RIM_ALPHA_MIN = 16;
+var SPECKLE_RIM_ALPHA_MAX = 220;
+var SPECKLE_CHROMA_EXCESS = 60;
+var SPECKLE_MIN_SAMPLE = 200;
+var SPECKLE_MAX_RATIO = 0.02;
+function rimSpeckleRatio(png) {
+  const { width: W, height: H, data } = png;
+  if (W < 3 || H < 3) return null;
+  const chroma = new Uint8Array(W * H);
+  for (let i = 0; i < W * H; i++) {
+    const o = i * 4;
+    const r = data[o];
+    const g = data[o + 1];
+    const b = data[o + 2];
+    chroma[i] = Math.max(r, g, b) - Math.min(r, g, b);
+  }
+  const neighbourhood = [];
+  let sampled = 0;
+  let speckled = 0;
+  for (let y = 1; y < H - 1; y++) {
+    for (let x = 1; x < W - 1; x++) {
+      const i = y * W + x;
+      const a = data[i * 4 + 3];
+      if (a <= SPECKLE_RIM_ALPHA_MIN || a >= SPECKLE_RIM_ALPHA_MAX) continue;
+      sampled++;
+      neighbourhood.length = 0;
+      for (let dy = -1; dy <= 1; dy++) {
+        for (let dx = -1; dx <= 1; dx++) neighbourhood.push(chroma[(y + dy) * W + (x + dx)]);
+      }
+      neighbourhood.sort((p, q) => p - q);
+      if (chroma[i] - neighbourhood[4] > SPECKLE_CHROMA_EXCESS) speckled++;
+    }
+  }
+  if (sampled < SPECKLE_MIN_SAMPLE) return null;
+  return { ratio: speckled / sampled, sampled };
+}
+function speckleRefusal(label, ratio) {
+  return [
+    `Damaged cutout \u2014 ${(ratio * 100).toFixed(1)}% of ${label}'s soft edge is isolated colour speckle (want <= ${(SPECKLE_MAX_RATIO * 100).toFixed(0)}%).`,
+    "A background-removal pass over an image that was ALREADY transparent re-keys every edge and sprays colour noise along it. Trimming or defringing cannot fix this.",
+    "  -> From `genex image --clean`? Ship the `--transparent` original instead.",
+    "  -> Source really had a background? Re-clean with `--bg-mode matte` (soft edges).",
+    "  Override (stamped in the output): --allow-speckle"
+  ].join("\n");
+}
 var DEFRINGE_BAND_PX = 2;
 function defringeAgainstMatte(png, matte = { r: 255, g: 255, b: 255 }) {
   const { width: W, height: H, data } = png;
@@ -3374,7 +3456,8 @@ function defringeAgainstMatte(png, matte = { r: 255, g: 255, b: 255 }) {
 }
 var HARD_AUDIT_KINDS = /* @__PURE__ */ new Set([
   "mask-frame-mismatch",
-  "white-trough"
+  "white-trough",
+  "cutout-speckle"
 ]);
 var TROUGH_OPAQUE_MIN_ALPHA = 200;
 var TROUGH_WHITE_MIN = 235;
@@ -3535,6 +3618,22 @@ async function collectUiAuditFindings(assetDir, srcDir, cwd = process.cwd()) {
       }
     }
   }
+  for (const [base, p] of pngByBase) {
+    if (/-mask\.png$/.test(base)) continue;
+    if (!referenced(base)) continue;
+    let png;
+    try {
+      png = PNG2.sync.read(await fs11.readFile(p));
+    } catch {
+      continue;
+    }
+    const speckle = rimSpeckleRatio(png);
+    if (!speckle || speckle.ratio <= SPECKLE_MAX_RATIO) continue;
+    findings.push({
+      kind: "cutout-speckle",
+      message: `${base}: ${(speckle.ratio * 100).toFixed(1)}% of the soft edge is isolated colour speckle (want <= ${(SPECKLE_MAX_RATIO * 100).toFixed(0)}%) \u2014 a background-removal pass re-keyed edges that were already transparent and sprayed colour noise along them. Nothing downstream repairs it: ship the \`--transparent\` original, or re-clean the true source with \`--bg-mode matte\`. Do not ship this sprite.`
+    });
+  }
   const loosenedNames = [...metaByName.entries()].filter(([, meta]) => meta.loosened).map(([name]) => name);
   if (loosenedNames.length > 0) {
     findings.push({
@@ -3866,13 +3965,109 @@ async function inlineLocalImage(filePath, flag) {
   const mime = IMAGE_MIME_BY_EXT[path13.extname(filePath).toLowerCase()] ?? "image/png";
   return { ok: true, dataUri: `data:${mime};base64,${bytes.toString("base64")}` };
 }
-var SKYBOX_ENVIRONMENT_SUFFIX = ". Pure environment: sky, clouds, atmosphere, distant horizon haze. No buildings, no structures, no trees, no objects, no ground detail.";
+var SKYBOX_ENVIRONMENT_SUFFIX = ". The image contains ONLY sky: cloud, atmosphere, light, weather and distant haze at the horizon. Every structure, object, plant and ground surface is outside the frame.";
 var SKYBOX_PROMPT_MAX = 2e3;
+var SKYBOX_STRUCTURE_NOUNS = [
+  "building",
+  "buildings",
+  "house",
+  "houses",
+  "hut",
+  "huts",
+  "cabin",
+  "cabins",
+  "tower",
+  "towers",
+  "castle",
+  "castles",
+  "cathedral",
+  "cathedrals",
+  "church",
+  "churches",
+  "temple",
+  "temples",
+  "shrine",
+  "shrines",
+  "monastery",
+  "palace",
+  "fortress",
+  "citadel",
+  "ruin",
+  "ruins",
+  "city",
+  "cityscape",
+  "skyline",
+  "town",
+  "village",
+  "settlement",
+  "street",
+  "streets",
+  "road",
+  "roads",
+  "courtyard",
+  "plaza",
+  "bridge",
+  "bridges",
+  "wall",
+  "walls",
+  "gate",
+  "gates",
+  "fence",
+  "fences",
+  "pillar",
+  "pillars",
+  "column",
+  "columns",
+  "statue",
+  "statues",
+  "monument",
+  "obelisk",
+  "spire",
+  "spires",
+  "rooftop",
+  "rooftops",
+  "tree",
+  "trees",
+  "forest",
+  "jungle",
+  "ship",
+  "ships",
+  "boat",
+  "boats",
+  "car",
+  "cars",
+  "vehicle",
+  "vehicles",
+  "person",
+  "people",
+  "figure",
+  "figures",
+  "character",
+  "characters",
+  "creature",
+  "creatures",
+  "dragon",
+  "banner",
+  "banners",
+  "flag",
+  "flags",
+  "torch",
+  "torches",
+  "lamp",
+  "lamps"
+];
+var SKYBOX_NOUN_RE = new RegExp(`\\b(${SKYBOX_STRUCTURE_NOUNS.join("|")})\\b`, "gi");
+function skyboxStructureNouns(prompt) {
+  const found = /* @__PURE__ */ new Set();
+  for (const m of prompt.matchAll(SKYBOX_NOUN_RE)) found.add(m[1].toLowerCase());
+  return [...found];
+}
 function applySkyboxGuard(prompt, raw) {
-  if (raw) return { prompt, guarded: false };
+  if (raw) return { prompt, guarded: false, nouns: [] };
+  const nouns = skyboxStructureNouns(prompt);
   const guarded = `${prompt}${SKYBOX_ENVIRONMENT_SUFFIX}`;
-  if (guarded.length > SKYBOX_PROMPT_MAX) return { prompt, guarded: false };
-  return { prompt: guarded, guarded: true };
+  if (guarded.length > SKYBOX_PROMPT_MAX) return { prompt, guarded: false, nouns };
+  return { prompt: guarded, guarded: true, nouns };
 }
 function buildGenOptions(kind, opts) {
   const options = { ...opts.generationOptions };
@@ -3927,6 +4122,23 @@ async function runGenerate(kind, opts) {
     return;
   }
   const skyboxGuard = kind === "skybox" ? applySkyboxGuard(typedPrompt, opts.raw) : void 0;
+  if (skyboxGuard && skyboxGuard.nouns.length > 0) {
+    log.error(
+      `A skybox is sky only \u2014 this prompt names ${skyboxGuard.nouns.join(", ")}.`
+    );
+    log.plain(
+      [
+        "  Structures painted into a sky render at infinite distance: they never get closer",
+        "  as the player moves, and they read as broken the moment the camera strafes.",
+        `  ${c.cyan("\u2192")} Build them as scene geometry (${c.cyan("npx genex model")}); describe only light, colour,`,
+        "    cloud, weather and time of day here.",
+        `  ${c.cyan("\u2192")} Genuinely want it painted into the sky (a space-station panorama for a scene`,
+        `    with no world geometry)? Re-run with ${c.cyan("--raw")}.`
+      ].join("\n")
+    );
+    process.exitCode = 1;
+    return;
+  }
   let prompt = skyboxGuard?.prompt ?? typedPrompt;
   if (kind === "image" && opts.glass) {
     const conflict = opts.transparent ? "--transparent" : opts.removeBackground ? "--remove-bg" : opts.editUrl ? "--edit" : opts.cleanUrl ? "--clean" : opts.upscaleUrl ? "--upscale" : opts.noWait ? "--no-wait" : void 0;
@@ -4660,6 +4872,14 @@ async function printPipelineStatePreflight(log, cwd = process.cwd()) {
         );
       }
     }
+    if (!/player character:/i.test(design)) {
+      const hasCharacter = await fs14.access(path14.join(cwd, "public", "assets", "meshy-character.json")).then(() => true, () => false);
+      if (!hasCharacter && await loadsPlayerBody(cwd)) {
+        warnings.push(
+          `Player character is the stock avatar \u2014 no generated character is wired. The game's own generated character is the player's body wherever a human body appears on screen, first-person included (genex-ai-character). Generate it, or record "Player character: VRM \u2014 <reason>" in DESIGN.md (no human body in this game / out of credits / player declined).`
+        );
+      }
+    }
     for (const w of warnings) log.warn(w);
   } catch {
   }
@@ -4687,6 +4907,21 @@ async function hasHudLikeDom(cwd) {
   }
   return false;
 }
+async function loadsPlayerBody(cwd) {
+  const BODY_LOADERS = /\bloadPlayerCharacter\s*\(|\bloadVrm(?:Clone)?\s*\(/;
+  try {
+    const entries = await fs14.readdir(path14.join(cwd, "src"), { recursive: true });
+    for (const rel of entries) {
+      if (rel.includes("node_modules")) continue;
+      if (rel.split(path14.sep)[0] === "controllers" || rel.startsWith("controllers/")) continue;
+      if (!/\.(ts|tsx|js|jsx)$/.test(rel)) continue;
+      const text = await fs14.readFile(path14.join(cwd, "src", rel), "utf8").catch(() => "");
+      if (BODY_LOADERS.test(text)) return true;
+    }
+  } catch {
+  }
+  return false;
+}
 async function hasExtractionSidecars(cwd) {
   try {
     const entries = await fs14.readdir(path14.join(cwd, "public"), { recursive: true });
@@ -4727,6 +4962,17 @@ async function deployGame(ctx, opts, log) {
     log.error(`No index.html in ${rel} \u2014 a game needs one to serve. Nothing deployed.`);
     return false;
   }
+  const lfsPointers = files.filter(
+    (f) => f.bytes.length < 1024 && f.bytes.subarray(0, 64).toString("latin1").startsWith("version https://git-lfs.github.com/spec/v")
+  );
+  if (lfsPointers.length > 0) {
+    log.error(
+      `${lfsPointers.length} file${lfsPointers.length > 1 ? "s" : ""} in ${rel} ${lfsPointers.length > 1 ? "are" : "is"} an unresolved Git LFS pointer, not the real asset \u2014 the game would fail to load at runtime. Run \`git lfs pull\` and rebuild. Nothing deployed.`
+    );
+    for (const p of lfsPointers.slice(0, 8)) log.dim(`  ${p.relPath}`);
+    if (lfsPointers.length > 8) log.dim(`  \u2026and ${lfsPointers.length - 8} more`);
+    return false;
+  }
   printMobilePreflight(files, log);
   await printUiAuditPreflight(log);
   await printPipelineStatePreflight(log);
@@ -15361,9 +15607,14 @@ var CONTROLLER_FILE_SETS = {
       "character/animation-packs.ts",
       "character/motion-actions.ts",
       "character/meshy/meshy-loader.ts",
+      // The player's body, resolved once: this game's own generated character
+      // when it has one, the visiting player's avatar when it doesn't. ONE
+      // shape for both lanes, so a character that lands at hour 2 is a file
+      // drop and not a rewrite of the boot path written at hour 0.
+      "character/player-character.ts",
       "character/presets.ts",
       // VRM avatar support (three-vrm): load + retarget the UAL clips + auto-fit
-      // the capsule + optional foot IK. Owner's avatar replaces the old mannequin.
+      // the capsule + optional foot IK — the FALLBACK body's lane.
       "character/vrm/vrm-loader.ts",
       "character/vrm/vrm-retarget.ts",
       "character/vrm/capsule-fit.ts",
@@ -15372,22 +15623,27 @@ var CONTROLLER_FILE_SETS = {
       NOTICE
     ],
     // 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; 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/.
+    // installFallbackAvatar (the bundled CC0 default) — so it is NOT 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. It is only ever the FALLBACK body: the player
+    // is this game's own generated character whenever it has one.
+    // 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",
+    // ONE sketch, with or without --character. The lane is a runtime decision
+    // inside loadPlayerCharacter, never a code edit the agent has to remember
+    // to make once the generated character lands.
     sketch: [
       `const physics = await PhysicsWorld.create();`,
-      `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);`,
-      `addEventListener("pointerdown", () => anims.playOneShot("Punch_Jab")); // per frame: anims.update(character, dt); vrm.update(dt);`
+      `const { user } = await waitForPlayer(); // @genex-ai/embed-sdk`,
+      `const player = await loadPlayerCharacter({ avatarUrl: user.avatarUrl }); // this game's character, else the avatar fallback`,
+      `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(player.scene); player.scene.position.y = fit.modelOffsetY;`,
+      `const anims = new CharacterAnimations(player.scene, player.clips, { locomotionProfile: player.locomotionProfile });`,
+      `addEventListener("pointerdown", () => anims.playOneShot("Punch_Jab")); // per frame: anims.update(character, dt); player.update(dt);`
     ]
   },
   car: {
@@ -15546,8 +15802,7 @@ async function runController(opts) {
         return;
       }
     } else {
-      const token = opts.token !== void 0 ? opts.token : await readUserToken();
-      await installOwnerAvatar({ root, srcDir, apiUrl: getApiUrl(opts.apiUrl), token, log });
+      await installFallbackAvatar({ root, srcDir, log });
     }
     log.plain("");
   }
@@ -15566,16 +15821,18 @@ async function runController(opts) {
   log.plain(
     kind === "touch" ? `  ${stepOffset + 2}. Wiring sketch (create behind a touch check; read per frame):` : `  ${stepOffset + 2}. Wiring sketch (controllers update BEFORE the physics step):`
   );
-  const sketch = kind === "character" && opts.character ? [
-    `const physics = await PhysicsWorld.create();`,
-    `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); const anims = new CharacterAnimations(native.scene, native.clips, { locomotionProfile: native.locomotionProfile });`,
-    `physics.onBeforeStep(() => character.update(dt, input)); // Rapier owns movement; then anims.update(character, dt)`
-  ] : set.sketch;
-  for (const line of sketch) {
+  for (const line of set.sketch) {
     log.dim(`       ${line}`);
   }
+  if (kind === "character" && !await exists3(path17.join(root, ASSETS_DEST, "meshy-character.json"))) {
+    log.plain("");
+    log.plain(
+      `  ${stepOffset + 3}. This game has no generated character yet \u2014 ${c.cyan(
+        'npx genex character "<look>"'
+      )} makes the player's real body;`
+    );
+    log.plain("     the avatar above is only the fallback until it lands. No code change when it does.");
+  }
 }
 async function installMeshyCharacterManifest(args) {
   const response = await apiFetch(
@@ -15607,6 +15864,7 @@ async function installMeshyCharacterManifest(args) {
 `
   );
   args.log.dim(`  public/assets/meshy-character.json (${args.characterId}, current revision)`);
+  args.log.success("This game's generated character is now the player's body \u2014 picked up on the next reload, no code change needed.");
   const pack2 = manifest.controllerPack;
   if (typeof pack2?.key === "string" && typeof pack2.version === "number") {
     args.log.success(`Meshy controller pack ${pack2.key} v${pack2.version}`);
@@ -15736,36 +15994,12 @@ function assertCompleteMeshyControllerPack(manifest) {
     incompletePack(`${pack2.key} v${pack2.version} fingerprint does not match its action bindings.`);
   }
 }
-async function installOwnerAvatar(args) {
-  const { root, srcDir, apiUrl, token, log } = args;
+async function installFallbackAvatar(args) {
+  const { root, srcDir, log } = args;
   const dest = path17.join(root, ASSETS_DEST, "avatar.vrm");
   await fs17.mkdir(path17.dirname(dest), { recursive: true });
-  if (token) {
-    try {
-      const res = await apiFetch(`${apiUrl}/api/avatars/me`, {
-        headers: { Authorization: `Bearer ${token}` }
-      });
-      if (res.ok) {
-        const me = await res.json();
-        if (me.vrmUrl) {
-          const vrmRes = await fetch(me.vrmUrl);
-          if (vrmRes.ok) {
-            const buf = Buffer.from(await vrmRes.arrayBuffer());
-            await fs17.writeFile(dest, buf);
-            log.dim(`  public/assets/avatar.vrm (your avatar \u2014 ${(buf.length / 1e6).toFixed(1)} MB)`);
-            return;
-          }
-        }
-      }
-      log.dim("  couldn't fetch your avatar; using the bundled default.");
-    } catch {
-      log.dim("  avatar fetch failed (offline?); using the bundled default.");
-    }
-  }
   await fs17.copyFile(path17.join(srcDir, "assets", "default-avatar.vrm"), dest);
-  log.dim(
-    token ? "  public/assets/avatar.vrm (bundled default)" : "  public/assets/avatar.vrm (bundled default \u2014 sign in and re-run for your own)"
-  );
+  log.dim("  public/assets/avatar.vrm (fallback avatar \u2014 bundled CC0 default)");
 }
 async function exists3(p) {
   try {
@@ -16394,6 +16628,15 @@ import path18 from "path";
 
 // src/lib/motion/npz.ts
 import zlib from "zlib";
+function decodeUcs4(b) {
+  let out = "";
+  for (let i = 0; i + 4 <= b.length; i += 4) {
+    const cp = b.readUInt32LE(i);
+    if (cp === 0) break;
+    out += cp > 1114111 ? "\uFFFD" : String.fromCodePoint(cp);
+  }
+  return out;
+}
 function readNpy(b) {
   if (b.toString("latin1", 1, 6) !== "NUMPY") throw new Error("not an .npy member");
   const major = b[6];
@@ -16411,7 +16654,7 @@ function readNpy(b) {
   if (descr === "<f8") return { shape, descr, data: new Float64Array(data.buffer, data.byteOffset, data.length / 8) };
   if (descr === "<i8") return { shape, descr, data: new BigInt64Array(data.buffer, data.byteOffset, data.length / 8) };
   if (descr === "|b1") return { shape, descr, data: new Uint8Array(data.buffer, data.byteOffset, data.length) };
-  if (descr.startsWith("<U")) return { shape, descr, data: data.toString("utf16le").replace(/\0+$/, "") };
+  if (descr.startsWith("<U")) return { shape, descr, data: decodeUcs4(data) };
   if (descr === "|O") throw new Error(".npz member is a pickled object array \u2014 regenerate the take with a current ARDY");
   throw new Error(`unsupported .npy dtype ${descr}`);
 }
@@ -17986,9 +18229,11 @@ ${c.bold("Usage")}
                                      without a physics controller. "quality" = the
                                      adaptive-quality kit (device tier, runtime governor,
                                      per-tier asset rungs) every game wires at boot.
-                                     Character defaults to the player's VRM + UAL pack.
+                                     Character's player body is the game's own generated
+                                     character, with a VRM avatar as the fallback.
   genex controller character --character <id>
-                                     Install the Meshy-native controller variant.
+                                     Point the game at its generated character (writes the
+                                     manifest; no code change \u2014 the loader picks it up).
   genex controller anims <sel \u2026>     Install legacy VRM + UAL animation clips by tag/name
                                      into public/assets/anims/. --list shows the catalog;
                                      --reset forgets the previous selection first.
@@ -18000,7 +18245,9 @@ ${c.bold("Usage")}
 ${c.bold("Options for the generators (`model` `skybox` `sfx` `music` `voice` `texture` `image` `video`)")}
   --terrain            (texture) seamless tiling surface for terrain/ground.
   --raw                (skybox) send the prompt exactly as written \u2014 skip the
-                       appended environment-only guard.
+                       appended environment-only clause AND the refusal on
+                       prompts that name structures/objects (a sky is sky only;
+                       landforms and weather always pass).
   --duration <sec>     (sfx, video, music) target clip length in seconds
                        (music: 10-300, default 90 \u2014 a looping gameplay track).
   --transparent        (image) transparent background (alpha) \u2014 for decals/stickers.
@@ -18116,8 +18363,8 @@ ${c.bold("Options for `character` / `animations search`")}
                        controller slots, requirements, review status, and estimated cost.
 
 ${c.bold("Options for `controller character` / legacy `controller anims`")}
-  --character <id>     (character) install the owned Meshy character manifest and
-                       same-rig native loader instead of the player's VRM.
+  --character <id>     (character) install the owned Meshy character manifest \u2014 the
+                       game's own generated character becomes the player's body.
   --list [selectors]   (anims) show the bundled VRM + UAL tag/name catalog.
   --reset              (anims) forget the previous game-local UAL selection.
 
@@ -18303,6 +18550,9 @@ function parseArgs(argv) {
       case "--no-defringe":
         parsed.options.defringe = false;
         break;
+      case "--allow-speckle":
+        parsed.options.allowSpeckle = true;
+        break;
       case "--loop":
         parsed.options.loop = true;
         break;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@genex-ai/cli-demo",
-  "version": "0.88.0-dev.219",
+  "version": "0.91.0-dev.228",
   "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/controllers/NOTICE.md

@@ -46,11 +46,13 @@ license (SPDX: `CC0-1.0`). No attribution is required by the license; this
 notice is provided as a courtesy — supporting Quaternius on Patreon is a nice
 way to say thanks.
 
-## Default avatar — CC0 1.0 Universal
+## Fallback avatar — CC0 1.0 Universal
 
-The character controller plays as your VRM avatar. When you have not chosen one
-(or run offline), the bundled default `assets/default-avatar.vrm` is copied to
-`public/assets/avatar.vrm`. It is **Wizzir** from the **100 Avatars** project by
+The player's body is the game's own generated character; a VRM avatar is the
+fallback lane. `genex controller character` copies the bundled default
+`assets/default-avatar.vrm` to `public/assets/avatar.vrm`, which covers local
+dev and load failures when that lane runs. It is **Wizzir** from the
+**100 Avatars** project by
 **Polygonal Mind** (polygonalmind.com), dedicated to the public domain under
 CC0 1.0 Universal (SPDX: `CC0-1.0`). Attribution is a courtesy, not required.