@genex-ai/cli-demo 0.63.0-dev.152 → 0.64.0-dev.154

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@genex-ai/cli-demo",
-  "version": "0.63.0-dev.152",
+  "version": "0.64.0-dev.154",
   "description": "Set up your project's agent workspace (.claude/.codex/.cursor in the game folder), authorize, create a game project, generate AI assets, and publish (genex CLI).",
   "type": "module",
   "bin": {

package/templates/controllers/character/meshy/meshy-loader.ts

@@ -34,9 +34,18 @@ export interface MeshyCharacterManifest {
     provider: "meshy";
     aiModel: "meshy-6";
     apiVersion?: string;
+    meshyApiVersion?: string;
     poseMode: "a-pose" | "t-pose";
     shouldRemesh: boolean;
     targetPolycount: number;
+    conceptModel?: string;
+    conceptGenerationId?: string;
+    conceptCandidate?: number;
+    sourceFaceCount?: number;
+    remeshTargetFaceCount?: number;
+    remeshActualFaceCount?: number;
+    remeshTopology?: "triangle";
+    previewGenerationId?: string;
   };
   model: {
     url: string;

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

@@ -12,33 +12,83 @@ crossfades, transition rules, and multiplayer authority contract.
 
 ## Generate a controller-ready character
 
+Before generating a Meshy character, discuss two or three visual directions.
+When the user names a visual reference, inspect references before writing the
+concept prompt. Recommend a neutral A-pose for characters that will be rigged.
+Ask which equipment and color direction matter, and explain that every
+riggable concept uses that neutral pose instead of an action pose.
+
+Generate exactly three concept candidates for the chosen direction. Lock all
+three to a neutral A-pose: never use a dynamic concept pose. Warn before
+generation when held, slung, or overlapping props, straps, clothing, or gear
+may fuse into the body or obscure a limb; recommend generating gameplay props
+separately.
+
 ```bash
 npx genex character "stylized desert courier, practical layered clothing"
 ```
 
-The default request uses Meshy 6 to generate, texture, remesh, and rig an
-A-pose humanoid. It generates the required controller-pack actions for that
-candidate and rejects bad structural or native motion instead of repairing it.
-If any required check fails, it retries the complete workflow once in a strict
-T-pose; optional actions start only after a full candidate passes. It remeshes
-and rigs the accepted model, adds the immutable preview-reviewed neutral-v3
-idle/walk/run/crouch/jump controller pack,
-and stores every successful model
-and clip at permanent Genex asset URLs. It prints the complete Genex-credit
+Generate concept images first and show the actual images to the user. Do not
+start Image-to-3D until the user explicitly selects a candidate.
+
+Open or link all three real candidate images, then wait for the user's choice.
+Do not treat a text description, task ID, filename, or your own preference as
+approval. Continue with the selected candidate only:
+
+```bash
+npx genex character preview <concept-id> --candidate <1|2|3> --user-approved
+```
+
+Meshy Image-to-3D first produces an unremeshed high-detail model. Show its
+front, back, left, and right views and report its measured face count. Preserve
+that model in R2. Before rigging, ask the user to approve a separate
+10,000-face triangle remesh. The 10k remesh—not the high-detail source—is
+rigged and animated.
+
+The high-detail pre-rig generation stays in the selected neutral A-pose. There
+is no dynamic-pose concept and no silent T-pose fallback. After the user has
+seen the four views and face count, wait for explicit approval and finalize:
+
+```bash
+npx genex character finalize <preview-id> \
+  --user-approved \
+  --approve-remesh 10000 \
+  --animation <action-id>
+```
+
+`--animation` is repeatable. Finalization uses Meshy 6, creates the approved
+10k triangle remesh, rigs it, adds the immutable preview-reviewed neutral-v3
+idle/walk/run/crouch/jump controller pack, and stores the source, remesh, rig,
+and clips at permanent Genex asset URLs. It prints the complete Genex-credit
 quote before enqueueing. The Meshy API key remains server-side; never ask the
 user for one or call Meshy directly from game code.
 
+Meshy's public API performs automatic rigging. The manual joint-marker step
+shown in Meshy Web is not exposed through that API, so do not claim that this
+part of the hosted workflow is reproduced.
+
+The legacy one-shot text workflow is explicit and does not masquerade as the
+reviewed image-first path:
+
+```bash
+npx genex character "compact fantasy knight" --direct-text
+```
+
 Useful options:
 
 ```bash
-npx genex character "compact fantasy knight" --height 1.7 --polycount 40000
-npx genex character "retro space pilot" --animation 466 --no-wait
+npx genex character finalize <preview-id> --user-approved --approve-remesh 10000 --height 1.7
+npx genex character finalize <preview-id> --user-approved --approve-remesh 10000 --animation 466 --no-wait
 npx genex wait <generation-id>
 ```
 
-`--animation <id-or-query>` is repeatable. `--no-controller-pack` deliberately
-omits the default locomotion pack. `--no-wait` returns a generation id for
-`genex wait`; it does not create a second paid request.
+`--animation <id-or-query>` is repeatable on `finalize`.
+`--no-controller-pack` is available only with the explicit `--direct-text`
+compatibility path. The guided parity workflow always installs neutral-v3.
+`--no-wait` returns a generation id for `genex wait`; it does not create a
+second paid request. Never add `--user-approved` until the user has actually
+seen and selected the candidate; never add `--approve-remesh 10000` until they
+have actually seen the four high-detail views and measured face count.
 
 Before handoff, capture idle, walk, run, crouch-idle, crouch-move, and jump.
 Inspect shoulders, elbows, wrists, and hands as well as the feet. Reject
@@ -85,10 +135,12 @@ after preview without asking the player to disable cache.
 `playOneShot()` returns false and emits one warning when a requested clip is
 absent; treat that as an installation failure, not a successful action.
 
-Meshy limb rotations are played unchanged. Never freeze hand tracks or apply
-post-mixer arm, leg, or foot corrections. A bad native rig or clip must be
-rejected and regenerated. Only horizontal root/hip translation is normalized
-so Rapier remains authoritative.
+Meshy limb rotations play unchanged. Never freeze hand tracks or apply
+post-mixer arm, hand, leg, or foot corrections. Only horizontal root or hip
+translation may be normalized for Rapier.
+
+A bad native rig or clip must be rejected and regenerated; validation never
+rewrites limb animation.
 
 A controller pack is an immutable exact action set. If a required binding is
 absent, installation fails instead of substituting Meshy's rig-basic Walking
@@ -108,8 +160,8 @@ durations, nominal speeds, trajectories, and gameplay requirements.
   signature matches. There is no runtime retargeting in this lane.
 - Do not repair hands, arms, or legs at runtime. Verify the installed manifest's
   exact slot-to-action mappings; stop and regenerate when a native pose is bad.
-- Rapier owns the player transform. Animation tracks are normalized
-  horizontally in place; never move the rendered character root separately.
+- Rapier owns the player transform. Only horizontal root or hip translation may
+  be normalized; never move the rendered character root separately.
 - `controller-loop` clips follow controller-local intent and measured speed.
   The state machine crossfades idle, walk, run, jump, directional slots, and
   explicit fallbacks exactly as it does for VRM + UAL.

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

@@ -32,14 +32,33 @@ 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, generate the character, and install it by character ID:
+Meshy's library first, and follow the reviewed image-first generation flow.
+
+Before generating a Meshy character, discuss two or three visual directions.
+When the user names a visual reference, inspect references before writing the
+concept prompt. Recommend a neutral A-pose for characters that will be rigged.
+
+Generate concept images first and show the actual images to the user. Do not
+start Image-to-3D until the user explicitly selects a candidate. All three
+concepts and the selected high-detail pre-rig generation stay in a neutral
+A-pose; never use a dynamic concept pose or silently substitute a T-pose. Warn
+that held, slung, or overlapping props and straps can fuse into the body or
+obscure limbs, and recommend separate gameplay props.
 
 ```bash
 npx genex animations search "rifle reload" --json
-npx genex character "stylized sci-fi courier, practical clothing" --animation 466
+npx genex character "stylized sci-fi courier, practical clothing"
+npx genex character preview <concept-id> --candidate <1|2|3> --user-approved
+npx genex character finalize <preview-id> --user-approved --approve-remesh 10000 --animation 466
 npx genex controller character --character <character-id>
 ```
 
+Meshy Image-to-3D first produces an unremeshed high-detail model. Show its
+front, back, left, and right views and report its measured face count. Preserve
+that model in R2. Before rigging, ask the user to approve a separate
+10,000-face triangle remesh. The 10k remesh—not the high-detail source—is
+rigged and animated.
+
 That is a separate, **same-rig Meshy-native lane**. Its animation-only GLBs are
 accepted only when their skeleton signature matches the active character
 revision; this lane does no runtime retargeting. The shared ECCTRL-derived
@@ -52,12 +71,12 @@ after preview without asking the player to disable cache. `playOneShot()`
 returns false and emits one warning when a requested clip is absent; treat
 that as an installation failure, not a successful action.
 
-Meshy limb rotations are played unchanged. Never freeze hand tracks or apply
-post-mixer arm, leg, or foot corrections. A bad native rig or clip must be
-rejected and regenerated. Only horizontal root/hip translation is normalized
-so Rapier remains authoritative. A controller pack is an immutable exact
-action set: if a required binding is absent, installation fails instead of
-substituting Meshy's rig-basic Walking or Running animation.
+Meshy limb rotations play unchanged. Never freeze hand tracks or apply
+post-mixer arm, hand, leg, or foot corrections. Only horizontal root or hip
+translation may be normalized for Rapier. A bad native rig or clip must be
+rejected and regenerated. A controller pack is an immutable exact action set:
+if a required binding is absent, installation fails instead of substituting
+Meshy's rig-basic Walking or Running animation.
 
 Because these files are game-owned, never run `genex controller character --force` over an edited
 fork as a migration strategy. Install a fresh copy elsewhere and port only the named changes.
@@ -204,6 +223,9 @@ npx genex controller anims sword pistol        # a sword+shooter game
 npx genex controller anims stealth climb crawl # a ninja game
 npx genex controller anims --list              # browse tags; --list <tag> for per-clip details
 npx genex animations search "rifle reload" --json
+npx genex character "stylized sci-fi courier, practical clothing"
+npx genex character preview <concept-id> --candidate <1|2|3> --user-approved
+npx genex character finalize <preview-id> --user-approved --approve-remesh 10000
 npx genex character animate <character-id> --action <action-id>
 npx genex controller character --character <character-id> # refresh the manifest
 ```
@@ -217,9 +239,12 @@ slots, fallbacks, and cadence data. UAL clips still land in
 genre hints, `playOneShot` options, overrides, foot IK, and remote-player
 animation.
 
-For Meshy characters, do not repair hands, arms, or legs at runtime. Verify
-that the installed manifest binds the expected action IDs; if a native pose
-is bad or a required binding is missing, stop and regenerate the character.
+For Meshy characters, do not repair hands, arms, or legs at runtime. Meshy limb
+rotations play unchanged. Never freeze hand tracks or apply post-mixer arm,
+hand, leg, or foot corrections. Only horizontal root or hip translation may be
+normalized for Rapier. Verify that the installed manifest binds the expected
+action IDs; if a native pose is bad or a required binding is missing, stop and
+regenerate the character.
 
 ## Crouch (built in)
 

package/templates/skills/genex-threejs-character-controller/references/animations.md

@@ -82,15 +82,25 @@ the time scale so slow motion doesn't pop).
 Use this lane when a game needs a custom generated humanoid or catalog depth
 that the personal-VRM library does not cover: sports, dance, tactical actions,
 prop interactions, or authored traversal. Load `$genex-ai-character`, search
-first, generate the controller-ready character, and add exact action IDs:
+first, then use the reviewed concept → high-detail preview → approved 10k
+triangle-remesh flow before adding exact action IDs:
 
 ```bash
 npx genex animations search "rifle reload" --json
-npx genex character "stylized sci-fi courier, practical clothing" --animation 466
+npx genex character "stylized sci-fi courier, practical clothing"
+npx genex character preview <concept-id> --candidate <1|2|3> --user-approved
+npx genex character finalize <preview-id> --user-approved --approve-remesh 10000 --animation 466
 npx genex character animate <character-id> --action <action-id>
 npx genex controller character --character <character-id>
 ```
 
+All three concepts and the selected high-detail model use a neutral A-pose.
+The high-detail source is preserved in R2 and shown from front, back, left, and
+right with its measured face count before the user is asked to approve the
+separate 10,000-face triangle remesh. Only that remesh is rigged and animated.
+Held, slung, or overlapping props can fuse into the body or hide limbs; warn
+before generation and prefer separate gameplay props.
+
 Search output exposes the numeric action ID, stable key, preview, loop mode,
 motion policy, controller slots, gameplay requirements, review status, and
 estimated cost. Use a returned ID; do not guess from a name. Search is free and
@@ -119,8 +129,9 @@ const anims = new CharacterAnimations(native.scene, native.clips, {
 
 During Meshy validation, record the action ID actually bound to every slot.
 A public preview is not evidence when the game is playing a different clip or
-a rig-basic fallback. The native loader plays every limb quaternion unchanged;
-never freeze hand tracks or add post-mixer arm, leg, or foot corrections.
+a rig-basic fallback. Meshy limb rotations play unchanged. Never freeze hand
+tracks or apply post-mixer arm, hand, leg, or foot corrections. Only horizontal
+root or hip translation may be normalized for Rapier.
 
 The loader rejects clips whose manifest skeleton signature differs from the
 current model revision or whose tracks target missing bones. This is deliberate

package/templates/skills/genex-threejs-skill-router/SKILL.md

@@ -17,7 +17,7 @@ map, execution order, and acceptance gate.
 | --- | --- |
 | shot composition, chase/side/orbit rigs, camera handoffs, projection ownership, pointer look, mouse-aimed action (shooter, FPS/first-person, sniper, turret, crosshair/reticle), mouse-look, floating origins | `$genex-threejs-camera-direction` |
 | on-foot player movement: walk/run/jump/crouch, third-person character, slopes, stairs, moving platforms, personal VRM animation, directional locomotion, transitions, action motion | `$genex-threejs-character-controller` |
-| a custom generated playable humanoid or Meshy animation coverage beyond UAL: search, generate, rig, add exact action IDs, install the same-rig adapter | `$genex-ai-character` + `$genex-threejs-character-controller` |
+| a custom generated playable humanoid or Meshy animation coverage beyond UAL: reference-informed A-pose concepts, explicit candidate + 10k-remesh approvals, exact action IDs, same-rig adapter | `$genex-ai-character` + `$genex-threejs-character-controller` |
 | the player drives or flies something: cars, drones, vehicle physics, gearbox, enter/exit between character and vehicle | `$genex-threejs-vehicle-controllers` |
 | playable on phones: touch/mobile input for any game — joystick, virtual buttons, drag zones, per-genre touch recipes, rotate-device overlay — wired by default for every NEW game when a recipe fits (skip with a one-line reason) | `$genex-threejs-touch-controls` |
 | anything falls, collides, gets pushed, or needs physics: Rapier world setup, colliders for meshes and GLBs, collision events | `$genex-threejs-physics-rapier` |
@@ -60,11 +60,31 @@ leaderboards. Multiplayer auth (`getColyseusAuth`) comes from it too.
 
 **Character-animation routing:** use the existing VRM + UAL character
 controller by default. Use `npx genex character` when the game needs a custom
-generated humanoid or an action unavailable in UAL. Load `$genex-ai-character`,
-search Meshy actions first with `npx genex animations search "<intent>" --json`,
-and use returned action IDs; never invent IDs or move the visual root. In both
-lanes, the ECCTRL-derived character controller owns collision and world
-translation.
+generated humanoid or an action unavailable in UAL. Before generating a Meshy
+character, discuss two or three visual directions. When the user names a visual
+reference, inspect references before writing the concept prompt. Recommend a
+neutral A-pose for characters that will be rigged.
+
+Generate concept images first and show the actual images to the user. Do not
+start Image-to-3D until the user explicitly selects a candidate. Generate
+exactly three concepts, all neutral A-pose; never use a dynamic concept pose or
+silently fall back to T-pose. Warn that held, slung, or overlapping props and
+straps can fuse into the body or obscure limbs, and recommend separate gameplay
+props.
+
+Meshy Image-to-3D first produces an unremeshed high-detail model. Show its
+front, back, left, and right views and report its measured face count. Preserve
+that model in R2. Before rigging, ask the user to approve a separate
+10,000-face triangle remesh. The 10k remesh—not the high-detail source—is
+rigged and animated. Keep every pre-animation generation in the selected
+neutral A-pose.
+
+Load `$genex-ai-character`, search Meshy actions first with
+`npx genex animations search "<intent>" --json`, and use returned action IDs;
+never invent IDs. Meshy limb rotations play unchanged. Never freeze hand tracks
+or apply post-mixer arm, hand, leg, or foot corrections. Only horizontal root
+or hip translation may be normalized for Rapier. In both lanes, the
+ECCTRL-derived character controller owns collision and world translation.
 
 **UI is mandatory routing:** every game has an interface — load
 `$genex-threejs-game-ui` for every NEW game and run its "Plan the UI first" gate

package/templates/skills/genex-threejs-skill-router/references/routing-map.md

@@ -145,7 +145,19 @@ Three.js release or branch, and do not blindly copy demo architecture.
    `$genex-threejs-physics-rapier` when anything falls, collides, or gets
    pushed; on-foot movement via `$genex-threejs-character-controller`;
    driving/flying and character↔vehicle enter/exit via
-   `$genex-threejs-vehicle-controllers`.
+   `$genex-threejs-vehicle-controllers`. For a custom Meshy player, load
+   `$genex-ai-character` and keep the generation decisions ahead of wiring:
+   discuss two or three visual directions, inspect any user-named references,
+   then generate and show exactly three neutral-A-pose concepts. Wait for an
+   explicit candidate selection before Image-to-3D. Warn that held, slung, or
+   overlapping props and straps may fuse into the body or hide limbs. Keep the
+   selected high-detail pre-rig output in neutral A-pose, preserve it in R2,
+   show front/back/left/right views plus its measured face count, and wait for
+   explicit approval of the separate 10,000-face triangle remesh. Only the 10k
+   remesh is rigged and animated; there is no dynamic concept pose or silent
+   T-pose fallback. Meshy limb rotations remain unchanged—never freeze or
+   correct arm, hand, leg, or foot tracks. Only horizontal root or hip
+   translation may be normalized for Rapier.
 6. Select the minimum scene-generation skills: geometry, materials, vegetation,
    architecture, planets, water, precipitation, clouds, or VFX. Show the
    planned loader from the very first asset load — a player must never stare

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

@@ -22,6 +22,35 @@ Read [references/visual-validation.md](references/visual-validation.md)
 for visual contracts, required inspection controls, mechanism-specific
 evidence, temporal checks, budgets, and explicit rejection criteria.
 
+## Meshy character approval evidence
+
+Before generating a Meshy character, discuss two or three visual directions.
+When the user names a visual reference, inspect references before writing the
+concept prompt. Recommend a neutral A-pose for characters that will be rigged.
+
+Generate concept images first and show the actual images to the user. Do not
+start Image-to-3D until the user explicitly selects a candidate. Validation
+must show all three actual concept images, confirm that every candidate uses a
+neutral A-pose, and preserve the user's explicit candidate selection. A task
+ID, filename, or agent summary is not visual evidence. Dynamic concept poses
+and silent T-pose fallbacks fail this checkpoint. Warn when held, slung, or
+overlapping props or straps can fuse into the character or hide a limb.
+
+Meshy Image-to-3D first produces an unremeshed high-detail model. Show its
+front, back, left, and right views and report its measured face count. Preserve
+that model in R2. Before rigging, ask the user to approve a separate
+10,000-face triangle remesh. The 10k remesh—not the high-detail source—is
+rigged and animated.
+
+The selected high-detail model remains in a neutral A-pose before animation.
+Record evidence that the user saw its four views and face count before
+`--approve-remesh 10000` was used. Historical Meshy characters remain valid;
+do not demand a silent regeneration or upgrade.
+
+Meshy limb rotations play unchanged. Never freeze hand tracks or apply
+post-mixer arm, hand, leg, or foot corrections. Only horizontal root or hip
+translation may be normalized for Rapier.
+
 ## Interaction smoke check (the game fast path)
 
 For plain game tasks — nothing from the procedural/visual-system pack loaded —
@@ -56,7 +85,9 @@ everything twice.
    locomotion continues normally.
    During Meshy validation, record the action ID actually bound to every slot.
    A public preview is not evidence when the game is playing a different clip
-   or a rig-basic fallback. Do not repair hands, arms, or legs at runtime: if a
+   or a rig-basic fallback. Meshy limb rotations play unchanged. Never freeze
+   hand tracks or apply post-mixer arm, hand, leg, or foot corrections. Only
+   horizontal root or hip translation may be normalized for Rapier. If a
    native pose is bad or a required binding is missing, stop and regenerate.
 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

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

@@ -73,6 +73,27 @@ its identity and every deliberate divergence in backend, resolution, asset,
 scale, or composition. Do not substitute a generic category match for the
 specific visual contract.
 
+For a Meshy player character, the pre-animation sign-off record additionally
+contains:
+
+```text
+two or three discussed visual directions
+the inspected references, when the user named one
+three actual concept-image URLs, all neutral A-pose
+the user's selected candidate
+high-detail source URL in R2
+front / back / left / right high-detail views
+measured high-detail face count
+the user's explicit approval of the separate 10,000-face triangle remesh
+```
+
+Do not accept a dynamic-pose concept, a silent T-pose fallback, or a rig built
+from the unremeshed high-detail source. Warn before generation when held,
+slung, or overlapping props and straps can fuse into the body or hide limbs.
+Animation naturally leaves the A-pose; its limb rotations remain native.
+Never freeze or correct arm, hand, leg, or foot tracks. Only horizontal root or
+hip translation may be normalized for Rapier.
+
 ## Required inspection controls
 
 Any runnable inspection surface should expose the controls relevant to its