@genex-ai/cli-demo 0.12.1 → 0.14.2

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

@@ -0,0 +1,150 @@
+# Drone: DroneController + propellers
+
+`DroneController` (`drone/drone-controller.ts`) is a PD flight brain over a
+**caller-created** dynamic body: each registered propeller contributes thrust
+along its mount's local +Y plus a reaction torque; every step the brain
+computes a hover throttle (weight / total upward thrust potential) and mixes
+per-propeller attitude corrections on top, clamped so attitude control never
+costs altitude. Unlike the car, the controller never creates or frees the
+body — you build body, colliders, and chassis visuals, then hand them over.
+
+`dronePresets` (`drone/presets.ts`) are complete recipes: `config` (merged
+over `DEFAULT_DRONE_CONFIG`), four propeller slots in a quad-X layout, and a
+collider recipe (`body`) with the density the gains were tuned against.
+
+## Wiring (from the preset recipe)
+
+```ts
+import * as THREE from "three";
+import { PhysicsWorld } from "./controllers/shared/physics-world.ts";
+import { cuboidCollider, cylinderCollider } from "./controllers/shared/colliders.ts";
+import { DroneController, type PropellerOptions } from "./controllers/drone/drone-controller.ts";
+import { dronePresets } from "./controllers/drone/presets.ts";
+import { KeyboardInput } from "./controllers/character/keyboard-input.ts";
+
+const physics = await PhysicsWorld.create();
+const preset = dronePresets["camera-drone"];
+
+// 1. Chassis visual root + one mount Object3D per propeller (descendants of
+//    the chassis; local +Y = thrust axis). spinModel is optional blade visual.
+const chassis = new THREE.Group();
+chassis.add(coreMesh); // your body visual
+const propellers: PropellerOptions[] = [];
+for (const p of preset.propellers) {
+  const mount = new THREE.Object3D();
+  mount.position.set(p.position.x, p.position.y, p.position.z);
+  chassis.add(mount);
+  const blade = new THREE.Mesh(bladeGeom, bladeMat);
+  mount.add(blade);
+  propellers.push({
+    object: mount,
+    spinModel: blade,
+    maxThrust: p.maxThrust,
+    torqueRatio: p.torqueRatio,
+    invertTorque: p.invertTorque,
+  });
+}
+scene.add(chassis);
+
+// 2. Dynamic body + colliders from the preset recipe (density sets the mass).
+const body = physics.createBody({ type: "dynamic", position: [-6, 1.6, 14] }, chassis);
+const b = preset.body;
+cuboidCollider(physics.world, body,
+  [b.cuboidHalfExtents.x, b.cuboidHalfExtents.y, b.cuboidHalfExtents.z],
+  { density: b.density });
+for (const pos of b.armCylinders.positions) {
+  cylinderCollider(physics.world, body, b.armCylinders.halfHeight, b.armCylinders.radius,
+    { position: [pos.x, pos.y, pos.z], density: b.density });
+}
+
+// 3. Controller + fixed-step update (BEFORE world.step()).
+const drone = new DroneController({
+  world: physics.world,
+  body,
+  chassis,
+  propellers,
+  config: preset.config,
+});
+const kb = new KeyboardInput(); // W/S throttle, A/D yaw, arrows pitch/roll
+physics.onBeforeStep(() => {
+  drone.setMovement(kb.getDroneMovement());
+  drone.update();
+});
+```
+
+The keyboard scheme is deliberately asymmetric (WASD = throttle/yaw, arrows
+= pitch/roll — they are NOT aliases; do not "unify" them). Touch sticks map
+as `joystickL` = climb/yaw, `joystickR` = pitch/roll.
+
+## Control modes: VELOCITY vs POSITION
+
+`DroneControlMode` — switch at runtime with `drone.setControlMode(mode)`:
+
+- **`"VELOCITY"`** — stick flying: inputs command velocities (up to
+  `maxHorizSpeed` / `maxVertSpeed` / `maxYawRate`) and the PD loop converts
+  them to tilt + throttle. Use while a player is on board.
+- **`"POSITION"`** — autopilot: the drone holds `targetPos` and faces
+  `targetFwd`. Use for parked, idle, or scripted drones. The parking recipe
+  (also what the enter/exit hook does on dismount):
+
+```ts
+drone.setTarget(drone.currPos, drone.bodyZAxis); // hold HERE, facing THIS way
+drone.setControlMode("POSITION");
+```
+
+Set the target BEFORE anything else moves — `currPos`/`bodyZAxis` are live
+vectors; `setTarget` copies them.
+
+## The PD gain mass-scaling rule
+
+`DroneConfig` gains fall into two families — this is the single most common
+tuning mistake:
+
+- **`VERT_POS_P/D`, `HORIZ_POS_P/D`** (POSITION-mode hold gains) are in
+  **absolute force units** — they MUST scale with the drone's mass. The
+  library defaults fit a ~2 kg drone; the `heavy-lifter` preset (~298 kg)
+  ships them pre-scaled ×100 (e.g. `VERT_POS_P: 900` vs default 9). A drone
+  that sags away from its hold point or oscillates around it after a mass
+  change has stale POSITION gains.
+- **`HORIZ_VEL_P`, `VERT_VEL_P`** (VELOCITY-mode gains) are in
+  **acceleration units** — mass-independent, usually fine as-is.
+- `airDragFactor` is also an absolute force per (m/s): meaningful on a 2 kg
+  drone, cosmetic on a 300 kg one.
+- Attitude feel: sluggish to tilt → raise `TILT_P`; wobbles/overshoots after
+  a maneuver → raise `TILT_D`. `maxTiltAngle` caps how far it leans (and
+  therefore horizontal acceleration).
+
+Tune at runtime with `drone.updateConfig({ TILT_P: 18 })` — it recomputes
+the cached tilt limit when `maxTiltAngle` changes.
+
+## Propeller sizing
+
+- Size `maxThrust` so total thrust ≈ **2× the drone's weight**: hover
+  throttle then sits near 0.5, which maximizes attitude authority (the mixer
+  clamps corrections to `min(1 - hover, hover)`). Check `drone.hoverThrottle`
+  at runtime — near 1 means underpowered (climbs barely, steers worse).
+- Diagonal pairs must share the same `invertTorque` value (quad-X
+  counter-rotation) or reaction torques won't cancel and the drone yaws
+  constantly.
+- `debug: true` on a propeller attaches upstream thrust/torque arrows +
+  axis markers under the mount — great while building a custom frame.
+
+## Presets and provenance
+
+| Preset | Mass | Feel | Provenance |
+| --- | --- | --- | --- |
+| `camera-drone` | ~2 kg (density 335) | gentle 20° tilt limit, strong drag, floaty on purpose | Genex-authored |
+| `racing-drone` | ~5 kg (density 240) | full 45° tilt, fast yaw, snappy `TILT_P: 18` | Genex-authored |
+| `heavy-lifter` | ~298 kg (density 200) | huge climb reserve, hover ~0.146, POSITION gains ×100 | upstream demo, verbatim |
+
+Each preset's `notes` field carries its own plain-language tuning hints; the
+`approxMassKg`/`approxHoverThrottle` fields are documentation values (Rapier
+derives the real mass from the colliders and density).
+
+## Telemetry for effects
+
+`drone.propellersInfo` (a `ReadonlyMap<string, PropellerState>`) exposes per
+propeller: `finalThrottle` (0..1 mixer output — rotor-wash/audio intensity),
+`worldThrustPos`/`worldThrustDir` (where and which way to emit), and
+`thrustImpulse`. `drone.hoverThrottle` reads the last computed hover value.
+All vectors are reused internal instances — copy, never mutate.

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

