@genex-ai/cli-demo 0.5.0 → 0.6.0

package/dist/index.js

@@ -816,6 +816,9 @@ async function deployGame(sshUrl, opts, log) {
     });
     if (push.code === 0) {
       log.success("Pushed.");
+      if (opts.playUrl) {
+        await waitUntilLive(opts.playUrl, await buildFingerprint(siteDir), opts.liveTimeoutMs ?? 12e4, log);
+      }
       return true;
     }
     log.warn("git push failed \u2014 your live game was NOT updated.");
@@ -850,6 +853,41 @@ async function fileExists(p) {
     return false;
   }
 }
+var sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+async function buildFingerprint(siteDir) {
+  let html;
+  try {
+    html = await fs6.readFile(path7.join(siteDir, "index.html"), "utf8");
+  } catch {
+    return null;
+  }
+  const m = html.match(/[A-Za-z0-9_]+-[A-Za-z0-9_-]{8}\.(?:js|css)/);
+  return m ? m[0] : null;
+}
+async function waitUntilLive(playUrl, fingerprint, timeoutMs, log) {
+  if (!fingerprint) {
+    log.dim(`  ${playUrl}`);
+    log.dim("  (GitHub Pages rebuilds ~30\u201390s after a push.)");
+    return;
+  }
+  log.step("Waiting for GitHub Pages to serve the new build\u2026");
+  const deadline = Date.now() + timeoutMs;
+  let n = 0;
+  while (Date.now() < deadline) {
+    try {
+      const res = await fetch(`${playUrl}?_genexlive=${n++}`, { cache: "no-store" });
+      if (res.ok && (await res.text()).includes(fingerprint)) {
+        log.success(`Live. \u{1F310}  ${playUrl}`);
+        return;
+      }
+    } catch {
+    }
+    await sleep(4e3);
+  }
+  log.warn("Still publishing \u2014 GitHub Pages can take a bit longer.");
+  log.dim(`  ${playUrl}`);
+  log.dim("  (Open it in ~30\u201360s; the new build is on its way.)");
+}
 async function warnIfAbsolutePaths(siteDir, log) {
   let html;
   try {
@@ -884,7 +922,7 @@ async function runPublish(opts) {
   if (opts.noPush) {
     log.info("Skipping build + git push (--no-push).");
   } else {
-    pushed = await deployGame(meta.sshUrl, { noBuild: opts.noBuild }, log);
+    pushed = await deployGame(meta.sshUrl, { noBuild: opts.noBuild, playUrl: meta.playUrl }, log);
   }
   log.step("Listing it in the gallery\u2026");
   let res;
@@ -918,7 +956,6 @@ async function runPublish(opts) {
   }
   if (meta.playUrl) {
     log.dim(`  play: ${meta.playUrl}`);
-    if (pushed === true) log.dim("  (GitHub Pages rebuilds ~30\u201390s after a push.)");
   }
 }
 
@@ -933,18 +970,18 @@ async function runPreview(opts) {
     process.exitCode = 1;
     return;
   }
-  const pushed = await deployGame(meta.sshUrl, { noBuild: opts.noBuild }, log);
+  const pushed = await deployGame(
+    meta.sshUrl,
+    { noBuild: opts.noBuild, playUrl: meta.playUrl },
+    log
+  );
   log.plain("");
   if (!pushed) {
     log.warn("Preview not updated \u2014 see the error above.");
     process.exitCode = 1;
     return;
   }
-  log.success("Preview deployed. \u{1F310}");
-  if (meta.playUrl) {
-    log.dim(`  ${meta.playUrl}`);
-    log.dim("  (GitHub Pages rebuilds ~30\u201390s after a push; it stays an unlisted draft until you publish.)");
-  }
+  log.success("Preview deployed \u2014 unlisted draft (run `genex publish` to list it).");
 }
 
 // src/commands/generate.ts
@@ -967,17 +1004,21 @@ async function downloadToFile(url, dest, headers) {
 }
 
 // src/commands/generate.ts
+var PUBLIC_PREFIX = "public/";
 var KIND_DIR = {
-  model: "assets/models",
-  skybox: "assets/skybox",
-  sfx: "assets/sfx",
-  texture: "assets/textures"
+  model: "public/assets/models",
+  skybox: "public/assets/skybox",
+  sfx: "public/assets/sfx",
+  texture: "public/assets/textures"
 };
-var sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+function runtimePath(rel) {
+  return `./${rel.replace(PUBLIC_PREFIX, "")}`;
+}
+var sleep2 = (ms) => new Promise((r) => setTimeout(r, ms));
 function fileDest(kind, slug, f) {
   if (kind === "texture") {
     const name = f.role.replace(/^texture-/, "");
-    return `assets/textures/${slug}/${name}.${f.ext}`;
+    return `public/assets/textures/${slug}/${name}.${f.ext}`;
   }
   return `${KIND_DIR[kind]}/${slug}.${f.ext}`;
 }
@@ -1082,19 +1123,21 @@ async function poll(apiUrl, token, id, onProgress) {
       }
     } catch {
     }
