@genex-ai/cli-demo 0.37.0 → 0.38.0

package/README.md

@@ -16,6 +16,7 @@ genex texture "<prompt>"   # generate a texture   → prints an asset URL
 genex image "<prompt>"     # generate an image    → prints an asset URL
 genex video "<prompt>"     # generate a video     → prints an asset URL
 genex controller <type>    # install a tuned character|car|drone controller → src/controllers/
+genex controller anims <sel…>  # download extra character animation clips (by tag or name) → public/assets/anims/
 ```
 
 > **Invoking it.** First-time setup runs via `npx @genex-ai/cli-demo@latest init`.

package/dist/index.js

@@ -11,6 +11,15 @@ import { fileURLToPath } from "url";
 var DEFAULT_AUTH_URL = "https://demo-web.glotech.world";
 var DEFAULT_API_URL = "https://demo-api.glotech.world";
 var DEFAULT_COLYSEUS_URL = "wss://demo-colyseus.glotech.world";
+var DEFAULT_ANIMS_BASE = "https://cdn.genex.technology/anims/ual1/v1/";
+var ANIMS_BASE_ENV = "GENEX_ANIMS_BASE";
+function getAnimsBase(override) {
+  const raw = override || process.env[ANIMS_BASE_ENV] || DEFAULT_ANIMS_BASE;
+  return raw.replace(/\/+$/, "") + "/";
+}
+function getAnimsCacheDir() {
+  return path.join(getGenexDir(), "cache", "anims");
+}
 var ENV_TOKEN_KEY = "GENEX_TOKEN";
 var AUTH_URL_ENV = "GENEX_AUTH_URL";
 var API_URL_ENV = "GENEX_API_URL";
@@ -1956,8 +1965,305 @@ function printHint(kind, files, log) {
 }
 
 // src/commands/controller.ts
+import fs12 from "fs/promises";
+import path13 from "path";
+
+// src/lib/anims.ts
 import fs11 from "fs/promises";
 import path12 from "path";
+var ANIMS_DEST = path12.join("public", "assets", "anims");
+var HIDDEN_TAG = "reference";
+async function runAnims(opts) {
+  const log = createLogger({ quiet: opts.quiet });
+  const root = opts.cwd ?? process.cwd();
+  const selectors = opts.selectors ?? [];
+  log.plain(c.bold("genex controller anims"));
+  log.plain("");
+  const { manifest, source } = await loadManifest(opts.animsBase);
+  if (source === "snapshot") {
+    log.dim("  (offline or CDN unreachable \u2014 using the bundled catalog snapshot)");
+  }
+  if (opts.list) {
+    printCatalog(log, manifest, selectors);
+    return;
+  }
+  const controllerMarker = path12.join(root, "src", "controllers", "character");
+  if (!await exists2(controllerMarker)) {
+    log.error(
+      `No character controller in this game (missing ${c.cyan("src/controllers/character/")}).`
+    );
+    log.plain(`  Run ${c.cyan("genex controller character")} first, then re-run this command.`);
+    process.exitCode = 1;
+    return;
+  }
+  const destDir = path12.join(root, ANIMS_DEST);
+  const gameManifestPath = path12.join(destDir, "manifest.json");
+  if (opts.reset) {
+    await fs11.rm(destDir, { recursive: true, force: true });
+    log.step(`Cleared ${c.cyan(ANIMS_DEST + path12.sep)} (--reset)`);
+  }
+  if (selectors.length === 0) {
+    const installed = await readGameManifest(gameManifestPath);
+    if (installed === null || installed.clips.length === 0) {
+      log.plain("  No animation packs installed yet.");
+    } else {
+      log.plain(`  Installed (${installed.clips.length} clips): ${installed.clips.join(", ")}`);
+    }
+    log.plain("");
+    log.plain(
+      `  Install with ${c.cyan("genex controller anims <tag|clip \u2026>")}; browse with ${c.cyan(
+        "genex controller anims --list"
+      )}.`
+    );
+    return;
+  }
+  let resolved;
+  try {
+    resolved = resolveSelectors(manifest, selectors);
+  } catch (err) {
+    log.error(err instanceof Error ? err.message : String(err));
+    process.exitCode = 1;
+    return;
+  }
+  const coreNames = new Set(manifest.core);
+  const byName = /* @__PURE__ */ new Map();
+  let bundledSkips = 0;
+  for (const entries of resolved.values()) {
+    for (const entry of entries) {
+      if (coreNames.has(entry.name)) {
+        bundledSkips++;
+        continue;
+      }
+      byName.set(entry.name, entry);
+    }
+  }
+  const wanted = [...byName.values()].sort((a, b) => a.name.localeCompare(b.name));
+  const cacheDir = path12.join(
+    opts.cacheDir ?? getAnimsCacheDir(),
+    `${manifest.library}-v${manifest.version}`
+  );
+  await fs11.mkdir(cacheDir, { recursive: true });
+  await fs11.mkdir(destDir, { recursive: true });
+  const base = getAnimsBase(opts.animsBase);
+  let installedCount = 0;
+  let presentCount = 0;
+  let addedBytes = 0;
+  const failures = [];
+  for (const entry of wanted) {
+    const dest = path12.join(destDir, entry.file);
+    if (await hasSize(dest, entry.bytes)) {
+      presentCount++;
+      continue;
+    }
+    try {
+      const cached = path12.join(cacheDir, entry.file);
+      if (!await hasSize(cached, entry.bytes)) {
+        const res = await fetch(base + entry.file);
+        if (!res.ok) throw new Error(`HTTP ${res.status}`);
+        const buf = Buffer.from(await res.arrayBuffer());
+        await fs11.writeFile(cached, buf);
+      }
+      await fs11.copyFile(cached, dest);
+      installedCount++;
+      addedBytes += entry.bytes;
+      log.dim(`  ${path12.join(ANIMS_DEST, entry.file)} (${formatMb(entry.bytes)})`);
+    } catch (err) {
+      failures.push(`${entry.name} (${err instanceof Error ? err.message : String(err)})`);
+    }
+  }
+  const previous = await readGameManifest(gameManifestPath);
+  const union = new Set(previous?.clips ?? []);
+  for (const entry of wanted) {
+    if (!failures.some((f) => f.startsWith(`${entry.name} (`))) union.add(entry.name);
+  }
+  const gameManifest = {
+    schema: 1,
+    library: manifest.library,
+    version: manifest.version,
+    clips: [...union].sort((a, b) => a.localeCompare(b))
+  };
+  await fs11.writeFile(gameManifestPath, JSON.stringify(gameManifest, null, 2) + "\n");
+  log.plain("");
+  const parts = [`${installedCount} clip${installedCount === 1 ? "" : "s"} installed`];
+  if (presentCount > 0) parts.push(`${presentCount} already present`);
+  if (bundledSkips > 0) parts.push(`${bundledSkips} already bundled in animation-library.glb`);
+  log.success(
+    `${parts.join(", ")} \u2192 ${c.cyan(ANIMS_DEST + path12.sep)}${addedBytes > 0 ? ` (+${formatMb(addedBytes)})` : ""}`
+  );
+  for (const [selector, entries] of resolved) {
+    const names = entries.filter((e) => !coreNames.has(e.name)).map((e) => e.name);
+    if (names.length > 0) log.dim(`  ${selector}: ${names.join(", ")}`);
+  }
+  log.info(
+    `Wiring: load the ${c.cyan("genex-threejs-character-controller")} skill \u2192 "Animation packs" (loadCharacterClips picks these up automatically).`
+  );
+  if (failures.length > 0) {
+    log.plain("");
+    log.error(
+      `${failures.length} clip${failures.length === 1 ? "" : "s"} failed to download: ${failures.join(", ")}`
+    );
+    log.plain(
+      "  Each clip needs the network once per machine \u2014 check your connection and re-run the same command (already-installed clips are skipped)."
+    );
+    process.exitCode = 1;
+  }
+}
+async function loadManifest(baseOverride) {
+  const base = getAnimsBase(baseOverride);
+  try {
+    const res = await fetch(base + "manifest.json", { signal: AbortSignal.timeout(5e3) });
+    if (res.ok) {
+      const manifest2 = await res.json();
+      if (manifest2.schema === 1 && Array.isArray(manifest2.clips)) {
+        return { manifest: manifest2, source: "cdn" };
+      }
+    }
+  } catch {
+  }
+  const snapshotPath = path12.join(getTemplatesDir(), "controllers", "assets", "anims-manifest.json");
+  const manifest = JSON.parse(await fs11.readFile(snapshotPath, "utf8"));
+  return { manifest, source: "snapshot" };
+}
+function resolveSelectors(manifest, selectors) {
+  const byName = new Map(manifest.clips.map((entry) => [entry.name, entry]));
+  const byLowerName = new Map(manifest.clips.map((entry) => [entry.name.toLowerCase(), entry]));
+  const tags = /* @__PURE__ */ new Map();
+  for (const entry of manifest.clips) {
+    for (const tag of entry.tags) {
+      const list = tags.get(tag) ?? [];
+      list.push(entry);
+      tags.set(tag, list);
+    }
+  }
+  const out = /* @__PURE__ */ new Map();
+  for (const selector of selectors) {
+    const exact = byName.get(selector) ?? byLowerName.get(selector.toLowerCase());
+    if (exact) {
+      out.set(selector, [exact]);
+      continue;
+    }
+    const tagHit = tags.get(selector) ?? tags.get(selector.toLowerCase());
+    if (tagHit) {
+      out.set(selector, tagHit);
+      continue;
+    }
+    const candidates = [...tags.keys(), ...byName.keys()];
+    const close = suggest(selector, candidates);
+    throw new Error(
+      `unknown clip/tag "${selector}"${close.length > 0 ? ` \u2014 closest: ${close.join(", ")}` : ""}. Run ${c.cyan(
+        "genex controller anims --list"
+      )} for the catalog.`
+    );
+  }
+  return out;
+}
+function suggest(input, candidates) {
+  const lower = input.toLowerCase();
+  const scored = [];
+  for (const candidate of candidates) {
+    const candidateLower = candidate.toLowerCase();
+    if (candidateLower.includes(lower) || lower.includes(candidateLower)) {
+      scored.push({ name: candidate, score: 0 });
+      continue;
+    }
+    const distance = levenshtein(lower, candidateLower, 2);
+    if (distance <= 2) scored.push({ name: candidate, score: distance });
+  }
+  scored.sort((a, b) => a.score - b.score || a.name.localeCompare(b.name));
+  return scored.slice(0, 4).map((s) => s.name);
+}
+function levenshtein(a, b, max) {
+  if (Math.abs(a.length - b.length) > max) return max + 1;
+  let prev = Array.from({ length: b.length + 1 }, (_, i) => i);
+  for (let i = 1; i <= a.length; i++) {
+    const curr = [i];
+    let rowMin = i;
+    for (let j = 1; j <= b.length; j++) {
+      curr[j] = Math.min(
+        prev[j] + 1,
+        curr[j - 1] + 1,
+        prev[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1)
+      );
+      if (curr[j] < rowMin) rowMin = curr[j];
+    }
+    if (rowMin > max) return max + 1;
+    prev = curr;
+  }
+  return prev[b.length];
+}
+function printCatalog(log, manifest, selectors) {
+  const coreNames = new Set(manifest.core);
+  if (selectors.length > 0) {
+    let resolved;
+    try {
+      resolved = resolveSelectors(manifest, selectors);
+    } catch (err) {
+      log.error(err instanceof Error ? err.message : String(err));
+      process.exitCode = 1;
+      return;
+    }
+    for (const [selector, entries] of resolved) {
+      log.plain(c.bold(selector));
+      for (const entry of entries) {
+        const bundled = coreNames.has(entry.name) ? " (bundled)" : "";
+        log.plain(
+          `  ${entry.name.padEnd(26)} ${entry.duration.toFixed(1)}s  ${formatMb(entry.bytes)}${bundled}  ${c.dim(entry.desc)}`
+        );
+      }
+    }
+    return;
+  }
+  const tags = /* @__PURE__ */ new Map();
+  for (const entry of manifest.clips) {
+    for (const tag of entry.tags) {
+      if (tag === HIDDEN_TAG) continue;
+      const list = tags.get(tag) ?? [];
+      list.push(entry);
+      tags.set(tag, list);
+    }
+  }
+  log.plain(
+    `${c.bold(`Animation packs`)} (${manifest.library} v${manifest.version}, ${manifest.clips.length} clips)`
+  );
+  log.plain(
+    `  Install: ${c.cyan("genex controller anims <tag|clip \u2026>")}   Details: ${c.cyan(
+      "genex controller anims --list <tag>"
+    )}`
+  );
+  log.plain("");
+  for (const [tag, entries] of [...tags.entries()].sort(([a], [b]) => a.localeCompare(b))) {
+    const bytes = entries.reduce((sum, entry) => sum + entry.bytes, 0);
+    const suffix = tag === "core" ? " \u2014 bundled in animation-library.glb" : ` (${formatMb(bytes)})`;
+    log.plain(`  ${c.bold(tag.padEnd(18))} ${entries.map((e) => e.name).join(", ")}${suffix}`);
+  }
+}
+async function readGameManifest(file) {
+  try {
+    return JSON.parse(await fs11.readFile(file, "utf8"));
+  } catch {
+    return null;
+  }
+}
+async function hasSize(file, bytes) {
+  try {
+    return (await fs11.stat(file)).size === bytes;
+  } catch {
+    return false;
+  }
+}
+async function exists2(p) {
+  try {
+    await fs11.access(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function formatMb(bytes) {
+  return bytes >= 1e6 ? `${(bytes / 1e6).toFixed(1)} MB` : `${Math.round(bytes / 1e3)} KB`;
+}
+
+// src/commands/controller.ts
 var CONTROLLER_KINDS = ["character", "car", "drone"];
 var SHARED = [
   "shared/math.ts",
@@ -1976,6 +2282,7 @@ var CONTROLLER_FILE_SETS = {
       ...SHARED,
       "character/character-controller.ts",
       "character/character-animations.ts",
+      "character/animation-packs.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.
@@ -1988,15 +2295,16 @@ var CONTROLLER_FILE_SETS = {
     ],
     // The player's VRM is written to public/assets/avatar.vrm at install time by
     // installOwnerAvatar (owner's avatar, or the bundled default) — so it is NOT
-    // a static manifest asset. animation-library.glb (46 clips) still is.
+    // a static manifest asset. animation-library.glb (the 12-clip core) still is;
+    // extra clips arrive via `genex controller anims` into public/assets/anims/.
     assets: ["assets/animation-library.glb"],
     skill: "genex-threejs-character-controller",
     sketch: [
       `const physics = await PhysicsWorld.create();`,
       `const { scene, vrm } = await loadVrm("./assets/avatar.vrm");`,
-      `const lib = await new GLTFLoader().loadAsync("./assets/animation-library.glb");`,
+      `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, retargetClips(vrm, lib.scene, lib.animations));`,
+      `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);`
     ]
   },
@@ -2036,45 +2344,49 @@ var CONTROLLER_FILE_SETS = {
     ]
   }
 };
-var CODE_DEST = path12.join("src", "controllers");
-var ASSETS_DEST = path12.join("public", "assets");
+var CODE_DEST = path13.join("src", "controllers");
+var ASSETS_DEST = path13.join("public", "assets");
 async function runController(opts) {
   const log = createLogger({ quiet: opts.quiet });
+  if (opts.kind?.trim() === "anims") {
+    await runAnims(opts);
+    return;
+  }
   const kind = opts.kind?.trim();
   if (!kind || !CONTROLLER_KINDS.includes(kind)) {
     log.error(
       `Missing or unknown controller type${kind ? ` "${kind}"` : ""}. Usage: ${c.cyan(
         "genex controller <character|car|drone> [--force]"
-      )}`
+      )} or ${c.cyan("genex controller anims <tag|clip \u2026>")}`
     );
     process.exitCode = 1;
     return;
   }
