@genex-ai/cli-demo 0.20.0 → 0.21.0

package/dist/index.js

@@ -1399,6 +1399,9 @@ async function runPublish(opts) {
     if (opts.description) body.description = opts.description;
     if (opts.regenerateCover) body.regenerateCover = true;
     if (opts.categories?.length) body.categories = opts.categories;
+    if (opts.sourceRepoUrl) body.sourceRepoUrl = opts.sourceRepoUrl;
+    if (opts.sourceAuthor) body.sourceAuthor = opts.sourceAuthor;
+    if (opts.license) body.license = opts.license;
     if (detections.embedSdkVersion) body.embedSdkVersion = detections.embedSdkVersion;
     body.multiplayer = detections.multiplayer;
     body.matchmaking = detections.matchmaking ?? null;
@@ -1906,6 +1909,72 @@ async function exists2(p) {
   }
 }
 
+// src/commands/explore.ts
+async function runExplore(opts) {
+  const log = createLogger({ quiet: opts.quiet });
+  const query = opts.query?.trim();
+  if (!query) {
+    log.error('Missing query. Usage: genex explore "<what you need>"');
+    process.exitCode = 1;
+    return;
+  }
+  const apiUrl = getApiUrl(opts.apiUrl);
+  let res;
+  try {
+    res = await fetch(`${apiUrl}/api/gallery/search-corpus?curated=1`);
+  } catch {
+    log.error("Couldn't reach Genex \u2014 please try again.");
+    process.exitCode = 1;
+    return;
+  }
+  if (!res.ok) {
+    log.error(`explore: API returned ${res.status} \u2014 please try again.`);
+    process.exitCode = 1;
+    return;
+  }
+  const { items } = await res.json();
+  const ranked = rank(items, query).slice(0, 5);
+  if (opts.json) {
+    console.log(JSON.stringify(ranked, null, 2));
+    return;
+  }
+  if (ranked.length === 0) {
+    log.plain(
+      `No curated projects matched "${query}". Try a broader term (terrain, grass, vehicle, water, building, dungeon, fish, shader).`
+    );
+    return;
+  }
+  for (const [i, p] of ranked.entries()) {
+    const meta = [
+      p.categories.join(", "),
+      p.license ?? "",
+      p.sourceAuthor ? `originally by ${p.sourceAuthor}` : ""
+    ].filter(Boolean).join(" \xB7 ");
+    log.plain(`${c.bold(`${i + 1}. ${p.title}`)} \u2014 ${meta}`);
+    if (p.description) log.plain(`   ${p.description.slice(0, 160)}`);
+    if (p.playUrl) log.plain(`   play:  ${p.playUrl}`);
+    if (p.cloneUrl) log.plain(`   clone: ${p.cloneUrl}   (editable source on main)`);
+    if (p.sourceRepoUrl) log.plain(`   upstream: ${p.sourceRepoUrl}`);
+  }
+  log.plain("");
+  log.plain(
+    `To use one: clone it as a starting template, or borrow parts into your current game \u2014 the genex-explore skill has the exact steps. Keep the credits.`
+  );
+}
+function rank(items, query) {
+  const terms = query.toLowerCase().split(/\s+/).filter(Boolean);
+  return items.map((p) => {
+    const hay = `${p.title} ${p.description} ${p.categories.join(" ")}`.toLowerCase();
+    let score = 0;
+    for (const t of terms) {
+      if (p.title.toLowerCase().includes(t)) score += 3;
+      if (p.categories.some((cat) => cat.includes(t))) score += 2;
+      if (hay.includes(t)) score += 1;
+    }
+    return { p, score };
+  }).filter((x) => x.score > 0).sort((a, b) => b.score - a.score || b.p.playsCount - a.p.playsCount).map((x) => x.p);
+}
+
 // src/index.ts
 var GEN_KINDS = /* @__PURE__ */ new Set(["model", "skybox", "sfx", "texture"]);
 function getVersion() {
@@ -1934,6 +2003,8 @@ ${c.bold("Usage")}
   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).
