@genex-ai/cli-demo 0.37.0 → 0.38.0

package/templates/controllers/character/animation-packs.ts

@@ -0,0 +1,70 @@
+// SPDX-License-Identifier: MIT
+// One-call animation loading for the character controller (Genex AG-775):
+// the bundled core library (./assets/animation-library.glb, 12 locomotion +
+// crouch + hit/death clips) PLUS every animation pack installed by
+// `genex controller anims <tags|clips…>` (./assets/anims/<Clip>.glb, listed in
+// ./assets/anims/manifest.json). Everything is retargeted onto the given VRM —
+// the per-file rig auto-detect in vrm-retarget.ts handles both the UE-style
+// UAL Pro rig and the older Rigify DEF-* rig — and returned as one flat clip
+// array ready for `new CharacterAnimations(scene, clips)`.
+//
+//   const { scene, vrm } = await loadVrm("./assets/avatar.vrm");
+//   const clips = await loadCharacterClips(vrm);
+//   const anims = new CharacterAnimations(scene, clips);
+//
+// Games that never ran `genex controller anims` just get the core clips (the
+// manifest fetch 404s and is ignored). Packs added later are picked up on the
+// next page load — no code change.
+import type * as THREE from "three";
+import { GLTFLoader } from "three/addons/loaders/GLTFLoader.js";
+import type { VRM } from "@pixiv/three-vrm";
+import { retargetClips } from "./vrm/vrm-retarget.ts";
+
+/** Shape of ./assets/anims/manifest.json (written by `genex controller anims`). */
+interface AnimsManifest {
+  schema: number;
+  clips: string[];
+}
+
+export interface LoadCharacterClipsOptions {
+  /** Asset base URL — where animation-library.glb + anims/ live. Default "./assets/". */
+  base?: string;
+}
+
+/**
+ * Load + retarget every animation the game has: the bundled core library and
+ * all installed pack clips. Missing pack files are skipped with a console
+ * warning (the game still runs on the clips that loaded).
+ */
+export async function loadCharacterClips(
+  vrm: VRM,
+  options: LoadCharacterClipsOptions = {},
+): Promise<THREE.AnimationClip[]> {
+  const base = options.base ?? "./assets/";
+  const loader = new GLTFLoader();
+  const clips: THREE.AnimationClip[] = [];
+
+  const library = await loader.loadAsync(base + "animation-library.glb");
+  clips.push(...retargetClips(vrm, library.scene, library.animations));
+
+  const manifest = await fetch(base + "anims/manifest.json")
+    .then((res) => (res.ok ? (res.json() as Promise<AnimsManifest>) : null))
+    .catch(() => null);
+  if (manifest !== null && Array.isArray(manifest.clips) && manifest.clips.length > 0) {
+    const packs = await Promise.all(
+      manifest.clips.map(async (name) => {
+        try {
+          return await loader.loadAsync(`${base}anims/${name}.glb`);
+        } catch {
+          console.warn(`[animation-packs] ${name}.glb failed to load — skipped.`);
+          return null;
+        }
+      }),
+    );
+    for (const pack of packs) {
+      if (pack !== null) clips.push(...retargetClips(vrm, pack.scene, pack.animations));
+    }
+  }
+
+  return clips;
+}

package/templates/controllers/character/character-animations.ts

@@ -32,11 +32,13 @@ import * as THREE from "three";
 // State resolver (pure port)
 // ---------------------------------------------------------------------------
 
-/** The seven animation states the resolver can produce. */
+/** The nine animation states the resolver can produce. */
 export type CharacterAnimationState =
   | "IDLE"
   | "WALK"
   | "RUN"
+  | "CROUCH_IDLE"
+  | "CROUCH_MOVE"
   | "JUMP_START"
   | "JUMP_IDLE"
   | "JUMP_FALL"
