@genex-ai/cli-demo 0.65.0-dev.162 → 0.66.0-dev.163

package/dist/index.js

@@ -12540,6 +12540,7 @@ var TOUCH_KIT = [
 ];
 var INPUT_AND_CAMERA = [
   "character/follow-camera.ts",
+  "character/aim-cue.ts",
   "character/keyboard-input.ts",
   "character/touch-joystick.ts",
   ...TOUCH_KIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@genex-ai/cli-demo",
-  "version": "0.65.0-dev.162",
+  "version": "0.66.0-dev.163",
   "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/aim-cue.ts

@@ -0,0 +1,124 @@
+// Ready-made pointer-lock aim UI for the bundled FollowCamera — the reticle +
+// "click to aim" cue that the camera's aim mode expects the game to draw.
+// FollowCamera itself ships no DOM (it only emits `onAimChange` events); this
+// helper turns those events into a minimal always-correct overlay so a game gets
+// the whole aim UX in two lines:
+//
+//     const cue = createAimCue();
+//     const followCam = new FollowCamera(camera, { domElement, onAimChange: cue.onAimChange });
+//
+// What it draws per aim state:
+// - "locked"      → a small centered reticle dot (cursor is hidden by the browser).
+// - "unlocked"    → a bottom-center pill, "Click to aim — Esc pauses". Also shown on
+//                   the "needs-gesture" re-emit (a re-lock that needs a fresh click).
+// - "unavailable" → the same pill, "Drag to look" (lock was refused, e.g. a
+//                   third-party embed without allow="pointer-lock" — drag still works).
+// - "off" / "paused" → nothing (aim disabled, or a menu owns the cursor).
+//
+// Games that want a custom HUD can skip this and read `onAimChange` directly.
+
+import type { FollowCameraAimEvent } from "./follow-camera.ts";
+
+export interface AimCueOptions {
+  /** DOM parent; default `document.body`. */
+  parent?: HTMLElement;
+  /** Text for the unlocked pill; default "Click to aim — Esc pauses". */
+  hint?: string;
+  /** Text for the drag-fallback pill (lock unavailable); default "Drag to look". */
+  dragHint?: string;
+}
+
+export interface AimCue {
+  /** Wire this to `FollowCameraOptions.onAimChange`. Idempotent per state. */
+  onAimChange: (e: FollowCameraAimEvent) => void;
+  /** Remove the overlay from the DOM. */
+  dispose: () => void;
+}
+
+const OVERLAY_STYLE: Partial<CSSStyleDeclaration> = {
+  position: "fixed",
+  inset: "0",
+  zIndex: "9",
+  pointerEvents: "none",
+  fontFamily: "system-ui, sans-serif",
+};
+
+const RETICLE_STYLE: Partial<CSSStyleDeclaration> = {
+  position: "absolute",
+  left: "50%",
+  top: "50%",
+  width: "6px",
+  height: "6px",
+  marginLeft: "-3px",
+  marginTop: "-3px",
+  borderRadius: "50%",
+  background: "rgba(255,255,255,0.9)",
+  boxShadow: "0 0 0 1.5px rgba(0,0,0,0.5)",
+  display: "none",
+};
+
+const PILL_STYLE: Partial<CSSStyleDeclaration> = {
+  position: "absolute",
+  left: "50%",
+  bottom: "6%",
+  transform: "translateX(-50%)",
+  padding: "6px 14px",
+  borderRadius: "999px",
+  background: "rgba(0,0,0,0.55)",
+  color: "#fff",
+  fontSize: "13px",
+  fontWeight: "500",
+  letterSpacing: "0.01em",
+  whiteSpace: "nowrap",
+  display: "none",
+};
+
+/**
+ * Create the aim overlay and return an `onAimChange` handler to wire into
+ * FollowCamera plus a `dispose()` that removes it. Safe to call once per game.
+ */
+export function createAimCue(options: AimCueOptions = {}): AimCue {
+  const parent = options.parent ?? document.body;
+  const hint = options.hint ?? "Click to aim — Esc pauses";
+  const dragHint = options.dragHint ?? "Drag to look";
+
+  const overlay = document.createElement("div");
+  Object.assign(overlay.style, OVERLAY_STYLE);
+
+  const reticle = document.createElement("div");
+  Object.assign(reticle.style, RETICLE_STYLE);
+
+  const pill = document.createElement("div");
+  Object.assign(pill.style, PILL_STYLE);
+  pill.textContent = hint;
+
+  overlay.appendChild(reticle);
+  overlay.appendChild(pill);
+  parent.appendChild(overlay);
+
+  const onAimChange = (e: FollowCameraAimEvent): void => {
+    // Idempotent: the "needs-gesture" re-emit repeats state "unlocked" by design.
+    if (e.state === "locked") {
+      reticle.style.display = "block";
+      pill.style.display = "none";
+    } else if (e.state === "unlocked") {
+      reticle.style.display = "none";
+      pill.textContent = hint;
+      pill.style.display = "block";
+    } else if (e.state === "unavailable") {
+      reticle.style.display = "none";
+      pill.textContent = dragHint;
+      pill.style.display = "block";
+    } else {
+      // "off" or "paused": a menu owns the cursor, or aim is disabled.
+      reticle.style.display = "none";
+      pill.style.display = "none";
+    }
+  };
+
+  const dispose = (): void => {
+    overlay.remove();
+  };
+
+  return { onAimChange, dispose };
+}

package/templates/controllers/character/follow-camera.ts

@@ -66,18 +66,29 @@ export type FollowCameraOptions = {
    */
   colliderMeshes?: THREE.Mesh[];
   /**
-   * Pointer-lock aim mode (AG-754). When true, a left-mouse click on `domElement`
-   * requests pointer lock; while locked, raw mouse movement drives the orbit
-   * directly (no drag needed). Esc — or any lock loss — returns to "unlocked".
-   * Ships NO DOM UI: wire `onAimChange` to render a reticle while locked and a
-   * "click to aim" cue while unlocked. Touch pointers never trigger lock (mobile
-   * controls are unchanged) and coarse-pointer-only devices report "off". First-
-   * person is this same mode plus a pinned zoom + eye-height target (see the
-   * character-controller wiring reference). Default false.
+   * Pointer-lock aim mode (AG-754). **Default true** on desktop (fine pointer):
+   * a left-mouse click on `domElement` requests pointer lock, and while locked
+   * raw mouse movement drives the orbit directly (no drag needed). Esc — or any
+   * lock loss — returns to "unlocked". Pass `pointerLockAim: false` to opt OUT —
+   * do this for cursor-core games (RTS, tower defense, card/board, point-and-click
+   * builders) where the OS cursor IS the input, and for orbit showcases.
+   * FollowCamera itself ships NO DOM UI; the character controller kit ships a
+   * ready-made cue helper (`aim-cue.ts` — `createAimCue()`) that you wire to
+   * `onAimChange` to draw a reticle while locked and a "click to aim" cue while
+   * unlocked. Touch pointers never trigger lock (mobile controls are unchanged)
+   * and coarse-pointer-only devices report "off". First-person is this same mode
+   * plus a pinned zoom + eye-height target (see the character-controller wiring
+   * reference).
    */
   pointerLockAim?: boolean;
-  /** Radians of view rotation per pixel of locked mouse movement. Default 0.0023. */
+  /** Radians of view rotation per pixel of locked mouse movement. Default 0.0023. Mutable via `aimSensitivity` setter. */
   aimSensitivity?: number;
+  /**
+   * Invert the vertical (pitch) axis in locked aim — mouse-up looks DOWN, for
+   * players who prefer flight-sim pitch. Default false. There is deliberately no
+   * horizontal-invert option: inverted yaw is a bug class, never a preference.
+   */
+  aimInvertY?: boolean;
   /** Fired on every aim-state transition (plus an initial "init" emit when aim is enabled). */
   onAimChange?: (e: FollowCameraAimEvent) => void;
 };
@@ -94,11 +105,26 @@ export type FollowCameraAimState =
   | "paused" // suspended by the game (menu open / driving) — clicks don't re-lock
   | "unavailable"; // lock permanently rejected (e.g. an iframe without allow="pointer-lock") → drag-orbit fallback
 
-/** Payload for {@link FollowCameraOptions.onAimChange}. */
+/**
+ * Payload for {@link FollowCameraOptions.onAimChange}.
+ *
+ * NOTE: reason `"needs-gesture"` is a **same-state re-emit** — it fires with
+ * `state === prev === "unlocked"` when a re-lock attempt could not run because
+ * the browser lacked a usable user gesture (a resume outside a click, or Chrome's
+ * post-Esc re-lock cooldown). The camera keeps the "unlocked" cue up and re-locks
+ * on the next pointerdown/keydown; UI handlers must treat it idempotently.
+ */
 export type FollowCameraAimEvent = {
   state: FollowCameraAimState;
   prev: FollowCameraAimState;
-  reason: "user-click" | "esc-or-lost" | "paused" | "resumed" | "rejected" | "init";
+  reason:
+    | "user-click"
+    | "esc-or-lost"
+    | "paused"
+    | "resumed"
+    | "rejected"
+    | "needs-gesture"
+    | "init";
 };
 
 /** Mutable scalar velocity slot for SmoothDamp (Unity-style ref param). */
@@ -247,13 +273,19 @@ export class FollowCamera {
   private _onContextMenu: (e: MouseEvent) => void;
 
   // Pointer-lock aim (AG-754). _pausedByGame gates re-lock while a menu or vehicle
-  // owns input; the two document listeners exist only when aim is capable.
+  // owns input; the document listeners exist only when aim is capable.
   private _aimSensitivity: number;
+  private _aimInvertY: boolean;
   private _onAimChange?: (e: FollowCameraAimEvent) => void;
   private _aimState: FollowCameraAimState;
   private _pausedByGame: boolean;
+  // Armed only after a re-lock could not run for lack of a user gesture; the next
+  // real gesture (canvas pointerdown, or this document keydown) retries the lock.
+  // Kept off after a deliberate Esc so a stray keypress never yanks the cursor back.
+  private _retryArmed: boolean;
   private _onLockChange: () => void;
   private _onLockError: () => void;
+  private _onRetryKeyDown: () => void;
 
   constructor(camera: THREE.PerspectiveCamera, options: FollowCameraOptions) {
     this._camera = camera;
@@ -345,13 +377,14 @@ export class FollowCamera {
       if (!this.enabled) return;
       if (this._aimState === "locked") {
         // Locked aim: raw movement deltas drive the orbit directly (no pointer
-        // tracking). SIGN (AG-754): mouse-right looks right, so azimuth ADDS
-        // movementX — the OPPOSITE of the drag path's -dx (drag moves the world,
-        // aim moves the view); pitch matches drag (mouse-up looks up = -movementY).
-        // Reasoned from the spherical math; verify both axes on the template-world
-        // testbed and flip a sign here if a scene disagrees (see the drag sign note).
+        // tracking). SIGN: mouse-right looks right, mouse-up looks up — the SAME
+        // convention as the drag path below (both pan the VIEW: azimuth uses the
+        // negative horizontal delta, pitch the negative vertical). Pinned by the
+        // signed projection test in follow-camera-aim.test.ts — do not "reason" a
+        // flip here; change the test if the convention itself ever changes.
         const s = this._aimSensitivity;
-        this.rotate(e.movementX * s, -e.movementY * s, true);
+        const pitch = this._aimInvertY ? e.movementY * s : -e.movementY * s;
+        this.rotate(-e.movementX * s, pitch, true);
         this._userDragRotate = true; // reuse the dragging smoothTime, like manual orbit
         return;
       }
@@ -424,12 +457,15 @@ export class FollowCamera {
 
     // ---- pointer-lock aim (AG-754) ----
     this._aimSensitivity = options.aimSensitivity ?? 0.0023;
+    this._aimInvertY = options.aimInvertY === true;
     this._onAimChange = options.onAimChange;
     this._pausedByGame = false;
+    this._retryArmed = false;
     this._onLockChange = () => {
       const locked =
         typeof document !== "undefined" && document.pointerLockElement === this._domElement;
       if (locked) {
+        this._retryArmed = false; // a live lock supersedes any pending gesture retry
         if (this._pausedByGame) {
           // A lock grant that lands AFTER setPaused(true): requestPointerLock is
           // async, so the click's request can resolve once a menu/vehicle has
@@ -441,6 +477,8 @@ export class FollowCamera {
       } else if (this._aimState === "locked") {
         // Lock lost. A game-driven pause routes to "paused"; anything else (Esc,
         // focus loss, tab hide) is the browser's release valve → back to "unlocked".
+        // Esc does NOT arm a keydown retry: the player asked for the cursor, so we
+        // wait for a deliberate click, not the next stray keypress.
         this._setAimState(
           this._pausedByGame ? "paused" : "unlocked",
           this._pausedByGame ? "paused" : "esc-or-lost",
@@ -450,11 +488,21 @@ export class FollowCamera {
     // pointerlockerror carries no detail; a genuine permission denial is caught on
     // the requestPointerLock() promise instead. Transient errors just stay "unlocked".
     this._onLockError = () => {};
-    // Capability gate: opt-in flag, a DOM document present (node/SSR safe), the
-    // element supports the API, and the device has a fine pointer (phones never
-    // lock — the mode reports "off" so games don't draw a desktop-only cue).
+    // A re-lock that failed for lack of a user gesture (a resume outside a click, or
+    // Chrome's post-Esc cooldown) arms this: the next keydown retries the lock, so
+    // the player can resume with WASD, not only a click. Only fires while armed +
+    // unlocked + not game-paused, so it never fights a deliberate Esc.
+    this._onRetryKeyDown = () => {
+      if (this._pausedByGame || this._aimState !== "unlocked" || !this._retryArmed) return;
+      this._retryArmed = false;
+      this._requestLock();
+    };
+    // Capability gate: aim is ON by default on desktop; opt out with
+    // `pointerLockAim: false` (cursor-core games). Also requires a DOM document
+    // (node/SSR safe), element API support, and a fine pointer (phones never lock —
+    // the mode reports "off" so games don't draw a desktop-only cue).
     const aimCapable =
-      options.pointerLockAim === true &&
+      options.pointerLockAim !== false &&
       typeof document !== "undefined" &&
       typeof this._domElement.requestPointerLock === "function" &&
       (typeof matchMedia !== "function" || matchMedia("(pointer: fine)").matches);
@@ -462,6 +510,7 @@ export class FollowCamera {
     if (aimCapable) {
       document.addEventListener("pointerlockchange", this._onLockChange);
       document.addEventListener("pointerlockerror", this._onLockError);
+      document.addEventListener("keydown", this._onRetryKeyDown);
       // Emit the opening state so one onAimChange handler owns ALL aim UI — the
       // "click to aim" cue appears immediately, before any interaction.
       this._onAimChange?.({ state: "unlocked", prev: "off", reason: "init" });
@@ -612,6 +661,17 @@ export class FollowCamera {
     return this._aimState;
   }
 
+  /**
+   * Radians of view rotation per pixel of locked mouse movement (default 0.0023).
+   * Mutable so a pause-menu sensitivity slider can retune aim live.
+   */
+  get aimSensitivity(): number {
+    return this._aimSensitivity;
+  }
+  set aimSensitivity(v: number) {
+    if (Number.isFinite(v) && v > 0) this._aimSensitivity = v;
+  }
+
   /**
    * Suspend or resume aim without disabling the camera. Call `setPaused(true)`
    * when a menu opens or the player starts driving; call `setPaused(false)` INSIDE
@@ -623,6 +683,7 @@ export class FollowCamera {
     if (this._aimState === "off" || this._aimState === "unavailable") return;
     this._pausedByGame = paused;
     if (paused) {
+      this._retryArmed = false; // a menu/vehicle owns input now — no gesture retry
       if (typeof document !== "undefined" && document.pointerLockElement === this._domElement) {
         document.exitPointerLock(); // _onLockChange lands on "paused" (_pausedByGame is set)
       } else {
@@ -692,8 +753,10 @@ export class FollowCamera {
     if (typeof document !== "undefined") {
       document.removeEventListener("pointerlockchange", this._onLockChange);
       document.removeEventListener("pointerlockerror", this._onLockError);
+      document.removeEventListener("keydown", this._onRetryKeyDown);
       if (document.pointerLockElement === this._domElement) document.exitPointerLock();
     }
+    this._retryArmed = false;
     this._pointers.clear();
     this._orbiting = false;
     this._pinching = false;
@@ -716,25 +779,65 @@ export class FollowCamera {
   }
 
   /**
-   * Request pointer lock and classify the outcome (AG-754). A SecurityError
-   * (permission denied — e.g. an iframe without allow="pointer-lock") is permanent,
-   * so we fall back to drag-orbit ("unavailable"). Any other rejection (Chrome's
-   * post-Esc re-lock cooldown, a missing gesture) is transient: stay "unlocked",
-   * the next click retries.
+   * Request pointer lock and classify the outcome (AG-754). Outcomes:
+   * - No usable user gesture (a resume outside a click, or Chrome's post-Esc
+   *   cooldown): skip the doomed request, keep the "click to aim" cue up (a
+   *   same-state "needs-gesture" re-emit), and arm a keydown retry.
+   * - SecurityError (permission denied — e.g. an iframe without
+   *   allow="pointer-lock"): permanent, fall back to drag-orbit ("unavailable").
+   * - NotSupportedError from `unadjustedMovement`: retry the plain request (still
+   *   inside the transient-activation window, so no new gesture is needed).
+   * - Any other rejection: transient — treat like the missing-gesture case.
    */
-  private _requestLock(): void {
+  private _requestLock(unadjusted = true): void {
     if (typeof document === "undefined") return;
-    const ret = this._domElement.requestPointerLock() as unknown as Promise<void> | undefined;
+    // Bail before requesting if the browser reports no active user activation:
+    // requestPointerLock would reject, so short-circuit to the cue + gesture retry.
+    // (Absent userActivation — older browsers, Node stubs — means "can't tell" → proceed.)
+    const ua =
+      typeof navigator !== "undefined"
+        ? (navigator as Navigator & { userActivation?: { isActive?: boolean } }).userActivation
+        : undefined;
+    if (ua && ua.isActive === false) {
+      this._retryArmed = true;
+      this._setAimState("unlocked", "needs-gesture", true);
+      return;
+    }
+    // Prefer raw device input (no OS mouse acceleration) where supported.
+    const request = this._domElement.requestPointerLock as unknown as (
+      options?: { unadjustedMovement?: boolean },
+    ) => Promise<void> | undefined;
+    const ret = request.call(this._domElement, unadjusted ? { unadjustedMovement: true } : undefined);
     ret?.catch?.((err: unknown) => {
-      if ((err as DOMException)?.name === "SecurityError") {
+      const name = (err as DOMException)?.name;
+      if (name === "NotSupportedError" && unadjusted) {
+        this._requestLock(false); // retry without the raw-input option
+        return;
+      }
+      if (name === "SecurityError") {
         this._setAimState("unavailable", "rejected");
+        return;
       }
+      // A rejection can land AFTER a menu paused aim (requestPointerLock is async,
+      // same race as the late grant in _onLockChange). Never pop the "click to aim"
+      // cue over an open menu — stay paused; the resume path re-requests anyway.
+      if (this._pausedByGame) return;
+      this._retryArmed = true;
+      this._setAimState("unlocked", "needs-gesture", true);
     });
   }
 
-  /** Transition aim state and fire onAimChange (no-op if unchanged). */
-  private _setAimState(state: FollowCameraAimState, reason: FollowCameraAimEvent["reason"]): void {
-    if (state === this._aimState) return;
+  /**
+   * Transition aim state and fire onAimChange. Same-state transitions are a no-op
+   * UNLESS `forceEmit` (the "needs-gesture" re-emit, which keeps the "unlocked"
+   * cue up after a failed silent re-lock — see FollowCameraAimEvent).
+   */
+  private _setAimState(
+    state: FollowCameraAimState,
+    reason: FollowCameraAimEvent["reason"],
+    forceEmit = false,
+  ): void {
+    if (state === this._aimState && !forceEmit) return;
     const prev = this._aimState;
     this._aimState = state;
     this._onAimChange?.({ state, prev, reason });

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

@@ -35,31 +35,42 @@ rules, floating-origin shot, pointer controls, and implementation limits.
 
 ## Aiming and pointer lock
 
-Decide the bucket first and say it in the build plan:
+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:
 
 - **MANDATORY** — first-person of any kind (FPS, walking sim, horror) and any
-  mouse-aimed action (third-person shooter, turret/range). Shipping without
-  pointer lock here is a defect, not a style choice — validation fails it.
-- **HIGHLY RECOMMENDED** — third-person free-camera action/adventure (the
-  default `genex controller character` game). Lock is the default; keep
-  drag-orbit 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/puzzle), spectator/orbit showcases, and touch (pointer lock
-  does not exist on touch — the bundled mode no-ops there automatically).
+  mouse-aimed action (third-person shooter, turret/range). Lock is on by default;
+  leave it on. Shipping this unlocked is a defect, not a style choice — validation
+  fails it.
+- **HIGHLY RECOMMENDED** — third-person free-camera action/adventure (the default
+  `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.)
 
 **Mechanism — games on the bundled controller (most games):** do NOT hand-roll
-lock handling; enable the `FollowCamera` aim mode and wire the two UI states:
+lock handling. Aim is already enabled; the kit ships a ready-made cue overlay —
+wire `createAimCue()` (from `aim-cue.ts`, installed by `genex controller
+character`) to `onAimChange` and you get the reticle + "click to aim" cue for free:
 
+    import { createAimCue } from "./controllers/character/aim-cue.ts";
+
+    const cue = createAimCue(); // reticle when locked, "Click to aim — Esc pauses" when not
     const followCam = new FollowCamera(camera, {
       domElement: renderer.domElement,
-      pointerLockAim: true,
-      onAimChange: ({ state }) => {
-        reticle.style.display = state === "locked" ? "" : "none";
-        cue.textContent = state === "unavailable" ? "Drag to look" : "Click to aim";
-        cue.style.display = state === "unlocked" || state === "unavailable" ? "" : "none";
-      },
+      onAimChange: cue.onAimChange,
     });
 
+Cursor-core game? Pass `pointerLockAim: false` instead and skip the cue. Want a
+custom HUD? Read `onAimChange` yourself — `{ state }` is one of `locked` /
+`unlocked` / `unavailable` / `paused` / `off` (the `needs-gesture` re-emit repeats
+`unlocked`, so treat states idempotently).
+
 Yaw/pitch re-sync on lock acquire is built in (aim shares the orbit state — the
 view never snaps). First-person is the same mode plus three lines: pin the zoom
 (`minDistance`/`maxDistance` ≈ 0.1), feed an eye-height target to `moveTo`, and
@@ -89,6 +100,18 @@ grants the permission.
 6. If the lock request is rejected (a third-party page embedding the game
    without `allow="pointer-lock"`), the mode falls back to drag-orbit — show
    "Drag to look" instead. Never a dead game.
+7. Gate firing/actions on `followCam.aimState === "locked"` — the click that
+   acquires the lock (and any drag in the fallback) must not also shoot.
+8. Do NOT exit the lock between rounds, respawns, or cutscenes — only for real
+   menus (`setPaused`). A lock you never released needs no gesture to keep.
+9. A re-lock that can't run without a fresh gesture (a resume outside a click, or
+   Chrome's post-Esc cooldown) fires `onAimChange` with reason `needs-gesture` and
+   keeps the "click to aim" cue up; the next click or keypress re-locks. Never
+   retry on a timer.
+
+**Not an OS setting:** pointer `movementX/movementY` is never inverted by the OS
+(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.
 
 ## Non-negotiable rules
 

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

@@ -89,7 +89,8 @@ fork as a migration strategy. Install a fresh copy elsewhere and port only the n
 | `shared/colliders.ts` | `cuboidCollider`, `collidersFromObject`, … | colliders for level geometry and GLB props |
 | `character/character-controller.ts` | `CharacterController` | the floating-capsule movement brain |
 | `character/presets.ts` | `characterPresets` | six named tunings |
-| `character/follow-camera.ts` | `FollowCamera` | orbit/zoom chase camera with collision pullback and an opt-in pointer-lock aim mode |
+| `character/follow-camera.ts` | `FollowCamera` | orbit/zoom chase camera with collision pullback and pointer-lock aim ON by default (opt out with `pointerLockAim: false`) |
+| `character/aim-cue.ts` | `createAimCue` | drop-in reticle + "click to aim" overlay; wire to `FollowCamera`'s `onAimChange` |
 | `character/keyboard-input.ts` | `KeyboardInput` | WASD/arrows/Shift/Space/F state, no per-frame polling setup |
 | `touch/*` | `TouchJoystick`, `VirtualButton`, `DragZone`, `RotateOverlay` | the shared touch kit — `$genex-threejs-touch-controls` owns the genre recipes |
 | `character/character-animations.ts` | `CharacterAnimations` | animation state machine, directional profiles, speed-matched cadence, `playOneShot`, procedural fallback |
@@ -107,6 +108,7 @@ import { CharacterAnimations } from "./controllers/character/character-animation
 import { loadCharacterClips } from "./controllers/character/animation-packs.ts";
 import { characterPresets } from "./controllers/character/presets.ts";
 import { FollowCamera } from "./controllers/character/follow-camera.ts";
+import { createAimCue } from "./controllers/character/aim-cue.ts";
 import { KeyboardInput } from "./controllers/character/keyboard-input.ts";
 import { loadVrm } from "./controllers/character/vrm/vrm-loader.ts";
 import { capsuleFromModel } from "./controllers/character/vrm/capsule-fit.ts";
@@ -142,9 +144,13 @@ const anims = new CharacterAnimations(avatar, clips);
 addEventListener("pointerdown", () => anims.playOneShot("Punch_Jab")); // punch on click
 
 const kb = new KeyboardInput();
+// Pointer-lock aim is ON by default (desktop). The kit's cue overlay gives you the
+// reticle + "click to aim" prompt; pass `pointerLockAim: false` for cursor-core games.
+const aimCue = createAimCue();
 const followCam = new FollowCamera(camera, {
   domElement: renderer.domElement,
   colliderMeshes: staticWallMeshes, // static environment ONLY — never the character mesh
+  onAimChange: aimCue.onAimChange,
 });
 
 // Fixed-substep phase: input + controller brain, BEFORE world.step().

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

@@ -106,6 +106,8 @@ import { FollowCamera } from "./controllers/character/follow-camera.ts";
 const followCam = new FollowCamera(camera, {
   domElement: renderer.domElement,
   colliderMeshes: staticWallMeshes,
+  // Pointer-lock aim is ON by default on desktop — see §5.1 to wire the cue, or
+  // pass `pointerLockAim: false` for a cursor-core game (RTS, card, builder).
 });
 ```
 
@@ -124,24 +126,29 @@ Rules that matter:
 - v1 limits (by design): no truck/pan, and the orbit space assumes the up axis
   stays roughly world +Y — far-from-Y custom gravity will misbehave.
 
-### Pointer-lock aim (opt-in)
+### Pointer-lock aim (on by default)
 
-Set `pointerLockAim: true` and a mouse click locks the pointer; while locked,
-mouse movement drives the orbit directly (no drag). The controller ships NO DOM —
-wire `onAimChange` to draw a reticle (locked) and a "click to aim" cue (unlocked):
+Aim is enabled by default on desktop: a click locks the pointer and mouse movement
+drives the orbit directly (no drag). FollowCamera ships no DOM of its own, but the
+kit ships a cue overlay — wire `createAimCue()` to `onAimChange` for the reticle +
+"click to aim" prompt:
 
 ```ts
+import { createAimCue } from "./controllers/character/aim-cue.ts";
+
+const aimCue = createAimCue();
 const followCam = new FollowCamera(camera, {
   domElement: renderer.domElement,
   colliderMeshes: staticWallMeshes,
-  pointerLockAim: true,
-  onAimChange: ({ state }) => {
-    reticle.style.display = state === "locked" ? "" : "none";
-    cue.style.display = state === "unlocked" || state === "unavailable" ? "" : "none";
-  },
+  onAimChange: aimCue.onAimChange, // reticle when locked, cue when not
 });
 ```
 
+Want a custom HUD? Read `onAimChange: ({ state }) => …` yourself instead of the cue.
+
+- **Opt out:** cursor-core games (RTS, tower defense, card, builder) pass
+  `pointerLockAim: false` — the camera then stays drag-orbit and never grabs the
+  cursor.
 - **Menus / vehicles:** `followCam.setPaused(true)` when a menu opens or the
   player starts driving; `followCam.setPaused(false)` INSIDE the closing
   click/keypress handler (re-lock needs a user gesture). Aim is on-foot only.
@@ -152,8 +159,8 @@ const followCam = new FollowCamera(camera, {
   third-party embed without `allow="pointer-lock"` goes `"unavailable"` and
   drag-orbit stays as the fallback — never a dead camera.
 
-The three-bucket rule (mandatory / recommended / never) and the full lock
-lifecycle contract live in `$genex-threejs-camera-direction`.
+The bucket rule (mandatory / recommended / never) and the full lock lifecycle
+contract live in `$genex-threejs-camera-direction`.
 
 ## 6. The loop — exact order
 

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

@@ -35,9 +35,9 @@ no matter how good it looks.
   dimmed icon — silence reads as broken input.
 - Camera-aimed shooting wants **pointer lock** — firing at a reticle with an
   unlocked drag-to-turn camera feels imprecise no matter how tight the numbers
-  are. The three-bucket rule + the bundled `FollowCamera` aim mode live in
-  `$genex-threejs-camera-direction`; on the bundled controller it's one option
-  flag, not hand-rolled events.
+  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.
 
 ## Movement: snappy beats realistic
 

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

@@ -239,6 +239,12 @@ document.addEventListener("keydown", (e) => {
 });
 ```
 
+- **On the bundled `FollowCamera`, it owns the lock — don't fight it.** Do NOT
+  call `document.exitPointerLock()` / `canvas.requestPointerLock()` yourself; that
+  desyncs its aim state (the cue flips wrong). Instead pause/resume through it:
+  `followCam.setPaused(true)` on Escape, `followCam.setPaused(false)` from the
+  Resume click, and read `onAimChange` for the cue. The raw calls above are only
+  for a hand-rolled camera with no bundled controller.
 - **Degradation is built in.** Where Keyboard Lock is absent (Safari, Firefox) or
   the game isn't fullscreen, the browser still releases pointer lock on Escape —
   so ALSO keep the pointer-lock-loss → pause path (`pointerlockchange`: if
@@ -246,8 +252,14 @@ document.addEventListener("keydown", (e) => {
   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.
-- **Dashboard embed:** full coverage needs the game iframe to permit keyboard
-  lock; standalone play (`<slug>.genex.technology`) works today regardless.
+- **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`).
+
+A mouse-aim game earns its keep with a **look-sensitivity slider** in the pause
+menu — trackpads feel slower than mice, so let the player tune it. On the bundled
+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 loader
 

package/templates/skills/genex-threejs-multiplayer/references/genre-recipes.md

@@ -66,8 +66,9 @@ slow physical projectiles, all against the same damage/defeat rules.)
 
 **Decisions:**
 - **Aim with pointer lock** — a first-person or mouse-aimed shooter is the MANDATORY pointer-lock
-  bucket (see `$genex-threejs-camera-direction`); ship it locked, not drag-to-turn, or aim feels
-  imprecise before netcode is even in play.
+  bucket (see `$genex-threejs-camera-direction`); the bundled camera locks by default, so ship it
+  locked (not drag-to-turn) — and gate firing on `aimState === "locked"` so the lock-acquiring
+  click doesn't also shoot.
 - **The attacker judges the hit locally** ("favor the shooter"): raycast/cone-check against what
   *you* see, then broadcast ONE attack event naming the `targets` — and draw your own muzzle
   flash / tracer / swing arc **right there**, because `send` never echoes back to you. A high-ping

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

@@ -196,13 +196,16 @@ concept-driven — a richer first build beats a grey-box one.
 
 - Start from the playable game target: player verb, scene scale, camera distance,
   input mode, and frame budget.
-- Pointer bucket (decide before building, state it in the plan): **mandatory
-  pointer lock** — first-person of any kind, and any mouse-aimed action
-  (third-person shooter, turret/range). **Lock by default** — third-person
-  free-camera action/adventure; drag-orbit only with a stated reason (e.g. a
+- Pointer bucket (decide before building, state it in the plan): the bundled
+  `FollowCamera` locks the pointer by default on desktop, so this is mostly a
+  decision to opt OUT. **mandatory pointer lock** — first-person of any kind, and
+  any mouse-aimed action (third-person shooter, turret/range); leave it on.
+  **Lock by default** — third-person free-camera action/adventure; on already,
+  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. The mechanism and
-  the full aim contract live in `$genex-threejs-camera-direction`.
+  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`.
 - 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.

package/templates/skills/genex-threejs-vehicle-controllers/references/enter-exit.md

@@ -207,9 +207,10 @@ onHandoff: (fromId, toId) => followCam.setPaused(toId !== CHARACTER_ID),
 
 Enter is clean — exiting a lock needs no gesture. On **exit**, though, `onHandoff`
 runs deferred inside `update()`, NOT in the F-key handler, so `setPaused(false)`'s
-re-lock request has no live user gesture and the browser refuses it: aim returns to
-**unlocked** (the "click to aim" cue shows) and the player clicks once to re-aim —
-don't assume a seamless re-lock. Vehicle cameras keep their `alignHeading` behavior.
+re-lock request has no live user gesture: aim emits `needs-gesture`, the "click to
+aim" cue stays up, and the next gesture (a click OR any keypress — the walk keys
+count) re-locks automatically. So it recovers on its own; just don't expect the lock
+back on the exact exit frame. Vehicle cameras keep their `alignHeading` behavior.
 
 ## Multiplayer
 

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

@@ -106,10 +106,14 @@ everything twice.
    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 turns the view); press Esc and assert the
-   "click to aim/resume" cue appears. 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.
+   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
+   `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.
 7. **Ask the scene the three things the screenshot cannot answer** (below). Run it
    once, in the same browser you already have open.