-    await sleep(3e3);
+    await sleep2(3e3);
   }
   return null;
 }
 function printHint(kind, written, log) {
-  const primary = written[0] ?? "";
+  const load = runtimePath(written[0] ?? "");
   const hint = {
-    model: `Load with GLTFLoader and add to the scene \u2014 see the genex-ai-model skill. Use the relative path "./${primary}".`,
-    skybox: `Load as an equirectangular texture \u2192 scene.background + scene.environment \u2014 see genex-ai-skybox. Path "./${primary}".`,
-    sfx: `Load with AudioLoader into a THREE.PositionalAudio (camera needs an AudioListener) \u2014 see genex-ai-sfx. Path "./${primary}".`,
-    texture: `Load with TextureLoader, set RepeatWrapping, build a MeshStandardMaterial \u2014 see genex-ai-texture. Path "./${primary}".`
+    model: `Load with GLTFLoader and add to the scene \u2014 see the genex-ai-model skill. Use the relative path "${load}".`,
+    skybox: `Load as an equirectangular texture \u2192 scene.background + scene.environment \u2014 see genex-ai-skybox. Path "${load}".`,
+    sfx: `Load with AudioLoader into a THREE.PositionalAudio (camera needs an AudioListener) \u2014 see genex-ai-sfx. Path "${load}".`,
+    texture: `Load with TextureLoader, set RepeatWrapping, build a MeshStandardMaterial \u2014 see genex-ai-texture. Path "${load}".`
   };
-  log.success("Done. Asset saved into ./assets (commit it \u2014 `genex publish` ships it with the game).");
+  log.success(
+    "Done. Asset saved into public/assets (so Vite ships it; load it as ./assets/\u2026 \u2014 `genex publish` commits and ships it with the game)."
+  );
   log.dim(`  ${hint[kind]}`);
 }
 
@@ -1117,10 +1160,10 @@ ${c.bold("Usage")}
   genex init [<name>] [options]      Scaffold + authorize + create the draft project.
   genex preview [options]            Build + push to the hosted draft URL (unlisted).
   genex publish [options]            Build + push, then list the game in the gallery.
-  genex model "<prompt>" [options]   Generate a 3D model (GLB) into ./assets/models.
-  genex skybox "<prompt>" [options]  Generate a skybox (equirect) into ./assets/skybox.
-  genex sfx "<prompt>" [options]     Generate a sound effect (mp3) into ./assets/sfx.
-  genex texture "<prompt>" [options] Generate a PBR texture into ./assets/textures.
+  genex model "<prompt>" [options]   Generate a 3D model (GLB) into public/assets/models.
+  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.
 
 ${c.bold("Options for the generators (`model` `skybox` `sfx` `texture`)")}
   --terrain            (texture) seamless tiling surface for terrain/ground.

package/package.json

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

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

@@ -24,11 +24,33 @@ Write a specific prompt — "weathered wooden barrel with rusted iron bands" bea
 "barrel". The command blocks until the mesh is ready (up to ~a minute), then saves:
 
 ```
-assets/models/<slug>.glb
+public/assets/models/<slug>.glb
 ```
 
 `<slug>` is derived from the prompt (e.g. `weathered-wooden-barrel.glb`). The file
-is **committed by `npx genex publish`**, so it ships inside your published game.
+lives under `public/` so Vite ships it in the build (load it as `./assets/models/...` —
+the `public/` prefix is stripped when served). It is **committed by `npx genex publish`**,
+so it ships inside your published game.
+
+## Hero models must face forward
+
+For the model the player controls (a ship, car, character — the "hero"), the mesh should
+**face forward**: its front pointing down the direction of travel (conventionally `+Z`,
+i.e. "looking forward"). A hero whose nose points sideways reads as broken at a glance.
+
+- **In the prompt:** when it's the player's craft, ask for it facing forward — e.g.
+  `"...game-ready, facing forward, front toward +Z"`.
+- **On load (fallback):** if the imported GLB still isn't forward, rotate it once so its
+  nose aligns with travel. Wrap the model in a parent `Object3D` and apply the correction
+  to the child, so your movement code can rotate the parent cleanly:
+  ```ts
+  const hero = new THREE.Object3D();
+  gltf.scene.rotation.y = Math.PI / 2; // one-time facing correction — tune per model
+  hero.add(gltf.scene);
+  scene.add(hero); // move/rotate `hero`, not gltf.scene
+  ```
+- Orientation **is** visible in a still — confirm the hero faces forward in your
+  self-check screenshot before moving on.
 
 ## Load it into the scene
 
