@genex-ai/cli-demo 0.86.0-dev.217 → 0.88.0-dev.219

package/templates/skills/genex-ai-character/references/motion.md

@@ -0,0 +1,145 @@
+# Custom animations with `genex motion` — the full procedure
+
+Text → raw motion takes on the platform GPU service → objective verify →
+YOUR pick → local compile → a rig-independent set the vendored runtime plays
+on any humanoid. The skeleton is a 27-joint humanoid core at 20 fps; takes
+arrive as `.npz` files plus a machine verify report. Everything after `gen`
+runs locally and free — regenerate compiled sets as often as you like.
+
+**Rig limits (say them to the user before promising a move):** biped,
+human-proportioned characters only. Rigs without finger bones (many Meshy
+characters) cannot curl fingers around a grip — prefer weapon-carry looks
+that read well with flat hands there, or use a rig with fingers for hero
+characters. Takes are 2–10 seconds.
+
+## The loop
+
+```bash
+# 1. Generate (bills per take, default 4; ALWAYS --no-wait — jobs run minutes)
+npx genex motion gen "soldier rifle low-ready idle, fully upright, head held high" --takes 4 --no-wait
+npx genex wait <id>                       # prints one URL per take + the report
+
+# 2. Download the takes it printed and RENAME them — filenames drive everything
+mkdir -p takes && curl -o takes/rifle-idle.npz "<take-url>"
+
+# 3. Verify locally (same math the service ran; free, reproducible)
+npx genex motion verify takes/
+
+# 4. Pick the takes whose MOTION reads right (the report is data, not taste),
+#    then compile the set
+npx genex motion compile takes/ --out src/motion/rifle.json
+
+# 5. Vendor the runtime once per game (+ the proven rifle starter set)
+npx genex motion install --set rifle
+```
+
+## Take naming — the routing contract
+
+`verify` and `compile` classify each take by its FILENAME stem. Rename
+downloaded takes before running them:
+
+| Stem pattern | Compiles into |
+|---|---|
+| `<set>-run-forward` / `-back` | `forward` / `back` gait |
+| `<set>-strafe-left` / `-strafe-right` | `strafeLeft` / `strafeRight` |
+| `<set>-run-fl` / `-fr` / `-bl` / `-br` | the four diagonal gaits |
+| `<set>-idle` or `…stance…` | the `idle` loop |
+| `…jump…` (`jump-stand`, `jump-run`) | `jumpStand` / `jumpRun` one-shots |
+| anything else | a named freeform loop |
+
+A stem containing `aim`, `rifle`, or `pistol` marks the take as a WEAPON
+HOLD: verify adds the hold-shape gates, and compile grip-line-normalizes the
+idle (the whole body blades as one) and plucks `aim0`/`aim0Up`/`aim0Dn`
+upper-body mask poses from the hold takes.
+
+## The prompt wording ladder (hard-won — wrong words cost paid takes)
+
+- **Never ask for "sights" or a "cheek weld"** — you get a hunched
+  face-height hold that reads absurd on game rigs. Ask for the third-person
+  hold: *"weapon at chest height, arms extended"*, *"low-ready"* as the
+  fallback.
+- **Always add "fully upright, head held high"** — the model's prior slouches.
+- **Describe hand geometry literally** (*"left hand forward on the handguard,
+  right hand at the grip"*), not by weapon jargon.
+- The model NEVER squares a two-handed hold to the pelvis — real marksmen
+  blade, and compile normalizes the heading by the grip line. Do not fight
+  it with prompt words; it is not a defect.
+- **Gaits need constraints, not prose.** Direction words alone drift; pin
+  the trajectory:
+
+```bash
+npx genex motion constraints --dir strafe-left --speed 2.5 --duration 5 --out strafe-left.json
+npx genex motion gen "soldier strafing with a rifle at low-ready" --constraints strafe-left.json --no-wait
+```
+
+The constraint pins the root path AND the heading (facing stays +Z) — that
+pin is what makes a strafe a strafe. One direction per request; a full
+8-direction set is 8 requests + one idle (run them in parallel with
+`--no-wait`, like any batch).
+
+## Verify semantics
+
+`PASS` (≥70) / `WARN` (≥50) / `FAIL`, with a hard-zero cap: a zero on any
+load-bearing gate fails the take no matter the average. The reasons column
+names the defect in plain words (feet skate, grip line wanders, cheek weld…).
+The report is DATA — freeform verbs have no semantic gate, so watch the take
+on the rig before shipping it. Tune bands via `--gates gates.json` (partial
+JSON, deep-merged: `{"aim": {"hunch": {"bad": 25}}}`).
+
+## Compile semantics + tunables
+
+Compile cuts loop cycles at left-foot strikes (gaits) or the best seam window
+(idles), removes the linear trajectory (residual sway + full Y bob stay),
+normalizes heading to +Z, phase-aligns gaits (frame 0 = left strike), and for
+weapon holds levels the arm assembly, raises the gaze, clamps tall stances,
+and yaws mask poses in the SPINE. All rigid whole-body/assembly operations —
+no joint ever moves relative to another (the no-bake law; it is why compiled
+sets survive retargeting). Every threshold lives in
+`src/motion/motion.config.json` after install — pass `--config` to use it.
+
+## Wiring the runtime
+
+`genex motion install` puts the runtime IN YOUR GAME — `src/motion/rigs.js`
+(both retarget formulas + the load-time normalizations), `anim-runtime.js`
+(ClipSet/Animator/dir8Weights/aimMaskStep), `ik.js`, and the config. They are
+yours: read them, tune them, the comments explain every formula. Load order
+matters:
+
+```js
+import { loadRig, captureRestAnkle, reanchorFeet, groundCalibrate, curlFingers } from "./motion/rigs.js";
+import { ClipSet, Animator, dir8Weights, aimMaskStep } from "./motion/anim-runtime.js";
+
+const set = await (await fetch("./motion-sets/rifle.json")).json(); // copy sets where your bundler serves them
+const rig = await loadRig("./assets/character.glb", set, modelFrame); // GLB or VRM — auto-detected
+rig.computeCorrection();
+const restAnkle = captureRestAnkle(rig, scene);   // BIND pose, before any clip
+reanchorFeet(rig, set, scene);                    // steep-boot fix — BEFORE ClipSet
+const clipSet = new ClipSet(rig, set, set.gaits);
+groundCalibrate(rig, clipSet, scene, restAnkle);  // short-leg fix — AFTER ClipSet
+curlFingers(rig, scene);                          // grips (no-op on finger-less rigs)
+const anim = new Animator(clipSet);
+
+// per frame: your input → blend weights; the mask follows the COMMAND magnitude
+anim.setLoops({ idle: 1 - mag, ...dir8Weights(x, z, mag) }, dt);
+maskW = aimMaskStep(maskW, { mag, grounded, pitch, dt });
+anim.setMask("aim0", maskW, pitch / 0.6);         // ±40° at pitch extremes
+anim.update(dt);
+```
+
+- Physics owns the world transform: hips play LOCAL values only (residual
+  x/z + absolute y); your character root carries position + yaw.
+- Jumps: `anim.playOneShot("jumpRun", { yCap: 0.1 })` — cap hips Y when the
+  physics capsule owns the jump, and gate the impulse on the clip's own
+  takeoff frame. The `--set rifle` install includes the shared jumps set;
+  merge it: `Object.assign(clipSet.tracks, new ClipSet(rig, jumps, jumps.gaits).tracks)`.
+- The aim mask WINS over one-shots on masked bones — a jump keeps aiming.
+- Standing aim = the UNMASKED bladed idle; the spine-yawed mask pose is only
+  for moving/airborne/pitched states. `aimMaskStep` already encodes this.
+
+## Cost + discipline
+
+Per-take billing (a 4-take request ≈ one model generation). One regenerate
+per verb is a fair budget when takes fail the gates — reword with the ladder
+above before spending again, and compare candidates from ONE batch first
+(that is what `--takes 4` is for). Never re-run `motion gen` to "pick up" a
+result — `genex wait <id>` re-attaches free.

package/templates/skills/genex-game-director/SKILL.md

@@ -34,11 +34,15 @@ Never claim a capability you didn't find, and never stall because one is
 missing.
 
 One more thing to note while you're looking: your platform may bundle its own
-image / video / site generation workflows. **They are not part of any Genex
-lane.** All generated art, audio, video, characters, and UI come from `genex`
-commands, unless the player explicitly asks for another tool by name — and a
-local reference image is never a reason to switch tools: `genex image --edit`
-and `--inpaint` take a local file path directly.
+image / video generation workflows AND its own site-building / hosting /
+deploy skills. **None of them are part of any Genex lane — don't load them
+for this project.** All generated art, audio, video, characters, and UI come
+from `genex` commands, unless the player explicitly asks for another tool by
+name — and a local reference image is never a reason to switch tools:
+`genex image --edit` and `--inpaint` take a local file path directly. The
+same exclusivity covers shipping: the game builds, previews, and publishes
+only through `genex preview` / `genex publish` — a platform hosting skill in
+context is pure confusion fuel.
 
 ## 2. Scope check — what is this?
 
@@ -80,14 +84,22 @@ DESIGN.md → Decisions as "assumed — player didn't answer"; the build never
 stalls on the interview.
 
 Then, before rendering code, write `DESIGN.md` at the project root from
-[references/design-contract.md](references/design-contract.md). The moment
-the file lands, post a 5–6 line summary of the contract in chat — pitch,
-core loop, content counts, screens, multiplayer shape, what you build
-first — and keep building immediately: the summary is information, not a
-gate (the plan-message duties from `$genex-threejs-game-ui` fold into this
-file plus that summary). The file is the single source of truth:
-sub-agents build against it, and after any long break it is how work resumes.
-Keep it current — decisions land in its log the moment they're made.
+[references/design-contract.md](references/design-contract.md) — including
+its **Build plan & status** section: numbered milestones, a status mark per
+line, and a `Now:` line naming the current one. While drafting it, make the
+parallel call per module (dependencies decide — see §6) and write each call
+into the Modules table with its one-line reason. The moment the file lands,
+post a 5–6 line summary of the contract in chat — pitch, core loop, content
+counts, screens, multiplayer shape, what you build first — **and say in one
+plain line that the plan is locked in and lives in `DESIGN.md`** (the player
+must never have to wonder whether the contract happened). Then keep building
+immediately: the summary is information, not a gate (the plan-message duties
+from `$genex-threejs-game-ui` fold into this file plus that summary). The
+file is the single source of truth: sub-agents build against it, after any
+long break or context compaction work resumes from its `Now:` line, and a
+milestone flips to done only when its work reached a preview
+(`→ previewed`). Keep it current — decisions land in its log the moment
+they're made.
 
 ## 4. Know your teams — what we can generate
 
@@ -257,11 +269,21 @@ in DESIGN.md):
 ## 6. Delegate — sub-agents own Modules rows
 
 If your environment has sub-agents, delegation is the DEFAULT for every