@@ -0,0 +1,199 @@
+# Enter/exit: character ↔ vehicle handoff
+
+`EnterExitManager` (`interact/enter-exit.ts`) owns the whole flow: it puts a
+proximity sensor on every registered vehicle, surfaces a "Press F" prompt
+when the on-foot character walks into one, and on interact **parks** the
+character (hidden + physics disabled) and hands control — input routing and
+camera target — to the vehicle; interacting again places the character
+beside the vehicle and hands control back.
+
+It needs the on-foot character from `npx genex controller character`
+(`CharacterController` implements the `park()`/`unpark()` contract the
+manager calls; see `$genex-threejs-character-controller`). `CHARACTER_ID`
+(`"character"`) is the reserved id for the on-foot unit.
+
+## Wiring
+
+```ts
+import { EnterExitManager, CHARACTER_ID } from "./controllers/interact/enter-exit.ts";
+
+const mgr = new EnterExitManager({
+  world: physics.world,
+  character, // the CharacterController instance
+  applyCharacterInput: () => {
+    character.setMovement(kb.getCharacterMovement()); // routed only while on foot
+  },
+  onPromptChange: (target) => {
+    // Drive your DOM prompt from here; fires on change only (incl. -> null).
+    promptEl.textContent = target ? `Press F to enter ${target.label}` : "";
+    promptEl.style.display = target ? "block" : "none";
+  },
+  onHandoff: (fromId, toId) => {
+    // Fires after control switches — seat visuals + input hygiene (below).
+  },
+});
+
+mgr.registerVehicle({
+  id: "car",
+  label: "Car",
+  vehicle: car,                       // VehicleController satisfies this structurally
+  exitAxis: "bodyX",                  // cars step out sideways
+  exitLength: 2.2,
+  // radius ≥ the chassis half-length (2.4 here) — see "Sensor and exit tuning".
+  sensor: { kind: "cylinder", halfHeight: 0.5, radius: 2.5, offset: { x: 0, y: 0.1, z: 0 } },
+  applyInput: () => car.setMovement(kb.getCarMovement()), // routed only while driving
+});
+
+mgr.registerVehicle({
+  id: "drone",
+  label: "Drone",
+  vehicle: drone,
+  exitAxis: "up",                     // the drone drops the pilot off below it
+  exitLength: 1.6,
+  sensor: { kind: "ball", radius: 2.4 },
+  applyInput: () => drone.setMovement(kb.getDroneMovement()),
+  onOccupantEnter: () => {
+    drone.setControlMode("VELOCITY"); // stick flying while boarded
+  },
+  onOccupantExit: () => {
+    // Fires BEFORE the character is unparked — capture the hold pose first.
+    drone.setTarget(drone.currPos, drone.bodyZAxis);
+    drone.setControlMode("POSITION"); // autopilot-hover where it was left
+  },
+});
+
+// Sensor events: feed the raw collision tap into the manager.
+physics.onCollisionEvent((h1, h2, started) =>
+  mgr.handleIntersectionEvent(h1, h2, started)
+);
+
+// Interact: EDGE-triggered (key transition, never a held-key poll — that
+// would enter and exit every frame). kb.onInteract is the F key, pre-guarded.
+kb.onInteract(() => mgr.requestInteract());
+```
+
+Loop order per fixed substep (inside `physics.onBeforeStep`): **`mgr.update(dt)`
+FIRST** (consumes the interact request, refreshes the camera feed, routes
+input to the active unit), then the controller `update()`s, then the world
+steps. Skip `character.update()` while `character.isParked`. Sensor events
+drain after the step, so proximity lags input by at most one frame — as
+designed.
+
+Registration order = prompt priority: when two sensors overlap, the first
+registered vehicle wins the prompt.
+
+## Sensor and exit tuning
+
+- Default sensor: cylinder `halfHeight 0.4, radius 1.5, offset (0, 0.1, 0)`.
+  `radius` is the knob that matters for prompt range. Sensors are mass-0 —
+  they never shift the chassis center of mass.
+- **Long-chassis gotcha (measured in the testbed):** the sensor is centered
+  on the body, so if the chassis half-length exceeds the sensor radius
+  (testbed car: half-length 2.4 vs radius 2.2), walking up from dead astern
+  touches the bumper before the capsule enters the sensor — the prompt only
+  appears after sliding along the side, while a side approach prompts
+  immediately. Fix: sensor radius ≥ chassis half-length, or an offset
+  sensor per end.
+- `exitLength` (default 1.5) is how far along `exitAxis` the character
+  reappears. Raise it if the character spawns inside a wide chassis. The
+  default equals the default sensor radius so immediate re-entry stays
+  possible — intended.
+- Exiting a flipped vehicle whose forward axis is parallel to up produces a
+  degenerate exit basis (faithful upstream non-guard). If vehicles in your
+  game can end up nose-down, right them before allowing exit.
+
+## Seat visuals: Sitting_Enter / Driving_Loop / Sitting_Exit
+
+`park()` hides the character body and visuals — the manager does NOT animate
+a seated pilot; that is game glue on the `onHandoff` seam. The pattern: keep
+a reference to the character's visual model, re-parent it into a seat anchor
+under the vehicle's chassis object, and play the seat clips through a
+dedicated `THREE.AnimationMixer` (the locomotion state machine is idle while
+parked). The clips ship in `animation-library.glb` (installed by
+`npx genex controller character`).
+
+```ts
+const seatMixer = new THREE.AnimationMixer(characterModel);
+const seatAnchor = new THREE.Group();
+
+function enterSeat(host: THREE.Object3D, seatPos: THREE.Vector3) {
+  seatAnchor.position.copy(seatPos);        // e.g. (0, 0.55, -0.6) for a car cabin
+  host.add(seatAnchor);
+  characterModel.position.set(0, 0, 0);     // remember the old pose to restore on exit
+  characterModel.quaternion.identity();
+  seatAnchor.add(characterModel);
+  const enter = seatMixer.clipAction(sittingEnterClip); // "Sitting_Enter"
+  enter.reset();
+  enter.setLoop(THREE.LoopOnce, 1);
+  enter.clampWhenFinished = true;
+  enter.play();
+  // On the mixer's "finished" event, crossFade to the "Driving_Loop" action.
+}
+
+function exitSeat() {
+  // Optionally play "Sitting_Exit" (LoopOnce) before restoring; then:
+  seatMixer.stopAllAction();
+  seatAnchor.removeFromParent();
+  character.root.add(characterModel);       // restore the remembered pose
+}
+
+// onHandoff wiring: enter when control moves TO a vehicle, exit when it
+// returns to the character.
+onHandoff: (fromId, toId) => {
+  if (toId !== CHARACTER_ID) enterSeat(hostFor(toId), seatPosFor(toId));
+  else exitSeat();
+  // Input hygiene: zero the released unit's held inputs, or an exited car
+  // keeps driving on its last merged input state.
+  if (fromId === "car") car.setMovement({ forward: false, backward: false,
+    steerLeft: false, steerRight: false, brake: false });
+}
+```
+
+While parked, tick `seatMixer.update(renderDelta)` in the render loop
+instead of the locomotion `CharacterAnimations.update()`. With a rig-less
+model (no matching clips) skip the mixer and just re-seat the visual — the
+handoff still works.
+
+## Camera handoff via FollowCamera
+
+The manager exposes a camera feed; the bundled `FollowCamera` consumes it.
+Per RENDER frame (render delta — never inside the fixed step):
+
+```ts
+const t = mgr.cameraTarget;              // activeUnit.currPos + bodyYAxis * 0.5
+followCam.moveTo(t.x, t.y, t.z, true);
+followCam.setUp(mgr.cameraUp);           // activeUnit.upAxis
+if (mgr.activeControllerId === CHARACTER_ID) {
+  if (physics.stepsLastFrame > 0 && character.isOnPlatform) {
+    followCam.applyPlatformTurn(character.turnOnYQuat); // per-physics-step delta
+  }
+} else if (mgr.activeVehicle) {
+  followCam.alignHeading(mgr.activeVehicle.bodyZAxis, delta); // ease behind the vehicle
+}
+followCam.update(delta);
+```
+
+`alignHeading` eases the orbit behind the vehicle at `headingAlignGain`
+(default 5; 0 disables) and always yields to an active user drag-orbit.
+`cameraTarget`/`cameraUp` are reused internal vectors — copy, never mutate.
+
+**Follow camera v1 limits (by design):** no pointer-lock look mode, no
+truck/pan (the pivot is always the followed unit), and the orbit space
+assumes up ≈ +Y — `camera.up` lerps toward the fed up-axis, but a
+far-from-Y gravity direction will misbehave. For rigs beyond this, see
+`$genex-threejs-camera-direction`.
+
+## Multiplayer
+
+Occupancy is shared state — remote players must see who is in what. With
+`$genex-threejs-multiplayer` (load it before writing any networking code):
+
+- Put `driving: "car" | "drone" | null` in each player's synced state; on
+  remote change, show/hide that player's on-foot avatar and seat their
+  visual in the vehicle (the seat-visual pattern above, minus the physics).
+- The occupant simulates the vehicle and publishes its pose; everyone else
+  interpolates a plain mesh. Never run the vehicle controllers for a remote
+  player's vehicle.
+- Gate entry on a shared occupancy key so two players can't board the same
+  seat: claim it (e.g. `room.shared.set("occupant:car", room.id)`) and treat
+  a losing race as "prompt stays up".