feat: kickable ball (B / pad Y) and detachable chase camera (C)

Ball: a light free sphere injected into the MJCF after the robot body
(keyframe qpos grown 21 -> 28, ball parked 50 m away by default). B or
gamepad Y pops/respawns it ~0.35 m in front of the duck with a small
jitter; a watchdog teleports it back when it rolls past the grid fade
(3 m); R re-parks it. Rendered as a procedural beach ball, local-only
(not shared with multiplayer ghosts).

Camera: chase mode on by default eases the camera behind the duck's
heading at the current orbit distance (wheel zoom preserved); dragging
detaches back to free orbit-follow, C toggles chase back on. HUD keycaps,
welcome modal and README updated; cache-buster bumped to 26.

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
tfrere
2026-08-20 14:29:07 +02:00
parent ef74255166
commit bbe381e114
3 changed files with 193 additions and 6 deletions
+6
View File
@@ -33,10 +33,15 @@ and [apirrone/mjlab_microduck](https://github.com/apirrone/mjlab_microduck).
- A / E: strafe
- Space: roll (one barrel roll, then back to running)
- F: kick, alternating feet
- B: pop / respawn a kickable ball in front of the duck
- C: toggle the chase camera (on by default; dragging detaches it)
- R: reset
- Drag to orbit, scroll to zoom
- Colour dots: repaint the duck (it quacks)
The ball is local-only: it lives in your tab's physics and is not shared
with the multiplayer ghosts.
### Gamepad
Plug in a controller and the same mapping as the real robot runtime applies:
@@ -44,6 +49,7 @@ Plug in a controller and the same mapping as the real robot runtime applies:
- Left stick: forward / back + strafe
- Right stick: turn
- X: roll
- Y: pop / respawn the ball
- RB / LB: right / left kick
- D-pad down: sit / stand toggle
- Right trigger: mouth (analog) + quack
+6 -1
View File
@@ -393,10 +393,13 @@
<span class="hint"><span class="key" id="key-left">A</span><span class="key" id="key-right">E</span> strafe</span><br />
<span class="hint"><span class="key" id="key-roll">Space</span> roll</span> &nbsp;
<span class="hint"><span class="key" id="key-kick">F</span> kick</span> &nbsp;
<span class="hint"><span class="key" id="key-ball">B</span> ball</span> &nbsp;
<span class="hint"><span class="key" id="key-cam">C</span> camera</span> &nbsp;
<span class="hint"><span class="key" id="key-reset">R</span> reset</span> &nbsp;
drag to orbit &middot; scroll to zoom<br />
<span id="pad-hint">gamepad:
<span class="hint"><span class="key" id="key-pad-x">X</span> roll</span> &nbsp;
<span class="hint"><span class="key" id="key-pad-y">Y</span> ball</span> &nbsp;
<span class="hint"><span class="key" id="key-pad-rb">RB</span><span class="key" id="key-pad-lb">LB</span> kick</span> &nbsp;
<span class="hint"><span class="key" id="key-pad-sit">&dArr;</span> sit</span> &nbsp;
<span class="hint"><span class="key" id="key-pad-run">&uArr;</span> run</span> &nbsp;
@@ -422,6 +425,8 @@
<li><b>Move</b><span>Arrows or ZQSD to run and turn, A / E to strafe, drag to orbit.</span></li>
<li><b>Roll</b><span>Space triggers a barrel roll, then it gets back up.</span></li>
<li><b>Kick</b><span>F throws a kick, alternating feet (RB / LB on the pad).</span></li>
<li><b>Ball</b><span>B pops a ball to kick around (Y on the pad).</span></li>
<li><b>Camera</b><span>Follows from behind; drag to break free, C re-attaches.</span></li>
<li><b>Gamepad</b><span>Plug one in - same mapping as the real robot.</span></li>
<li><b>Ghosts</b><span>Other visitors right now appear as translucent ducks, live.</span></li>
</ul>
@@ -471,7 +476,7 @@
appended: a plain src attribute can 401 when the browser blocks the
*.static.hf.space auth cookie inside the hub iframe. -->
<script type="module">
const V = "25"; // bump on rl.js changes to defeat heuristic caching
const V = "26"; // bump on rl.js changes to defeat heuristic caching
const sign = new URLSearchParams(location.search).get("__sign");
const suffix = sign ? `&__sign=${encodeURIComponent(sign)}` : "";
import(`./rl.js?v=${V}${suffix}`);
+181 -5
View File
@@ -79,6 +79,13 @@ const CTRL_DT = TIMESTEP * DECIMATION; // 50 Hz
// Velocity command limits, same as infer_policy.py's keyboard mapping.
const VEL_FWD = 0.25, VEL_BACK = -0.2, VEL_LAT = 0.2, VEL_ANG = 1.0;
// Kickable ball: radius, parking spot (far away = hidden by default) and
// the distance past which the respawn watchdog brings it back (the grid
// fades out at 3 m, so a ball beyond that is invisible anyway).
const BALL_RADIUS = 0.05;
const BALL_PARK_POS = "50 0 0.05";
const BALL_MAX_DIST = 3.0;
const mount = document.getElementById("scene");
const loadingEl = document.getElementById("loading");
const hudEl = document.getElementById("hud");
@@ -137,11 +144,32 @@ async function buildPhysicsXml() {
doc.querySelector("worldbody").appendChild(
el("geom", { name: "floor", type: "plane", size: "0 0 0.05", pos: "0 0 0" }),
);
// STAND keyframe from mjlab's scene_walk.xml (STAND2 pose).
// Kickable ball: a light free sphere (beach-ball feel). MuJoCo has no
// restitution parameter - the bounce comes from solref damping < 1, and
// the rolling-friction term makes it come to rest. Default contype /
// conaffinity (1) collide with the floor and the duck's collision-class
// geoms; the self_collision_only class (contype=2) correctly ignores it.
// Appended AFTER the robot body so the trunk freejoint stays first in
// qpos: qpos[0..6] indexing is hardcoded in syncRig, the fall watchdog
// and the ghosts' getLocalState.
const ballBody = el("body", { name: "ball", pos: BALL_PARK_POS });
ballBody.appendChild(el("freejoint", { name: "ball_freejoint" }));
ballBody.appendChild(el("geom", {
name: "ball_geom", type: "sphere", size: String(BALL_RADIUS),
mass: "0.03", friction: "0.4 0.01 0.003", solref: "0.03 0.4",
}));
doc.querySelector("worldbody").appendChild(ballBody);
// STAND keyframe from mjlab's scene_walk.xml (STAND2 pose). The ball's
// 7 free-joint values MUST be appended or nq (21 + 7 = 28) won't match
// and the model won't compile; parked 50 m away = effectively absent.
const qposFree = "0 0 0.12 1 0 0 0";
const pose14 = Array.from(DEFAULT_POSE).join(" ");
const kf = doc.createElement("keyframe");
kf.appendChild(el("key", { name: "STAND", qpos: `${qposFree} ${pose14}`, ctrl: pose14 }));
kf.appendChild(el("key", {
name: "STAND",
qpos: `${qposFree} ${pose14} ${BALL_PARK_POS} 1 0 0 0`,
ctrl: pose14,
}));
root.appendChild(kf);
const meshFiles = [...doc.querySelectorAll("asset > mesh")].map((m) => m.getAttribute("file"));
return { xml: new XMLSerializer().serializeToString(doc), meshFiles };
@@ -194,6 +222,8 @@ const dofAdr = JOINT_NAMES.map((n) => model.jnt(n).dofadr);
const gyroAdr = model.sensor("imu_ang_vel").adr;
const trunkId = mujoco.mj_name2id(model, mujoco.mjtObj.mjOBJ_BODY.value, "trunk_base");
const standKeyId = mujoco.mj_name2id(model, mujoco.mjtObj.mjOBJ_KEY.value, "STAND");
const ballQposAdr = model.jnt("ball_freejoint").qposadr;
const ballDofAdr = model.jnt("ball_freejoint").dofadr;
let uiReady = false;
const lastAction = new Float32Array(NUM_JOINTS);
@@ -204,7 +234,7 @@ const velCmd = new Float32Array(3); // twist command, driven by held keys
// the control loop reads it before the input section below has evaluated.
const padCmd = new Float32Array(3);
let padActive = false;
const padPrev = { x: false, rb: false, lb: false, dpadDown: false, dpadUp: false, rtArmed: true };
const padPrev = { x: false, y: false, rb: false, lb: false, dpadDown: false, dpadUp: false, rtArmed: true };
// Declared before the control loop starts: buildObs reads it via
// effectiveCmd on the very first control step.
const held = new Set();
@@ -212,6 +242,9 @@ const held = new Set();
let mode = "walk"; // "walk" | "sitstand" | "roll" | "kickL" | "kickR"
let sitFlag = 0;
const isKick = () => mode === "kickL" || mode === "kickR";
// Local-only kickable ball: false while parked at the keyframe spot
// (mesh hidden), true once popped in front of the duck.
let ballActive = false;
// The twist the policy actually receives: live gamepad sticks win over the
// held keys. No input means zero command - the duck stands in place.
@@ -257,11 +290,40 @@ function resetSim() {
mujoco.mj_forward(model, data);
lastAction.fill(0);
sitFlag = 0;
// The keyframe re-parks the ball 50 m away; reflect that in the flag
// so the render loop hides the mesh again.
ballActive = false;
// Buttons reflect sitFlag; keep them honest after auto-resets.
if (uiReady) syncButtons();
}
resetSim();
// Pop / respawn the ball ~0.35 m in front of the duck, with a small
// random heading + distance jitter so repeated pops land somewhere
// nearby instead of always on the same spot. qvel is zeroed so a respawn
// doesn't carry the old momentum.
function spawnBall() {
const qpos = data.qpos, qvel = data.qvel;
// Trunk yaw from the free-joint quaternion (qpos[3..6] = w x y z);
// the duck walks toward its local +X.
const yaw = Math.atan2(
2 * (qpos[3] * qpos[6] + qpos[4] * qpos[5]),
1 - 2 * (qpos[5] * qpos[5] + qpos[6] * qpos[6]),
);
const heading = yaw + (Math.random() - 0.5) * 0.7;
const dist = 0.35 + (Math.random() - 0.5) * 0.1;
qpos[ballQposAdr] = qpos[0] + Math.cos(heading) * dist;
qpos[ballQposAdr + 1] = qpos[1] + Math.sin(heading) * dist;
qpos[ballQposAdr + 2] = BALL_RADIUS + 0.02;
qpos[ballQposAdr + 3] = 1;
qpos[ballQposAdr + 4] = 0;
qpos[ballQposAdr + 5] = 0;
qpos[ballQposAdr + 6] = 0;
for (let i = 0; i < 6; i++) qvel[ballDofAdr + i] = 0;
mujoco.mj_forward(model, data);
ballActive = true;
}
// ── Observation ─────────────────────────────────────────────────────────
const _q = new THREE.Quaternion();
const _g = new THREE.Vector3();
@@ -324,6 +386,16 @@ async function controlStep() {
fallenSince = null;
}
// Ball respawn watchdog: a kicked ball that wandered past the grid's
// fade distance is invisible and unreachable - bring it back near
// the duck. Re-read qpos: resetSim above may have re-parked the ball.
if (ballActive) {
const q = data.qpos;
const dx = q[ballQposAdr] - q[0];
const dy = q[ballQposAdr + 1] - q[1];
if (dx * dx + dy * dy > BALL_MAX_DIST * BALL_MAX_DIST) spawnBall();
}
// One-shot roll, step-counted like the robot runtime (a single roll is
// ~1 s = 50 control steps there): hand back to walking once the trunk has
// tipped over and is upright again, or after a hard 2 s window if the roll
@@ -462,6 +534,36 @@ const rig = await rigPromise;
scene.add(rig.placer);
const trunkGroup = rig.bodies.get("trunk_base");
// Beach-ball look: alternating longitude panels drawn on a small canvas
// and wrapped around the sphere (equirectangular UVs), so the rolling
// actually reads visually. Colours match the dark scene + yellow accents.
function makeBeachBallTexture() {
const c = document.createElement("canvas");
c.width = 512;
c.height = 256;
const ctx = c.getContext("2d");
const panels = ["#ffd23f", "#efe9dc", "#22222c", "#efe9dc", "#ffd23f", "#efe9dc", "#22222c", "#efe9dc"];
const w = c.width / panels.length;
for (let i = 0; i < panels.length; i++) {
ctx.fillStyle = panels[i];
ctx.fillRect(Math.floor(i * w), 0, Math.ceil(w) + 1, c.height);
}
const tex = new THREE.CanvasTexture(c);
tex.colorSpace = THREE.SRGBColorSpace;
return tex;
}
// Same Z-up -> Y-up trick as the duck rig: the group takes the axis fix,
// the mesh inside takes the raw MJCF free-joint pose.
const ballGroup = new THREE.Group();
ballGroup.rotation.x = -Math.PI / 2;
const ballMesh = new THREE.Mesh(
new THREE.SphereGeometry(BALL_RADIUS, 32, 24),
new THREE.MeshStandardMaterial({ map: makeBeachBallTexture(), roughness: 0.35, metalness: 0 }),
);
ballMesh.visible = false;
ballGroup.add(ballMesh);
scene.add(ballGroup);
const controls = new OrbitControls(camera, renderer.domElement);
controls.enableDamping = true;
controls.dampingFactor = 0.08;
@@ -469,6 +571,50 @@ controls.minDistance = 0.25;
controls.maxDistance = 3;
controls.maxPolarAngle = Math.PI / 2 - 0.03;
// Chase cam (default ON): each frame the camera eases toward a point
// behind the duck's heading at the current orbit distance, while the
// orbit target keeps easing to the trunk in syncRig. Implemented by
// overwriting camera.position AFTER controls.update() so we never fight
// OrbitControls' own spherical bookkeeping; the wheel still zooms in
// chase mode because the behind-point distance is re-read from the live
// camera-target distance every frame.
// Detach: any pointer grab on the canvas (drag start) drops back to the
// free orbit-follow. We listen on pointerdown rather than the controls'
// "start" event because in this three.js version the wheel dispatches
// "start" too, and scroll-to-zoom must not detach the chase.
let chaseCam = true;
const CHASE_PITCH = 0.42; // rad above horizontal, keeps the floor in view
const CHASE_EASE = 0.05; // exponential ease, cinematic on turns
const _chasePos = new THREE.Vector3();
const _chaseDir = new THREE.Vector3();
function updateChaseCam() {
if (!chaseCam) return;
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 dist = camera.position.distanceTo(controls.target);
const horiz = dist * Math.cos(CHASE_PITCH);
const vert = dist * Math.sin(CHASE_PITCH);
// Duck forward in MJCF is (cos yaw, sin yaw, 0); Z-up -> Y-up maps it
// to three-space (cos yaw, 0, -sin yaw). Behind = minus that.
_chasePos.set(
controls.target.x - Math.cos(yaw) * horiz,
controls.target.y + vert,
controls.target.z + Math.sin(yaw) * horiz,
);
camera.position.lerp(_chasePos, CHASE_EASE);
// Re-project onto the orbit sphere: lerping between two points at the
// same radius cuts the chord, which would slowly zoom the camera in
// during large swings (e.g. re-attaching after the duck turned around).
_chaseDir.copy(camera.position).sub(controls.target);
const len = _chaseDir.length();
if (len > 1e-6) camera.position.copy(controls.target).addScaledVector(_chaseDir, dist / len);
camera.lookAt(controls.target);
}
renderer.domElement.addEventListener("pointerdown", () => { chaseCam = false; });
function resize() {
const w = mount.clientWidth, h = mount.clientHeight;
camera.aspect = w / h;
@@ -487,6 +633,14 @@ function syncRig() {
trunkGroup.position.set(qpos[0], qpos[1], qpos[2]);
trunkGroup.quaternion.set(qpos[4], qpos[5], qpos[6], qpos[3]);
for (let j = 0; j < NUM_JOINTS; j++) setJoint(rig, JOINT_NAMES[j], qpos[qposAdr[j]]);
// Ball: raw MJCF pose inside the Z-up group, hidden while parked.
ballMesh.visible = ballActive;
if (ballActive) {
ballMesh.position.set(qpos[ballQposAdr], qpos[ballQposAdr + 1], qpos[ballQposAdr + 2]);
ballMesh.quaternion.set(
qpos[ballQposAdr + 4], qpos[ballQposAdr + 5], qpos[ballQposAdr + 6], qpos[ballQposAdr + 3],
);
}
// Follow cam: ease the orbit target toward the trunk and translate the
// camera by the same delta, so the camera-to-duck distance and viewing
// angle stay constant while the duck walks. Mouse orbit/zoom still work:
@@ -556,12 +710,16 @@ const keyEls = {
turnl: el("key-turnl"), turnr: el("key-turnr"),
left: el("key-left"), right: el("key-right"),
roll: el("key-roll"), reset: el("key-reset"), kick: el("key-kick"),
ball: el("key-ball"), cam: el("key-cam"),
padX: el("key-pad-x"), padSit: el("key-pad-sit"),
padRun: el("key-pad-run"), padRt: el("key-pad-rt"),
padRb: el("key-pad-rb"), padLb: el("key-pad-lb"),
padY: el("key-pad-y"),
};
const STICK_R = 15; // px, max dot travel inside the 46px stick circle
let resetFlashAt = -Infinity;
let ballFlashAt = -Infinity;
let padYFlashAt = -Infinity;
function renderStats() {
const [vx, vy, wz] = effectiveCmd();
@@ -590,7 +748,10 @@ function renderStats() {
keyEls.roll.classList.toggle("lit", mode === "roll" && rollSource === "kb");
keyEls.kick.classList.toggle("lit", isKick() && kickSource === "kb");
keyEls.reset.classList.toggle("lit", performance.now() - resetFlashAt < 400);
keyEls.ball.classList.toggle("lit", performance.now() - ballFlashAt < 400);
keyEls.cam.classList.toggle("lit", chaseCam); // steady while chasing
keyEls.padX.classList.toggle("lit", mode === "roll" && rollSource === "pad");
keyEls.padY.classList.toggle("lit", performance.now() - padYFlashAt < 400);
keyEls.padRb.classList.toggle("lit", mode === "kickR" && kickSource === "pad");
keyEls.padLb.classList.toggle("lit", mode === "kickL" && kickSource === "pad");
keyEls.padSit.classList.toggle("lit", sitting);
@@ -611,6 +772,7 @@ function loop() {
syncJaw();
ghosts?.update();
controls.update();
updateChaseCam();
renderStats();
renderer.render(scene, camera);
}
@@ -640,6 +802,8 @@ let kickNextLeft = false;
window.addEventListener("keydown", (e) => {
if (e.repeat) return;
if (e.code === "KeyR") { resetSim(); resetFlashAt = performance.now(); return; }
if (e.code === "KeyB") { spawnBall(); ballFlashAt = performance.now(); return; }
if (e.code === "KeyC") { chaseCam = !chaseCam; return; }
if (e.code === "Space") { e.preventDefault(); triggerRoll(); return; }
if (e.code === "KeyF") {
e.preventDefault();
@@ -692,11 +856,16 @@ pollPad = function pollGamepad() {
padCmd.fill(0);
}
// Standard mapping indices: X=2, LB=4, RB=5, DpadDown=13, RT=7 (analog).
// Standard mapping indices: X=2, Y=3, LB=4, RB=5, DpadDown=13, RT=7 (analog).
const x = !!gp.buttons[2]?.pressed;
if (x && !padPrev.x) triggerRoll("pad");
padPrev.x = x;
// Y: pop / respawn the ball, same rising-edge pattern as X.
const y = !!gp.buttons[3]?.pressed;
if (y && !padPrev.y) { spawnBall(); padYFlashAt = performance.now(); }
padPrev.y = y;
// RB / LB: right / left kick, same buttons as the robot runtime.
const rb = !!gp.buttons[5]?.pressed;
if (rb && !padPrev.rb) triggerKick("right", "pad");
@@ -857,13 +1026,20 @@ uiReady = true;
// Deterministic hooks for automated verification (rAF pauses in
// background tabs, and the control loop is async).
window.rl = {
model, data, mujoco,
model, data, mujoco, camera, controls,
get mode() { return mode; },
get sitFlag() { return sitFlag; },
buildObs, cmd,
velCmd, lastAction, resetSim,
spawnBall,
get ballActive() { return ballActive; },
get ballQposAdr() { return ballQposAdr; },
get chaseCam() { return chaseCam; },
set chaseCam(v) { chaseCam = !!v; },
step: async (n = 1) => { for (let i = 0; i < n; i++) await controlStep(); },
render: () => { syncRig(); renderer.render(scene, camera); },
// One full render-loop iteration, for tests driving frames manually.
frame: () => { syncRig(); syncJaw(); controls.update(); updateChaseCam(); renderStats(); renderer.render(scene, camera); },
get ghosts() { return ghosts; },
};