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=<ref> 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 <cursoragent@cursor.com>
This commit is contained in:
tfrere
2026-09-07 10:49:16 +02:00
parent 57b9fad1ca
commit cb0312619f
5 changed files with 422 additions and 14 deletions
+10
View File
@@ -41,6 +41,16 @@ export default function App() {
window.addEventListener("touchstart", armTouch, { once: true, passive: true });
if (params.get("touch") === "1") armTouch();
// ?policy=<org/repo or .onnx URL>: 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.
+174
View File
@@ -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],
};
}
+122 -6
View File
@@ -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=<ref> (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.
+5
View File
@@ -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,
+111 -8
View File
@@ -403,6 +403,7 @@ function Quickbar() {
})}
</Box>
</HudPlate>
<PolicyChip />
{/* Sound is fully disabled for now (SOUND_DISABLED in audio.js) -
the mute toggle comes back with the finished sound design. */}
{/* <SoundToggle /> */}
@@ -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 (
<HudPlate caption="Policy" captionFill="orange">
<Box sx={{ display: "inline-flex", alignItems: "stretch", height: "100%" }}>
<Box
sx={{
...hudHitSx,
px: "0.85rem",
cursor: "default",
color: ORANGE,
maxWidth: "14rem",
overflow: "hidden",
textOverflow: "ellipsis",
display: "inline-block",
lineHeight: `${CELL_H}px`,
}}
title={cp.ref}
>
{cp.name}
</Box>
<Box
component="button"
type="button"
aria-label={`Unload policy ${cp.name}`}
onClick={() => { 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"}
</Box>
</Box>
</HudPlate>
);
}
// 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 (
<Box
sx={{
@@ -493,15 +546,64 @@ function OsdLoad() {
letterSpacing: "0.14em",
color: ORANGE,
textShadow: "0 0 8px rgba(255, 122, 47, 0.4)",
textAlign: "right",
lineHeight: 1.9,
}}
>
LOADING ROLLERS
<Box
component="span"
sx={{ display: "inline-block", ml: "0.15em", animation: `${recBlink} 0.8s steps(1) infinite` }}
>
{"\u2588"}
</Box>
{lines.map((l) => (
<Box key={l}>
{l}
<Box
component="span"
sx={{ display: "inline-block", ml: "0.15em", animation: `${recBlink} 0.8s steps(1) infinite` }}
>
{"\u2588"}
</Box>
</Box>
))}
</Box>
);
}
// 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 (
<Box
role="alert"
sx={{
position: "fixed",
top: "7.4rem",
right: "1.5rem",
zIndex: 10,
maxWidth: "24rem",
fontFamily: MONO,
fontSize: "0.66rem",
letterSpacing: "0.1em",
textTransform: "uppercase",
textAlign: "right",
lineHeight: 1.7,
color: "#ff4b3a",
textShadow: "0 0 8px rgba(255, 75, 58, 0.45)",
}}
>
{msg}
</Box>
);
}
@@ -520,6 +622,7 @@ export default function Hud() {
<Quickbar />
<Telemetry />
<OsdLoad />
<PolicyToast />
</>
)}
</>