Files
chenlin d5e9004f6c
Checks / Layout, translation and Colab checks (push) Has been cancelled
Checks / Ruff (push) Has been cancelled
Checks / Framework tests (native backend, CPU) (push) Has been cancelled
Checks / Portable Rust controller (push) Has been cancelled
docs: add AI agent workflow guide and clean up residual single-robot references
2026-11-05 11:52:07 +08:00

5.2 KiB
Raw Permalink Blame History

MJRL Robotics Platform

简体中文 · Workflow · Command reference

Bring a robot model into MuJoCo, verify its dynamics and controls, and package it as a native simulation application. The platform also adapts compatible external policies and trains locomotion policies with the same environment on native MuJoCo CPU or MuJoCo Warp GPU.

Tier Starting point Output
0 Mesh, URDF, or an MJCF without verified controls Compiled model and viewer application
1 Compatible policy and explicit observation, action, and joint metadata Adapted ONNX policy and layout with numerical parity results
2 Complete robot model and known kinematics Deterministic controller and native verification report
3 Legged robot with a calibrated stance and explicit control intent Robot specification and training through a locked morphology template

We recommend opening this repository folder directly in an AI coding agent (such as Claude Code, Antigravity, Cursor, or Codex) and instructing the AI in natural language to onboard and train your robot.

The repository includes AGENTS.md, CLAUDE.md, and specialized workflow skills under .claude/skills/ (setup-env, onboard-asset, tier1-adapt, tier2-control, tier3-train, new-task, train, controls, deploy, and bundle-manual). When opened at the repository root, the agent automatically follows these rules and verification gates—you can simply point it at your URDF, MJCF, or mesh directory and ask it to set up the environment, inspect and calibrate the model, generate tasks/<robot_id>/robot_spec.py, launch or resume PPO training, run measured replay probes, and package a native .app bundle.

Run the model viewer

From the checkout, with Python 3.10–3.13:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e ".[dev]"
python scripts/onboard.py inspect assets/smoke/smoke_biped.xml
python scripts/deploy.py --robot viewer_smoke --model assets/smoke/smoke_biped.xml --bundle out/viewer_demo
python scripts/play.py --app out/viewer_demo/viewer_smoke.app --headless --steps 20

Choose an unused output directory. The smoke model exercises loading and packaging. For a new robot, replace the input with your own model and follow the report's recommended route. On Windows, activate with .venv\Scripts\Activate.ps1.

Bring your own robot

  1. Run scripts/onboard.py inspect with the source model and any available profile or policy metadata. Use build-mjcf for URDF and standalone meshes.
  2. Choose the route in Workflow. Simulate both physics and command response before building a controlled application.
  3. For legged locomotion, calibrate the stance and run scaffold-tier3. It generates tasks/<robot_id>/robot_spec.py. The biped, quadruped, wheeled biped, and multipod templates supply observations, rewards, domain randomization, curriculum, and PPO.
  4. Run python scripts/train.py --list to discover registered robots and python scripts/train.py --task <robot_id> --dry-run to check resolution.

A native .app contains the model, its dependencies, controller or policy, and a Python runtime entry point. The host supplies Python and the listed runtime libraries. The existing Rust browser and board workflow uses the legacy bundle format. The native exporter and runtime support wheeled-biped hybrid actions. The legacy Rust runtime accepts its position-action layout.

The four templates completed one PPO update each on native CPU and Warp GPU using synthetic robot fixtures. These runs validate the execution paths.

The Go1 example also completed 1,000 PPO updates on an RTX 5080. Its selected checkpoint averaged 0.401 m/s at a 0.400 m/s forward command over 18 seconds, with 0.022 m/s mean absolute error and no resets. Native checkpoint and ONNX replay passed forward, reverse, lateral, turning and idle probes. These are flat-floor simulation results, not hardware qualification or evidence that every robot will learn with the same run size.

The wheeled-biped example verifies hybrid leg-position and wheel-velocity control. Its selected policy passed native forward, reverse, yaw and idle probes, with keyboard and gamepad tests at its declared ±0.91 m/s and ±0.77 rad/s ranges. The G1 biped example passed seven isolated native probes and full-range keyboard tests after 7,800 Warp updates. The development record includes accepted applications and unsuccessful trials, with their measured reasons.

Reference