-  const srcDir = path12.join(getTemplatesDir(), "controllers");
+  const srcDir = path13.join(getTemplatesDir(), "controllers");
   const root = opts.cwd ?? process.cwd();
   const set = CONTROLLER_FILE_SETS[kind];
   log.plain(c.bold(`genex controller ${kind}`));
   log.plain("");
-  log.step(`Installing the ${kind} controller into ${c.cyan(CODE_DEST + path12.sep)}`);
+  log.step(`Installing the ${kind} controller into ${c.cyan(CODE_DEST + path13.sep)}`);
   const plan = [
-    ...set.code.map((rel) => ({ from: rel, rel: path12.join(CODE_DEST, rel) })),
+    ...set.code.map((rel) => ({ from: rel, rel: path13.join(CODE_DEST, rel) })),
     ...set.assets.map((rel) => ({
       from: rel,
-      rel: path12.join(ASSETS_DEST, path12.basename(rel))
+      rel: path13.join(ASSETS_DEST, path13.basename(rel))
     }))
   ];
   let copied = 0;
   let skipped = 0;
   try {
     for (const file of plan) {
-      const dest = path12.join(root, file.rel);
-      if (!opts.force && await exists2(dest)) {
+      const dest = path13.join(root, file.rel);
+      if (!opts.force && await exists3(dest)) {
         skipped++;
         log.dim(`  skipped ${file.rel} (exists \u2014 use --force to overwrite)`);
         continue;
       }
-      await fs11.mkdir(path12.dirname(dest), { recursive: true });
-      await fs11.copyFile(path12.join(srcDir, file.from), dest);
+      await fs12.mkdir(path13.dirname(dest), { recursive: true });
+      await fs12.copyFile(path13.join(srcDir, file.from), dest);
       copied++;
       log.dim(`  ${file.rel}`);
     }
@@ -2106,8 +2418,8 @@ async function runController(opts) {
 }
 async function installOwnerAvatar(args) {
   const { root, srcDir, apiUrl, token, log } = args;
-  const dest = path12.join(root, ASSETS_DEST, "avatar.vrm");
-  await fs11.mkdir(path12.dirname(dest), { recursive: true });
+  const dest = path13.join(root, ASSETS_DEST, "avatar.vrm");
+  await fs12.mkdir(path13.dirname(dest), { recursive: true });
   if (token) {
     try {
       const res = await apiFetch(`${apiUrl}/api/avatars/me`, {
@@ -2119,7 +2431,7 @@ async function installOwnerAvatar(args) {
           const vrmRes = await fetch(me.vrmUrl);
           if (vrmRes.ok) {
             const buf = Buffer.from(await vrmRes.arrayBuffer());
-            await fs11.writeFile(dest, buf);
+            await fs12.writeFile(dest, buf);
             log.dim(`  public/assets/avatar.vrm (your avatar \u2014 ${(buf.length / 1e6).toFixed(1)} MB)`);
             return;
           }
@@ -2130,14 +2442,14 @@ async function installOwnerAvatar(args) {
       log.dim("  avatar fetch failed (offline?); using the bundled default.");
     }
   }
-  await fs11.copyFile(path12.join(srcDir, "assets", "default-avatar.vrm"), dest);
+  await fs12.copyFile(path13.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)"
   );
 }
-async function exists2(p) {
+async function exists3(p) {
   try {
-    await fs11.access(p);
+    await fs12.access(p);
     return true;
   } catch {
     return false;
@@ -2230,6 +2542,10 @@ ${c.bold("Usage")}
   genex video "<prompt>" [options]   Generate a video (mp4); prints a public asset URL.
   genex controller <type> [--force]  Install a physics controller (character|car|drone)
                                      into src/controllers (+ assets into public/assets).
+  genex controller anims <sel \u2026>     Download extra character animation clips by tag or
+                                     exact name (sword, stealth, Celebration, \u2026) into
+                                     public/assets/anims/. --list shows the catalog;
+                                     --reset forgets the previous selection first.
   genex explore ["<query>"] [options] Search the curated community gallery \u2014 proven
                                      Three.js systems you can clone or borrow parts
                                      from. No query lists the whole catalog.
@@ -2390,6 +2706,12 @@ function parseArgs(argv) {
       case "--force":
         parsed.options.force = true;
         break;
+      case "--list":
+        parsed.options.list = true;
+        break;
+      case "--reset":
+        parsed.options.reset = true;
+        break;
       case "--regenerate-cover":
         parsed.options.regenerateCover = true;
         break;
@@ -2419,6 +2741,8 @@ function parseArgs(argv) {
           parsed.options.name = arg;
         } else if (parsed.command === "explore") {
           parsed.options.name = `${parsed.options.name} ${arg}`;
+        } else if (parsed.command === "controller") {
+          (parsed.options.selectors ??= []).push(arg);
         } else {
           parsed.error = `Unexpected argument: ${arg}`;
           return parsed;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@genex-ai/cli-demo",
-  "version": "0.37.0",
+  "version": "0.38.0",
   "description": "Set up your ~/.claude workspace, authorize, create a game project, generate AI assets, and publish (genex CLI).",
   "type": "module",
   "bin": {

package/templates/controllers/NOTICE.md

@@ -33,15 +33,18 @@ Every ported source file carries its own SPDX header
 (`SPDX-FileCopyrightText: 2023-2026 Erdong Chen`,
 `SPDX-License-Identifier: MIT`).
 
-## Quaternius Universal Animation Library — CC0 1.0 Universal
+## Quaternius Universal Animation Library [Pro] — CC0 1.0 Universal
 
-- `assets/animation-library.glb` — the Universal Animation Library by
-  **Quaternius** (quaternius.com): 46 humanoid animation clips on a
-  Blender-Rigify-style skeleton, as bundled by upstream ecctrl.
+- `assets/animation-library.glb` — the bundled 12-clip core, cut from the
+  **Universal Animation Library [Pro]** by **Quaternius** (quaternius.com):
+  120 humanoid animation clips on a UE-mannequin-style skeleton.
+- `public/assets/anims/*.glb` — additional per-clip cuts from the same
+  library, installed on demand by `npx genex controller anims`.
 
 Dedicated to the public domain under the Creative Commons CC0 1.0 Universal
 license (SPDX: `CC0-1.0`). No attribution is required by the license; this
-notice is provided as a courtesy.
+notice is provided as a courtesy — supporting Quaternius on Patreon is a nice
+way to say thanks.
 
 ## Default avatar — CC0 1.0 Universal