@genex-ai/cli-demo 0.68.0-dev.174 → 0.69.0-dev.175

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@genex-ai/cli-demo",
-  "version": "0.68.0-dev.174",
+  "version": "0.69.0-dev.175",
   "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/skills/genex-threejs-camera-direction/SKILL.md

@@ -35,9 +35,12 @@ rules, floating-origin shot, pointer controls, and implementation limits.
 
 ## Aiming and pointer lock
 
-On the bundled `FollowCamera`, **pointer-lock aim is ON by default** on desktop:
-a click locks the pointer and raw mouse movement drives the view. You rarely turn
-it on — you decide whether to turn it OFF. Name the bucket in the build plan:
+The rule is binary: during play, **the cursor is either a gameplay tool or it is
+locked away**. An OS arrow parked over the action in a game that never uses it is
+a shipped defect, not a default. On the bundled `FollowCamera`, pointer-lock aim
+is ON by default on desktop — a click locks the pointer and raw mouse movement
+drives the view — so mostly you decide whether to turn it OFF. Name the bucket in
+the build plan:
 
 - **MANDATORY** — first-person of any kind (FPS, walking sim, horror) and any
   mouse-aimed action (third-person shooter, turret/range). Lock is on by default;
@@ -47,11 +50,16 @@ it on — you decide whether to turn it OFF. Name the bucket in the build plan:
   `genex controller character` game). On by default; leave it on. Opt out with
   `pointerLockAim: false` only for a stated reason (a cursor-heavy UI at the core
   of play).
