@genex-ai/cli-demo 0.11.0 → 0.14.2

package/README.md

@@ -11,6 +11,7 @@ genex model "<prompt>"     # generate a 3D model  → assets/models/
 genex skybox "<prompt>"    # generate a 360° sky  → assets/skybox/
 genex sfx "<prompt>"       # generate a sound fx  → assets/sfx/
 genex texture "<prompt>"   # generate a texture   → assets/textures/
+genex controller <type>    # install a tuned character|car|drone controller → src/controllers/
 ```
 
 > **Invoking it.** First-time setup runs via `npx @genex-ai/cli-demo@latest init`.

package/dist/index.js

@@ -2,7 +2,7 @@
 
 // src/index.ts
 import { readFileSync } from "fs";
-import path12 from "path";
+import path13 from "path";
 import { fileURLToPath as fileURLToPath2 } from "url";
 
 // src/commands/init.ts
@@ -91,6 +91,7 @@ async function walk(rootSrc, src, dest, opts, result) {
     const srcPath = path2.join(src, entry.name);
     const destPath = path2.join(dest, entry.name);
     const rel = path2.relative(rootSrc, srcPath);
+    if (opts.exclude?.includes(rel)) continue;
     if (entry.isDirectory()) {
       await fs2.mkdir(destPath, { recursive: true });
       await walk(rootSrc, srcPath, destPath, opts, result);
@@ -740,7 +741,10 @@ async function runInit(opts) {
   for (const t of targets) {
     const src = t.full ? templatesDir : path7.join(templatesDir, "skills");
     const dest = t.full ? t.baseDir : path7.join(t.baseDir, "skills");
-    const { copied, updated } = await copyTemplates(src, dest, { force: opts.force });
+    const { copied, updated } = await copyTemplates(src, dest, {
+      force: opts.force,
+      exclude: ["controllers"]
+    });
     const added = copied.length - updated.length;
     totalNew += added;
     totalUpdated += updated.length;
@@ -1450,13 +1454,202 @@ function printHint(kind, written, log) {
   log.dim(`  ${hint[kind]}`);
 }
 
+// src/commands/controller.ts
+import fs10 from "fs/promises";
+import path12 from "path";
+var CONTROLLER_KINDS = ["character", "car", "drone"];
+var SHARED = [
+  "shared/math.ts",
+  "shared/physics-world.ts",
+  "shared/colliders.ts"
+];
+var INPUT_AND_CAMERA = [
+  "character/follow-camera.ts",
+  "character/keyboard-input.ts",
+  "character/touch-joystick.ts"
+];
+var NOTICE = "NOTICE.md";
+var CONTROLLER_FILE_SETS = {
+  character: {
+    code: [
+      ...SHARED,
+      "character/character-controller.ts",
+      "character/character-animations.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.
+      "character/vrm/vrm-loader.ts",
+      "character/vrm/vrm-retarget.ts",
+      "character/vrm/capsule-fit.ts",
+      "character/vrm/foot-ik.ts",
+      ...INPUT_AND_CAMERA,
+      NOTICE
+    ],
+    // 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.
+    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 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));`,
+      `addEventListener("pointerdown", () => anims.playOneShot("Punch_Jab")); // per frame: anims.update(character, dt); vrm.update(dt);`
+    ]
+  },
+  car: {
+    code: [
+      ...SHARED,
+      "vehicle/vehicle-controller.ts",
+      "vehicle/wheel.ts",
+      "vehicle/presets.ts",
+      "interact/enter-exit.ts",
+      ...INPUT_AND_CAMERA,
+      NOTICE
+    ],
+    assets: [],
+    skill: "genex-threejs-vehicle-controllers",
+    sketch: [
+      `const physics = await PhysicsWorld.create(); // then physics.step(delta) every frame`,
+      `const car = new VehicleController({ world: physics.world, position, carConfig: vehiclePresets["arcade-kart"].carConfig }); // + chassis colliders + car.addWheel(...) per preset slot`,
+      `scene.add(car.chassisObject); physics.onBeforeStep(() => { car.setMovement(keyboard.getCarMovement()); car.update(); });`
+    ]
+  },
+  drone: {
+    code: [
+      ...SHARED,
+      "drone/drone-controller.ts",
+      "drone/presets.ts",
+      "interact/enter-exit.ts",
+      ...INPUT_AND_CAMERA,
+      NOTICE
+    ],
+    assets: [],
+    skill: "genex-threejs-vehicle-controllers",
+    sketch: [
+      `const physics = await PhysicsWorld.create(); // then physics.step(delta) every frame`,
+      `const drone = new DroneController({ world: physics.world, body, chassis, propellers, config: dronePresets["camera-drone"].config });`,
+      `physics.onBeforeStep(() => { drone.setMovement(keyboard.getDroneMovement()); drone.update(); });`
+    ]
+  }
+};
+var CODE_DEST = path12.join("src", "controllers");
+var ASSETS_DEST = path12.join("public", "assets");
+async function runController(opts) {
+  const log = createLogger({ quiet: opts.quiet });
+  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]"
+      )}`
+    );
+    process.exitCode = 1;
+    return;
+  }
+  const srcDir = path12.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)}`);
+  const plan = [
+    ...set.code.map((rel) => ({ from: rel, rel: path12.join(CODE_DEST, rel) })),
+    ...set.assets.map((rel) => ({
+      from: rel,
+      rel: path12.join(ASSETS_DEST, path12.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)) {
+        skipped++;
+        log.dim(`  skipped ${file.rel} (exists \u2014 use --force to overwrite)`);
+        continue;
+      }
+      await fs10.mkdir(path12.dirname(dest), { recursive: true });
+      await fs10.copyFile(path12.join(srcDir, file.from), dest);
+      copied++;
+      log.dim(`  ${file.rel}`);
+    }
+  } catch (err) {
+    log.error(`Copy failed: ${String(err)}`);
+    process.exitCode = 1;
+    return;
+  }
+  log.success(
+    `Controller files ready (${copied} copied${skipped > 0 ? `, ${skipped} skipped` : ""}).`
+  );
+  log.plain("");
+  if (kind === "character") {
+    const token = opts.token !== void 0 ? opts.token : await readUserToken();
+    await installOwnerAvatar({ root, srcDir, apiUrl: getApiUrl(opts.apiUrl), token, log });
+    log.plain("");
+  }
+  log.plain(c.bold("Next steps"));
+  log.plain(
+    `  1. ${c.cyan(
+      kind === "character" ? "npm i @dimforge/rapier3d-compat @pixiv/three-vrm" : "npm i @dimforge/rapier3d-compat"
+    )} (three is already in the scaffold).`
+  );
+  log.plain(`  2. Load the ${c.cyan(set.skill)} skill for wiring, presets, and tuning.`);
+  log.plain("  3. Wiring sketch (controllers update BEFORE the physics step):");
+  for (const line of set.sketch) {
+    log.dim(`       ${line}`);
+  }
+}
+async function installOwnerAvatar(args) {
+  const { root, srcDir, apiUrl, token, log } = args;
+  const dest = path12.join(root, ASSETS_DEST, "avatar.vrm");
+  await fs10.mkdir(path12.dirname(dest), { recursive: true });
+  if (token) {
+    try {
+      const res = await fetch(`${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 fs10.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 fs10.copyFile(path12.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) {
+  try {
+    await fs10.access(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 // src/index.ts
 var GEN_KINDS = /* @__PURE__ */ new Set(["model", "skybox", "sfx", "texture"]);
 function getVersion() {
   try {
-    const here = path12.dirname(fileURLToPath2(import.meta.url));
+    const here = path13.dirname(fileURLToPath2(import.meta.url));
     const pkg = JSON.parse(
-      readFileSync(path12.resolve(here, "..", "package.json"), "utf8")
+      readFileSync(path13.resolve(here, "..", "package.json"), "utf8")
     );
     return pkg.version ?? "0.0.0";
   } catch {
@@ -1473,6 +1666,8 @@ ${c.bold("Usage")}
   genex skybox "<prompt>" [options]  Generate a skybox (equirect) into public/assets/skybox.
   genex sfx "<prompt>" [options]     Generate a sound effect (mp3) into public/assets/sfx.
   genex texture "<prompt>" [options] Generate a PBR texture into public/assets/textures.
+  genex controller <type> [--force]  Install a physics controller (character|car|drone)
+                                     into src/controllers (+ assets into public/assets).
 
 ${c.bold("Options for the generators (`model` `skybox` `sfx` `texture`)")}
   --terrain            (texture) seamless tiling surface for terrain/ground.
@@ -1527,6 +1722,7 @@ ${c.bold("Examples")}
   genex skybox "golden hour over a misty mountain range"
   genex sfx "punchy laser zap" --duration 2
   genex texture "mossy cracked cobblestone" --terrain
+  genex controller character
 `;
 function parseArgs(argv) {
   const parsed = {
@@ -1696,6 +1892,9 @@ async function main() {
     case "init":
       await runInit(parsed.options);
       break;
+    case "controller":
+      await runController({ ...parsed.options, kind: parsed.options.name });
+      break;
     case "preview":
       await runPreview(parsed.options);
       break;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@genex-ai/cli-demo",
-  "version": "0.11.0",
+  "version": "0.14.2",
   "description": "Set up your ~/.claude workspace, authorize, create a game project, generate AI assets, and publish (genex CLI).",
   "type": "module",
   "bin": {
@@ -36,7 +36,12 @@
     "access": "public"
   },
   "devDependencies": {
-    "tsup": "^8.0.0"
+    "@dimforge/rapier3d-compat": "^0.19.3",
+    "@pixiv/three-vrm": "^3.5.4",
+    "@types/three": "^0.185.0",
+    "three": "^0.185.1",
+    "tsup": "^8.0.0",
+    "typescript": "^5.8.0"
   },
   "repository": {
     "type": "git",

package/templates/controllers/NOTICE.md

@@ -0,0 +1,65 @@
+# Third-party notices
+
+The controller code and assets in this directory are vendored into your game
+by `npx genex controller`. They bundle the following third-party work:
+
+## ecctrl — MIT License
+
+The character, vehicle, and drone controllers are a vanilla-TypeScript port of
+the **ecctrl** character/vehicle controller library (a pmndrs project),
+pinned at upstream commit `e2f4eb8`.
+
+Copyright (c) 2023-2026 Erdong Chen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+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
+
+- `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.
+
+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.
+
+## Default 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
+**Polygonal Mind** (polygonalmind.com), dedicated to the public domain under
+CC0 1.0 Universal (SPDX: `CC0-1.0`). Attribution is a courtesy, not required.
+
+## @pixiv/three-vrm — MIT License
+
+The VRM support in `character/vrm/` (loader, animation retargeter, foot IK) is
+built on the **@pixiv/three-vrm** npm package, MIT-licensed by pixiv Inc.
+`vrm-retarget.ts` adapts that package's official humanoid-retarget example (MIT)
+to the Quaternius rig. Install it into your game with `npm i @pixiv/three-vrm`.
+
+Copyright (c) 2019-2026 pixiv Inc. — Permission is hereby granted, free of
+charge, to any person obtaining a copy of this software and associated
+documentation files, to deal in the Software without restriction. THE SOFTWARE
+IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND. (Full MIT text ships with the
+`@pixiv/three-vrm` package's LICENSE file.)