@@ -59,28 +61,40 @@ export interface CharacterStateSnapshot {
   readonly runActive: boolean;
   /** True during the short jump window (default 0.1 s), not for the whole airborne arc. */
   readonly jumpActive: boolean;
+  /**
+   * True while the capsule is crouched (AG-775). OPTIONAL for backward
+   * compatibility — a five-boolean snapshot (e.g. an older networked remote
+   * player) behaves exactly as before (treated as `false`).
+   */
+  readonly crouchActive?: boolean;
 }
 
 /** Snapshot plus the previous frame's ground flag (derived internally by CharacterAnimations). */
 export interface AnimationStateContext extends CharacterStateSnapshot {
   readonly wasOnGround: boolean;
+  /** Always present in the context (missing snapshot flag defaults to false). */
+  readonly crouchActive: boolean;
 }
 
 /** Custom state-resolver signature — must stay a pure function over the context. */
 export type AnimationStateResolver = (ctx: AnimationStateContext) => CharacterAnimationState;
 
 /**
- * Pure animation-state resolver (exact upstream logic). Check order is load-bearing:
+ * Pure animation-state resolver (upstream logic + crouch). Check order is load-bearing:
  * JUMP_START outranks everything (fires on the ground frame where the jump window opened);
- * JUMP_LAND outranks IDLE/WALK/RUN for exactly one evaluation after touchdown.
+ * JUMP_LAND outranks IDLE/WALK/RUN for exactly one evaluation after touchdown; crouch
+ * outranks the standing ground states (landing while crouched flashes JUMP_LAND for one
+ * evaluation, then settles into CROUCH_*).
  */
 export function resolveAnimationState(ctx: AnimationStateContext): CharacterAnimationState {
-  const { isOnGround, wasOnGround, isFalling, isMoving, runActive, jumpActive } = ctx;
+  const { isOnGround, wasOnGround, isFalling, isMoving, runActive, jumpActive, crouchActive } =
+    ctx;
 
   if (jumpActive && wasOnGround) return "JUMP_START";
 
   if (isOnGround) {
     if (!wasOnGround) return "JUMP_LAND";
+    if (crouchActive) return isMoving ? "CROUCH_MOVE" : "CROUCH_IDLE";
     if (!isMoving) return "IDLE";
     return runActive ? "RUN" : "WALK";
   }
@@ -99,6 +113,8 @@ const ALL_STATES: readonly CharacterAnimationState[] = [
   "IDLE",
   "WALK",
   "RUN",
+  "CROUCH_IDLE",
+  "CROUCH_MOVE",
   "JUMP_START",
   "JUMP_IDLE",
   "JUMP_FALL",
@@ -116,6 +132,13 @@ const CLIP_SEARCH: Record<CharacterAnimationState, ClipSearchSpec> = {
   IDLE: { exact: ["Idle_Loop"], aliases: ["idle", "stand", "breath"] },
   WALK: { exact: ["Walk_Loop"], aliases: ["walk"] },
   RUN: { exact: ["Jog_Fwd_Loop", "Sprint_Loop"], aliases: ["run", "jog", "sprint"] },
+  // Aliases stay SPECIFIC on purpose: a bare "crouch" substring would greedily
+  // match any of the 9+ Crouch_* pack clips (Crouch_Enter, Crouch_Bwd_Loop, …).
+  CROUCH_IDLE: { exact: ["Crouch_Idle_Loop"], aliases: ["crouch_idle", "sneak_idle"] },
+  CROUCH_MOVE: {
+    exact: ["Crouch_Fwd_Loop"],
+    aliases: ["crouch_walk", "crouch_fwd", "sneak_walk", "sneak"],
+  },
   // Only the LOOP jump states (JUMP_IDLE/JUMP_FALL) end with a bare "jump" alias (lowest priority
   // — the specific compound tokens above always win when present) so a rig whose only airborne clip
   // is named "Jump" / "Jumping" still animates mid-air instead of playing the ground loop.
@@ -191,6 +214,8 @@ export function buildClipMap(
     IDLE: null,
     WALK: null,
     RUN: null,
+    CROUCH_IDLE: null,
+    CROUCH_MOVE: null,
     JUMP_START: null,
     JUMP_IDLE: null,
     JUMP_FALL: null,
@@ -207,6 +232,10 @@ export function buildClipMap(
   if (map.WALK === null) map.WALK = map.RUN;
   if (map.JUMP_FALL === null) map.JUMP_FALL = map.JUMP_IDLE;
   if (map.JUMP_IDLE === null) map.JUMP_IDLE = map.JUMP_FALL;
+  // Crouch degrades to the standing loops on rigs without crouch clips (old
+  // 46-clip libraries, Mixamo exports) — wrong pose beats a frozen T-pose.
+  if (map.CROUCH_IDLE === null) map.CROUCH_IDLE = map.IDLE;
+  if (map.CROUCH_MOVE === null) map.CROUCH_MOVE = map.WALK ?? map.CROUCH_IDLE;
   return map;
 }
 
@@ -290,8 +319,8 @@ export class CharacterAnimations {
   #resolver: AnimationStateResolver;
   #onChange: ((state: CharacterAnimationState, ctx: AnimationStateContext) => void) | undefined;
   #actions = new Map<string, THREE.AnimationAction>();
-  // Every provided clip by name — lets playOneShot reach clips beyond the 7
-  // locomotion states (the full 46-clip UAL catalog: Punch_*, Sword_*, Sitting_*…).
+  // Every provided clip by name — lets playOneShot reach clips beyond the 9
+  // locomotion states (any installed pack clip: Punch_*, Sword_*, Sitting_*…).
   #clipsByName = new Map<string, THREE.AnimationClip>();
   #oneShotAction: THREE.AnimationAction | null = null;
   #oneShotOnDone: (() => void) | undefined;
@@ -375,6 +404,7 @@ export class CharacterAnimations {
       isMoving: false,
       runActive: false,
       jumpActive: false,
+      crouchActive: false,
     };
 
     this.#onFinished = (event) => {
@@ -423,6 +453,16 @@ export class CharacterAnimations {
     return this.#clipMap;
   }
 
+  /**
+   * True while a {@link playOneShot} clip is playing (or holding its final
+   * pose with `holdPose`). Feed `() => !anims.oneShotActive` to foot IK's
+   * `allowReachDown` so one-shot choreography can't drag the pelvis down
+   * a step edge, and use it to block "fire again" spam in game code.
+   */
+  get oneShotActive(): boolean {
+    return this.#oneShotAction !== null;
+  }
+
   /** True when the procedural bob/lean drives the model instead of animation clips. */
   get usingProceduralFallback(): boolean {
     return this.#usingProceduralFallback;
@@ -446,6 +486,8 @@ export class CharacterAnimations {
     ctx.isMoving = snapshot.isMoving;
     ctx.runActive = snapshot.runActive;
     ctx.jumpActive = snapshot.jumpActive;
+    // Optional in the snapshot (older five-boolean remote-player objects).
+    ctx.crouchActive = snapshot.crouchActive ?? false;
 
     const next = this.#resolver(ctx);
     const stateChanged = next !== this.#state;
@@ -493,8 +535,9 @@ export class CharacterAnimations {
    * Play a full-body one-shot clip (punch, wave, pick-up, cast…) over the current
    * locomotion, then hand control back to the state machine when it finishes. Any
    * NON-locomotion clip from the set passed to the constructor works — see the
-   * character-controller skill's 46-clip catalog (Punch_Jab/Cross, Sword_Attack,
-   * Pistol_Shoot, Interact, Hit_Chest, …). Returns false if the clip name is unknown.
+   * character-controller skill's tagged pack catalog (Punch_Jab/Cross, Sword_Attack,
+   * Pistol_Shoot, Interact, Hit_Chest, …; install more with `genex controller anims`).
+   * Returns false if the clip name is unknown.
    *
    * @example
    * // punch on click:

package/templates/controllers/character/character-controller.ts

@@ -42,6 +42,7 @@ export type MovementInput = {
   joystick?: { x: number; y: number };
   run?: boolean;
   jump?: boolean;
+  crouch?: boolean;
 };
 
 /** Read-only view of the merged movement state (returned by the `input` getter). */
@@ -65,8 +66,12 @@ type ResolvedMovementInput = {
   joystick: { x: number; y: number };
   run: boolean;
   jump: boolean;
+  crouch: boolean;
 };
 
+/** Crouch input interpretation — see {@link CharacterControllerOptions.crouchMode}. */
+export type CrouchMode = "toggle" | "hold";
+
 /**
  * Options for {@link CharacterController}. Every value has a tuned default —
  * start from a preset in `./presets.ts` and only override what feels wrong.
@@ -111,6 +116,22 @@ export interface CharacterControllerOptions {
   /** Capsule radius. Default `0.3`. */
   capsuleRadius?: number;
 
+  // ── crouch (NEW, no upstream source — AG-775) ──
+  /**
+   * Crouch input interpretation: `"toggle"` (press flips crouch; browser-friendly,
+   * holding C while WASD-ing is awkward) or `"hold"` (crouch while held). Default `"toggle"`.
+   */
+  crouchMode?: CrouchMode;
+  /** Crouched target speed as a fraction of `maxWalkVel` (run is ignored while crouched). Default `0.45`. */
+  crouchSpeedRatio?: number;
+  /**
+   * Crouched capsule cylinder half-height as a fraction of the standing one.
+   * The capsule bottom keeps its float clearance (the ray origin shifts with
+   * the shrink), so the character's HEAD drops by `2*(1-scale)*capsuleHalfHeight`.
+   * Default `0.6`.
+   */
+  crouchCapsuleScale?: number;
+
   // ── forward direction ──
   /** `true` = always face the camera/custom forward (strafe mode). Default `false`. */
   lockForward?: boolean;
@@ -269,6 +290,8 @@ export class CharacterController {
   private readonly fallingGravityScale: number;
   private readonly fallingMaxVel: number;
   private readonly enableToggleRun: boolean;
+  private readonly crouchMode: CrouchMode;
+  private readonly crouchSpeedRatio: number;
   private groundDetectionMode: GroundDetectionMode;
   private readonly slopeMaxAngle: number;
   private readonly floatHeight: number;
@@ -301,6 +324,7 @@ export class CharacterController {
     joystick: { x: 0, y: 0 },
     run: false,
     jump: false,
+    crouch: false,
   };
   private jumpElapsedTime = 0;
   private _jumpActive = false;
@@ -308,6 +332,19 @@ export class CharacterController {
   private _runActive = false;
   private canRunAgain = false;
 
+  // ── crouch state (NEW, no upstream source — AG-775) ──
+  private _crouchActive = false;
+  /** What the player WANTS (toggle latch / hold level); `_crouchActive` lags it while a ceiling blocks standing. */
+  private crouchIntent = false;
+  private canCrouchAgain = false;
+  private readonly standingHalfHeight: number;
+  private readonly crouchedHalfHeight: number;
+  /** Slightly-slimmed standing capsule for the stand-up ceiling check (the 2%/5%
+   *  shrink keeps grazing contacts the crouched capsule already tolerates from
+   *  false-blocking the stand). */
+  private readonly standCheckShape: RAPIER.Capsule;
+  private readonly standCheckPos = new THREE.Vector3();
+
   // ── fixed axes ──
   private readonly fixedZero = new THREE.Vector3(0, 0, 0);
   private readonly fixedOrigin = new THREE.Vector3(0, 0, 0);
@@ -469,6 +506,10 @@ export class CharacterController {
     this.fallingGravityScale = options.fallingGravityScale ?? 3;
     this.fallingMaxVel = options.fallingMaxVel ?? 20;
     this.enableToggleRun = options.enableToggleRun ?? true;
+    this.crouchMode = options.crouchMode ?? "toggle";
+    this.crouchSpeedRatio = options.crouchSpeedRatio ?? 0.45;
+    this.standingHalfHeight = capsuleHalfHeight;
+    this.crouchedHalfHeight = capsuleHalfHeight * (options.crouchCapsuleScale ?? 0.6);
     this.groundDetectionMode = options.groundDetection ?? "shapeCast";
     this.slopeMaxAngle = options.slopeMaxAngle ?? Math.PI / 2.5;
     this.floatHeight = options.floatHeight ?? 0.2;
@@ -517,6 +558,7 @@ export class CharacterController {
     // Ground-query scratch shapes (reused every step).
     this.rayShape = new RAPIER.Ball(this.rayRadius);
     this.ray = new RAPIER.Ray(this.rayOrigin, this.rayDirection);
+    this.standCheckShape = new RAPIER.Capsule(this.standingHalfHeight * 0.98, this.capsuleRadius * 0.95);
 
     // Visual root (the JSX children slot).
     this.root = new THREE.Group();
@@ -679,6 +721,13 @@ export class CharacterController {
   get jumpActive(): boolean {
     return this._jumpActive;
   }
+  /**
+   * `true` while the capsule is crouched. May stay `true` after the player asks
+   * to stand — standing is ceiling-gated and retried automatically.
+   */
+  get crouchActive(): boolean {
+    return this._crouchActive;
+  }
   /** `true` while the character always faces the forward direction (strafe mode). */
   get lockForward(): boolean {
     return this.isLockForward;
@@ -712,6 +761,17 @@ export class CharacterController {
     }
     if (movement.run !== undefined) this.movementState.run = movement.run;
     if (movement.jump !== undefined) this.movementState.jump = movement.jump;
+    if (movement.crouch !== undefined) this.movementState.crouch = movement.crouch;
+  }
+
+  /**
+   * Programmatic crouch request (e.g. an on-screen crouch button:
+   * `btnCrouch.onPress = () => character.setCrouch(!character.crouchActive)`).
+   * Sets the INTENT — the capsule change applies on the next `update()`, and
+   * standing still waits for ceiling clearance.
+   */
+  setCrouch(active: boolean): void {
+    this.crouchIntent = active;
   }
 
   /** Toggle strafe mode (always face the camera/custom forward direction). */
@@ -752,6 +812,7 @@ export class CharacterController {
     this.movementState.joystick.y = 0;
     this.movementState.run = false;
     this.movementState.jump = false;
+    this.movementState.crouch = false;
   }
 
   /**
@@ -804,7 +865,15 @@ export class CharacterController {
     const leftward = this.movementState.leftward;
     const rightward = this.movementState.rightward;
     const run = this.getRunState(this.movementState.run || false);
-    const jump = this.getJumpState(this.movementState.jump || false);
+    // Crouch runs BEFORE jump: jumping while crouched first requests a stand
+    // (ceiling-checked); until the character actually stands, the jump input is
+    // masked so the shrunken capsule never launches into the obstacle above.
+    const crouchWasActive = this._crouchActive;
+    const crouch = this.getCrouchState(
+      this.movementState.crouch || false,
+      this.movementState.jump || false,
+    );
+    const jump = this.getJumpState((this.movementState.jump || false) && !crouch);
     const joystick = this.movementState.joystick;
     const hasControlInput =
       forward ||
@@ -812,6 +881,8 @@ export class CharacterController {
       leftward ||
       rightward ||
       jump ||
+      this.movementState.crouch ||
+      crouch !== crouchWasActive ||
       Math.abs(joystick.x) > 1e-4 ||
       Math.abs(joystick.y) > 1e-4;
 
@@ -1437,6 +1508,85 @@ export class CharacterController {
     return this._runActive;
   }
 
+  /**
+   * Crouch state machine (NEW, no upstream source — AG-775). Intent follows the
+   * input (toggle latch or hold level); the ACTIVE state follows intent except
+   * that standing up is gated on ceiling clearance and retried every step while
+   * the intent stays "stand" (walk out from under the obstacle and you pop up).
+   * Runs before the sleep early-out, so a stuck stand request keeps retrying.
+   */
+  private getCrouchState(crouchPressed: boolean, jumpPressed: boolean): boolean {
+    if (this.crouchMode === "toggle") {
+      // Only toggle crouch intent on the key's rising edge
+      if (crouchPressed && !this.canCrouchAgain) this.crouchIntent = !this.crouchIntent;
+      this.canCrouchAgain = crouchPressed;
+      // Jump doubles as a stand request (the jump itself stays masked while crouched).
+      if (jumpPressed && this.crouchIntent) this.crouchIntent = false;
+    } else {
+      this.crouchIntent = crouchPressed;
+    }
+
+    if (this.crouchIntent && !this._crouchActive) {
+      this._crouchActive = true;
+      this.setCapsuleHalfHeight(this.crouchedHalfHeight);
+    } else if (!this.crouchIntent && this._crouchActive && this.canStandUp()) {
+      this._crouchActive = false;
+      this.setCapsuleHalfHeight(this.standingHalfHeight);
+    }
+    return this._crouchActive;
+  }
+
+  /**
+   * Resize the capsule cylinder, shifting the shrunk shape DOWN inside the body
+   * by the height delta: the capsule BOTTOM keeps its ground clearance (feet
+   * stay planted) and all the change comes off the TOP, while the body ORIGIN —
+   * and with it `root`, the attached avatar, and the float-ray origin — stays at
+   * standing height. (Dropping the origin instead sinks the fixed-offset avatar
+   * into the floor, which foot IK then "fixes" by hyper-bending the knees.)
+   * Rapier re-derives mass properties from the new shape automatically.
+   */
+  private setCapsuleHalfHeight(halfHeight: number): void {
+    this._collider.setHalfHeight(halfHeight);
+    this._collider.setTranslationWrtParent({
+      x: 0,
+      y: -(this.standingHalfHeight - halfHeight),
+      z: 0,
+    });
+  }
+
+  /**
+   * `true` when the STANDING capsule fits — the ceiling check before standing
+   * up. The body origin never moves on crouch (only the collider shape/offset
+   * does), so the standing capsule is tested right at the current translation.
+   * Uses the same collider filter as the ground queries.
+   */
+  private canStandUp(): boolean {
+    const position = this._body.translation();
+    this.standCheckPos.set(position.x, position.y, position.z);
+    let blocked = false;
+    this.world.intersectionsWithShape(
+      this.standCheckPos,
+      this._body.rotation(),
+      this.standCheckShape,
+      () => {
+        blocked = true;
+        return false; // first hit is enough
+      },
+      RAPIER.QueryFilterFlags.EXCLUDE_SENSORS,
+      undefined,
+      this._collider,
+      this._body,
+      this.rayFilter,
+    );
+    return !blocked;
+  }
+
+  /** Target ground speed: crouch caps at `crouchSpeedRatio * maxWalkVel` (run ignored). */
+  private targetMoveSpeed(run: boolean): number {
+    if (this._crouchActive) return this.maxWalkVel * this.crouchSpeedRatio;
+    return run ? this.maxRunVel : this.maxWalkVel;
+  }
+
   /** Move impulse (slope climb + rejectVel + above-CoM lean) (upstream l.454-494). */
   private moveCharacter(run: boolean, fpsCorr: number): void {
     // Moving direction: rotate inputDir up/down the slope in front
@@ -1461,7 +1611,7 @@ export class CharacterController {
       (this._actualSlopeAngle > this.slopeMaxAngle ? this.airDragFactor : 1);
     this.baseImpulse
       .copy(this._movingDirection)
-      .multiplyScalar(run ? this.maxRunVel : this.maxWalkVel)
+      .multiplyScalar(this.targetMoveSpeed(run))
       .sub(this._relativeVelOnPlane);
     this._moveImpulse.copy(this.baseImpulse).sub(this.rejectVel).multiplyScalar(multiplier);
 
@@ -1629,8 +1779,6 @@ export class CharacterController {
     // Current moving velocity arrow
     d.velocityArrow.position.copy(this.currentPos);
     d.velocityArrow.setDirection(this.currVelDir.copy(this._relativeVel).normalize());
-    d.velocityArrow.setLength(
-      this._relativeVel.length() / (this._runActive ? this.maxRunVel : this.maxWalkVel)
-    );
+    d.velocityArrow.setLength(this._relativeVel.length() / this.targetMoveSpeed(this._runActive));
   }
 }

package/templates/controllers/character/keyboard-input.ts

@@ -19,6 +19,7 @@ export interface CharacterMovementIntent {
   rightward: boolean;
   run: boolean;
   jump: boolean;
+  crouch: boolean;
 }
 
 /** Movement intent for the car. Field names match the vehicle controller's `VehicleInput`. */
@@ -58,6 +59,7 @@ type NamedKey =
   | "space"
   | "shift"
   | "f"
+  | "c"
   | "up"
   | "down"
   | "left"
@@ -65,6 +67,7 @@ type NamedKey =
 
 // Bindings ported from the upstream keyboard map: letters/arrows/space match by
 // KeyboardEvent.code; Shift matches by event.key so ShiftLeft AND ShiftRight both work.
+// Crouch is KeyC, NOT Ctrl — Ctrl+W (crouch-walking forward) would close the browser tab.
 const CODE_BINDINGS: Readonly<Partial<Record<string, NamedKey>>> = {
   KeyW: "w",
   KeyS: "s",
@@ -72,6 +75,7 @@ const CODE_BINDINGS: Readonly<Partial<Record<string, NamedKey>>> = {
   KeyD: "d",
   Space: "space",
   KeyF: "f",
+  KeyC: "c",
   ArrowUp: "up",
   ArrowDown: "down",
   ArrowLeft: "left",
@@ -89,6 +93,7 @@ const ALL_NAMED_KEYS: readonly NamedKey[] = [
   "space",
   "shift",
   "f",
+  "c",
   "up",
   "down",
   "left",
@@ -111,6 +116,7 @@ export class KeyboardInput {
     space: false,
     shift: false,
     f: false,
+    c: false,
     up: false,
     down: false,
     left: false,
@@ -183,6 +189,9 @@ export class KeyboardInput {
   get f(): boolean {
     return this.#keys.f;
   }
+  get c(): boolean {
+    return this.#keys.c;
+  }
   get up(): boolean {
     return this.#keys.up;
   }
@@ -206,7 +215,8 @@ export class KeyboardInput {
 
   // ---- Derived intents (exact upstream wrapper mappings, touch terms merged by the caller) ----
 
-  /** WASD or arrows to move, Shift to run, Space to jump. Merge touch input caller-side:
+  /** WASD or arrows to move, Shift to run, Space to jump, C to crouch (the controller's
+   *  crouchMode decides toggle vs hold). Merge touch input caller-side:
    *  `{ ...kb.getCharacterMovement(), run: kb.shift || btnRun.pressed, joystick: {...} }`. */
   getCharacterMovement(): CharacterMovementIntent {
     const k = this.#keys;
@@ -217,6 +227,7 @@ export class KeyboardInput {
       rightward: k.d || k.right,
       run: k.shift,
       jump: k.space,
+      crouch: k.c,
     };
   }
 

package/templates/controllers/character/presets.ts

@@ -36,7 +36,9 @@ export interface CharacterPreset {
  *
  * Quick tuning map: "slippery" -> lower `slideGripFactor`; "floaty" -> lower
  * `fallingGravityScale`; "sluggish" -> raise `accDeltaTime`; "jumps too weak"
- * -> raise `jumpVel`; "tips over" -> raise `autoBalanceSpringK`.
+ * -> raise `jumpVel`; "tips over" -> raise `autoBalanceSpringK`; "sneaks too
+ * fast" -> lower `crouchSpeedRatio`; "can't fit under obstacles" -> lower
+ * `crouchCapsuleScale`.
  */
 export const characterPresets: Readonly<
   Record<
@@ -57,6 +59,8 @@ export const characterPresets: Readonly<
       "decisive jump, moderate grip. Tuned for collider density 1.",
     options: {
       density: 1,
+      crouchSpeedRatio: 0.45,
+      crouchCapsuleScale: 0.6,
     },
   },
 
@@ -92,6 +96,9 @@ export const characterPresets: Readonly<
       autoBalanceDampingC: 3,
       autoBalanceSpringOnY: 8,
       autoBalanceDampingOnY: 0.76,
+      // Crouch is a Genex extension (no upstream counterpart) — library defaults.
+      crouchSpeedRatio: 0.45,
+      crouchCapsuleScale: 0.6,
     },
   },
 
@@ -113,6 +120,10 @@ export const characterPresets: Readonly<
       airDragFactor: 0.3,
       slideGripFactor: 0.8,
       enableToggleRun: false,
+      // Snappy games sneak a bit faster; hold-to-crouch matches hold-to-run.
+      crouchMode: "hold",
+      crouchSpeedRatio: 0.5,
+      crouchCapsuleScale: 0.6,
     },
   },
 
@@ -132,6 +143,9 @@ export const characterPresets: Readonly<
       jumpDuration: 0.15,
       fallingGravityScale: 2.2,
       moveImpulsePointOffset: 0.6,
+      // Weighty crawl-speed sneak, shallower stance change.
+      crouchSpeedRatio: 0.4,
+      crouchCapsuleScale: 0.65,
     },
   },
 
@@ -152,6 +166,8 @@ export const characterPresets: Readonly<
       fallingGravityScale: 1,
       fallingMaxVel: 10,
       airDragFactor: 0.05,
+      crouchSpeedRatio: 0.45,
+      crouchCapsuleScale: 0.6,
     },
   },
 
@@ -168,6 +184,8 @@ export const characterPresets: Readonly<
       accDeltaTime: 0.08,
       decDeltaTime: 0.03,
       rejectVelFactor: 0.2,
+      crouchSpeedRatio: 0.45,
+      crouchCapsuleScale: 0.6,
     },
   },
 };