+  genex explore "<query>" [options]  Search the curated community gallery \u2014 proven
+                                     Three.js systems you can clone or borrow parts from.
 
 ${c.bold("Options for the generators (`model` `skybox` `sfx` `texture`)")}
   --terrain            (texture) seamless tiling surface for terrain/ground.
@@ -1972,9 +2043,17 @@ ${c.bold("Options for `preview` / `publish`")}
   --categories <list>  (publish) 1-3 gallery categories, comma-separated.
                        Valid: games, assets, physics, terrain, lighting, vfx.
   --regenerate-cover   (publish) Re-mint the disc cover (concept changed).
+  --source-repo-url <url>  (publish) Upstream repo this game is a port of \u2014
+                       shown as "Ported from \u2026" credit on the game page.
+  --source-author <name>   (publish) Upstream author to credit.
+  --license <label>        (publish) Upstream license label (e.g. MIT).
   --api-url <url>      (publish) Override the API base URL.
   --env <path>         Token env file (default: ~/.genex/env).
 
+${c.bold("Options for `explore`")}
+  --json               Print the top matches as JSON (for tools/agents).
+  --api-url <url>      Override the API base URL.
+
 ${c.bold("Global")}
   --quiet              Reduce output.
   -h, --help           Show this help.
@@ -1999,6 +2078,7 @@ ${c.bold("Examples")}
   genex sfx "punchy laser zap" --duration 2
   genex texture "mossy cracked cobblestone" --terrain
   genex controller character
+  genex explore "grass"
 `;
 function parseArgs(argv) {
   const parsed = {
@@ -2019,7 +2099,10 @@ function parseArgs(argv) {
     "--description",
     "--categories",
     "--timeout",
-    "--duration"
+    "--duration",
+    "--source-repo-url",
+    "--source-author",
+    "--license"
   ]);
   let i = 0;
   while (i < argv.length) {
@@ -2058,6 +2141,9 @@ function parseArgs(argv) {
       case "--quiet":
         parsed.options.quiet = true;
         break;
+      case "--json":
+        parsed.options.json = true;
+        break;
       default: {
         if (needsValue.has(arg)) {
           const value = argv[i++];
@@ -2073,6 +2159,8 @@ function parseArgs(argv) {
           parsed.command = arg;
         } else if (parsed.options.name === void 0) {
           parsed.options.name = arg;
+        } else if (parsed.command === "explore") {
+          parsed.options.name = `${parsed.options.name} ${arg}`;
         } else {
           parsed.error = `Unexpected argument: ${arg}`;
           return parsed;
@@ -2115,6 +2203,15 @@ function applyValueFlag(options, flag, value) {
     case "--categories":
       options.categories = value.split(",").map((s) => s.trim().toLowerCase()).filter(Boolean);
       break;
+    case "--source-repo-url":
+      options.sourceRepoUrl = value;
+      break;
+    case "--source-author":
+      options.sourceAuthor = value;
+      break;
+    case "--license":
+      options.license = value;
+      break;
     case "--timeout": {
       const n = Number(value);
       if (!Number.isFinite(n) || n <= 0) {
@@ -2180,6 +2277,9 @@ async function main() {
     case "publish":
       await runPublish(parsed.options);
       break;
+    case "explore":
+      await runExplore({ ...parsed.options, query: parsed.options.name });
+      break;
     default:
       log.error(`Unknown command: ${parsed.command}`);
       log.plain(`Run ${c.cyan("genex --help")} for usage.`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@genex-ai/cli-demo",
-  "version": "0.20.0",
+  "version": "0.21.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

@@ -32,25 +32,33 @@ 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:
+## Models that point somewhere must face forward
+
+Any model with a "front" the game aims — the hero the player controls, an **NPC that
+walks toward or looks at players**, a turret, a vehicle — should face **forward**: its
+front toward `+Z` (glTF's "looking forward"), so yaw/`lookAt` code points it correctly.
+A hero whose nose points sideways — or an enemy that chases you while staring off to the
+side — reads as broken at a glance.
+
+- **In the prompt:** ask for it — e.g. `"...game-ready, facing forward, front toward +Z"`.
+  Treat this as a hint, not a guarantee: generated meshes regularly come back rotated
+  anyway, so the check below is never optional.
+- **On load (always check — hero AND NPC):** if the GLB isn't `+Z`-forward, rotate it
+  once. Wrap the model in a parent `Object3D` and put the correction on the child, so
+  game code rotates the parent cleanly:
   ```ts