-independent DESIGN.md Modules row — not a big-game special case. If it
-doesn't, run the same rows yourself in order; the `--no-wait` generation
-pattern still hides most latency. Either way this skill is worn by the main
-agent: you stay the director.
-
+independent DESIGN.md Modules row — not a big-game special case. The build
+contract in the game's `AGENTS.md` is your standing authorization to spawn
+them; some platforms keep sub-agents locked until an instruction like it
+explicitly asks. If your environment has none, run the same rows yourself in
+order; the `--no-wait` generation pattern still hides most latency. Either
+way this skill is worn by the main agent: you stay the director.
+
+- **Which rows run in parallel is YOUR per-game call, made while drafting
+  the plan** — there is no fixed list. Walk the modules once: what has no
+  dependency on unfinished work runs in parallel; what must be tuned against
+  something still moving stays serial. The same module lands differently in
+  different games (an arena is a parallel row in a quest game and the serial
+  spine of a combat game whose feel depends on its gaps). Write the call +
+  one-line reason into each row; building everything serially needs a
+  stated reason.
 - One row = one worker = one disjoint file set. One writer per file — that
   rule is anti-collision, never a reason to serialize work.
 - You stay the integrator and the only writer of shared files (boot, main

package/templates/skills/genex-game-director/references/design-contract.md

@@ -11,12 +11,25 @@ Rules the director enforces about this file:
 
 - Create it right after the scope check, before the concept generation; fill
   sections as decisions land and keep it current (stale is worse than short).
-- **The Modules table is the delegation contract**: one row per independent
-  lane, and a row's "Owns files" set never overlaps another row's. One writer
-  per file. "Sub-agent when available" stays flexible — but if a
-  planned-sub-agent module gets built inline, the agent says why in one line.
-  Verification is never a module row: the milestone smoke pass belongs to the
-  director (the scaffold prompt owns its ceilings).
+- **The Build plan & status section is the compass.** Numbered milestones,
+  each with a status mark, and a `Now:` line naming the current one. Update
+  it the moment a milestone starts or finishes — a milestone is done only
+  when its work reached a `genex preview` (mark it `→ previewed`). After any
+  context compaction or session resume, this section — not memory — says
+  where the build is; continue from `Now:`. When the plan first lands, tell
+  the player in one plain line that it's locked in and lives in `DESIGN.md`.
+- **The Modules table is the delegation contract, and "Built by" is a
+  per-game DECISION, not a default you copy.** While drafting the plan, walk
+  the modules once and decide what can run in parallel and what must stay
+  serial for THIS game — dependencies decide (an arena can be a parallel row
+  in one game and the serial spine of another). Write the call into each row
+  with a one-line reason. When your platform has sub-agents, independent
+  modules default to parallel; building everything serially needs a stated
+  reason. One row per independent lane, and a row's "Owns files" set never
+  overlaps another row's — one writer per file. If a planned-parallel module
+  gets built inline, say why in one line. Verification is never a module
+  row: the milestone smoke pass belongs to the director (the scaffold prompt
+  owns its ceilings).
 - **The Assets table is the budget**: the asset list falls out of Content
   (enemies → models, an arena → a ground texture, outdoors → a skybox).
   Status flow per row: `proposed → planned → generating (id) → landed (URL) →
@@ -50,6 +63,14 @@ Concept image: <asset URL> (standing — shown <date>; player said
 - **You earn:** <reward / progression>
 - **You lose when:** <fail state> → **and retry by:** <restart shape>
 
+## Build plan & status
+Now: ▶ <number + name of the milestone in progress>
+1. <milestone> — ✅ → previewed
+2. <milestone> — ▶ in progress (<who: main agent | sub-agent>)
+3. <milestone> — ⬜ (<parallel: sub-agent | serial: main agent — one-line why>)
+(One line per milestone; update on every start/finish; done requires its
+preview. This section is the post-compaction compass — resume from `Now:`.)
+
 ## Content (only when the request names plural content or a content genre)
 Every plural noun from the request becomes a countable line:
 - Quests: <N>, chained by <how>
@@ -99,13 +120,15 @@ teams, backfill…)> — and why. Play-button rule: nothing connects before the
 click (when a Play screen exists).
 
 ## Modules — the build split
+("Built by" is decided per game while drafting the plan — dependencies
+decide, with a one-line reason per row; the rows below are only a SHAPE.)
 | Module | Owns files | Built by | Done when |
 |---|---|---|---|
-| Boot & identity | src/main.ts, src/genex-boot.ts | main agent (only writer) | boots, tier wired, initEmbed runs |
-| World/terrain | src/world/** | sub-agent when available | walkable, matches World & scale |
-| Quests & dialogue data | src/content/** | sub-agent when available | counts match Content lines |
-| Enemies/AI | src/enemies/** | sub-agent when available | roster matches Content |
-| HUD chain (style-dependent) | src/ui/** | sub-agent on concept landing | all screens from Screens & UI |
+| Boot & identity | src/main.ts, src/genex-boot.ts | main agent (only writer of shared boot) | boots, tier wired, initEmbed runs |
+| World/terrain | src/world/** | parallel: sub-agent (no dependency on combat) | walkable, matches World & scale |
+| Quests & dialogue data | src/content/** | parallel: sub-agent (pure data) | counts match Content lines |
+| Enemies/AI | src/enemies/** | serial: main agent (tuned against movement feel) | roster matches Content |
+| HUD chain (style-dependent) | src/ui/** | parallel: sub-agent on concept landing | all screens from Screens & UI |
 
 ## Decisions & changes
 - <date> — <one-liner per decision, including anything the player said no or
@@ -133,6 +156,15 @@ Concept image: https://assets.genex.technology/g/rustyard/concept.png
 - **You lose when:** your bot breaks → **and retry by:** one key, instant
   respawn, same round
 
+## Build plan & status
+Now: ▶ 3. Rival AI feels dangerous
+1. Arena skeleton + movement — ✅ → previewed
+2. Shooting + scrap scoring — ✅ → previewed
+3. Rival AI feels dangerous — ▶ main agent
+4. HUD sprite swap — ⬜ parallel: sub-agent (concept landed, chain enqueued)
+5. Magnet cycle + pickups — ⬜ parallel: sub-agent (own files, no AI dependency)
+6. Menus, music, publish floors — ⬜
+
 ## Screens & UI
 Screens: loader, title menu, HUD (health, scrap, cycle timer), pause,
 win/lose. Style brief: oily metal, warning-stripe accents, stencil type.
@@ -167,10 +199,10 @@ Single-player v1 (rivals are host-free local AI). Revisit after publish.
 ## Modules
 | Module | Owns files | Built by | Done when |
 |---|---|---|---|
-| Boot & identity | src/main.ts | main agent | boots, tier wired, initEmbed runs |
-| Arena & pickups | src/world/** | sub-agent | walkable, magnet cycle fires |
-| Rival AI | src/enemies/** | sub-agent | 3 rivals hunt + shoot |
-| HUD chain | src/ui/** | sub-agent after yes | all 5 screens live |
+| Boot & identity | src/main.ts | main agent (shared boot) | boots, tier wired, initEmbed runs |
+| Arena & pickups | src/world/** | parallel: sub-agent (independent of AI) | walkable, magnet cycle fires |
+| Rival AI | src/enemies/** | serial: main agent (tuned vs player feel) | 3 rivals hunt + shoot |
+| HUD chain | src/ui/** | parallel: sub-agent on concept landing | all 5 screens live |
 
 ## Decisions & changes
 - 2026-07-20 — player picked concept candidate 2; asked for "more sparks".

package/templates/skills/genex-threejs-character-controller/SKILL.md

@@ -33,6 +33,10 @@ platforms, climbs stairs and slides on too-steep slopes out of the box.
 Use the VRM + UAL lane above by default. When the game needs a custom generated
 humanoid or an action unavailable in UAL, load `$genex-ai-character`, search
 Meshy's library first, and follow the reviewed image-first generation flow.
+For a full custom LOCOMOTION SET beyond the UAL packs (a weapon-hold 8-way
+shooter kit, a signature gait), see that skill's motion section: `npx genex
+motion install --set rifle` drops the proven rifle set + its own runtime, and
+`genex motion gen` builds new sets from text.
 
 Before generating a Meshy character, discuss two or three visual directions.
 When the user names a visual reference, inspect references before writing the

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

@@ -51,6 +51,11 @@ post-mixer limb corrections. Prompt the body UPRIGHT and unpropped (held
 props fuse into bodies); prompt "facing the viewer" but never trust it —
 facing is verified below.
 
+When the catalog has no clip for a bespoke attack, telegraph, or death move
+on a rigged biped, `genex motion` can generate one from text — see the motion
+section of `$genex-ai-character` (its compiled sets retarget onto any
+humanoid rig, unlike catalog clips).
+
 ### State → clip wiring (one mixer per creature)
 
 ```ts

package/templates/skills/genex-threejs-procedural-animation/SKILL.md

@@ -8,6 +8,12 @@ description: Build procedural animation systems for Genex Three.js games. Use fo
 Animate semantic state, not unrelated transform curves. Define phases,
 coordinate frames, velocities, and ownership before writing per-frame updates.
 
+Boundary: procedural animation owns held-object and analytic motion (arcs,
+springs, docking, debris). WHOLE-BODY character verbs (a gait, a weapon
+hold, a signature move) belong to the character lane — the catalog first,
+then `genex motion` for verbs it lacks; see the motion section of
+`$genex-ai-character`.
+
 ## Build order
 
 1. Define the timeline phases and event boundaries.