@@ -55,7 +77,8 @@ To place many copies, `model.clone()` per instance. For animated GLBs, drive
   (`/assets/...`) — GitHub Pages serves the game at a subpath.
 - Set `base: "./"` in `vite.config.ts` before `npm run build` (see the scaffold
   prompt's publish step).
-- Commit the `assets/` folder — `npx genex publish` pushes it with the game.
+- Keep generated assets under `public/assets/` — Vite only ships files under `public/`
+  (or files you `import`); `npx genex publish` commits and pushes that folder with the game.
 
 ## Options
 

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

@@ -18,7 +18,7 @@ npx genex sfx "punchy laser zap, short and dry" --duration 2
 Blocks until ready, then saves:
 
 ```
-assets/sfx/<slug>.mp3
+public/assets/sfx/<slug>.mp3
 ```
 
 Committed by `npx genex publish`, so it ships with your game.
@@ -55,7 +55,8 @@ Reuse one loaded `buffer` across many plays; create a fresh `Audio`/`PositionalA
 
 ## Publish checklist
 
-- Relative path `./assets/sfx/...`; `base: "./"` in `vite.config.ts`; commit `assets/`.
+- Relative path `./assets/sfx/...`; `base: "./"` in `vite.config.ts`; files live under
+  `public/assets/` so Vite ships them; `npx genex publish` commits and pushes them.
 
 ## Troubleshooting
 

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

@@ -26,7 +26,7 @@ npx genex skybox "<prompt>"
 Blocks until ready, then saves:
 
 ```
-assets/skybox/<slug>.jpg
+public/assets/skybox/<slug>.jpg
 ```
 
 The JPG is **committed by `npx genex publish`**, so it ships with your game.
@@ -63,7 +63,8 @@ texture.dispose; // (dispose the PMREM source later if you stop using it)
 
 - Use the **relative** path `./assets/skybox/...` (GitHub Pages serves at a subpath).
 - `base: "./"` in `vite.config.ts` before `npm run build`.
-- Commit `assets/` — `npx genex publish` pushes it with the game.
+- Generated files live under `public/assets/` so Vite ships them; `npx genex publish`
+  commits and pushes that folder with the game.
 
 ## Troubleshooting
 

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

@@ -27,7 +27,7 @@ npx genex texture "lush green grass" --terrain    # seamless tiling for ground/t
 Blocks until ready, then saves:
 
 ```
-assets/textures/<slug>/basecolor.<ext>
+public/assets/textures/<slug>/basecolor.<ext>
 ```
 
 Committed by `npx genex publish`, so it ships with your game.
@@ -67,7 +67,8 @@ scene.add(ground);
 
 ## Publish checklist
 
-- Relative path `./assets/textures/...`; `base: "./"` in `vite.config.ts`; commit `assets/`.
+- Relative path `./assets/textures/...`; `base: "./"` in `vite.config.ts`; files live under
+  `public/assets/` so Vite ships them; `npx genex publish` commits and pushes them.
 
 ## Troubleshooting
 

package/templates/skills/genex-threejs-multiplayer/SKILL.md

@@ -72,6 +72,41 @@ const room = await connect<State>({
 See [references/realtime-patterns.md](references/realtime-patterns.md) for the ready-made
 `RemoteInterpolator` helper and a complete movement example.
 
+## Smoothness is human-tested — you cannot see it
+
+Lag, stutter, and jitter are *motion over time*. A screenshot is one frozen instant, so
+**you cannot tell from a screenshot (or any still capture) whether remote movement feels
+smooth.** Don't try. Trying to "verify smoothness" from captures leads to blind parameter
+tuning, regressions, and reverts.
+
+Your job is bounded:
+
+1. **Use the reference `RemoteInterpolator` as written.** Render-delay + lerp between the
+   last two snapshots, with a clamp (no extrapolation). Don't hand-roll your own smoother.
+2. **Verify it *runs*, not that it *feels good*:** two clients, two distinct meshes, both
+   move, no console errors, each player sees the other. That's all a capture can prove.
+3. **Then hand the feel off to the human.** Say plainly: *"Multiplayer smoothness depends on
+   your network and can only be felt by a person — open it in two tabs or with a friend and
+   tell me how it feels."* Stop there; don't keep tuning on speculation.
+
+**Do NOT add velocity extrapolation, "keep gliding," dead-reckoning, or prediction for
+*remote* players** until a human reports a specific symptom. The reference deliberately
+clamps instead of extrapolating — extrapolation overshoots on turns and looks worse, which
+is exactly the trap to avoid.
+
+### When the human reports a problem, match the symptom (don't guess)
+
+- **"My own plane feels laggy."** You're rendering yourself from the echoed server copy.
+  Render *yourself* from your local predicted object instead (zero latency).
+- **"Other players teleport / stutter / move in steps."** Snapping to raw state, or
+  `RENDER_DELAY_MS` too low for the jitter. Confirm remotes go through the interpolator,
+  then raise `RENDER_DELAY_MS` (e.g. 100 → 150).
+- **"Other players rubber-band / float past corners / overshoot."** That's extrapolation or
+  raw network round-trip latency — *more smoothing won't fix it.* Remove any extrapolation
+  and accept the small honest delay; true RTT is not a client-side bug.
+- **"Everyone lags equally, including stationary objects."** Likely `me.set` per frame
+  flooding the relay — move publishing to the fixed 10–20 Hz tick.
+
 ## Config wiring (required — the browser can't read `.genex/project.json`)
 
 The game runs in the browser; `.genex/project.json` (which holds `slug`, `colyseusUrl`,