-  const hero = new THREE.Object3D();
+  const rig = 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
+  rig.add(gltf.scene);
+  scene.add(rig); // move/rotate/lookAt `rig`, not gltf.scene
   ```
-- Orientation **is** visible in a still — confirm the hero faces forward in your
-  self-check screenshot before moving on.
+  Clones inherit the fix only if you clone the corrected child (or the whole rig) —
+  never the raw `gltf.scene`.
+- **Verify it, don't assume it.** Orientation **is** visible in a still — in your
+  self-check screenshot confirm the hero faces its travel direction AND that NPCs driven
+  by chase/aim code face their target (an enemy rotated 90° from its victim is this
+  pipeline's most common visible bug). If you can't capture real gameplay (a draft's
+  sign-in gate is up), say so plainly instead of skipping the check silently.
 
 ## Load it into the scene
 

package/templates/skills/genex-explore/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: genex-explore
+description: Search the curated Genex community gallery with `npx genex explore` before hand-writing hard visual or physics systems. Use when the game needs terrain, grass, water, vehicles, buildings, dungeons, flocking/boids, or advanced shader work — proven open-source Three.js implementations you can clone as a starting point or borrow parts from, credits included.
+---
+
+# Genex Explore — proven building blocks from the community gallery
+
+Some systems are notoriously hard to get right from scratch: believable grass,
+vehicle physics, procedural buildings and dungeons, fish/boid flocking, water,
+advanced shader effects. The curated community gallery holds **faithful ports of
+proven open-source Three.js projects** — playable, cloneable, and licensed for
+reuse. Search it before hand-writing one of those systems.
+
+## When to use
+
+Before building a hard visual/physics system by hand, run:
+
+```bash
+npx genex explore "<what you need>"
+```
+
+Examples: `npx genex explore "grass"`, `npx genex explore "vehicle physics"`,
+`npx genex explore "procedural building"`. No sign-in needed — this works even
+before `genex init`.
+
+Each result prints everything you need to act on it:
+
+- `play:` — open it in the browser to judge whether it fits.
+- `clone:` — the public repo with **editable source on `main`**.
+- `upstream:` — the original source repo, with its author and license.
+
+Add `--json` for machine-readable output.
+
+## How to integrate a result
+
+**As a NEW game (start from the whole project):**
+
+1. `git clone <clone URL from the output> <name>` — pick a short one-word name.
+2. `cd <name>`, then `npx @genex-ai/cli-demo@latest init <name>` — choose
+   "Ignore files and continue" if it warns the folder isn't empty; never use
+   `--force`. This creates your own project; the original is untouched.
+3. `npm install`, keep `base: './'` in `vite.config`, then build your changes
+   and ship with `npx genex preview`.
+
+**To BORROW parts into the current project:**
+
+1. Clone the result somewhere temporary, separate from your project
+   (e.g. `/tmp/genex-explore-src`).
+2. Study how it implements the part you need, then bring **just that** over —
+   real code and assets, adapted to your file paths. Don't wholesale-overwrite
+   your game.
+3. Reused assets must live under `public/assets/` to ship. New assets are
+   generated as usual with `$genex-ai-model`, `$genex-ai-skybox`,
+   `$genex-ai-sfx`, or `$genex-ai-texture`.
+
+## Credits rule (non-negotiable)
+
+Every curated result carries an upstream link, author, and license — that
+credit is part of the deal that makes these projects reusable. Whatever you
+build from one:
+
+- keep the attribution block in the README (upstream source repo URL, author,
+  license) exactly as the port carries it;
+- keep any in-game credits screens or notices in place;
+- carry the credit into anything you publish or remix from it.
+
+If nothing matches your query, try a broader term (terrain, grass, vehicle,
+water, building, dungeon, fish, shader) — or build it with the regular
+`genex-threejs-*` skills instead.

package/templates/skills/genex-threejs-camera-direction/SKILL.md

@@ -33,6 +33,18 @@ Read [references/camera-rigs.md](references/camera-rigs.md)
 for exact chase/side/orbit rigs, projection values, transition
 rules, floating-origin shot, pointer controls, and implementation limits.
 
+## Aiming and pointer lock
+
+Camera-aimed action — a third-person shooter reticle, first-person look —
+wants **pointer lock**, not drag-orbit: request it on canvas click
+(`canvas.requestPointerLock()`), drive yaw/pitch from `mousemove` deltas while
+locked, and treat lock loss (Esc) as aim-paused — show a small "click to aim"
+hint whenever unlocked. Keep drag-orbit for non-combat cameras (exploration,
+building, spectating). Pointer lock works everywhere a Genex game runs:
+standalone the game is the top-level page, and the platform's game frame
+already grants the pointer-lock permission — no setup needed. Re-sync
+yaw/pitch from the camera whenever lock is acquired (rule below).
+
 ## Non-negotiable rules
 
 - Use subject dimensions to derive offsets; do not tune one fixed distance for

package/templates/skills/genex-threejs-embed-auth/SKILL.md

@@ -260,6 +260,24 @@ instead. Don't code around any of this: no `?`/`#` URL params of yours will
 be affected, and `isEmbedded()` / the return-trip handling are internal SDK
 concerns.
 
