Files
VibemakerSandbox/README.md
T
chenlin fc5ee4f2c6 feat: release v0.2 multi-robot simulator
Add declarative robot packages, shared simulation lifecycle and Microban ONNX/PD walking with independent head control.

Unify comic UI and chase camera; default robot packages to a 4.5m arena with real collision walls. Include regression tests, asset provenance/licenses and verification evidence.
2026-10-28 14:00:26 +08:00

116 lines
9.2 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
---
title: Microduck Sandbox
emoji: 🐤
colorFrom: yellow
colorTo: gray
sdk: docker
app_port: 8080
pinned: false
license: apache-2.0
---
# Browser robot simulation platform
MuJoCo WASM + onnxruntime-web + three.js, with **Microduck** (legs / rollers) and **Microban** Robot Packages. Physics and ONNX inference run locally in the browser; no simulation backend is required.
The application opens directly into simulation, defaults to Microduck, and keeps pause, reset, robot selection and a collapsible keyboard reference on that same screen. There is no welcome / RESUME menu or BIOS animation. Anton is bundled locally, so the default interface does not wait for an external font service.
## Robots
| Robot | Default scene / presentation | Controls |
|---|---|---|
| Microduck | Shared 4.5 × 4.5 m bounded arena, ball, original GLB/palette/comic effects | Existing walking, skating, skills and recovery |
| Microban | Shared 4.5 × 4.5 m bounded arena, dark/orange grid and comic UI, MJCF robot visuals | Walking policy + independent head rotation |
Switch robots using **Robot** in the toolbar. Returning to Microduck restores the session's colour and feet / rollers choice, but initializes a fresh physical state. Failed loads keep the previous robot available and show an inline retry action.
Microduck policies / assets originate from [pollen-robotics/microduck](https://github.com/pollen-robotics/microduck) and [pollen-robotics/microduck_rl](https://github.com/pollen-robotics/microduck_rl). Microban assets originate from [Rhoban/microban](https://github.com/Rhoban/microban); exact source hashes, dirty-worktree provenance and license notices are included in its Package.
## Keyboard and mouse
| Action | Binding |
|---|---|
| Forward / backward / turn | Arrow keys or physical WASD positions (layout labels adapt when supported) |
| Pause / continue | Esc or toolbar |
| Reset current robot | Space or toolbar |
| Orbit / zoom | Mouse drag / wheel |
| Microduck left / right kick | Q / E |
| Microduck alternate kick | F |
| Microduck sit / stand; roller crouch | R |
| Microduck ground pick | G |
| Microduck forward roll; roller crouch | T |
| Microduck feet / rollers | M or quickbar |
| Restore rear chase camera (both robots) | C |
| Microban independent head rotation | H |
The on-screen reference comes from the same Package bindings as the keyboard, and its skill entries are also clickable buttons. Text fields / selectors retain their normal keyboard behavior. Focused buttons retain native Space / Enter behavior without also resetting the robot. Losing focus, pausing, resetting or switching clears held movement keys.
All bundled robots, and future Packages omitting `presentation.world`, use the shared **4.5 × 4.5 m** arena (length and width increased 50% from 3 m). Its four real collision walls are 0.25 m high and 0.05 m thick, with Microduck's dark glowing grid. Microban's interior stays flat; no relief or automatic coordinate clamping is added. Explicit `world: "flat"` remains available for generic-runtime diagnostics. Both robots start with the camera behind the body. Mouse orbit detaches chase mode; **C** restores rear following and the default zoom, including while paused (pressing C again does not detach). Microduck mouse dragging still applies physical forces to the robot / ball. Microban mouse dragging orbits the camera. Gamepad / touch are not part of this release's acceptance scope.
## Microban fidelity and limits
- Actual ONNX interface: `obs [1, 63]` → `actions [1, 18]`.
- The model has 19 actuated joints; the policy controls 18 body joints, **not head**. Metadata's 19 names are resolved by name, not mistaken for actor output order.
- Projected gravity uses the trunk frame; the gyro retains the original IMU-site frame. Current policy has no extra reference-phase input.
- Physics timestep: 0.005 s; control decimation: 4 (50 Hz).
- **Simplified actuation**, not BAM: joint PD at every physics substep, kp=0.3, kd=0.02, torque limit=0.65 Nm.
- Default commands: forward 0.15 m/s, backward −0.1 m/s, turn ±0.6 rad/s. These are commanded, not guaranteed measured tracking speeds. Drift remains possible.
- Head follows the source's 0.35 Hz / ±π/4 sinusoid, with 0.5 s start / stop blending. It does not restart the walking controller.
- Falling stops policy updates and requests manual reset. There is no automatic stand-up policy for Microban.
BAM battery / friction / delay modeling, Placo squat, training, hardware control, ROS, camera observations, external Packages and online sharing are **not implemented** in this release. Ghost networking, stickers and celebration / entrance sequences are deferred. Audio retains the existing `SOUND_DISABLED=true` master setting; simulation never waits for an audio-unlock gesture.
## Development
Binary robot meshes and ONNX files use Git LFS:
```bash
git lfs install
git lfs pull
cd app
npm ci
npm run dev # http://localhost:5173
npm run build # app/dist/
npm run preview # production bundle
```
Use a Node version supported by Vite (this revision was tested with Node 24). The Dockerfile builds with Node 22 and serves the static bundle through nginx on port 8080; a Docker build itself is not part of the local browser verification.
### Verification
```bash
cd app
npm test # pure logic tests
npm run validate:packages # schemas, World, paths, source hashes
npx playwright install chromium
npm run test:e2e # real browser / WASM + UI + regression + ownership tests
npm run test:regression # accepted Microduck golden trajectories only
npm run format:check
npm audit
```
`npm run baseline:record` writes **candidates** under `app/test-results/baseline-candidates/`; it never overwrites accepted fixtures. Review changes before accepting any new baseline. See [baseline provenance](app/test/fixtures/microduck/README.md).
For a running production server, set `TEST_BASE_URL` and run the product-facing tests, e.g. `TEST_BASE_URL=http://127.0.0.1:5175 npm run test:e2e -- chase-camera deployment simulation-shell robot-switching microban-walking microban-observation microduck-regression runtime-smoke`. Development-only fixture pages are deliberately not shipped in `dist/`.
For prefixed hosting, build and preview with `VITE_BASE=/play/`; `DEPLOY_PATH=/play/` selects that entry path for `deployment.spec.js`. Private HF authentication behavior beyond the retained same-origin asset signing has not been independently deployment-tested.
`?test=1` is an internal deterministic-step hook, not a normal launch mode. `?boot=1` is no longer required. Legacy `?move`, `?policy` and `?session` requests remain limited to the Microduck adapter; they do not load arbitrary Robot Packages or replace Microban's controller.
## Architecture and extension
- `app/public/robots/*/robot.json`: model, joint groups, observations, actions, skills, bindings and presentation.
- `app/public/worlds/`: arena / flat World manifests.
- `app/src/platform/`: schemas / loading, SimCore, observation and action pipelines, term registries, ONNX, PD backend, overlay skills, input, MJCF renderer and transactional runtime manager.
- `app/src/robots/registry.js`: trusted bundled adapters; no remote JS execution.
- `app/src/robots/microduck/runtime.js`: compatibility adapter retaining original skill / recovery quirks and GLB presentation while using shared runtimes, scheduler, input, observation / action mapping and actuation.
- `app/src/game/worlds/arena/`: arena physics composition and rendering. `game/game.js` and `game/arena.js` are compatibility entry points, not generic engines.
A robot expressible with existing capabilities can be added by a Package and index entry, without a robot-id branch in the platform. Current generic scope is floating-base robots with scalar joint groups, unit-gear actuators, supported proprioceptive terms, ONNX primary control, position targets and optional sinusoidal overlays. Unsupported capabilities are rejected, not silently simulated incorrectly. New capabilities require explicit registry / schema work.
See [Package authoring](docs/robots/package-authoring.md), [Microban details](docs/robots/microban.md), [approved design](docs/superpowers/specs/2026-10-27-multi-robot-platform-design.md), [implementation plan](docs/superpowers/plans/2026-10-27-multi-robot-platform-implementation.md) and [initial verification](docs/superpowers/verification/2026-10-27-multi-robot-platform.md) and [style/camera verification](docs/superpowers/verification/2026-10-28-style-and-chase-camera.md), plus [arena-style verification](docs/superpowers/verification/2026-10-28-arena-presentation.md) and [current bounded-default verification](docs/superpowers/verification/2026-10-28-default-bounded-arena.md).
## License
The original application code is [Apache-2.0](LICENSE). Bundled third-party models, meshes, policies and samples retain their respective licenses; do **not** assume that every asset is Apache-2.0. Microban's copied XML retains its Apache-2.0 notice, and its upstream repository's mixed-license text, provenance and additional Apache notice are included in [`app/public/robots/microban/`](app/public/robots/microban/). Review those file-specific terms before redistribution. The bundled Anton font is SIL OFL-1.1; its notice is included at [`app/public/licenses/Anton-OFL.txt`](app/public/licenses/Anton-OFL.txt).