feat: click-to-walk waypoint control

app/src/game/controls/waypoint.js

@@ -0,0 +1,153 @@
+// Waypoint input source (see controller.js for the source interface
+// contract). PLAN.md Project 1 Phase A: click a point on the arena floor,
+// the duck walks there. No new policy - this only turns a click into the
+// same [vx, vy, wz] twist the walking policy already tracks.
+//
+// Click, not drag-follow: the mouse already drives OrbitControls (camera
+// orbit) and the duck/ball grab-drag, so a live cursor-follow twist would
+// fight both. A plain click (small movement, short hold) on empty floor
+// is otherwise unclaimed input, and reads naturally as "go here" - the
+// same gesture Project 5's tile grid uses.
+//
+// Arbitration: registered LAST in game.js's source list, so it is the
+// Controller's fallback exactly like the keyboard source used to be -
+// any keyboard/pad/touch input immediately preempts it (see
+// controller.js's arbitration notes), and getManualOverride() cancels the
+// pending target outright so releasing manual input doesn't snap the duck
+// back onto a stale click.
+
+import * as THREE from "three";
+import { ARENA_HALF } from "../constants.js";
+
+const WAYPOINT_ARRIVE_RADIUS = 0.12; // m, dead zone - commands zero inside it
+const WAYPOINT_TURN_GAIN = 2.2; // rad/s commanded per rad of heading error, pre-clamp
+const WAYPOINT_SMOOTH_ALPHA = 0.15; // EMA toward the steered command, per render frame
+const WAYPOINT_CLICK_SLOP = 6; // px, pointerdown -> pointerup movement budget for a "click"
+const WAYPOINT_CLICK_MS = 500; // ms, pointerdown -> pointerup duration budget
+
+const wrapPi = (a) => Math.atan2(Math.sin(a), Math.cos(a));
+// Three world (x, y, z) -> MJCF ground (x, -z); floor sits at three y = 0.
+const FLOOR_PLANE = new THREE.Plane(new THREE.Vector3(0, 1, 0), 0);
+
+export class WaypointSource {
+  id = "waypoint";
+  connected = true; // a mouse is assumed present, like the keyboard
+  command = new Float32Array(3); // [vx, 0, wz], EMA-smoothed toward the target
+  axes = { jaw: 0, orbitX: 0, orbitY: 0 }; // drives none of these
+  pressed = {};
+  onAction = () => {}; // assigned by the Controller at registration
+
+  #camera;
+  #renderer;
+  #getVelocityLimits;
+  #getDuckPose; // () => [x, y, yaw] MJCF ground pose
+  #isSuppressed; // () => true while a click must not arm (grabbing, locked, wrong mode)
+  #getManualOverride; // () => true while another source is actively driving
+  #target = null; // [x, y] MJCF, or null when idle
+  #active = false;
+  #downAt = null; // { x, y, t } pointerdown snapshot, for the click-vs-drag check
+  #raycaster = new THREE.Raycaster();
+  #ndc = new THREE.Vector2();
+  #hit = new THREE.Vector3();
+  #onDown = null;
+  #onUp = null;
+
+  constructor({ camera, renderer, getVelocityLimits, getDuckPose, isSuppressed, getManualOverride }) {
+    this.#camera = camera;
+    this.#renderer = renderer;
+    this.#getVelocityLimits = getVelocityLimits;
+    this.#getDuckPose = getDuckPose;
+    this.#isSuppressed = isSuppressed;
+    this.#getManualOverride = getManualOverride;
+  }
+
+  init() {
+    this.#onDown = (e) => {
+      if (e.pointerType !== "mouse" || e.button !== 0) return;
+      if (e.target !== this.#renderer.domElement) return;
+      if (this.#isSuppressed()) return;
+      this.#downAt = { x: e.clientX, y: e.clientY, t: performance.now() };
+    };
+    this.#onUp = (e) => {
+      if (!this.#downAt || e.pointerType !== "mouse" || e.button !== 0) { this.#downAt = null; return; }
+      const { x, y, t } = this.#downAt;
+      this.#downAt = null;
+      if (this.#isSuppressed()) return;
+      const moved = Math.hypot(e.clientX - x, e.clientY - y);
+      const held = performance.now() - t;
+      // A drag (orbit or grab) shows up as either more movement than a
+      // click budget allows, or a slow deliberate press - either way, not
+      // a click.
+      if (moved > WAYPOINT_CLICK_SLOP || held > WAYPOINT_CLICK_MS) return;
+      this.#setTargetFromEvent(e);
+    };
+    window.addEventListener("pointerdown", this.#onDown);
+    window.addEventListener("pointerup", this.#onUp);
+  }
+
+  dispose() {
+    window.removeEventListener("pointerdown", this.#onDown);
+    window.removeEventListener("pointerup", this.#onUp);
+  }
+
+  isActive() {
+    return this.#active;
+  }
+
+  // Current target in MJCF ground coords, or null - read by game.js to
+  // place the click marker. Read-only.
+  get target() {
+    return this.#target;
+  }
+
+  // Cancel a pending target without walking it down (sim reset, mode
+  // change out from under it).
+  cancel() {
+    this.#target = null;
+    this.#active = false;
+    this.command.fill(0);
+  }
+
+  poll() {
+    if (this.#target && this.#getManualOverride()) this.#target = null;
+    if (!this.#target) {
+      this.command.fill(0);
+      this.#active = false;
+      return;
+    }
+    const [px, py, yaw] = this.#getDuckPose();
+    const dx = this.#target[0] - px, dy = this.#target[1] - py;
+    const dist = Math.hypot(dx, dy);
+    if (dist < WAYPOINT_ARRIVE_RADIUS) {
+      this.#target = null;
+      this.command.fill(0);
+      this.#active = false;
+      return;
+    }
+    const err = wrapPi(Math.atan2(dy, dx) - yaw);
+    const [limF, , limA] = this.#getVelocityLimits();
+    const wz = Math.min(limA, Math.max(-limA, err * WAYPOINT_TURN_GAIN));
+    // Forward speed falls off with heading error so the duck turns in
+    // place first rather than strafing (there is no strafe) toward a
+    // target that's behind it.
+    const vx = limF * Math.max(0, Math.cos(err));
+    this.command[0] += WAYPOINT_SMOOTH_ALPHA * (vx - this.command[0]);
+    this.command[2] += WAYPOINT_SMOOTH_ALPHA * (wz - this.command[2]);
+    this.#active = true;
+  }
+
+  #setTargetFromEvent(e) {
+    const r = this.#renderer.domElement.getBoundingClientRect();
+    this.#ndc.set(
+      ((e.clientX - r.left) / r.width) * 2 - 1,
+      -((e.clientY - r.top) / r.height) * 2 + 1,
+    );
+    this.#raycaster.setFromCamera(this.#ndc, this.#camera);
+    if (!this.#raycaster.ray.intersectPlane(FLOOR_PLANE, this.#hit)) return;
+    const lim = ARENA_HALF - 0.05;
+    this.#target = [
+      Math.min(lim, Math.max(-lim, this.#hit.x)),
+      Math.min(lim, Math.max(-lim, -this.#hit.z)), // three -> MJCF
+    ];
+  }
+}

app/src/game/game.js

@@ -47,6 +47,7 @@ import { KeyboardSource } from "./controls/keyboard.js";
 import { GamepadSource } from "./controls/gamepad.js";
 import { haptics } from "./haptics.js";
 import { TouchSource } from "./controls/touch.js";
+import { WaypointSource } from "./controls/waypoint.js";
 import * as fx from "./fx/fx-wireframe.js";
 import { createCeremony, CAM_RESET_S } from "./ceremony.js";
 import {
@@ -71,6 +72,16 @@ import ortWasmUrl from "onnxruntime-web/ort-wasm-simd-threaded.wasm?url";
 
 let bootStarted = false;
 
+// Trunk yaw from the freejoint quat (MuJoCo wxyz), Z-up so this is rotation
+// about z. Shared by the chase cam and the waypoint follower - both need
+// "which way is the duck facing" in MJCF ground coords.
+function duckYaw(qpos) {
+  return Math.atan2(
+    2 * (qpos[3] * qpos[6] + qpos[4] * qpos[5]),
+    1 - 2 * (qpos[5] * qpos[5] + qpos[6] * qpos[6]),
+  );
+}
+
 // HMR teardown for the ghost session: invalidating this module (directly or
 // via an edit to ghosts.js) used to stack a live 15 Hz broadcast interval
 // plus a ghost room per reload (the historical "stale module" bug class).
@@ -396,8 +407,23 @@ async function boot({ scene, camera, renderer }) {
   const kbSource = new KeyboardSource({ getVelocityLimits: () => velLims() });
   const padSource = new GamepadSource({ getVelocityLimits: () => velLims() });
   const touchSource = new TouchSource({ getVelocityLimits: () => velLims() });
-  // Keyboard last: it reads zero when idle, so it doubles as the fallback.
-  const controller = new Controller({ sources: [padSource, touchSource, kbSource] });
+  // Click-to-walk (PLAN.md Project 1 Phase A): reads zero until a floor
+  // click arms a target, so - like the keyboard before it - it doubles as
+  // the fallback. Any keyboard/pad/touch input preempts it by arbitration
+  // order alone; getManualOverride also cancels the pending target outright
+  // so releasing manual input doesn't snap the duck back onto a stale click.
+  const waypointSource = new WaypointSource({
+    camera, renderer,
+    getVelocityLimits: () => velLims(),
+    getDuckPose: () => {
+      const qpos = data.qpos;
+      return [qpos[0], qpos[1], duckYaw(qpos)];
+    },
+    isSuppressed: () => inputLocked || headMode || mode !== "walk" || !!grab,
+    getManualOverride: () => padSource.isActive() || touchSource.isActive() || kbSource.isActive(),
+  });
+  // Keyboard, pad and touch preempt by priority; waypoint is the fallback.
+  const controller = new Controller({ sources: [padSource, touchSource, kbSource, waypointSource] });
   // Right-stick camera state, read by the telemetry before the camera-orbit
   // section below has evaluated.
   let padOrbitLive = false;
@@ -1274,10 +1300,7 @@ async function boot({ scene, camera, renderer }) {
     if (mode === "roll" || isKick()) {
       rawYaw = chaseHeldYaw;
     } else {
-      rawYaw = Math.atan2(
-        2 * (qpos[3] * qpos[6] + qpos[4] * qpos[5]),
-        1 - 2 * (qpos[5] * qpos[5] + qpos[6] * qpos[6]),
-      );
+      rawYaw = duckYaw(qpos);
       chaseHeldYaw = rawYaw;
     }
     // "turning" reads the raw per-source wz commands (not the locked/merged
@@ -1326,10 +1349,7 @@ async function boot({ scene, camera, renderer }) {
   const _tgtFrom = new THREE.Vector3(), _tgtTo = new THREE.Vector3();
   function startCameraReset() {
     const qpos = data.qpos;
-    const yaw = Math.atan2(
-      2 * (qpos[3] * qpos[6] + qpos[4] * qpos[5]),
-      1 - 2 * (qpos[5] * qpos[5] + qpos[6] * qpos[6]),
-    );
+    const yaw = duckYaw(qpos);
     chaseHeldYaw = yaw;
     chaseYawSmooth = yaw;
     chaseYawFollow = yaw;
@@ -1437,11 +1457,22 @@ async function boot({ scene, camera, renderer }) {
     if (now - grabHoverAt < 80) return;
     grabHoverAt = now;
     grabRayFrom(e);
-    renderer.domElement.style.cursor = grabPick() ? "grab" : "";
+    const clickable = mode === "walk" && !headMode;
+    renderer.domElement.style.cursor = grabPick() ? "grab" : (clickable ? "crosshair" : "");
   });
   window.addEventListener("pointerup", endGrab);
   window.addEventListener("pointercancel", endGrab);
 
+  // Waypoint marker: pulsing ring at the clicked floor point, hidden while
+  // idle. Positioned each frame in frame() from waypointSource.target.
+  const waypointMarker = new THREE.Mesh(
+    new THREE.RingGeometry(0.05, 0.065, 32),
+    new THREE.MeshBasicMaterial({ color: 0xff7a2f, transparent: true, opacity: 0.85, side: THREE.DoubleSide }),
+  );
+  waypointMarker.rotation.x = -Math.PI / 2; // flat on the floor, three y-up
+  waypointMarker.visible = false;
+  scene.add(waypointMarker);
+
   // Pause: while the menu is up over a live game, keys belong to the menu.
   const setInputLock = (v) => { inputLocked = v; controller.setLocked(v); };
   useGame.subscribe(
@@ -1760,6 +1791,12 @@ async function boot({ scene, camera, renderer }) {
     updateChaseCam();
     ceremony.drive();
     ball.drive(() => spawnBall({ fromQueue: true }));
+    const wpTarget = waypointSource.target;
+    waypointMarker.visible = !!wpTarget;
+    if (wpTarget) {
+      waypointMarker.position.set(wpTarget[0], 0.012, -wpTarget[1]); // MJCF -> three
+      waypointMarker.scale.setScalar(1 + 0.15 * Math.sin(performance.now() * 0.006));
+    }
     renderTelemetry();
   }
 
@@ -1772,6 +1809,7 @@ async function boot({ scene, camera, renderer }) {
   const srcTag = (source) => (source === "gamepad" ? "pad" : "kb");
 
   controller.on("reset", () => resetSim());
+  controller.on("reset", () => waypointSource.cancel());
   controller.on("spawnBall", () => spawnBall());
   controller.on("headToggle", () => toggleHeadMode());
   controller.on("chaseToggle", () => { chaseCam = !chaseCam; });