+### Validating a draft (read before self-testing)
+
+An unpublished draft shows the sign-in gate to any browser that isn't signed
+in as the owner — **including your own test browser** (Playwright, headless
+Chrome). The game still boots behind the overlay: console logs, DOM snapshots,
+and key events all work — but every screenshot shows the gate, not the game,
+and a gate capture is NOT visual evidence.
+
+- Validate what the gate can't hide: a clean console, the canvas booting, the
+  HUD present in a DOM snapshot, controls registering.
+- Do NOT work around the gate: don't dig through the SDK's internals for
+  undocumented URL fragments, and don't drive the user's own signed-in
+  browser.
+- For the visual pass on a draft, hand it off plainly: "open your draft page
+  and tell me what you see" — the owner's view is the real check. Once the
+  game is **published**, any fresh browser gets in as a guest, so your own
+  test browser works again for full visual validation.
+
 ## Checklist
 
 - [ ] `initGameSentry({ slug: GENEX.slug })` is the very first call in `main.ts`.

package/templates/skills/genex-threejs-game-feel/SKILL.md

@@ -33,6 +33,10 @@ no matter how good it looks.
   itself, or apply them only to hand-rolled movement.)
 - If an action can't fire (cooldown, no ammo), say so instantly — a click, a
   dimmed icon — silence reads as broken input.
+- Camera-aimed shooting wants **pointer lock** (click to aim, Esc releases —
+  `$genex-threejs-camera-direction` has the rig rules); firing at a reticle
+  with an unlocked drag-to-turn camera feels imprecise no matter how tight
+  the numbers are.
 
 ## Movement: snappy beats realistic
 

package/templates/skills/genex-threejs-visual-validation/SKILL.md

@@ -32,7 +32,15 @@ this is the whole acceptance gate, and it is also the minimum for every game:
 2. Press each documented control once (keys, pointer); assert a **visible
    response** to every one — the player moves, the camera turns, the button
    fires.
-3. Capture one screenshot of live gameplay.
+3. Capture one screenshot of live gameplay — of the **game**, not a sign-in
+   gate or loading screen. A capture of the SDK's "Sign in to play" overlay is
+   NOT gameplay evidence; if a draft's gate blocks the view, say so plainly
+   (see the embed-auth skill's "Validating a draft" note) instead of passing
+   the capture off as validation.
+4. In that screenshot, check oriented models: the hero faces its travel
+   direction, and NPCs driven by chase/aim code face their target. A model
+   rotated 90° reads as broken — `$genex-ai-model` has the one-time facing
+   fix.
 
 Everything deeper (baselines, seed sweeps, mosaics, budgets) belongs to
 visual-system work — the sequence above.