-- **NEVER** — cursor-core games (top-down click-to-move, tower defense, builders,
-  card/board/puzzle) and spectator/orbit showcases. These **must pass
-  `pointerLockAim: false`** — otherwise the bundled camera grabs the cursor on the
-  first click. (Touch needs nothing: pointer lock doesn't exist there and the mode
-  no-ops on coarse pointers.)
+- **Keyboard-driven games lock too** — a racer, platformer, or runner that never
+  reads the mouse still locks the pointer on the play/Start click: the cursor is
+  not a tool there, so lock it away (hidden cursor, no stray clicks, Esc = pause
+  as usual). Bundled-controller games get this for free; a hand-rolled game uses
+  the minimal lock recipe in `$genex-threejs-game-ui` (~6 lines).
+- **NEVER** — cursor-core games where the pointer IS the gameplay tool (top-down
+  click-to-move, tower defense, builders, card/board/puzzle) and spectator/orbit
+  showcases. These **must pass `pointerLockAim: false`** — otherwise the bundled
+  camera grabs the cursor on the first click. (Touch needs nothing: pointer lock
+  doesn't exist there and the mode no-ops on coarse pointers.)
 
 **Mechanism — games on the bundled controller (most games):** do NOT hand-roll
 lock handling. Aim is already enabled; the kit ships a ready-made cue overlay —
@@ -113,6 +121,36 @@ grants the permission.
 (trackpad "natural scrolling" only flips the wheel). If look feels inverted it's a
 sign bug in the rig, not a device quirk — fix the sign, don't sniff the trackpad.
 
+## The screen-direction contract
+
+Every input axis has one correct on-screen direction, for every rig, bundled or
+hand-rolled. These four invariants are testable and non-negotiable:
+
+1. Mouse/touchpad RIGHT turns the view right; mouse UP looks up (down only behind
+   an explicit invert option the player chose).
+2. `KeyD`/ArrowRight moves or turns the player toward screen-RIGHT; `KeyA`/
+   ArrowLeft toward screen-left. Same for a touch stick's +x.
+3. Drag-pan picks ONE convention — grab-the-world (terrain follows the pointer)
+   or move-the-camera — and BOTH axes obey it. One axis each is the
+   "diagonals feel twisted" bug.
+4. See the OS-setting note above: inversion is always your sign, never the device.
+
+The formula that settles every sign argument: `screenRight = cross(cameraForward, worldUp)`.
+For a Y-up world and forward `(sin yaw, 0, cos yaw)`, screen-right is
+`(-cos yaw, 0, sin yaw)`. **Warning — `(cos yaw, 0, -sin yaw)` is the LEFT
+vector** (that's `cross(worldUp, cameraForward)`), and writing it as "right" is
+the single most-shipped direction bug in generated games: two independent
+projects inverted their A/D exactly this way. Related trap: positive
+`rotation.y` turns a +Z-facing object toward +X, which is screen-LEFT from a
+chase camera behind it — so "positive yaw = turn right" is false in this basis.
+
+Never derive signs by intuition — intuition about right-handed frames is wrong
+about half the time and has been wrong in every shipped instance. Copy a
+verified pair (sign AND basis together) from
+[references/camera-rigs.md](references/camera-rigs.md), then confirm with the
+input-direction part of the smoke check: hold D and watch which way the world
+answers.
+
 ## Non-negotiable rules
 
 - Use subject dimensions to derive offsets; do not tune one fixed distance for
@@ -122,6 +160,8 @@ sign bug in the rig, not a device quirk — fix the sign, don't sniff the trackp
 - During an explicit handoff, use one interpolation stage. Do not stack a
   transition blend and a second follow smoother over the same interval.
 - Re-sync yaw/pitch from the camera when pointer lock is acquired.
+- Hand-rolled steering/pan/look math copies a verified basis from the reference
+  and passes the input-direction check — signs are never derived by intuition.
 - Update the projection matrix whenever FOV, near, far, or aspect changes.
 - Keep stars or infinite backgrounds camera-relative when large translation
   would create false parallax or precision loss.

package/templates/skills/genex-threejs-camera-direction/references/camera-rigs.md

@@ -11,6 +11,7 @@ Use this reference for scale-aware chase, side, orbit, authored-shot, pointer-lo
 - Explicit camera handoffs
 - cinematic implementation shot ownership
 - Pointer-look and movement constraints
+- Verified screen-direction bases
 - Floating origin and background handling
 - Projection and lifecycle ownership
 - Failure modes and diagnostics
@@ -166,6 +167,9 @@ yaw -= mouseDeltaX * 0.0022
 pitch -= mouseDeltaY * 0.0018
 ```
 
+Expected on screen: mouse-right orbits the view right, mouse-up tilts it up —
+verify both axes against the screen-direction contract before retuning the scales.
+
 Pitch bounds vary by flight mode. The implementation also enforces camera height above
 the ship:
 
@@ -281,6 +285,9 @@ distance = movementSpeed * dt
 
 Default speed is `9`, sensitivity `0.0023`.
 
+Expected on screen: mouse-right turns the view right, mouse-up looks up — assert
+both axes (yaw-only evidence has let inverted pitch ship).
+
 Keys are cleared on:
 
 - pointer-lock exit;
@@ -295,6 +302,61 @@ Scene-specific constraints then run after controls:
 
 Input control and spatial constraint are separate layers.
 
+## Verified screen-direction bases
+
+Copy these pairs whole — the sign and the basis are only correct TOGETHER. Each
+was derived from `screenRight = cross(cameraForward, worldUp)` and verified
+against the on-screen result; if you change one half, re-verify with the
+input-direction check instead of reasoning about it.
+
+**Chase-cam steering** (vehicle/character heading, camera behind):
+
+```text
+heading  = (sin yaw, 0, cos yaw)          // matches rotation.y for a +Z-front model
+yaw     -= steer * rate * dt              // steer: D/right = +1, A/left = -1
+position += heading * speed * dt
+camera at position - heading * dist, lookAt(position)
+```
+
+Why the minus: the camera looks along `heading`, so screen-right is
+`cross(heading, up) = (-cos yaw, 0, sin yaw)`, while `d(heading)/d(yaw) =
+(cos yaw, 0, -sin yaw)` — exactly screen-LEFT. Increasing yaw always veers the
+nose left on screen, so "D turns right" needs `yaw -=`. (Equivalently
+`yaw += steer` is correct only with heading `(-sin yaw, 0, cos yaw)` — a pair,
+never a lone sign.)
+
+**RTS / overhead pan camera** (fixed pitch, yaw-orbiting):
+
+```text
+right         = (-cos yaw, 0, sin yaw)    // pitch-independent screen-right on the ground
+forwardGround = (sin yaw, 0, cos yaw)     // into the screen along the ground
+D / ArrowRight: target += right * pan     A / ArrowLeft: target -= right * pan
+W / ArrowUp:    target += forwardGround * pan     S: target -= forwardGround * pan
+```
+
+Drag-pan, grab-the-world (terrain follows the pointer; both axes, one
+convention — `movementY` is positive DOWNWARD):
+
+```text
+target -= right * movementX * k
+target += forwardGround * movementY * k
+```
+
+Move-the-camera convention = flip BOTH signs, never one. The classic shipped bug
+writes `right = (cos yaw, 0, -sin yaw)` — that is `cross(up, forward)`, the LEFT
+vector — inverting A/D and the horizontal drag while W/S stay correct.
+
+**Pointer-look** (locked mouse driving yaw/pitch, Euler order `YXZ`):
+
+```text
+yaw   -= movementX * sensitivity          // mouse-right -> view turns RIGHT
+pitch -= movementY * sensitivity          // mouse-up    -> view tilts UP
+```
+
+Expected on screen, both axes, before any tuning: a straight-ahead landmark
+slides LEFT when the mouse moves right (the view pans right) and slides DOWN
+when the mouse moves up (the view tilts up).
+
 ## Floating origin and background handling
 
 The Saturn scene first computes a virtual camera pose, stores its orientation

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

@@ -37,7 +37,10 @@ no matter how good it looks.
   unlocked drag-to-turn camera feels imprecise no matter how tight the numbers
   are. The bucket rule + the bundled `FollowCamera` aim mode live in
   `$genex-threejs-camera-direction`; on the bundled controller it's ON by default
-  (with a ready-made cue), not hand-rolled events.
+  (with a ready-made cue), not hand-rolled events. Direction is half of it: a
+  movement key or look axis whose on-screen direction contradicts its label is a
+  defect, not a tuning issue — the screen-direction contract and verified bases
+  are in `$genex-threejs-camera-direction`.
 
 ## Movement: snappy beats realistic
 

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

@@ -250,8 +250,15 @@ document.addEventListener("keydown", (e) => {
   so ALSO keep the pointer-lock-loss → pause path (`pointerlockchange`: if
   unlocked while `playing`, `setPhase("paused")`). Escape then always pauses; it
   only *also* drops fullscreen on browsers without the lock — unavoidable there.
-- **Only for immersive/pointer-lock games.** A top-down or menu-driven game never
-  captures the mouse and has no window to shrink — skip all of this.
+- **Skip Keyboard Lock + fullscreen only when the cursor stays a tool.**
+  Cursor-core / top-down / menu-driven games never capture the pointer — skip
+  `enterImmersive` and Keyboard Lock entirely. But ANY game that locks the
+  pointer during play — aim games AND keyboard-only racers/platformers/runners
+  under the lock-or-tool rule (next section) — keeps the Escape → pause path and
+  the `pointerlockchange` fallback (if unlocked while `playing`, pause): without
+  it, Esc frees the cursor while the game keeps running. Keyboard-only games may
+  still skip Keyboard Lock + fullscreen; the lock + pause/resume path is the
+  non-negotiable part.
 - **Dashboard embed:** no setup needed — the platform's game frame grants keyboard
   lock (and pointer lock + fullscreen), so Escape-to-pause works the same inside
   `/world/` + `/draft/` as it does standalone (`<slug>.genex.technology`).
@@ -261,6 +268,28 @@ menu — trackpads feel slower than mice, so let the player tune it. On the bund
 camera the setter is live: `slider.oninput = () => { followCam.aimSensitivity = +slider.value; };`
 (radians per pixel; default `0.0023`, a usable range is ~`0.0008`–`0.005`).
 
+## The cursor during play: locked or a tool
+
+During play the OS cursor is either the gameplay tool (cursor-core: click-to-move,
+tower defense, builders, card/board — it stays visible, that's correct) or it is
+**locked away — including keyboard-only games** (racer, platformer, runner): an
+arrow parked over the action for the whole session is a shipped defect. Games on
+the bundled `FollowCamera` get the lock free (on by default). A hand-rolled game
+locks with ~6 lines, reusing this section's Escape flow:
+
+```ts
+// In the Play/Start/Resume CLICK handler (lock needs a user gesture):
+canvas.requestPointerLock?.();          // hides the cursor, focuses the game
+// Already in the Escape recipe above: pointerlockchange → if unlocked while
+// playing, pause; the Resume click re-locks. Keyboard games need nothing more —
+// no reticle, no aim code; the lock just parks the cursor.
+```
+
+If the lock is genuinely unavailable (a third-party embed without
+`allow="pointer-lock"`), fall back to hiding the idle cursor over the canvas:
+`canvas.style.cursor = "none"` after ~2s without `pointermove`, restored
+instantly on move. Menus and pause screens always keep their cursor.
+
 ## The loader
 
 The loader is the first thing every player sees — a bare "Loading… 3/5" over
@@ -399,6 +428,9 @@ architecture and consume the shared style brief.
 - HUD sprites never enqueued at the gate — the placeholder CSS shipped as the
   final HUD.
 - No pause screen, or a pause that isn't bound to Escape.
+- The OS arrow parked over the action for the whole session in a keyboard-driven
+  game (the cursor is either a gameplay tool or locked away — see the cursor
+  section).
 - A style brief whose fonts were never actually loaded (a system-stack display
   font at runtime).
 - A micro-element (reticle, cue, toast, damage number) left as default CSS

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

@@ -15,7 +15,7 @@ map, execution order, and acceptance gate.
 
 | Work needed | Load |
 | --- | --- |
-| 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` |
+| 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, hand-rolled steering/pan/look input signs (screen-direction contract), 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: 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` |
@@ -204,8 +204,16 @@ concept-driven — a richer first build beats a grey-box one.
   drag-orbit (`pointerLockAim: false`) only with a stated reason (e.g. a
   cursor-heavy UI core). **Never** — cursor-core games (click-to-move, tower
   defense, builder, card/puzzle), orbit showcases, touch-only; these MUST pass
-  `pointerLockAim: false`. The mechanism and the full aim contract live in
-  `$genex-threejs-camera-direction`.
+  `pointerLockAim: false`. Keyboard-only games (racer, platformer) lock too —
+  the cursor is either a gameplay tool or locked away during play. The mechanism
+  and the full aim contract live in `$genex-threejs-camera-direction`.
+- Input direction (always — every game that moves with keys or pointer):
+  D/ArrowRight must move or turn the player screen-RIGHT, mouse-right must turn
+  the view right, drag-pan axes share one convention. The screen-direction
+  contract and verified copy-paste bases live in
+  `$genex-threejs-camera-direction` — hand-rolled steering/pan/look math copies
+  one instead of deriving signs, and the smoke check's input-direction pass
+  verifies it.
 - Art direction follows THIS game's concept. The style examples inside skills
   are examples, not defaults — never default to neon/cyberpunk/synthwave (or any
   other single register) unless the concept calls for it.
@@ -222,7 +230,7 @@ concept-driven — a richer first build beats a grey-box one.
 - Use `$genex-threejs-visual-validation` before declaring graphics/procedural-system
   work done. **Game fast path:** for game tasks that loaded no procedural/visual-system
   skill, done = a screenshot plus an interaction smoke check (load the page, press each
-  control, see the visible response) — don't run the full diagnostic gate — PLUS the
+  control, see the visible response in its labeled direction) — don't run the full diagnostic gate — PLUS the
   floors from the routing-map's acceptance gate: the generated sprite HUD wired in
   (not the CSS placeholder), pause on Escape, the branded loader with its key-art
   background, the brief's fonts actually loaded, the renderer baseline + at least one

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

@@ -180,7 +180,10 @@ Three.js release or branch, and do not blindly copy demo architecture.
    (`$genex-threejs-visual-validation` owns the capture discipline).
 7. Add camera direction when framing, controls, transitions, or scale perception
    affect play — or the game aims with the mouse (shooter/FPS/turret): the
-   step-4 bucket decision executes here.
+   step-4 bucket decision executes here. And before ANY hand-rolled
+   steering/pan/look math: the screen-direction contract (D → screen-right,
+   mouse-right → view right, drag axes one convention) with verified copy-paste
+   bases lives there — signs are copied, never derived.
 8. Add procedural animation when object motion needs authored phases,
    convergence, looping, or deterministic timelines.
 9. Add shared fields before writing multiple independent noise layers.
@@ -250,7 +253,7 @@ module — a corrupted entry point costs more than the minutes saved.
 
 **Game fast path:** for a game task that loaded no procedural/visual-system skill,
 done = a screenshot plus an interaction smoke check (load the page, press each
-control, assert a visible response — `$genex-threejs-visual-validation` has the
+control, assert a visible response in its labeled direction — `$genex-threejs-visual-validation` has the
 procedure), **plus the UI floor from `$genex-threejs-game-ui` (the generated
 sprite HUD wired in — not the CSS placeholder — pause on Escape, the branded
 loader with its key-art background, the brief's font pair actually loaded)

package/templates/skills/genex-threejs-touch-controls/SKILL.md

@@ -75,6 +75,10 @@ Pick what matches the game; most games need exactly one or two of these.
   lives on the stick; the static circle is fine for slower games. On the
   bundled character controller, pass it through instead — see
   `$genex-threejs-character-controller` (`joystick: { x: joy.x, y: joy.y }`).
+  Touch axes obey the same screen-direction contract as WASD and the mouse
+  (`$genex-threejs-camera-direction`): stick-right must move the player
+  screen-right, drag-right must turn the view right — a flipped feel is a sign
+  bug in the mapping, never a device quirk.
 - **Camera look → drag zone on the right half.** Default `DragZone()` is
   exactly that; per frame `const { dx, dy } = look.consumeDelta()` then apply
   to yaw/pitch with the same sensitivity scale as the mouse path. Games on the

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

@@ -72,9 +72,17 @@ everything twice.
    skill's "Self-testing a draft" section) — so you see the game, not the
    sign-in gate.
 2. Press each documented control once (keys, pointer); assert a **visible
-   response** to every one — the player moves, the camera turns, the button
-   fires. For an animated character, capture idle, walk, run, crouch-idle,
-   crouch-move, and jump. Inspect shoulders, elbows, wrists, and hands as well
+   response in its labeled direction** — this is the input-direction pass, and
+   it is part of THIS check, not an extra testing loop. Hold `KeyD`/ArrowRight
+   ~0.5s and screenshot-diff: the controlled thing moves or turns toward
+   screen-RIGHT (for a pan camera the viewport slides right — the terrain
+   streams LEFT); `KeyA`/ArrowLeft mirrors it. Keyboard synthesis needs no
+   pointer lock, so this works headless. For drag rigs, drag right AND drag up:
+   both axes must follow the one stated convention (grab-the-world or
+   move-the-camera — never one each). A response in the WRONG direction is a
+   fail, not a note: two shipped games passed "controls respond" while D
+   steered screen-left. For an animated character, capture idle, walk, run,
+   crouch-idle, crouch-move, and jump. Inspect shoulders, elbows, wrists, and hands as well
    as the feet: a fully bound non-T-pose can still be stylistically broken.
    Reject shrugging palms-up poses, permanently raised elbows, or a gait whose
    upper-body style contradicts the requested character. “No T-pose” is not
@@ -104,16 +112,19 @@ everything twice.
    floating above detached wheels means the model was box-fit against the
    preset's wheelbase (the vehicle skill's "Custom generated bodies" rules
    fix it).
-6. Aim games get one extra pass (MANDATORY bucket — first-person or mouse-aimed):
-   state which pointer bucket the game chose; click the canvas and assert the
-   pointer locks (cursor gone, mouse-RIGHT turns the view RIGHT — check the axis,
-   not just that it moves); press Esc and assert the "click to aim/resume" cue
-   appears. The cue should be the bundled `createAimCue` helper (or an equivalent
+6. The cursor pass — every game, per the lock-or-tool rule: during play the OS
+   cursor is either the gameplay tool (cursor-core — confirm the explicit
+   `pointerLockAim: false` opt-out, cursor stays) or it is LOCKED away; a
+   non-cursor-core game with the arrow parked over the action is a defect, even
+   a keyboard-only racer. Aim games additionally: click the canvas and assert
+   the pointer locks (cursor gone, mouse-RIGHT turns the view RIGHT and
+   mouse-UP looks UP — name BOTH axes; yaw-only evidence has let inverted pitch
+   ship); press Esc and assert the "click to aim/resume" cue appears. The cue
+   should be the bundled `createAimCue` helper (or an equivalent
    `onAimChange`-driven overlay) — a MANDATORY-bucket game with no unlocked cue
-   fails. Also confirm a cursor-core game opted OUT (`pointerLockAim: false`) so it
-   isn't grabbing the cursor. Headless caveat: `requestPointerLock` throws in
-   headless Chromium — assert the wiring and the unlocked cue in a screenshot, and
-   say plainly that the lock itself needs one manual click.
+   fails. Headless caveat: `requestPointerLock` throws in headless Chromium —
+   assert the wiring and the unlocked cue in a screenshot, and say plainly that
+   the lock itself needs one manual click (do the both-axes look check there).
 7. **Ask the scene the three things the screenshot cannot answer** (below). Run it
    once, in the same browser you already have open.
 
@@ -279,6 +290,12 @@ visual-system work — the sequence above.
 
 - a MANDATORY-bucket aim game never requests pointer lock, or locks with no
   visible unlocked cue;
+- a movement key or look axis whose on-screen direction contradicts its label
+  (D turning the vehicle screen-left, mouse-up looking down with no invert
+  option);
+- drag-pan axes that mix conventions (one axis grab-the-world, the other
+  move-the-camera);
+- a non-cursor-core game that leaves the OS cursor visible during play;
 - approval relies on a single frame;
 - post-processing cannot be disabled per pass;
 - random seeds are not reproducible;