From cb0312619f09138069130328c3bef05736e1730c Mon Sep 17 00:00:00 2001 From: tfrere Date: Mon, 7 Sep 2026 10:49:16 +0200 Subject: [PATCH] feat: load community policies from the hub Resolve an org/repo Hub id (or a direct .onnx URL) into a validated onnxruntime session and swap it into the walk slot only, keeping recovery/sitstand/kicks/roulade on the official set: - custom-policy.js: manifest schema-2 checks (reject only present-and-wrong claims, walk-slot compatible kinds only), publish smoke run mirror (1 input / 1 output, zeros + 2 noisy inferences, [1,14] finite non-constant output), honors manifest action_scale - game.js: name-agnostic inference (session inputNames/outputNames instead of hardcoded obs/actions), per-session action scale, Number.isFinite guard before writing ctrl, watchdog that auto-reverts to the official walker on 3 abnormal endings (recovery entries + solver explosions) in a rolling 20 s window or any non-finite action - ?policy= URL param (parsed in App.jsx, loaded after boot, never blocking it; failures surface in the HUD on the official walker) - HUD: active-policy chip with unload X, LOADING POLICY OSD line, toast-style OSD message on load errors and watchdog reverts Co-authored-by: Cursor --- app/src/App.jsx | 10 ++ app/src/game/custom-policy.js | 174 ++++++++++++++++++++++++++++++++++ app/src/game/game.js | 128 +++++++++++++++++++++++-- app/src/store.js | 5 + app/src/ui/Hud.jsx | 119 +++++++++++++++++++++-- 5 files changed, 422 insertions(+), 14 deletions(-) create mode 100644 app/src/game/custom-policy.js diff --git a/app/src/App.jsx b/app/src/App.jsx index fb42460..d71382c 100644 --- a/app/src/App.jsx +++ b/app/src/App.jsx @@ -41,6 +41,16 @@ export default function App() { window.addEventListener("touchstart", armTouch, { once: true, passive: true }); if (params.get("touch") === "1") armTouch(); + // ?policy=: request a community walk policy. + // Only the request is recorded here; the game loads it after boot + // (never blocking it) and flips the status to active/error itself. + const policyRef = params.get("policy"); + if (policyRef) { + useGame.setState({ + customPolicy: { ref: policyRef, name: policyRef, status: "loading" }, + }); + } + // The title menu opens right away and holds its own loading gate // (central spinner) until logo, fonts, duck stage and game boot are // in. ?boot=1 skips the title entirely - testing hook. diff --git a/app/src/game/custom-policy.js b/app/src/game/custom-policy.js new file mode 100644 index 0000000..4092063 --- /dev/null +++ b/app/src/game/custom-policy.js @@ -0,0 +1,174 @@ +// Community policy loading: resolve a Hub repo id (or a direct .onnx URL) +// into a validated onnxruntime session the game can drop into its walk +// slot. Mirrors the official publish pipeline's smoke run: shape checks, +// a zeros inference and two noisy inferences that must produce finite, +// non-constant actions before the session ever touches the duck. +// +// The module is deliberately framework-free (no game imports): the caller +// hands in the `ort` namespace it already booted, and pure helpers like +// manifestIncompatibility are reusable by standalone pages without pulling +// the game bundle in. + +import { OBS_SIZE, NUM_JOINTS } from "./constants.js"; + +const HUB_BASE = "https://huggingface.co"; + +// Manifest claims the sim cannot satisfy (schema 2). Only present-and-wrong +// claims reject: an absent field is trusted to match the microduck defaults. +// Returns a human-readable reason, or null when the manifest is acceptable. +export function manifestIncompatibility(manifest) { + if (!manifest || typeof manifest !== "object") return null; + if (Array.isArray(manifest.policies)) { + return "multi-policy set: not loadable in v1 (pick a single-policy repo)"; + } + if (manifest.model_api != null && manifest.model_api > 2) { + return `model_api ${manifest.model_api} is newer than this sim supports`; + } + if (manifest.obs_len != null && manifest.obs_len !== OBS_SIZE) { + return `expects ${manifest.obs_len} observations (sim provides ${OBS_SIZE})`; + } + if (manifest.action_len != null && manifest.action_len !== NUM_JOINTS) { + return `outputs ${manifest.action_len} actions (sim drives ${NUM_JOINTS})`; + } + const robotModel = manifest.robot?.model; + if (robotModel != null && robotModel !== "microduck") { + return `targets robot "${robotModel}", not microduck`; + } + // v1 only swaps the walk slot: perpetual, constant-command policies. + if (manifest.kind != null && manifest.kind !== "perpetual") { + return `"${manifest.kind}" policies are not supported yet (walk-slot only)`; + } + if (manifest.slot != null && manifest.slot !== "walk") { + return `slot "${manifest.slot}" is not supported yet (walk-slot only)`; + } + const encoding = manifest.command?.encoding; + if (encoding != null && encoding !== "constant") { + return `command encoding "${encoding}" is not supported yet`; + } + if (manifest.mode != null && manifest.mode !== "walk") { + return `mode "${manifest.mode}" is not supported yet (walk-slot only)`; + } + return null; +} + +// A policy ref is either an org/repo Hub id or a direct URL to a .onnx. +export function resolvePolicyRef(ref) { + const r = String(ref || "").trim(); + if (/^https?:\/\//i.test(r)) { + return { kind: "url", name: r.split("/").pop() || r, onnxUrl: r, manifestUrl: null }; + } + if (!/^[\w.-]+\/[\w.-]+$/.test(r)) { + throw new Error(`invalid policy ref "${r}" (expected org/repo or a .onnx URL)`); + } + return { + kind: "hub", + name: r, + repoId: r, + onnxUrl: `${HUB_BASE}/${r}/resolve/main/policy.onnx`, + manifestUrl: `${HUB_BASE}/${r}/resolve/main/manifest.json`, + }; +} + +// Manifest fetch for the loader (and any future policy-browsing page): +// 404 (no manifest) resolves to null, network/parse failures throw. +export async function fetchPolicyManifest(repoId) { + const res = await fetch(`${HUB_BASE}/${repoId}/resolve/main/manifest.json`); + if (res.status === 404) return null; + // The Hub answers 401 for repos that don't exist (or are private). + if (res.status === 401 || res.status === 403) { + throw new Error(`repo "${repoId}" not found on the Hub (or private)`); + } + if (!res.ok) throw new Error(`manifest fetch failed (HTTP ${res.status})`); + return res.json(); +} + +// Publish-pipeline smoke run: 1 input / 1 output, a zeros pass plus two +// small-noise passes; every output must be [1,14], finite, and the noisy +// passes must not produce identical actions (a constant net is a dud). +async function validateSession(ort, session) { + const { inputNames, outputNames } = session; + if (inputNames.length !== 1 || outputNames.length !== 1) { + throw new Error( + `expected 1 input / 1 output, got ${inputNames.length}/${outputNames.length}`, + ); + } + const runOnce = async (fill) => { + const buf = new Float32Array(OBS_SIZE); + if (fill) for (let i = 0; i < OBS_SIZE; i++) buf[i] = (Math.random() - 0.5) * 0.1; + const feeds = { [inputNames[0]]: new ort.Tensor("float32", buf, [1, OBS_SIZE]) }; + const out = (await session.run(feeds))[outputNames[0]]; + const dims = out.dims; + if (dims.length !== 2 || dims[0] !== 1 || dims[1] !== NUM_JOINTS) { + throw new Error(`bad output shape [${dims.join(",")}] (expected [1,${NUM_JOINTS}])`); + } + const act = out.data; + for (let j = 0; j < NUM_JOINTS; j++) { + if (!Number.isFinite(act[j])) throw new Error("non-finite actions in smoke run"); + } + return Float32Array.from(act); + }; + await runOnce(false); + const a = await runOnce(true); + const b = await runOnce(true); + let maxDiff = 0; + for (let j = 0; j < NUM_JOINTS; j++) maxDiff = Math.max(maxDiff, Math.abs(a[j] - b[j])); + if (maxDiff < 1e-9) throw new Error("constant output in smoke run (dead policy)"); +} + +// Load + validate a community policy. Resolves to everything the game needs +// to swap its walk slot; throws with a clear message on any failure. +// onProgress receives coarse stages for the HUD loading line. +export async function loadCustomPolicy(ref, { ort, onProgress = () => {} } = {}) { + const resolved = resolvePolicyRef(ref); + let name = resolved.name; + let actionScale = 1.0; + + if (resolved.manifestUrl) { + onProgress("manifest"); + let manifest = null; + try { + manifest = await fetchPolicyManifest(resolved.repoId); + } catch (e) { + // TypeError = the fetch itself failed (offline, CORS); anything else + // already carries a specific message (missing repo, bad status). + throw e instanceof TypeError ? new Error(`could not reach the Hub: ${e.message}`) : e; + } + if (manifest) { + const reason = manifestIncompatibility(manifest); + if (reason) throw new Error(reason); + if (typeof manifest.name === "string" && manifest.name) name = manifest.name; + if (Number.isFinite(manifest.action_scale)) actionScale = manifest.action_scale; + } + } + + onProgress("download"); + const res = await fetch(resolved.onnxUrl); + if (!res.ok) { + throw new Error( + res.status === 404 + ? `no policy.onnx found at ${resolved.name}` + : `policy download failed (HTTP ${res.status})`, + ); + } + const bytes = new Uint8Array(await res.arrayBuffer()); + + onProgress("session"); + let session; + try { + session = await ort.InferenceSession.create(bytes, { executionProviders: ["wasm"] }); + } catch (e) { + throw new Error(`not a loadable ONNX model: ${e?.message || e}`); + } + + onProgress("validate"); + await validateSession(ort, session); + + return { + session, + name, + ref: String(ref), + actionScale, + inputName: session.inputNames[0], + outputName: session.outputNames[0], + }; +} diff --git a/app/src/game/game.js b/app/src/game/game.js index 707607f..e226055 100644 --- a/app/src/game/game.js +++ b/app/src/game/game.js @@ -57,6 +57,7 @@ import { playPropSweep, playLineBlip, setRumble, } from "./audio.js"; import { createBallActor } from "./ball-actor.js"; +import { loadCustomPolicy as loadCustomPolicyModule } from "./custom-policy.js"; import { initGhosts } from "./ghosts.js"; import { makeInfiniteGrid, makeArenaWalls } from "./arena.js"; import { createBallVisual } from "./ball-visual.js"; @@ -352,6 +353,74 @@ async function boot({ scene, camera, renderer }) { } donePolicies("7/7"); + // ── Community policy slot (walk only) ───────────────────────────────── + // A validated Hub policy can replace sessions.walk; every other slot + // (recovery, sitstand, kicks, roulade, rollers) stays official. The + // official walker is pinned here so a swap is always reversible. + const officialWalk = sessions.walk; + let customPolicy = null; // { session, name, ref, actionScale } + // Watchdog: abnormal-ending timestamps (recovery entries + solver + // explosions) while a custom policy drives the duck. 3 within a rolling + // 20 s window auto-reverts; ~10 s without a new event clears the slate + // so player-caused falls don't slowly accumulate into a revert. + const WATCHDOG_WINDOW_MS = 20000; + const WATCHDOG_LIMIT = 3; + const WATCHDOG_HEALTHY_MS = 10000; + let watchdogEvents = []; + + const actionScaleFor = (session) => + (customPolicy && session === customPolicy.session ? customPolicy.actionScale : ACTION_SCALE); + + function revertCustomPolicy(revertReason = null) { + if (!customPolicy) return; + const prev = customPolicy; + customPolicy = null; + watchdogEvents = []; + sessions.walk = officialWalk; + if (revertReason) { + console.warn(`[policy] reverted "${prev.name}": ${revertReason}`); + setStore({ + customPolicy: { ref: prev.ref, name: prev.name, status: "error", revertReason }, + }); + } else { + setStore({ customPolicy: null }); + } + } + + function watchdogAbnormalEnd(kind) { + if (!customPolicy) return; + const now = performance.now(); + watchdogEvents.push(now); + watchdogEvents = watchdogEvents.filter((t) => now - t < WATCHDOG_WINDOW_MS); + if (watchdogEvents.length >= WATCHDOG_LIMIT) { + revertCustomPolicy(`${watchdogEvents.length} ${kind === "exploded" ? "explosions/falls" : "falls"} in ${Math.round(WATCHDOG_WINDOW_MS / 1000)} s`); + } + } + + // One load at a time; a failure (or a bogus boot-time ?policy=) leaves + // the official walker untouched and surfaces the error in the store. + let policyLoadBusy = false; + async function loadCustomPolicyIntoGame(ref) { + if (policyLoadBusy) return; + policyLoadBusy = true; + setStore({ customPolicy: { ref: String(ref), name: String(ref), status: "loading" } }); + try { + const loaded = await loadCustomPolicyModule(ref, { ort }); + revertCustomPolicy(); // drop any previous custom walker first + customPolicy = loaded; + watchdogEvents = []; + sessions.walk = loaded.session; + setStore({ customPolicy: { ref: loaded.ref, name: loaded.name, status: "active" } }); + console.info(`[policy] custom walk policy active: ${loaded.name} (${loaded.ref})`); + } catch (e) { + const error = e?.message || String(e); + console.warn(`[policy] load failed for "${ref}":`, e); + setStore({ customPolicy: { ref: String(ref), name: String(ref), status: "error", error } }); + } finally { + policyLoadBusy = false; + } + } + const doneCompile = bootLine("COMPILING PHYSICS"); let model, data; try { @@ -865,12 +934,31 @@ async function boot({ scene, camera, renderer }) { // Settle phase: ctrl frozen on the pose held at the fall (approximates // the runtime's limp beat), physics keeps stepping, no inference. if (recovery?.state !== "fallen") { - const feeds = { obs: new ort.Tensor("float32", buildObs(), [1, OBS_SIZE]) }; - const out = await activeSession().run(feeds); - const act = out.actions.data; - lastAction.set(act); - const ctrl = data.ctrl; - for (let j = 0; j < NUM_JOINTS; j++) ctrl[j] = DEFAULT_POSE[j] + act[j] * ACTION_SCALE; + // Tensor names come from the session itself (community exports don't + // all use obs/actions), and the action scale is per-session (official + // policies stay at ACTION_SCALE = 1). + const session = activeSession(); + const feeds = { + [session.inputNames[0]]: new ort.Tensor("float32", buildObs(), [1, OBS_SIZE]), + }; + const out = await session.run(feeds); + const act = out[session.outputNames[0]].data; + let finite = true; + for (let j = 0; j < NUM_JOINTS; j++) { + if (!Number.isFinite(act[j])) { finite = false; break; } + } + if (!finite) { + // Never write a NaN/Inf into ctrl. A custom policy producing one is + // instantly reverted; ctrl holds the previous step's targets. + if (customPolicy && session === customPolicy.session) { + revertCustomPolicy("non-finite action tensor"); + } + } else { + const scale = actionScaleFor(session); + lastAction.set(act); + const ctrl = data.ctrl; + for (let j = 0; j < NUM_JOINTS; j++) ctrl[j] = DEFAULT_POSE[j] + act[j] * scale; + } } for (let s = 0; s < DECIMATION; s++) { applyGrabForce(); // mouse perturbation, fresh velocity every substep @@ -878,9 +966,20 @@ async function boot({ scene, camera, renderer }) { } stepAudioSim(); // footsteps / rumble / ball thumps off the fresh state + // Watchdog housekeeping: a healthy stretch (no abnormal ending for + // ~10 s) forgives earlier events, so player-caused falls spread over + // a session never accumulate into a revert. + if (customPolicy && watchdogEvents.length && + performance.now() - watchdogEvents[watchdogEvents.length - 1] > WATCHDOG_HEALTHY_MS) { + watchdogEvents = []; + } + const death = poseIsDead(); if (death === "exploded") { haptics.pulse("explode"); + // Solver explosions only implicate the custom policy while it is the + // one driving (legs walk); one-shots and rollers stay official. + if (loco === "legs" && mode === "walk") watchdogAbnormalEnd("exploded"); resetSim(); } else if (recovery) { // Recovery state machine owns the duck: settle -> stand policy -> @@ -912,6 +1011,9 @@ async function boot({ scene, camera, renderer }) { if (++fallDebounce >= FALL_DEBOUNCE_STEPS) { fallDebounce = 0; exitHeadMode(); + // Recovery entry = one abnormal ending for the custom-policy + // watchdog (the rolling window absorbs player-caused falls). + watchdogAbnormalEnd("fallen"); recovery = { state: "fallen", steps: 0 }; // Haptic thud on the confirmed fall (one-shot: this transition // fires once per fall, the recovery machine owns the duck after). @@ -1988,6 +2090,8 @@ async function boot({ scene, camera, renderer }) { resetSim, spawnBall: () => spawnBall(), startEntrance: () => ceremony.startEntrance(), + loadCustomPolicy: (ref) => loadCustomPolicyIntoGame(ref), + clearCustomPolicy: () => revertCustomPolicy(), }); // Deterministic hooks for automated verification (rAF pauses in @@ -2002,6 +2106,10 @@ async function boot({ scene, camera, renderer }) { velCmd: kbSource.command, lastAction, resetSim, controller, kbSource, padSource, spawnBall, triggerKick, triggerRoll, sessions, ort, + loadCustomPolicy: loadCustomPolicyIntoGame, + clearCustomPolicy: revertCustomPolicy, + get customPolicy() { return customPolicy; }, + get watchdogEvents() { return watchdogEvents.slice(); }, get loco() { return loco; }, get locoSwitching() { return locoSwitching; }, toggleLoco, setLoco, ensureRollers, @@ -2056,6 +2164,14 @@ async function boot({ scene, camera, renderer }) { // with READY. + fade on its own. setStore({ bootDone: true }); + // ?policy= (parsed in App.jsx into the store): load the community + // policy now that the sim is up. Fire-and-forget - a bad ref surfaces + // its error in the HUD while the official walker keeps the duck alive. + const requestedPolicy = store().customPolicy; + if (requestedPolicy?.status === "loading" && requestedPolicy.ref) { + loadCustomPolicyIntoGame(requestedPolicy.ref); + } + // ── Multiplayer ghosts (WebRTC, serverless signaling) ──────────────── // Broadcast this duck's pose and render up to 3 other visitors live as // translucent ducks. Fire-and-forget: any failure just means no ghosts. diff --git a/app/src/store.js b/app/src/store.js index 34452df..31763db 100644 --- a/app/src/store.js +++ b/app/src/store.js @@ -29,6 +29,11 @@ export const useGame = create( locoSwitching: false, rollersLoading: false, // OSD line while the roller stack streams in variant: "classic", + // Community walk policy: null = official walker. Written by the game + // (game.js loadCustomPolicyIntoGame / the watchdog) and by App.jsx for + // the boot-time ?policy= request. + // { ref, name, status: "loading"|"active"|"error", error?, revertReason? } + customPolicy: null, padConnected: false, touchMode: false, ballActive: false, diff --git a/app/src/ui/Hud.jsx b/app/src/ui/Hud.jsx index afc69bb..d6b8b79 100644 --- a/app/src/ui/Hud.jsx +++ b/app/src/ui/Hud.jsx @@ -403,6 +403,7 @@ function Quickbar() { })} + {/* Sound is fully disabled for now (SOUND_DISABLED in audio.js) - the mute toggle comes back with the finished sound design. */} {/* */} @@ -410,6 +411,54 @@ function Quickbar() { ); } +// Active community policy chip: rides the quickbar row in the same panel +// language. Shows the policy's name and an X that swaps the official +// walker back in (gameApi.clearCustomPolicy). +function PolicyChip() { + const cp = useGame((s) => s.customPolicy); + if (cp?.status !== "active") return null; + return ( + + + + {cp.name} + + { uiClick(); gameApi.clearCustomPolicy?.(); }} + sx={{ + ...hudHitSx, + px: "0.6rem", + color: "rgba(250, 248, 242, 0.72)", + "&:hover": { + color: ORANGE, + background: "rgba(255, 122, 47, 0.12)", + }, + "&:active": { filter: "brightness(0.92)" }, + }} + > + {"\u2715"} + + + + ); +} + // Mute / unmute panel: same cartouche language as the other groups. The // toggle ramps audio.js's master gain (~50 ms) and persists; unmuting // plays the HUD click as confirmation (muting stays silent, obviously). @@ -480,7 +529,11 @@ function Telemetry() { function OsdLoad() { const rollersLoading = useGame((s) => s.rollersLoading); - if (!rollersLoading) return null; + const policyLoading = useGame((s) => s.customPolicy?.status === "loading"); + const lines = []; + if (rollersLoading) lines.push("LOADING ROLLERS"); + if (policyLoading) lines.push("LOADING POLICY"); + if (!lines.length) return null; return ( - LOADING ROLLERS - - {"\u2588"} - + {lines.map((l) => ( + + {l} + + {"\u2588"} + + + ))} + + ); +} + +// Toast-style OSD line for policy failures: a load error or a watchdog +// revert paints below the loading line for a few seconds, then clears the +// store slot (the official walker is already back by then). +function PolicyToast() { + const cp = useGame((s) => s.customPolicy); + const isError = cp?.status === "error"; + useEffect(() => { + if (!isError) return; + const t = setTimeout(() => { + if (useGame.getState().customPolicy === cp) { + useGame.setState({ customPolicy: null }); + } + }, 9000); + return () => clearTimeout(t); + }, [cp, isError]); + if (!isError) return null; + const msg = cp.revertReason + ? `POLICY REVERTED \u00b7 ${cp.revertReason}` + : `POLICY LOAD FAILED \u00b7 ${cp.error ?? "unknown error"}`; + return ( + + {msg} ); } @@ -520,6 +622,7 @@ export default function Hud() { + )}