@genex-ai/cli-demo 0.11.0 → 0.14.2

package/templates/skills/genex-getting-started/SKILL.md

@@ -47,6 +47,11 @@ Each has a focused skill with the exact loader code — `$genex-ai-model`,
 
 ## Publishing
 
+Before your first `genex preview`, the play URL (`https://<slug>.genex.technology/`)
+already serves a **standard placeholder world** — the owner's avatar in a small
+playground, unrelated to your code. It is NOT in your repo; never treat it as a
+starting point or try to modify it. Your first `preview` replaces it automatically.
+
 `npx genex preview` deploys to your unlisted draft URL; `npx genex publish`
 lists the game in the public gallery. When publishing, pick 1–3 gallery
 categories from what you actually built — `games`, `assets`, `physics`,

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

@@ -0,0 +1,205 @@
+---
+name: genex-threejs-character-controller
+description: Add a tuned physics character controller to a Genex Three.js game with `npx genex controller character` — dynamic-capsule movement (walk/run/jump, slopes, stairs, moving platforms), follow camera, keyboard + touch input, and animation binding. Use for any on-foot player or third-person movement, and whenever the user asks for ecctrl — this is that controller, ported to plain Three.js.
+---
+
+# Genex Three.js Character Controller
+
+## Run the command first — never hand-write the controller
+
+```bash
+npx genex controller character
+npm i @dimforge/rapier3d-compat @pixiv/three-vrm   # three is already in the scaffold
+```
+
+The command vendors tested, tuned controller code into the game: TypeScript
+modules into `src/controllers/` (including `character/vrm/` — VRM loading,
+animation retargeting, capsule auto-fit, foot IK) and the 46-clip
+`animation-library.glb` into `public/assets/`. It also writes the player's
+avatar to `public/assets/avatar.vrm` — **your** avatar when you're signed in,
+otherwise a bundled CC0 default (attribution in `src/controllers/NOTICE.md`).
+The character plays as that VRM. The copied files are then owned by the game —
+edit them freely; re-running skips existing files unless `--force`. Do not write
+a character controller from scratch and do not swap in a kinematic-controller
+tutorial: this one is a real dynamic body that pushes crates, rides moving
+platforms, climbs stairs and slides on too-steep slopes out of the box.
+
+## What you get
+
+| Module (under `src/controllers/`) | Exports you use | Job |
+| --- | --- | --- |
+| `shared/physics-world.ts` | `PhysicsWorld` | Rapier WASM init, fixed-timestep loop, body↔Object3D sync, collision events |
+| `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 |
+| `character/keyboard-input.ts` | `KeyboardInput` | WASD/arrows/Shift/Space/F state, no per-frame polling setup |
+| `character/touch-joystick.ts` | `TouchJoystick`, `VirtualButton` | mobile controls |
+| `character/character-animations.ts` | `CharacterAnimations` | animation state machine + fuzzy clip binding + `playOneShot` + procedural fallback |
+| `character/vrm/*` | `loadVrm`, `retargetClips`, `capsuleFromModel`, `FootIK` | load the VRM avatar, retarget the 46 UAL clips onto its humanoid rig, auto-fit the capsule, ground the feet |
+
+## Minimal wiring
+
+```ts
+import { GLTFLoader } from "three/addons/loaders/GLTFLoader.js";
+import { PhysicsWorld } from "./controllers/shared/physics-world.ts";
+import { CharacterController } from "./controllers/character/character-controller.ts";
+import { CharacterAnimations } from "./controllers/character/character-animations.ts";
+import { characterPresets } from "./controllers/character/presets.ts";
+import { FollowCamera } from "./controllers/character/follow-camera.ts";
+import { KeyboardInput } from "./controllers/character/keyboard-input.ts";
+import { loadVrm } from "./controllers/character/vrm/vrm-loader.ts";
+import { retargetClips } from "./controllers/character/vrm/vrm-retarget.ts";
+import { capsuleFromModel } from "./controllers/character/vrm/capsule-fit.ts";
+
+const physics = await PhysicsWorld.create(); // nothing RAPIER-related may run before this resolves
+
+// Load the player's avatar + the animation library, then retarget onto the VRM.
+const { scene: avatar, vrm } = await loadVrm("./assets/avatar.vrm");
+const lib = await new GLTFLoader().loadAsync("./assets/animation-library.glb");
+
+const fit = capsuleFromModel(avatar);          // collider fits THIS avatar's bounds
+const character = new CharacterController(physics.world, camera, {
+  ...characterPresets["default"].options,
+  ...fit,
+  position: { x: 0, y: 2, z: 0 },
+  userData: { controller: { excludeVehicleRay: true } }, // car wheels must never drive on the player
+});
+scene.add(character.root);
+character.root.add(avatar);                     // parent the avatar under the character root
+avatar.position.y = fit.modelOffsetY;           // root = capsule CENTER; drop the model so feet touch the floor
+physics.registerBody(character.body, character.root); // root now follows the body, interpolated
+
+const anims = new CharacterAnimations(avatar, retargetClips(vrm, lib.scene, lib.animations));
+addEventListener("pointerdown", () => anims.playOneShot("Punch_Jab")); // punch on click
+
+const kb = new KeyboardInput();
+const followCam = new FollowCamera(camera, {
+  domElement: renderer.domElement,
+  colliderMeshes: staticWallMeshes, // static environment ONLY — never the character mesh
+});
+
+// Fixed-substep phase: input + controller brain, BEFORE world.step().
+physics.onBeforeStep(() => {
+  character.setMovement(kb.getCharacterMovement()); // send the COMPLETE intent every step
+  character.update(); // ignores any dt argument — uses the fixed world.timestep internally
+});
+
+// Render phase: step physics, then camera, then animations.
+const pivot = new THREE.Vector3();
+renderer.setAnimationLoop(() => {
+  const delta = clock.getDelta();
+  physics.step(delta); // runs the fixed substeps + world.step() + mesh sync
+
+  pivot.copy(character.currPos).addScaledVector(character.bodyYAxis, 0.5);
+  followCam.moveTo(pivot.x, pivot.y, pivot.z, true);
+  followCam.setUp(character.upAxis);
+  if (physics.stepsLastFrame > 0 && character.isOnPlatform) {
+    followCam.applyPlatformTurn(character.turnOnYQuat); // per-physics-step delta — gate on steps
+  }
+  followCam.update(delta);
+
+  anims.update(character, delta); // see the animations reference
+  vrm.update(delta);              // REQUIRED — ticks the humanoid rig + spring bones
+  renderer.render(scene, camera);
+});
+```
+
+The loop contract is strict: the controller's `update()` runs once per fixed
+physics substep **before** `world.step()` (that is what `onBeforeStep` gives
+you), and camera + animations run once per **render** frame with the render
+delta, after `physics.step(delta)`. Read
+[references/wiring.md](references/wiring.md) for the full walkthrough — level
+colliders, model placement, moving platforms, camera details, enter/exit
+hooks, and disposal.
+
+## Presets and tuning
+
+Spread a preset into the options and override only what feels wrong:
+`"default"`, `"heavy-body-reference"`, `"platformer-snappy"`, `"souls-heavy"`,
+`"moon-bounce"` (needs world gravity `(0, -1.62, 0)`), `"ice-slide"`. Read
+[references/tuning-and-presets.md](references/tuning-and-presets.md) for the
+preset table with provenance, the density/spring scaling rule, and the
+"user says X → tune Y" map. Two traps worth knowing up front:
+
+- `slopeMaxAngle` defaults to `Math.PI / 2.5` (72°) — a 50° ramp is **walkable
+  out of the box**. Cap it (e.g. `Math.PI / 4`) if steep slopes should slide.
+- The capsule ships with friction `-0.5` **on purpose** (grip is synthesized by
+  the controller). Do not "fix" it to a positive value.
+
+## Animations
+
+`CharacterAnimations` resolves seven locomotion states (IDLE / WALK / RUN /
+JUMP_START / JUMP_IDLE / JUMP_FALL / JUMP_LAND) from the controller's live flags
+and crossfades mixer actions. Every OTHER library clip — punches, sword swings,
+pistol fire, spells, sit, dance, hit reactions — plays through
+`anims.playOneShot("Punch_Jab")`, which layers over locomotion and returns to it
+when done (punch-on-click is the default). Read
+[references/animations.md](references/animations.md) for the VRM load + retarget
+wiring, the **full 46-clip catalog** with genre hints, `playOneShot` options,
+overrides, foot IK, and remote-player animation.
+
+## Mobile: TouchJoystick + VirtualButton
+
+```ts
+import { TouchJoystick, VirtualButton } from "./controllers/character/touch-joystick.ts";
+
+const joy = new TouchJoystick({ wrapperStyle: { left: "20px", bottom: "20px" } }); // position is REQUIRED
+const btnJump = new VirtualButton({ label: "Jump", wrapperStyle: { right: "30px", bottom: "30px" } });
+
+physics.onBeforeStep(() => {
+  character.setMovement({
+    ...kb.getCharacterMovement(),
+    jump: kb.space || btnJump.pressed,
+    joystick: { x: joy.x, y: joy.y }, // non-zero joystick overrides the digital keys
+  });
+  character.update();
+});
+```
+
+Show them only on touch devices: `joy.setVisible(navigator.maxTouchPoints > 0)`.
+Give the canvas `touch-action: none` so camera drags aren't hijacked by page
+scrolling. Joystick deflection sets direction only — the controller normalizes
+it, so half-deflection is not half-speed.
+
+## Multiplayer rule (mandatory)
+
+**The local player is physics-authoritative; remote players are interpolated
+visuals only.** Exactly one `CharacterController` exists — yours. For every
+remote player: create a plain mesh (or the same GLB), move it with the
+interpolator from `$genex-threejs-multiplayer`, and **never** create a rigid
+body, a `CharacterController`, or any physics for it. Simulating remote
+players' physics locally guarantees divergence — every client would compute a
+different world.
+
+- Publish your own `currPos` + yaw on the fixed 10–20 Hz tick, not per frame.
+- To animate remotes, sync the five animation booleans and feed them to a
+  per-remote `CharacterAnimations` — see the animations reference.
+- Load `$genex-threejs-multiplayer` before writing any networking code; it is
+  mandatory for any 2+ player game.
+
+## If the user asks for ecctrl
+
+ecctrl is a React / React Three Fiber component; a Genex game is plain
+Three.js with no React, so the package cannot run here. Tell the user plainly:
+*"the library you named requires React, and this game is plain Three.js —
+Genex ships the same controller, ported for your setup."* This vendored
+controller **is** ecctrl's floating-capsule controller translated to plain
+TypeScript classes (same physics model, same tuning options, same feel; see
+`src/controllers/NOTICE.md`). Run `npx genex controller character` and carry
+on — never add React or install the React package to satisfy the request.
+
+## Known benign warning
+
+`@dimforge/rapier3d-compat` logs `using deprecated parameters for the
+initialization function` once at boot. It comes from the library's own
+embedded WASM loader, is harmless, and cannot be fixed from user code — do not
+spend time chasing it.
+
+## Vehicles
+
+For a drivable car or flyable drone — and character ↔ vehicle enter/exit —
+run `npx genex controller car` / `npx genex controller drone` and load the
+`$genex-threejs-vehicle-controllers` skill. The character side of enter/exit is
+already built in: `character.park()`, `character.unpark(position, rotation)`
+and the `isParked` getter (skip `character.update()` while parked).

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

@@ -0,0 +1,235 @@
+# Character animations
+
+`CharacterAnimations` turns the controller's live flags into crossfaded
+`THREE.AnimationMixer` playback: seven states, alias-based clip binding that
+works with the bundled library, Mixamo exports, or arbitrary rigs, and a
+procedural bob/lean fallback when a model has no usable clips at all.
+
+## The bundled assets
+
+`npx genex controller character` sets the game up to play as a **VRM avatar**:
+
+- `public/assets/avatar.vrm` — the player's avatar (yours when signed in, else a
+  bundled CC0 default). Always present; always one path.
+- `public/assets/animation-library.glb` (6.4 MB) — 46 clips on a shared
+  Quaternius rig (provenance in `src/controllers/NOTICE.md`).
+
+VRM helpers live in `src/controllers/character/vrm/`. Install three-vrm once:
+`npm i @pixiv/three-vrm`.
+
+Load the avatar, retarget the library clips onto its humanoid rig, and auto-fit
+the capsule — all with **relative** paths so the published game works under its
+subpath:
+
+```ts
+import { GLTFLoader } from "three/addons/loaders/GLTFLoader.js";
+import { loadVrm } from "./controllers/character/vrm/vrm-loader.ts";
+import { retargetClips } from "./controllers/character/vrm/vrm-retarget.ts";
+import { capsuleFromModel } from "./controllers/character/vrm/capsule-fit.ts";
+import { CharacterController } from "./controllers/character/character-controller.ts";
+import { CharacterAnimations } from "./controllers/character/character-animations.ts";
+import { characterPresets } from "./controllers/character/presets.ts";
+
+const { scene, vrm } = await loadVrm("./assets/avatar.vrm");
+const lib = await new GLTFLoader().loadAsync("./assets/animation-library.glb");
+
+// capsuleFromModel derives the collider from the avatar's bounds — no manual
+// per-avatar tuning even as heights/proportions vary across the library.
+const fit = capsuleFromModel(scene);
+const character = new CharacterController(physics.world, camera, {
+  ...characterPresets["default"].options,
+  ...fit,
+  position: { x: 0, y: 2, z: 0 },
+});
+character.root.add(scene);
+scene.position.y = fit.modelOffsetY; // root = capsule CENTER; drop the model so feet touch the floor
+
+// retargetClips maps the Quaternius rig onto the VRM's normalized humanoid rig
+// (VRM 0.x and 1.0 alike); the result feeds CharacterAnimations unchanged.
+const anims = new CharacterAnimations(scene, retargetClips(vrm, lib.scene, lib.animations));
+```
+
+Per render frame, **after** `physics.step(delta)`:
+
+```ts
+anims.update(character, delta); // the controller itself satisfies the snapshot type
+vrm.update(delta);              // REQUIRED — ticks the humanoid rig + spring bones
+```
+
+`vrm.update(delta)` MUST run every frame, AFTER `anims.update`: it applies the
+animated normalized pose onto the render mesh and advances spring bones (hair,
+cloth). `anims.update` takes the RAW render delta — pause/slow-motion go through
+`anims.setPaused(true)` / `anims.setTimeScale(0.5)` (fade durations stretch with
+the time scale so slow motion doesn't pop).
+
+### Foot IK (optional)
+
+`vrm/foot-ik.ts` plants feet on uneven ground (no skating/floating on steps and
+slopes). It's **opt-in** — locomotion and combat work without it; enable it once
+the avatar's animations look right, injecting a ground query backed by rapier:
+
+```ts
+import { FootIK } from "./controllers/character/vrm/foot-ik.ts";
+const footIK = new FootIK(vrm, (foot) => {
+  const hit = physics.world.castRay(
+    new RAPIER.Ray({ x: foot.x, y: foot.y + 0.5, z: foot.z }, { x: 0, y: -1, z: 0 }),
+    1.5, true);
+  return hit ? foot.y + 0.5 - hit.timeOfImpact : null;
+});
+// each frame, after vrm.update(delta):
+footIK.update(delta);
+```
+
+## States and default clips
+
+The pure resolver (`resolveAnimationState`) maps controller flags to one of:
+
+| State | Bundled clip | Notes |
+| --- | --- | --- |
+| `IDLE` | `Idle_Loop` | starts playing immediately on construction |
+| `WALK` | `Walk_Loop` | |
+| `RUN` | `Jog_Fwd_Loop` | **the default run clip**; `Sprint_Loop` also binds via alias — force it with an override if the user wants an all-out sprint look |
+| `JUMP_START` | `Jump_Start` | one-shot, played at 1.6× so it finishes inside the hop |
+| `JUMP_IDLE` | `Jump_Loop` | airborne, moving up |
+| `JUMP_FALL` | `Jump_Loop` | airborne, moving down (shares the clip — no restart mid-air) |
+| `JUMP_LAND` | `Jump_Land` | one-shot |
+
+## One-shot actions + the 46-clip catalog
+
+The seven states above cover locomotion. **Every other clip** plays through
+`anims.playOneShot(clipName, options?)`: it crossfades the clip over the current
+motion, plays it once, then hands control back to the state machine. Returns
+`false` if the clip name isn't in the set you passed to the constructor.
+
+Punch-on-click is the controller default:
+
+```ts
+let jab = true;
+addEventListener("pointerdown", () => {
+  anims.playOneShot(jab ? "Punch_Jab" : "Punch_Cross");
+  jab = !jab;
+  // Raycast forward from the character; if it hits another player, YOUR game
+  // decides the reaction — e.g. remoteAnims.playOneShot("Hit_Chest").
+});
+```
+
+`options`: `fadeIn` (default 0.1 s), `timeScale`, `clamp` (hold the final pose —
+for deaths), `onDone`.
+
+Full catalog (clip → motion → reach for it when):
+
+| Clip(s) | Motion | Use for |
+| --- | --- | --- |
+| `Punch_Jab` / `Punch_Cross` | quick / heavy punch | melee, click-to-attack (default) |
+| `Punch_Enter` | raise fists | enter a fighting stance |
+| `Hit_Chest` / `Hit_Head` | flinch | taking damage (multiplayer-friendly reactions) |
+| `Death01` | collapse | death — pair with `clamp: true` |
+| `Sword_Idle` / `Sword_Attack` / `Sword_Attack_RM` | ready / swing / swing+step | melee weapons (`_RM` = root motion, travels) |
+| `Pistol_Idle_Loop` / `Pistol_Aim_Up` / `_Neutral` / `_Down` | aim poses | shooters — pick by camera pitch |
+| `Pistol_Shoot` / `Pistol_Reload` | fire / reload | shooter actions |
+| `Spell_Simple_Enter` / `_Idle_Loop` / `_Shoot` / `_Exit` | cast cycle | magic / RPG |
+| `Roll` / `Roll_RM` | dodge roll | dodge (`_RM` travels) |
+| `Interact` / `PickUp_Table` / `Fixing_Kneeling` | reach / pick up / kneel-work | pickups, levers, crafting |
+| `Sitting_Enter` / `_Idle_Loop` / `_Talking_Loop` / `_Exit` | sit / sit-idle / chat / stand | seats, vehicles, dialogue |
+| `Dance_Loop` / `Idle_Talking_Loop` / `Idle_Torch_Loop` | dance / gesture / torch idle | emotes, NPCs, ambience |
+| `Push_Loop` / `Crouch_Idle_Loop` / `Crouch_Fwd_Loop` | push / crouch / crouch-walk | pushing, stealth |
+| `Swim_Idle_Loop` / `Swim_Fwd_Loop` | tread / swim | water |
+| `Walk_Formal_Loop` | stiff walk | override `WALK` for a formal gait |
+| `Driving_Loop` | seated at a wheel | vehicles (see `$genex-threejs-vehicle-controllers`) |
+| `A_TPose` | rest pose | reference only |
+
+For looping poses that should **persist** (aiming, sitting, swimming) rather than
+play once, drive them through the public `anims.mixer` escape hatch instead; the
+`$genex-threejs-vehicle-controllers` skill shows the seated pattern.
+
+## Binding arbitrary rigs (Mixamo included)
+
+`buildClipMap(clips, overrides?)` resolves each state in priority order:
+explicit override (exact, then case-insensitive) → library exact names →
+case-insensitive → each alias as a case-insensitive **substring**, shortest
+matching clip name wins (so `Walk_Loop` beats `Walk_Bwd_Loop`, and Mixamo's
+`walking` beats `walking_backwards`). Aliases include `idle`, `walk`, `run`,
+`jog`, `sprint`, `jump_start`, `takeoff`, `fall`, `land`, and a bare `jump`
+catch-all so a rig whose only airborne clip is "Jumping" still binds all four
+jump states. Unbound loop states chain (RUN↔WALK, JUMP_IDLE↔JUMP_FALL);
+unbound one-shots stay silent so the previous loop keeps playing.
+
+If a name refuses to bind, pass overrides:
+
+```ts
+const anims = new CharacterAnimations(model, gltf.animations, {
+  clipMap: { RUN: "Sprint_Loop", JUMP_START: "MyTakeoff" },
+  onChange: (state) => { if (state === "JUMP_LAND") playLandSfx(); },
+});
+console.log(anims.clipMap); // inspect what actually bound, per state
+```
+
+### Rig mismatch guard
+
+Clips whose tracks target bones the model doesn't have spam PropertyBinding
+warnings. When mixing a custom model (e.g. from `$genex-ai-model` — note
+generated props are usually rig-less) with the bundled library, filter first:
+
+```ts
+const clips = libGltf.animations.filter((clip) =>
+  clip.tracks.every((track) => {
+    const { nodeName } = THREE.PropertyBinding.parseTrackName(track.name);
+    return nodeName !== undefined && model.getObjectByName(nodeName) !== undefined;
+  })
+);
+```
+
+## Rig-less models: the procedural fallback
+
+Pass an empty clip array (or clips that bind nothing) and the default
+`fallback: "auto"` mode drives the model with a procedural walk/run bob, a
+forward lean while moving, an air lean, and a landing dip — additive over the
+model's transform at construction time, so any capsule, robot, or generated
+prop reads as alive with zero animation work. `fallback: "procedural"` forces
+it even when clips exist; `"none"` leaves the model static. Check
+`anims.usingProceduralFallback` to see which path is live.
+
+```ts
+const anims = new CharacterAnimations(placeholderMesh, []); // procedural fallback kicks in
+```
+
+## Remote players (multiplayer)
+
+The snapshot type is structural — **anything** with the five booleans works,
+which is exactly what remote players need. Remote players have no physics and
+no `CharacterController` (see the SKILL's multiplayer rule): sync the five
+flags from the owner and feed them straight in.
+
+```ts
+// Sender (local player), on the 10-20 Hz tick — alongside position/yaw:
+const flags = {
+  isOnGround: character.isOnGround,
+  isFalling: character.isFalling,
+  isMoving: character.isMoving,
+  runActive: character.runActive,
+  jumpActive: character.jumpActive,
+};
+
+// Receiver: one CharacterAnimations per remote model, fed the synced flags.
+remoteAnims.update(remoteState.flags, delta);
+```
+
+The mixer crossfades exactly as it does locally, so remote players animate
+correctly without simulating anything. In v1 every player loads the same
+`./assets/avatar.vrm` (the game owner's avatar), so remotes look like the owner —
+load each remote through `loadVrm` + `retargetClips` just like the local one, and
+call `vrm.update(delta)` per remote each frame. Relay one-shot events (punch, hit)
+alongside the flags and call `remoteAnims.playOneShot("Hit_Chest")` on receipt.
+Full networking patterns: `$genex-threejs-multiplayer`.
+
+## Gotchas
+
+- Call `anims.update` once per render frame, never inside
+  `physics.onBeforeStep`.
+- The state machine reads **input-based** `isMoving` — a character shoved by
+  physics while the player is idle stays in IDLE by design (matches the feel
+  players expect).
+- One-shots lock transitions until they finish (`JUMP_START` → the lock
+  releases into `JUMP_IDLE`); this is internal — don't try to manage it.
+- `dispose()` stops all actions and releases the mixer listener; call it when
+  the character leaves the scene.

package/templates/skills/genex-threejs-character-controller/references/tuning-and-presets.md

@@ -0,0 +1,102 @@
+# Presets and tuning
+
+Every option has a tuned default — start from a preset and override only what
+feels wrong. Spread the preset's `options` into the constructor:
+
+```ts
+import { characterPresets } from "./controllers/character/presets.ts";
+
+const character = new CharacterController(world, camera, {
+  ...characterPresets["platformer-snappy"].options,
+  maxRunVel: 8, // your overrides win
+  userData: { controller: { excludeVehicleRay: true } },
+});
+```
+
+## Preset table
+
+| Preset | Provenance | Assumed density | Feel |
+| --- | --- | --- | --- |
+| `default` | ported library defaults, verbatim | 1 | balanced third-person: walk 2 m/s, run 5 m/s, decisive jump, moderate grip |
+| `heavy-body-reference` | ported demo tuning, verbatim | **200** | heavy body with proportionally stiff springs — the reference for the scaling rule below |
+| `platformer-snappy` | Genex-authored | 1 | quick starts/stops, strong jump + heavy fall, extra air control, hold-to-run |
+| `souls-heavy` | Genex-authored | 1 | weighty, committed movement; low deliberate jump; pronounced run lean |
+| `moon-bounce` | Genex-authored | 1 | long floaty jumps — **requires world gravity `(0, -1.62, 0)`**; the preset does not set world gravity for you |
+| `ice-slide` | Genex-authored | 1 | near-zero grip, wide sliding turns |
+
+Every preset states the collider `density` it was tuned for
+(`assumedDensity`, mirrored into `options.density`). That matters because of:
+
+## The density/spring scaling rule
+
+The float spring and auto-balance springs apply raw impulses, so they scale
+roughly **linearly with body mass** (mass = density × capsule volume). Change
+`density` (or the capsule size) and the springs must scale in the same
+proportion or the character sinks/oscillates/faceplants. The two shipped
+anchor points:
+
+| Option | density 1 (`default`) | density 200 (`heavy-body-reference`) |
+| --- | --- | --- |
+| `springK` | 80 | 6400 |
+| `dampingC` | 6 | 860 |
+| `autoBalanceSpringK` | 0.5 | 50 |
+| `autoBalanceDampingC` | 0.03 | 3 |
+| `autoBalanceSpringOnY` | 0.08 | 8 |
+| `autoBalanceDampingOnY` | 0.006 | 0.76 |
+
+Recipe for "make the character feel heavier": raise `density`, multiply those
+six constants by the density ratio as a starting estimate (the reference
+values are hand-tuned near that line, not exactly on it), then fine-tune —
+pogo bounce means `dampingC` too low, sticky landings too high, slow-motion
+tip-overs mean the `autoBalance*` pair is too soft.
+
+## "User says X → tune Y" map
+
+| The user says | Change |
+| --- | --- |
+| "it's slippery / skates around" | raise `slideGripFactor` (default 0.5; `ice-slide` uses 0.05) |
+| "falling feels floaty" | raise `fallingGravityScale` (default 3) |
+| "jump too weak / too strong" | `jumpVel` (default 5 m/s); `jumpDuration` (default 0.1 s) stretches the takeoff window |
+| "it walks up cliffs / slopes that should slide" | lower `slopeMaxAngle` — **default is `Math.PI / 2.5` = 72°, so a 50° ramp is walkable out of the box**; `Math.PI / 4` makes 45°+ slide |
+| "should climb steeper slopes" | raise `slopeMaxAngle` |
+| "feels heavier / like a tank" | `souls-heavy` preset, or raise `density` + apply the spring scaling rule above |
+| "sluggish to start / stop" | raise `accDeltaTime` / `decDeltaTime` (responsiveness in (0, 1]; default 0.2 — higher is snappier) |
+| "drifts sideways through turns" | raise `rejectVelFactor` toward 1 (default 1; `ice-slide` lowers it to 0.2) |
+| "too slow / too fast" | `maxWalkVel` (default 2) / `maxRunVel` (default 5) |
+| "run should be hold, not toggle" | `enableToggleRun: false` (default true = Shift toggles) |
+| "no control in the air" | raise `airDragFactor` (default 0.1) |
+| "falls too fast at terminal velocity" | `fallingMaxVel` (default 20 m/s) |
+| "leans too much when running" | lower `moveImpulsePointOffset` (default 0.5; 0 = no lean) |
+| "wobbles / tips over" | raise `autoBalanceSpringK` + `autoBalanceDampingC` |
+| "turns to face direction too slowly" | raise `autoBalanceSpringOnY` |
+| "grounded flag flickers on stairs / ledges" | raise `rayHitForgiveness` (default 0.28) |
+| "bounces on landing (pogo)" | raise `dampingC`; "sticks to the ground on landing" → lower it |
+| "hovers too high / feet in the floor" | `floatHeight` (default 0.2) — and re-check the model's foot offset (wiring reference) |
+| "should always face the camera (strafe/shooter)" | `lockForward: true`, or `setLockForward(true)` at runtime |
+| "jump should push off slopes" | `slopeJumpFactor` (default 0 = straight up, 1 = off the slope normal) |
+| "moon / low gravity" | `moon-bounce` preset **plus** `PhysicsWorld.create({ gravity: [0, -1.62, 0] })` |
+| "camera feels laggy / rubber-bandy" | `FollowCamera` `smoothTime` (0.05 snappy → 0.25 cinematic) |
+| "camera clips through walls" | add the static level meshes to `FollowCamera` `colliderMeshes` |
+
+## Sizing a different character
+
+`capsuleHalfHeight` (default 0.3) and `capsuleRadius` (default 0.3) define the
+collider: total capsule height = `2 * (capsuleHalfHeight + capsuleRadius)` =
+1.2 by default, floating `floatHeight` above the ground. For a bigger
+character scale both, remember the ground-query defaults derive from them
+(`rayLength = capsuleRadius + 1`, `rayRadius = capsuleRadius / 2`,
+`rayOriginOffset = -capsuleHalfHeight`), and re-tune the springs — a bigger
+capsule is a heavier body at the same density.
+
+## Do-not-touch list
+
+- `friction: -0.5` on the capsule is intentional (negative averages against
+  the ground and keeps the capsule from grabbing walls); traction comes from
+  the controller's own grip model, not collider friction.
+- Ground detection: `"shapeCast"` (default) is forgiving on stairs and ledge
+  edges; `"rayCast"` is cheaper and stricter. Switch at runtime with
+  `setGroundDetection(...)` — don't hand-roll a third scheme.
+- Platform behavior (`followPlatform`, `applyCounterMass`,
+  `applyCounterJumpImp`, `applyCounterMoveImp`) defaults to physically-honest
+  and already handles moving/rotating platforms; only touch these for
+  deliberate arcade effects.