docs: add AI agent workflow guide and clean up residual single-robot references
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

This commit is contained in:
2026-11-05 11:52:07 +08:00
parent c32df70326
commit d5e9004f6c
45 changed files with 252 additions and 231 deletions
+24 -26
View File
@@ -5,22 +5,23 @@ description: Translate a built bundle's manual.en.json into Chinese as manual.zh
# The bundle's manual, in Chinese
`scripts/deploy.py` writes `manual.en.json` (`kk-bundle-manual/1`) into every
bundle: each pad control and each key the bundle reads, what it does in each
mode, how each mode is reached and left, and every mode switch. It is generated
from the controller's own account of its controls (`padGuide`), so it cannot
disagree with the bindings. The pad and the keyboard are two paths since
2026-09-29 and the manual lists them apart: in each mode `controls` is the pad
and `keys` the keyboard, and each switch says which `device` it is on. The
Chinese version is a translation of it, and this skill is how it is made: the
build cannot write natural Chinese, and a person or an agent can.
`scripts/deploy.py` writes `manual.en.json` into every bundle (both native
`mjrl-robot-app/1` bundles and legacy `kk-policy-bundle/1` bundles): each pad
control and each key the bundle reads, what it does in each mode, how each mode
is reached and left, and every mode switch. It is generated from the
controller's own account of its controls, so it cannot disagree with the
bindings. The pad and the keyboard are separate paths and the manual lists them
apart: in each mode `controls` is the pad and `keys` the keyboard, and each
switch says which `device` it is on. The Chinese version is a translation of
it, and this skill is how it is made: the build cannot write natural Chinese,
and a person or an agent can.
## Steps
1. Find the bundle directory. `deploy.py` prints it
(`[deploy] bundled <commit> -> …/out/bundle_<ts>/<name>`) and then prints the
`--translate` command with that path already filled in. It holds
`manual.en.json` and `bundle.json`.
1. Find the bundle directory. `deploy.py` writes `<bundle_parent>/<robot_id>`
(alongside `<robot_id>.app`) and prints the `--translate` command with that
path already filled in. The directory holds `manual.en.json` and
`bundle.json`.
2. Read `manual.en.json` in full.
3. Write `manual.zh.json` somewhere outside the bundle (a scratch file):
- the same JSON, field for field, in the same order;
@@ -34,22 +35,21 @@ build cannot write natural Chinese, and a person or an agent can.
entry in a mode's `keys` (`W`, `;`, `Space`, `↑`), and the `keys`
lists of `switches` (`Space`, `Ctrl + 1`, `Num 1`). They are identifiers,
and the check below refuses a translation that changes one.
4. Add it to the bundle, which checks it and packs the `.app` again:
4. Add it to the bundle, which checks it and packs the `.app` archive again:
```bash
python scripts/deploy.py --translate out/bundle_<ts>/<name> --language zh --manual <scratch file>
python scripts/deploy.py --translate <bundle-dir> --language zh --manual <scratch file>
```
It refuses a file whose non-text fields differ from the English one, and
holds the result to `deploy/app.schema`. Fix what it names and run it again.
5. If the `.app` is going to be committed (bundles are committed under
`out/bundle_<ts>/<name>.app`), commit it after this step, not before: the
translation changes the archive.
validates the result against the bundle's schema (`rl/mjrl/platform/app.schema`
for native apps or `deploy/app.schema` for legacy bundles). Fix what it names
and run it again.
## How to write it
For someone holding a gamepad or sitting at a keyboard, in plain Chinese. Keep
mode names as identifiers where they name a mode (`进入 jump`), and say what the
mode names as identifiers where they name a mode (`进入 locomotion`), and say what the
mode is in the sentence when the English does. The manual lists each mode's
keys on their own; say what a key does, never which pad control it is -- the
English never says that either.
@@ -79,16 +79,14 @@ English never says that either.
| let go of everything: every control back to rest | 全部松开:所有操作回到静止 |
| switch to X; press again to switch back | 进入 X;再按一次退出 |
| (from X, Y only) | (仅在 X、Y 中有效) |
| leave X, Y -- whichever is on -- back to locomotion | 退出 X、Y 中正在进行的那一个,回到 locomotion |
| leave X, Y -- whichever is on -- back to default | 退出 X、Y 中正在进行的那一个,回到默认模式 |
| click A once / double-click A / triple-click A | 单击 A / 双击 A / 三连击 A |
| click A four times / click A five times | 四连击 A / 五连击 A |
| switch to X; double-click again to switch back | 进入 X;再双击一次退出 |
A task's own words -- `closes the left claw as far as it is held`, from its
`controls.yaml` -- are translated like any other text: `按多深,左爪就夹多紧`;
`holds the carried arm straight out, thumb up, while held` is
`按住时手臂向前伸直,拇指朝上`, and thumb-web up is `虎口朝上`. A claw mode lists
only its own side's claw (the left claw's lists `LT` and Space, not `RT`), so
A mode's custom control descriptions from its `controls.yaml` are translated
like any other text (for example, `drives the elbow joint target` becomes
`驱动肘关节目标位置`). Each mode lists only the controls bound in that mode, so
translate what is there and add nothing.
## Why a separate step
@@ -61,8 +61,8 @@ DIFFERENTIAL_KEYS = {
KeyDirections = tuple[tuple[str, ...], tuple[str, ...]]
#: The keys that let go of everything, as the pad's release button does: Esc.
#: The keyboard's own, whatever button `--release` gives the pad. It was B until
#: Control-agent 3.1 put the right claw there (2026-09-29).
#: The keyboard's own release key, independent of whichever button `--release`
#: binds on the gamepad.
RELEASE_KEYS = ("key_escape",)
#: Seconds a key is held for its direction to reach full deflection; it is back
@@ -91,8 +91,8 @@ def check(name: str, kind: str, allowed) -> None:
absent = vocabulary.absent()
extra = f"\n {absent[name]}" if name in absent else ""
raise SystemExit(
f"[controls] {name!r} is not {kind} the robot's pad service publishes.\n"
f" It publishes: {' '.join(allowed)}{extra}\n"
f"[controls] {name!r} is not {kind} in the shared gamepad vocabulary.\n"
f" Allowed: {' '.join(allowed)}{extra}\n"
f" python -m controller --vocabulary"
)
@@ -177,13 +177,11 @@ def render(task: str, axes: list[str], bind: dict[str, tuple[str, int]],
out.append(" # The wheeled template scales this required pad channel to zero.")
out.append(f" {axis}: {{ source: {source}, sign: {sign} }}")
out += [
" # MEASURED: the signs are not measured against the robot's pad service.",
" # `controller/xbox.py` states the same evdev convention -- ABS_Y positive",
" # is **down**, ABS_X positive is **right** -- and the service passes both",
" # through unchanged, negating `dpad_y` and not `Ly`. Pushing the stick on",
" # the robot is what would settle it.",
" # `controller/xbox.py` uses the evdev convention -- ABS_Y positive is",
" # **down**, ABS_X positive is **right**. Confirm stick signs on the intended",
" # input device during verification.",
" #",
" # The service applies a 0.15 deadband and **rescales**, so full deflection",
" # The input layer applies a 0.15 deadband and **rescales**, so full deflection",
" # still reaches ±1. A consumer that applies its own on top narrows the",
" # range a person can ask for and cannot tell that it has.",
" deadzone: device_reported_rescaled",
+4 -3
View File
@@ -111,9 +111,10 @@ remedy and where the long form lives:
- **D — the task registry.** Loads no simulation dependencies, so it passes even where the GPU is
broken. A failure here is a packaging problem, not a simulation one — which is worth knowing
before looking in the wrong place.
- **E — the Rust toolchain builds the controller's host targets.** `cargo check` of the browser's
wasm and of `play --app`'s extension, and the wasm-bindgen CLI against `Cargo.lock`. It builds
rather than reading versions, because a missing target or linker passes `cargo --version`.
- **E — the Rust toolchain builds the legacy controller's host targets.** `cargo check` of the
browser's wasm and of the legacy `play --app` extension (`kk-policy-bundle/1`), and the
wasm-bindgen CLI against `Cargo.lock`. (Native `mjrl-robot-app/1` bundles run in pure Python.)
It builds rather than reading versions, because a missing target or linker passes `cargo --version`.
- **F — the device build links and loads.** `cargo test --lib -- --list` with the default
features: CycloneDDS, libclang, Rockchip's NPU header and a `libddsc` the loader finds. `--list` runs the binary
without running a test, so a failing crate test is not reported as an environment fault.
+3 -2
View File
@@ -122,7 +122,7 @@ def find_repo():
"""The repository root, if we are standing in it.
Identified by pyproject naming this project rather than by the directory
name, which is routinely different (kk-rl-mjlab, mjrl-lab, a worktree path).
name, which is routinely different (mjrl-lab, a custom clone name, or a worktree path).
"""
here = os.path.abspath(os.getcwd())
while True:
@@ -437,7 +437,8 @@ def main():
"" if steps else ": nothing missing"))
for step in steps:
print(" %s" % step)
print("\n Then verify: python <skill>/scripts/gates.py")
print("\n Then verify: python <skill>/scripts/gates.py --python-only")
print(" (omit --python-only to also check legacy Rust targets)")
return 0
+3 -3
View File
@@ -94,9 +94,9 @@ def locked_version(repo: Path, package: str) -> str | None:
def find_repo(start: Path | None = None) -> Path | None:
"""The repository root, identified by pyproject rather than directory name.
The directory is routinely named something else -- kk-rl-mjlab, a git
worktree path -- so matching on the name would fail on the machines this is
most needed on.
The directory is routinely named something else -- mjrl-lab, a custom clone
name, or a git worktree path -- so matching on the name would fail on the
machines this is most needed on.
"""
here = (start or Path.cwd()).resolve()
for candidate in [here, *here.parents]:
+4 -3
View File
@@ -3,20 +3,21 @@ __pycache__/
*.py[cod]
*.egg-info/
.pytest_cache/
.ruff_cache/
.venv/
venv/
build/
dist/
# Training artefacts
# Training and packaging artefacts
logs/
runs/
outputs/
# scripts/export.py's default output directory
# Default output directory for scripts/deploy.py and onboarding reports
out/
*.pt
*.onnx
# deploy/onnx2rknn.py's output, and the record of what built it
# deploy/convert/onnx2rknn.py's output, and the record of what built it
*.rknn
*.rknn.json
wandb/
+4 -1
View File
@@ -24,6 +24,7 @@ mjrl-lab/
│ ├── dds/ # legacy wire interface
│ └── fsm/ # legacy Rust controller
├── docs/ # manuals and design notes
├── notebooks/ # Colab GPU training notebook and guides
├── rl/
│ ├── mjlab/ # vendored simulator and manager library
│ ├── mjrl/
@@ -31,7 +32,9 @@ mjrl-lab/
│ │ ├── controllers/ # deterministic controller models
│ │ ├── onboarding/ # inspect, build, calibrate, verify
│ │ ├── platform/ # native app assembly and runtime
│ │ └── tasks/ # reusable MDP and curriculum code
│ │ ├── sensor/ # native camera and raycast sensors
│ │ ├── tasks/ # reusable MDP and curriculum code
│ │ └── viewer/ # live viewer, telemetry, and video recording
│ └── rsl_rl/ # vendored learning algorithms
├── scenes/ # built-in world configurations
├── scripts/ # onboard, train, play, export, deploy
+17 -1
View File
@@ -14,6 +14,22 @@ on native MuJoCo CPU or MuJoCo Warp GPU.
| 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 |
## Train with an AI Agent (Recommended)
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](AGENTS.md), [CLAUDE.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:
@@ -76,5 +92,5 @@ and unsuccessful trials, with their measured reasons.
- [Tutorial](docs/TUTORIAL.md) for verification, training, and measured replay.
- [Colab](docs/COLAB.md) for GPU training with your own registered robot.
- [Hardware and model facts](docs/HARDWARE.md) for calibration and actuator inputs.
- [Deployment format](deploy/BUNDLE.md) for application contents and runtime contracts.
- [Deploy guide](deploy/README.md) and [deployment format](deploy/BUNDLE.md) for application contents and runtime contracts.
- [Contributing](CONTRIBUTING.md) for repository layout and checks.
+13 -7
View File
@@ -1,6 +1,6 @@
# MJRL 机器人平台
<!-- tracks: README.md @ sha256:5e58614ff2c467bd -->
<!-- tracks: README.md @ sha256:124d41b6e17eb69c -->
[English](README.md) · [接入流程](docs/WORKFLOWS.md) · [命令手册](docs/USAGE.zh.md)
@@ -15,6 +15,12 @@ MuJoCo Warp GPU 上训练运动策略。
| 2 | 完整模型与已知运动学 | 确定性控制器及原生验证报告 |
| 3 | 站姿已标定且控制意图明确的足式机器人 | 机器人规格及锁定形态模板训练 |
## 使用 AI Agent 进行接入与训练(推荐)
建议使用 AI Agent(如 Claude Code、Antigravity、Cursor、Codex 等)直接打开本仓库根目录文件夹,并通过自然语言指挥 AI 进行机器人接入、训练与打包。
仓库内置了 [AGENTS.md](AGENTS.md)、[CLAUDE.md](CLAUDE.md) 以及位于 `.claude/skills/` 下的专用工作流技能(`setup-env`、`onboard-asset`、`tier1-adapt`、`tier2-control`、`tier3-train`、`new-task`、`train`、`controls`、`deploy`、`bundle-manual`)。在仓库根目录下打开后,AI Agent 会自动读取工作规则与验证门禁——你只需告知 URDF、MJCF 或网格模型路径,即可指挥 AI 自动完成环境配置、模型检查与站姿标定、生成 `tasks/<robot_id>/robot_spec.py`、启动或恢复 PPO 训练、执行量化回放评测以及打包原生 `.app` 应用。
## 运行模型查看应用
在代码库根目录中使用 Python 3.10–3.13:
@@ -65,9 +71,9 @@ Python 和所列依赖。现有 Rust 浏览器与板端走独立的旧版包格
## 参考
- [项目指南](docs/PROJECT_GUIDE.zh.md)
- [教程](docs/TUTORIAL.zh.md)
- [Colab](docs/COLAB.zh.md) 用于在 GPU 上训练自己注册的机器人
- [硬件与模型参数](docs/HARDWARE.zh.md)
- [部署包格式](deploy/BUNDLE.md)
- [贡献指南](CONTRIBUTING.md)
- [项目指南](docs/PROJECT_GUIDE.zh.md):导航与支持边界说明。
- [教程](docs/TUTORIAL.zh.md):验证、训练与量化回放流程。
- [Colab](docs/COLAB.zh.md):在 GPU 上训练已注册的机器人。
- [硬件与模型参数](docs/HARDWARE.zh.md):标定要求与执行器输入规范。
- [部署指南](deploy/README.zh.md)与[部署包格式](deploy/BUNDLE.md):应用结构与运行时契约。
- [贡献指南](CONTRIBUTING.md):目录结构与仓库检查项。
+5 -3
View File
@@ -84,10 +84,12 @@ and settled after Escape.
The packaged runtime reproduced seven 12-second probes, including sampled
joint state and per-axis body-frame tracking metrics. The app includes the
asset license and provenance along with English and Chinese operator manuals.
After building the app, use the repository's native reference checker.
Build the app and run the repository's native reference checker:
```bash
python scripts/deploy.py --check-reference out/platform_release_20261104/go1_example.app
python scripts/play.py --app out/platform_release_20261104/go1_example.app --headless \
python scripts/deploy.py --robot go1_example --checkpoint <checkpoint.pt> \
--output out/go1_example_bundle
python scripts/deploy.py --check-reference out/go1_example_bundle/go1_example.app
python scripts/play.py --app out/go1_example_bundle/go1_example.app --headless \
--steps 200 --command 0.4 0 0
```
+1 -1
View File
@@ -20,7 +20,7 @@ python scripts/onboard.py calibrate --model assets/multipod_example/multipod.xml
python scripts/onboard.py scaffold-tier3 --config assets/multipod_example/robot.json \
--calibration out/multipod-calibration.json --tasks-root out/multipod-scaffold
python scripts/train.py --task multipod_example --backend native --device cpu \
--num_envs 4 --max-iterations 1 --headless --no-tensorboard
--num-envs 4 --max-iterations 1 --headless --no-tensorboard
```
The checked-in robot specification is the calibrated task used by the
+1 -1
View File
@@ -138,7 +138,7 @@ whether the reader pairs at all -- and a mismatch does not raise, it leaves
The 2026-09-29 refresh is that case again. The `ImuData` fields reached mbus master
only in the 2026-09-28 merge, mbus's CHANGELOG has no release entry for them yet, and
the board last read (`deploy/README.md`) ran libmbus 2.4.0, from 2026-09-02. A
the board last read ran libmbus 2.4.0, from 2026-09-02. A
controller built from this tree pairs with an `mc_ctrl_driver` / `mc_forwarder` rebuilt
against `d9875988f065` or later, and with nothing older. `check_board.py` compares the
board's `idl_motor_control.h` with the one generated here and says which it is.
+1 -1
View File
@@ -261,7 +261,7 @@ operator fresh either way, so sending it every frame is harmless.
a page that wants to say which keys do something: `controls` is each mode's own
account of its bindings -- the lines the robot's controller prints before it
enables the motors -- on one line, the modes that read the pad alike named
together: `claw_left, claw_right: … | locomotion: …`. Show it as given;
together: `stand: … | locomotion: …`. Show it as given;
describing the bundle yourself would be a second copy of its bindings.
`fsm.bindings()` returns `[{name, pad, key, on, with, from, leaves}]` -- the mode
+11 -11
View File
@@ -13,8 +13,8 @@ places they have to run:
| | observation from | inference on | execution to |
|---|---|---|---|
| `kk-rl-mjlab`'s `play` | mjlab's simulation | ONNX, on the host | mjlab actuators |
| BEUNLIMITED's web sim | MuJoCo WASM | ONNX, in the browser | the same actuators |
| `mjrl-lab`'s `play` | mjlab's simulation | ONNX, on the host | mjlab actuators |
| the browser web sim | MuJoCo WASM | ONNX, in the browser | the same actuators |
| the robot | servos and IMU | RKNN, on the NPU | DDS to the motor controller |
That logic existed **three times**: this crate in Rust, `rl-wbc-fsm` in C++,
@@ -162,7 +162,7 @@ locomotion on `device`:
```
**That list is the sim2real gap, enumerated.** Nobody can see it today. It costs
one field per term in the exported contract — every term kk-rl-mjlab exports is
one field per term in the exported contract — every term `mjrl-lab` exports is
`Simulated`, so producing it is nearly free, and the value is entirely on the
consuming side.
@@ -292,8 +292,8 @@ So transitions become an **ordered rule list**, first match wins:
[[fsm.rule]] when = "in_state:safe" enter = "@initial"
[[fsm.rule]] when = "warm_start_reached" enter = "@warm_start_ref"
[[fsm.rule]] when = "in_state:warmstart" enter = "@stay"
[[fsm.rule]] when = "button:jump" enter = "jump"
[[fsm.rule]] when = "button:claw_left" enter = "claw_left"
[[fsm.rule]] when = "button:stand" enter = "stand"
[[fsm.rule]] when = "button:motion" enter = "motion"
[[fsm.rule]] when = "always" enter = "locomotion"
```
@@ -466,7 +466,7 @@ Built as of this document:
| the two-phase tick, four regimes, per-mode runtimes | `src/control.rs` |
| each mode's reading of the pad and keys, command shaping | `src/operator.rs` |
| the pad's manual as data (`pad_guide`) | `src/guide.rs` |
| a task's deploy hook, compiled in from `tasks/**/deploy/lib.rs` by `build.rs` | `src/hook.rs` |
| an optional task deploy hook, compiled in from `tasks/**/deploy/lib.rs` by `build.rs` | `src/hook.rs` |
| the recorded motion a reference-guided mode is driven by | `src/trajectory.rs` |
| a recorded run replayed, and where a host differs | `src/reference.rs` |
| the bundle format, one reader for every host with a filesystem | `src/bundle.rs` |
@@ -475,11 +475,11 @@ Built as of this document:
| `play`'s host: the pyo3 `Fsm` | `src/py.rs` |
| the robot's program: the loop, the two clocks, the shutdown path | `src/bin/controller.rs` |
156 tests. Two of them are control groups, because both of these modules replace
162 tests in the generic controller core. Two of them are control groups, because both of these modules replace
something that was previously written into code and would pass every obvious
assertion while ignoring the file: `the_cascade_is_the_file_s_rather_than_agreeing_with_it`
moves the tilt rule below the operator's button and requires a tilted robot to
jump, and `the_check_reads_what_training_recorded_rather_than_assuming_it` trains
switch modes, and `the_check_reads_what_training_recorded_rather_than_assuming_it` trains
a term as reconstructed and requires simulation to be reported as the divergence.
`control.rs` earned a third test the hard way. Its first `publish` used
@@ -507,8 +507,8 @@ into a `button:<name>` the rules can match. `pump` is compiled against the real
`[[fsm.button]]` names one thing the operator can ask for and which control asks
it: a pad button or a keyboard key, one device per entry, and two entries with
one name share its latch -- the pad's A and the keyboard's Space are both the
jump. It also carries the gesture (`rise`, `fall`, `hold`, `toggle`, or a click
one name share its latch -- the pad's A and the keyboard's Space can both drive
the same mode switch. It also carries the gesture (`rise`, `fall`, `hold`, `toggle`, or a click
count `single` … `quintuple` counted inside `[fsm] click_window_ms`), an optional
`with` modifier (a pad button, or `ctrl` / `shift` / `alt` for a key), `from`
(the states it may be pressed in) and `leaves` (latches it lets go of). Pad
@@ -598,6 +598,6 @@ second shutdown behaviour. None of it can be tested off the board.
## Open
- **Provenance in the exported contract.** Needs a field per observation term in
kk-rl-mjlab's exporter. Cheap to produce, and the whole value of the divergence
`mjrl-lab`'s exporter. Cheap to produce, and the whole value of the divergence
list depends on it.
- **Per-mode command vocabulary**, above.
+5 -5
View File
@@ -77,7 +77,7 @@ and one `.app` of it that somebody with none of this repository can use, on any
of the three hosts:
```bash
python scripts/deploy.py
python scripts/deploy.py --manifest <bundle-id>
```
It runs the cross build above first, every time, so the board's binary in the
@@ -94,7 +94,7 @@ removed rather than left for someone to upload. Then it is held to
For the wasm, a cargo build and wasm-bindgen are what it runs. Run it rather
than them: it reads the commit **after** looking at the tree, suffixes it `-dirty`
when the controller's source has uncommitted changes -- the crate, and every file
outside it the build reads, each task's hook among them (`SOURCES` in the script)
outside it the build reads (`SOURCES` in the script)
-- and holds the wasm-bindgen CLI
against the version the crate compiles with. The hand procedure lasted one day
before it recorded a commit whose source would have built a different controller
@@ -165,9 +165,9 @@ the policy `(0, 0)`.
**This is not cosmetic, and the C++ controller does not do it.** The policy is
trained that way — zero magnitude is a value no phase can produce, i.e. an
unambiguous "hold still". A free-running unit-magnitude clock was measured during
training to make the robot step in place while commanded to stand: roll-rate
autocorrelation peaked at the clock frequency, and 5.17 of 6 feet were on the
ground.
training to make the robot step in place while commanded to stand, with roll-rate
autocorrelation peaking at the clock frequency instead of holding all supports on
the ground.
The failure is invisible to every dimension check: gated or not, `gait_phase` is
2 wide and the observation is the same length. Only the values differ, and only
+2 -2
View File
@@ -32,8 +32,8 @@ not free to float:
- `deploy/convert/requirements.txt` pins `rknn-toolkit2==2.3.2`, and a `.rknn`
does not load under a `librknnrt` older than the toolkit that produced it;
- the board carries `librknnrt` 2.3.2 (`deploy/README.md`, *Verified against the
board*), and `.claude/skills/deploy/scripts/check_board.py` checks it.
- the board carries `librknnrt` 2.3.2, and
`.claude/skills/deploy/scripts/check_board.py` checks it.
Moving to another release means changing all three together, and the two sha256
values in `fetch.sh` with them.
+21 -15
View File
@@ -215,17 +215,18 @@ If this environment ever had them, uninstall first (this does not remove their d
pip uninstall -y mjlab rsl-rl-lib
```
### 2.1 The controller's toolchain: Rust
### 2.1 The legacy controller's toolchain: Rust
The controller (`deploy/fsm`) is Rust, one crate on three hosts. `scripts/deploy.py` builds two of
them on this machine with cargo — the browser's wasm and `play --app`'s extension — and
The legacy controller (`deploy/fsm`) is Rust, one crate on three hosts. `scripts/deploy.py` builds
two of them on this machine with cargo — the browser's wasm and the legacy `play --app` extension — and
cross-builds the board's binary and the Windows extension in Docker, which brings its own
toolchain. **Every row of section 0's decision table needs this subsection**; it does not branch
on the GPU.
toolchain. Native platform `.app` bundles (`mjrl-robot-app/1`) run in pure Python without this
toolchain; install this subsection when building or testing legacy `kk-policy-bundle/1` browser,
board, or extension targets.
> ⚠️ **Without cargo the test suite does not fail, it skips.** `tests/test_fsm_extension.py` and
> ⚠️ **Without cargo the legacy controller tests do not fail, they skip.** `tests/test_fsm_extension.py` and
> `tests/test_deploy_sources.py` skip when there is no cargo, so `pytest tests/` is green on a
> machine that has never built the controller.
> machine that has never built the legacy controller.
Four pieces. `detect.py` prints only the ones this machine lacks:
@@ -307,7 +308,7 @@ export PATH=$CYCLONEDDS_HOME/bin:$PATH
```
bindgen finds libclang in Xcode's command-line tools. Measured on an M3 Max (Darwin 25.5,
cargo 1.95.0) on 2026-10-08: the build takes about two minutes, gate F lists 195 tests, and
cargo 1.95.0): the build takes about two minutes, gate F lists 162 tests, and
`cargo test --lib` in `deploy/fsm` passes all of them. A test binary built before
`CYCLONEDDS_HOME` was exported carries no rpath and aborts with
`Library not loaded: @rpath/libddsc.11.dylib`; rebuild it (`cargo clean -p mjrl-fsm`) rather
@@ -394,9 +395,11 @@ A `ModuleNotFoundError` here means `pip install -e .` was not run or did not suc
python scripts/train.py --list
```
Expected: every `tasks/<robot_id>/robot_spec.py` appears by robot ID. A fresh
checkout reports an empty registry. This command loads no simulation
dependencies. Check the editable install and literal robot specs if it fails.
Expected: every `tasks/<robot_id>/robot_spec.py` appears by robot ID (on a fresh
checkout: `g1_example`, `go1_example`, `multipod_example`, and
`wheeled_biped_example`), followed by the built-in scenes. This command loads no
simulation dependencies. Check the editable install and literal robot specs if
it fails.
### Gate E — The Rust toolchain builds the controller's host targets
@@ -420,7 +423,7 @@ a new machine also downloads them.
cargo test --locked --lib --manifest-path deploy/fsm/Cargo.toml -- --list
```
Expected: a list of lines ending in `: test` (179 of them on 2026-09-29). `--list` runs the test
Expected: a list of lines ending in `: test` (162 in the generic controller core). `--list` runs the test
binary without running a test, so it proves `libddsc` is found at load time — which a
`cargo check` never would — and a failing crate test cannot pass itself off as an environment
fault. 9 s cold on the same machine. A checkout without Rockchip's NPU header fails here, in
@@ -516,9 +519,12 @@ wandb also works, but tensorboard is less trouble.)
infers defaults from the `mjData` of a resting pose, and a moving robot has many more contacts
than a resting one.
Inspect the model's contact geometry and measure contact load. A capacity change
to the shared simulator recipe requires an explicit template revision and
updated lock validation.
**Remedy**: pass `--warp-max-constraints N` and/or `--warp-max-contacts N` on the command line
(for example, `g1_example` uses `--warp-max-constraints 300`). Warp runs record these capacities in
`warp-allocation.json` beside their checkpoints for resume, replay, and export. Also inspect the
model's collision geometry (`onboard.py build-mjcf` or `tools/hull_collision.py`) if contact load is
unreasonably high. A default capacity change inside the shared simulator recipe requires an explicit
template revision and updated lock validation.
### `"cuda" device requested but this build of Warp does not support CUDA`
+20 -15
View File
@@ -1,9 +1,9 @@
<!-- tracks: AGENT_SETUP.md @ sha256:62621d9b01a77c30 -->
<!-- tracks: AGENT_SETUP.md @ sha256:076262f3d4d73ae1 -->
# 环境搭建说明(写给 AI agent)
本文档写给**在一台全新机器上把 mjrl-lab 跑起来的 AI agent**。
人类读者请从 [`../README.md`](../README.md) 开始。
人类读者请从 [`../README.zh.md`](../README.zh.md) 开始。
## 机械的部分由两个脚本完成
@@ -203,15 +203,15 @@ pip install -e .
pip uninstall -y mjlab rsl-rl-lib
```
### 2.1 控制器的工具链:Rust
### 2.1 旧版控制器的工具链:Rust
控制器(`deploy/fsm`)是 Rust 写的,一个 crate 跑在三种宿主上。`scripts/deploy.py` 在本机用
cargo 构建其中两种 —— 浏览器的 wasm 和 `play --app` 的扩展 —— 板端二进制和 Windows 扩展则在
Docker 里交叉编译,镜像自带工具链。**第 0 节决策表的每一行都需要本小节**;它不按有没有 GPU
分叉。
旧版控制器(`deploy/fsm`)是 Rust 写的,一个 crate 跑在三种宿主上。`scripts/deploy.py` 在本机用
cargo 构建其中两种 —— 浏览器的 wasm 和旧版 `play --app` 的扩展 —— 板端二进制和 Windows 扩展则在
Docker 里交叉编译,镜像自带工具链。原生平台 `.app` 应用(`mjrl-robot-app/1`)使用纯 Python 运行,
不需要此工具链;仅当需要构建或测试旧版 `kk-policy-bundle/1` 的浏览器、板端或扩展目标时才需安装本小节。
> ⚠️ **没有 cargo 时测试集不会失败,而是跳过。** 没有 cargo,`tests/test_fsm_extension.py` 和
> `tests/test_deploy_sources.py` 会 skip,于是在一台从没构建过控制器的机器上,
> ⚠️ **没有 cargo 时旧版控制器测试不会失败,而是跳过。** 没有 cargo,`tests/test_fsm_extension.py` 和
> `tests/test_deploy_sources.py` 会 skip,于是在一台从没构建过旧版控制器的机器上,
> `pytest tests/` 也是绿的。
一共四样。`detect.py` 只打印这台机器缺的那几样:
@@ -290,8 +290,8 @@ export CYCLONEDDS_HOME=$HOME/.local/opt/cyclonedds-11.0.1
export PATH=$CYCLONEDDS_HOME/bin:$PATH
```
bindgen 从 Xcode 命令行工具里找 libclang。2026-10-08 在一台 M3 Max(Darwin 25.5,cargo
1.95.0)上实测:构建约两分钟,gate F 列出 195 个测试,`deploy/fsm` 里 `cargo test --lib` 全部
bindgen 从 Xcode 命令行工具里找 libclang。在一台 M3 Max(Darwin 25.5,cargo
1.95.0)上实测:构建约两分钟,gate F 列出 162 个测试,`deploy/fsm` 里 `cargo test --lib` 全部
通过。在 `export CYCLONEDDS_HOME` 之前构建出来的测试二进制没有 rpath,会以
`Library not loaded: @rpath/libddsc.11.dylib` 中止;重新构建它(`cargo clean -p mjrl-fsm`),
不必重装 CycloneDDS。
@@ -373,8 +373,9 @@ python -c "import mjlab, rsl_rl, os; print(os.path.dirname(mjlab.__file__)); pri
python scripts/train.py --list
```
预期:每个 `tasks/<robot_id>/robot_spec.py` 按机器人 ID 列出。新检出报告空注册表。
该命令无需加载仿真依赖。失败时检查可编辑安装和机器人规格数据。
预期:每个 `tasks/<robot_id>/robot_spec.py` 按机器人 ID 列出(新检出包含
`g1_example`、`go1_example`、`multipod_example` 和 `wheeled_biped_example`),
随后列出内置场景。该命令无需加载仿真依赖。失败时检查可编辑安装和机器人规格数据。
### Gate E —— Rust 工具链能构建控制器的宿主目标
@@ -397,7 +398,7 @@ wasm-bindgen --version
cargo test --locked --lib --manifest-path deploy/fsm/Cargo.toml -- --list
```
预期:一串以 `: test` 结尾的行(2026-09-29 时是 179 行)。`--list` 会运行测试二进制但不执行
预期:一串以 `: test` 结尾的行(通用控制器核心包含 162 个测试)。`--list` 会运行测试二进制但不执行
任何测试,所以它能证明加载时找得到 `libddsc` —— 这是 `cargo check` 永远证明不了的 —— 同时
crate 自己的测试失败也没法冒充成环境故障。同一台机器上冷构建 9 s。缺 Rockchip NPU 头文件的
checkout 会在这里、在 `build.rs` 中失败;解决办法是 `fetch.sh`(2.2 节)。
@@ -485,7 +486,11 @@ tensorboard 省事。)
`njmax` / `nconmax` 是每个 world 上约束行数和接触数的上限。mujoco_warp 从静止姿态的
`mjData` 推断默认值,而运动中的机器人接触数比静止时多得多。
检查碰撞几何并测量接触负载。若需调整共享仿真容量,应明确修订模板并重新验证锁定规则。
**补救**:在命令行传入 `--warp-max-constraints N` 和/或 `--warp-max-contacts N`(例如
`g1_example` 使用 `--warp-max-constraints 300`)。Warp 训练会在检查点旁的
`warp-allocation.json` 中保存该容量供续训、回放和导出使用。若接触负载过高,也应检查碰撞几何
(`onboard.py build-mjcf` 或 `tools/hull_collision.py`)。若需调整共享仿真配方的默认容量,
应明确修订模板并重新验证锁定规则。
### `"cuda" device requested but this build of Warp does not support CUDA`
+1 -1
View File
@@ -16,7 +16,7 @@ platform. Use [Agent setup](AGENT_SETUP.md) to establish the environment and
| Extend the platform | [Contributing](../CONTRIBUTING.md) |
The checkout includes calibrated Go1, G1, six-legged and wheeled-biped examples,
covering all four locked families. G1 also has a separate compliant-gain variant.
covering all four locked families.
Their asset READMEs distinguish execution checks, measured
learning and accepted policies; registration alone is not a performance or
hardware qualification. Add another robot with the onboarding tools to give it
+2 -3
View File
@@ -1,6 +1,6 @@
# 项目指南
<!-- tracks: PROJECT_GUIDE.md @ sha256:ed077c5edd6cf510 -->
<!-- tracks: PROJECT_GUIDE.md @ sha256:1db03214fd026c6f -->
接入资产或策略时先读[接入流程](WORKFLOWS.md)。用[环境准备](AGENT_SETUP.zh.md)
建立环境,用[命令手册](USAGE.zh.md)查询命令和配置。
@@ -12,12 +12,11 @@
| 配置键盘或手柄 | [操作控制](CONTROLS.zh.md) |
| 训练和测量足式策略 | [教程](TUTORIAL.zh.md) |
| 在 Colab GPU 上训练 | [Colab](COLAB.zh.md) |
| 打包原生应用或检查旧版部署包 | [部署指南](../deploy/README.md)与[包格式](../deploy/BUNDLE.md) |
| 打包原生应用或检查旧版部署包 | [部署指南](../deploy/README.zh.md)与[包格式](../deploy/BUNDLE.md) |
| 理解双后端与模板锁定 | [平台设计](DESIGN.md)与[上游依赖](VENDOR.md) |
| 扩展平台 | [贡献指南](../CONTRIBUTING.md) |
本仓库包含经过标定的 Go1、G1、六足和轮足双足样例,覆盖四个锁定模板。
G1 另有一个独立的柔顺增益变体。
各资产的 README 区分执行检查、实际学习效果与验收通过的策略;注册本身不代表
性能达标或硬件认证。用接入工具为新机器人生成任务 ID,再运行
`python scripts/train.py --list` 查看本地注册项。
+2 -1
View File
@@ -14,7 +14,8 @@ instructions.
third-party notices. The legacy Rockchip runtime has separate provenance
and terms described in its [runtime notes](../deploy/fsm/vendor/rknpu2/README.md).
- Inspect tracked configuration, generated packages, and archives for private
content. Shared defaults are in `.env`. Keep `.env.local` out of the snapshot.
content. Shared option keys are documented in `.env.example`. Keep `.env` and
`.env.local` out of the snapshot.
- Choose the commit identity, confirm the target remote and branch, and
review changes already present there before publishing.
- Keep release downloads and provenance tied to actual artifacts. Record
+3 -4
View File
@@ -39,10 +39,9 @@ on 2026-11-04. All training runs started for this snapshot have finished.
Bundling fingerprints inputs, rejects missing gates, and reruns the packaged
response before publication. The reader uses its own trusted schema.
- Original exclusive robot assets/tasks were removed after shared mechanisms were
extracted. Historical ignored exports were initially preserved, then removed
during workspace cleanup: `out/pre_platform_exports_20261104/` and
`out/bundle_example/jumper/`. Training logs, failure reports and other user
applications were retained. Scene dimensions are explicit nominal parameters.
extracted. Historical ignored exports under `out/` were removed during
workspace cleanup, while training logs, failure reports and user applications
were retained. Scene dimensions are explicit nominal parameters.
## Measured evidence
+2 -2
View File
@@ -92,7 +92,7 @@ python scripts/play.py --task my_robot --checkpoint <model_N.pt> --headless \
--evaluation-out evaluation.json
```
报告检查点、后端、环境数、迭代数、命令、观测噪声、仿真时长、跟踪误差与重置。
报告检查点、后端、环境数、迭代数、命令、观测噪声、仿真时长、跟踪误差与重置。仅当评测包含与无噪声回放的对比时,才额外使用干净观测回放进行比较。
## 导出到原生仿真
@@ -112,4 +112,4 @@ python scripts/onboard.py verify --model out/native_policy/robot.xml \
使用通过的报告及其对应导出文件构建原生应用。详见
[控制器设置](CONTROLLER_SETUP.md#native-hybrid-policy-export)和
[部署指南](../deploy/README.md)。
[部署指南](../deploy/README.zh.md)。
+3 -3
View File
@@ -197,9 +197,9 @@ The legacy target flags build the separate Rust bundle format.
## Defaults
Precedence is command line, shell environment, `.env.local`, `.env`, then the
argument default. A blank task means a task is required on task entry points.
A blank model selects the robot's registered model. The committed defaults
are:
argument default. Copy `.env.example` to `.env` to set local defaults. A blank
task means a task is required on task entry points. A blank model selects the
robot's registered model. The effective defaults are:
```dotenv
MJRL_TASK=
+27 -9
View File
@@ -1,6 +1,6 @@
# 命令手册
<!-- tracks: USAGE.md @ sha256:5d4ada2976459092 -->
<!-- tracks: USAGE.md @ sha256:3f15279c7bd4459d -->
用 Python 3.10–3.13 建立环境并执行 `python -m pip install -e ".[dev]"`。
平台配置见[环境准备](AGENT_SETUP.zh.md)。可编辑安装负责连接两个包根目录。
@@ -73,12 +73,29 @@ extraction = extract_policy_metadata(
`penalized_contact_geoms` 和 `termination_contact_geoms`。模型及控制路径
相对输入 JSON 解析。标定报告须对应实际 XML 和编译依赖。
也可提供完整的已验证规格。完整字段包括 `base_body`、`base_height`、
`foot_geoms` 或 `foot_bodies`,以及 `position_joints`。每个位置关节提供
`name`、`kp`、`kd`、`effort_limit`、`action_scale`、`home`,
可选 `armature`。站立根高度是 `base_height`,各关节默认位置是 `home`。
支撑物体需要直属的命名碰撞几何。双足和轮足双足至少两个支撑,四足至少四个,
多足至少五个。轮足双足还需至少两个不限位转动关节,设置 `kp: 0`、
不传 `--calibration` 时,可根据已验证的模型参数提供完整 `RobotSpec`,格式示例如下:
```json
{
"robot_id": "sample_biped",
"family": "biped",
"model_path": "assets/sample_biped/robot.xml",
"base_body": "base",
"base_height": 0.32,
"foot_geoms": ["left_foot", "right_foot"],
"penalized_contact_geoms": ["left_shin", "right_shin"],
"termination_contact_geoms": ["torso"],
"position_joints": [
{"name": "left_hip", "kp": 20, "kd": 1, "effort_limit": 8, "action_scale": 0.25, "home": 0.1},
{"name": "right_hip", "kp": 20, "kd": 1, "effort_limit": 8, "action_scale": 0.25, "home": 0.1}
]
}
```
请使用针对该机器人标定的数值。站立根高度是 `base_height`,各关节默认位置是 `home`,
可选 `armature` 为该关节的附加转动惯量。提供 `foot_geoms` 或 `foot_bodies`;
每个支撑刚体需要直属的命名碰撞几何。双足和轮足双足至少两个支撑,四足至少四个,
多足至少五个。轮足双足还需在 `velocity_joints` 中提供至少两个不限位转动关节,设置 `kp: 0`、
正 `kd`、力矩上限和轮速动作尺度。
仅生成 `tasks/<robot_id>/robot_spec.py`,任务 ID 等于机器人 ID。
@@ -148,8 +165,9 @@ python scripts/play.py --app <output-parent>/<robot_id>.app --headless --steps 1
## 默认值
优先级从高到低为命令行、环境变量、`.env.local`、`.env`、参数默认。
空任务要求显式指定,空模型选择已注册模型。
优先级从高到低为命令行、环境变量、`.env.local`、`.env`、参数默认。可将
`.env.example` 复制为 `.env` 自定义本地默认值。空任务要求显式指定,空模型选择
已注册模型。有效默认值为:
```dotenv
MJRL_TASK=
+5 -7
View File
@@ -85,7 +85,7 @@ include = ["tasks*", "scenes*", "controller*", "mjrl*", "mjlab*", "rsl_rl*"]
# never hit it, which is exactly what makes it easy to ship.
[tool.setuptools.package-data]
scenes = ["assets/*/*.png"]
tasks = ["templates/**/*.json", "templates/**/AGENTS.md"]
tasks = ["templates/**/AGENTS.md"]
# The gamepad dictionary is data, read at run time by `controller.vocabulary`
# and at compile time by `deploy/fsm`. Same reason as the scene textures: a
# wheel with the module and not the file fails on first use, not on build.
@@ -118,13 +118,11 @@ select = ["E4", "E7", "E9", "F"]
# A notebook cell imports where it first needs a name, after the form fields
# Colab reads off the top of the cell; ruff 0.16 lints notebooks by default.
"notebooks/*.ipynb" = ["E402"]
# One-off checks and asset tools are written dense -- several statements to a
# line, an import where it is first needed -- on purpose: each is read once,
# beside the measurement it produced. Only the layout is exempt; a dead import
# or an empty f-string is still a finding there.
# One-off checks are written dense -- several statements to a line, an import
# where it is first needed -- on purpose: each is read once, beside the
# measurement it produced. Only the layout is exempt; a dead import or an empty
# f-string is still a finding there.
"tools/checks/*" = ["E401", "E402", "E701", "E702"]
"assets/*/tools/*" = ["E401", "E402", "E701", "E702"]
"tasks/*/tools/*" = ["E701"]
[tool.pytest.ini_options]
testpaths = ["tests"]
+4 -5
View File
@@ -1,7 +1,6 @@
# Asset Zoo
| Robot | Image |
|-------|-------|
| **Unitree G1** | <img src="../../../docs/source/_static/content/g1.png" width="200" height="150" alt="Unitree G1 Humanoid"> |
| **Unitree Go1** | <img src="../../../docs/source/_static/content/go1.png" width="200" height="150" alt="Unitree Go1 Quadruped"> |
| **i2rt YAM** | <img src="../../../docs/source/_static/content/yam.png" width="200" height="150" alt="i2rt YAM Robot Arm"> |
| Robot | Description |
|-------|-------------|
| **Unitree G1** | Unitree G1 Humanoid (`rl/mjlab/asset_zoo/robots/unitree_g1`) |
| **Unitree Go1** | Unitree Go1 Quadruped (`rl/mjlab/asset_zoo/robots/unitree_go1`) |
-2
View File
@@ -1,5 +1,3 @@
# Terrains
Procedurally generate terrains using primitive geometries and heightfields.
<img src="../../../docs/source/_static/content/rough_terrain.png" alt="Rough Terrain">
+1 -1
View File
@@ -50,7 +50,7 @@ from dataclasses import dataclass
from pathlib import Path
from typing import Any
from mjrl.viewer.keys import ViewerKeys as ViewerKeys
from mjrl.viewer.keys import ViewerKeys
try:
import tomllib
+1 -1
View File
@@ -950,7 +950,7 @@ class NativeSimulation:
**Putting each environment's control and warm start back costs** one
`mj_setState` and two small copies per environment, under the GIL. Measured
on the i9-14900KF (2026-09-26), example_robot.tripod on 8 threads, medians of 5
on the i9-14900KF (2026-09-26), a 6-legged locomotion task on 8 threads, medians of 5
runs interleaved with the code before it, before -> after:
| envs | `sim.step` ms | `env.step` ms | this function ms |
+9 -30
View File
@@ -31,8 +31,8 @@ __all__ = [
def load_command_script(spec: str):
"""`FILE[:NAME]` -> the callable `NAME` (default `script`) defined in `FILE`.
The file is loaded by path, not imported by name: a clip's script lives next
to whatever draws the clip (`tools/readme_media.py`), which is not a package.
The file is loaded by path, not imported by name, so standalone evaluation
or video-capture scripts outside the package tree can be passed directly.
"""
path, sep, name = spec.rpartition(":")
if not sep or not name.isidentifier():
@@ -55,15 +55,10 @@ def script_commands(env, script) -> list[str]:
"""Have command terms hold what `script` says, from each term's own `compute` on.
`script(t)` returns `{term name: values}` for `t` seconds since this was
installed; it is written into each named term **after** the term's own
`compute`, which is where the operator writes -- so a pad that is plugged in
and nudged does not drive a scripted term, and the term's own bookkeeping
(metrics, resample timers, the posture term's walking band) still runs.
Two kinds of term are understood: a velocity command (`vel_command_b`,
three values) and a posture command (`posture_command`, four). A posture's
height may be NaN, the term's own
neutral height, or `(height, share)`, that share of the way there from it.
installed; it is written into each named velocity command term (`vel_command_b`,
three values) **after** the term's own `compute`, which is where the operator
writes -- so a pad that is plugged in and nudged does not drive a scripted
term, and the term's own bookkeeping (metrics, resample timers) still runs.
"""
import torch
@@ -79,8 +74,8 @@ def script_commands(env, script) -> list[str]:
term = env.command_manager.get_term(name)
except KeyError:
raise ValueError(f"the task has no command term {name!r} to script") from None
if not hasattr(term, "posture_command") and not hasattr(term, "vel_command_b"):
raise ValueError(f"command term {name!r} is neither a velocity nor a posture "
if not hasattr(term, "vel_command_b"):
raise ValueError(f"command term {name!r} is not a velocity "
"command; a script cannot drive it")
_install(term, name, script, env, origin, step_dt, torch)
return names
@@ -93,18 +88,6 @@ def _install(term, name, script, env, origin, step_dt, torch) -> None:
compute(dt, env_ids)
t = (env.common_step_counter - origin) * step_dt
values = list(script(t)[name])
if hasattr(term, "posture_command"):
rest = term.cfg.neutral_height
height = values[3]
if isinstance(height, tuple):
values[3] = rest + (height[0] - rest) * height[1]
elif math.isnan(height):
values[3] = rest
term.posture_command[:] = torch.tensor(
values, device=term.device, dtype=torch.float32
)
term.hold_to_band()
return
columns = term.command.shape[1]
if len(values) != columns:
raise ValueError(f"a script of {len(values)} values for {name!r}, a command of "
@@ -140,8 +123,7 @@ def configure_velocity_replay(env_cfg, training_cfg, checkpoint: dict,
if ladder is not None:
params = ladder.params or {}
fractions, ceilings = params.get("fractions"), params.get("ceilings")
levels, angles = params.get("levels"), params.get("ang_levels")
level_count = len(fractions) if fractions else len(levels or ())
level_count = len(fractions) if fractions else 0
infos = checkpoint.get("infos") or {}
curriculum = infos.get("curriculum") or {}
saved = curriculum.get("command") or {}
@@ -150,9 +132,6 @@ def configure_velocity_replay(env_cfg, training_cfg, checkpoint: dict,
raise ValueError("checkpoint has no valid saved command curriculum level")
if fractions and ceilings and len(ceilings) == 3:
x, y, yaw = (float(value) * float(fractions[level]) for value in ceilings)
elif levels and angles and len(levels) == len(angles):
x = y = float(levels[level])
yaw = float(angles[level])
else:
raise ValueError("unsupported command curriculum: no valid command range ladder")
if not all(math.isfinite(value) for value in (x, y, yaw)) or x <= 0 or y < 0 or yaw <= 0:
+5 -5
View File
@@ -14,8 +14,8 @@ file runs during `import scenes`, and `--list` has to stay usable on a machine
without the simulation dependencies. `registry.load` imports the module.
`--scene` also takes a **path** to an imported `kk-scene-package/1` or `/2` --
a directory, a `.zip` or a `.map` that scene-generator, kingkong_design's map
library or this repository's own `scenes/tools/export_web_scene.py` wrote.
a directory, a `.zip` or a `.map` written by an external scene generator or this
repository's own `scenes/tools/export_web_scene.py`.
`scripts/play.py` accepts one and `scripts/train.py` refuses it;
`scenes/package.py` says why.
@@ -129,9 +129,9 @@ register(
description="**changes the ground**: generated slopes, stairs and rough surface",
tags=("terrain",),
# A 10 x 7 grid of difficulty tiles with a flat control column, sized from
# this robot's foot-lift height. An instrument for the curriculum to move
# a robot through, not a place. Stairs worth walking on for fun would be a
# new scene, not this one with its levels shipped.
# explicit nominal terrain parameters. An instrument for the curriculum to
# move a robot through, not a place. Stairs worth walking on for fun would
# be a new scene, not this one with its levels shipped.
use="training",
)
+1 -1
View File
@@ -29,7 +29,7 @@ The sky is a **cube map** rather than a builtin gradient, because a builtin one
runs from zenith to horizon and nothing else -- it cannot be warm on one side of
the compass and cold on the other, which is most of what makes a low sun read as
a low sun rather than as an orange filter over the whole world. The six faces are
generated by `assets/scenes/beach/tools/make_skybox.py`, which draws the
generated by `tools/make_skybox.py`, which draws the
sun's disc into them as well, so the sun is where the light says it is rather
than merely implied. That file holds the sun direction and **it has to stay the
negation of the light's `dir` below**: disagreeing puts the bright part of the sky
+9 -10
View File
@@ -5,11 +5,11 @@ another simulator can import, this one reads one somebody else wrote. The format
is the same in both directions, which is the point -- a room exported by
scene-generator and a pitch exported from here are the same kind of file.
python scripts/play.py --task example_robot.flat --scene out/bedroom.scene
python scripts/play.py --task example_robot.flat --scene out/bedroom.scene.zip
python scripts/play.py --task example_robot.flat --scene library/maps/bedroom.map
python scripts/play.py --task go1_example --scene out/bedroom.scene
python scripts/play.py --task go1_example --scene out/bedroom.scene.zip
python scripts/play.py --task go1_example --scene library/maps/bedroom.map
`/2` is what kingkong_design's map library is written in: the `/1` world, plus
`/2` is what the map library format is written in: the `/1` world, plus
the robot the map was authored around (`robot/`) and a thumbnail (`preview/`).
Both are verified like every other file and neither is loaded -- the robot here
is the task's own, the one the policy was trained on -- and `spawn` becomes
@@ -56,7 +56,7 @@ heading in **degrees** -- while the robot here starts where its task puts it, at
the environment origin facing +X. So the world is attached in a frame that moves
the spawn point to the origin and turns its heading onto +X, and the robot's
initial state is left alone. Ignoring `spawn` is not a small offset: measured on
kingkong_design's 13 maps (c655914), 6 put it away from the origin, and a robot at
13 reference maps (c655914), 6 put it away from the origin, and a robot at
the origin instead stands in a shelf (shelf-maze: 0.82 m of shelf within 0.25 m
of it), on a 0.7 m ramp (switchback-slopes) or in bedroom furniture (0.45 m).
@@ -70,8 +70,7 @@ and shelf-maze (-0.03 m, 60%) are buried the same way.
It is not enough to delete the task's plane. Every robot task's
`feet_ground_contact` sensor counts contacts with the **body** named `terrain`,
so a foot on anything that lives elsewhere reads as a foot in the air -- and
`example_robot.ref_free_jump` decides take-off and landing from that sensor. So every
so a foot on anything that lives elsewhere reads as a foot in the air. So every
geom of the package that collides and does not move -- the ground, and equally
a start platform, a bridge deck, a ramp or a table top -- is rebuilt inside that
body (`_Terrain`), the ground under the name `terrain` so that everything that
@@ -96,7 +95,7 @@ from .registry import Scene
__all__ = ["PackageError", "ScenePackage", "is_package_path", "load_package", "read_package"]
#: The versions this importer reads. An unknown one is refused rather than read
#: as the nearest known one: kingkong_design's contract says a consumer that
#: as the nearest known one: the package contract says a consumer that
#: does not know a version must reject it.
SCHEMAS = ("kk-scene-package/1", "kk-scene-package/2")
MANIFEST = "scene-package.json"
@@ -109,7 +108,7 @@ SUFFIX = ".map"
#: collide on base names, and MuJoCo's asset lookup falls back to the base name.
PLATFORM_DIR = "platforms/"
#: What `/2` adds beside the world, kept out of the shared section for the same
#: reason as `PLATFORM_DIR`: every map in kingkong_design's library carries both
#: reason as `PLATFORM_DIR`: every `/2` map carries both
#: `preview/preview.png` and `robot/preview/preview.png`, and the robot's meshes
#: are free to share a base name with the world's. Only for `/2`, where the
#: names mean this -- in a `/1` package `robot/` would be an ordinary directory.
@@ -762,7 +761,7 @@ def _entities(package: ScenePackage) -> dict[str, Any]:
"""The props that are their own file, as mjlab entities.
A prop carrying a `file` is the exporter saying it belongs **beside a robot**
rather than in the room: kk-rl-mjlab writes its football that way because it
rather than in the room: `mjrl-lab` writes its football that way because it
places one per environment at that environment's origin. Rebuilding it as an
entity is what makes the round trip a round trip -- exported from here,
imported back, and placed the same way.
+1 -2
View File
@@ -199,8 +199,7 @@ def scene(*, foot_bodies=()) -> Scene:
variable, and if it also changed the lighting then "the robot walks
differently here" would have two candidate explanations and no way to
separate them by looking. Sharing the look makes `--scene soft` against no
scene at all a one-variable comparison, in the same way `example_robot.flat` is a
one-variable control for two of the gait tasks.
scene at all a clean one-variable comparison.
The consequence to keep in mind: **the two are indistinguishable in a
screenshot.** A frame from this scene and a frame from `default` differ only
+8 -11
View File
@@ -213,11 +213,10 @@ FEATURES = "web"
#:
#: **Not only the crate's directory, either.** This was `Cargo.toml`,
#: `Cargo.lock` and `src/` until 2026-09-28, and the controller was also built
#: from files outside them: `build.rs`, which compiles in every task's deploy
#: hook -- so a commit that changed only `tasks/example_robot/deploy/lib.rs`
#: shipped a different arm under the previous commit's name, and an uncommitted
#: one without `-dirty` -- the dictionary `src/vocabulary.rs` includes, the IDL
#: the board's bus is generated from, and the NPU header `vendor/` holds.
#: from files outside them: `build.rs`, which compiles in optional task deploy
#: hooks (`tasks/**/deploy/lib.rs`), the dictionary `src/vocabulary.rs`
#: includes, the IDL the board's bus is generated from, and the NPU header
#: `vendor/` holds.
#: `tests/test_bundle.py` holds this list to what rustc and `build.rs` actually
#: read.
SOURCES = (
@@ -963,9 +962,8 @@ def write_reference(out: Path, extension: Path | None,
# The mode the cascade runs with nobody touching anything -- the one these
# frames converge on and infer in -- rather than the first mode by name,
# whose home may be another policy's entirely: `robot`'s `claw_left` sorts
# first and carries an arm 1.6 rad from the walking stance, so the frames
# converged on a pose the warm start never reaches and not one inferred.
# whose home pose may belong to another policy entirely, so the frames
# would converge on a pose the warm start never reaches.
import tomllib
cfg = tomllib.loads((out / "controller.toml").read_text("utf-8")).get("fsm", {})
@@ -1507,8 +1505,7 @@ def assemble(out: Path, modes: dict[str, Path], fsm_path: Path | None, meta: dic
if name.endswith(f"/{BOARD_BINARY}"):
(out / name).chmod(0o755)
# One copy of a model per export directory. `claw_left` and `claw_right`
# are one export carried on two sides, and shipped them twice.
# One copy of a model per export directory when two modes share an export.
stored: dict[Path, dict[str, str]] = {}
listed: dict[str, dict] = {}
unconverted: list[str] = []
@@ -2074,7 +2071,7 @@ def validate_app(out: Path) -> None:
#: be held against the one shipped last week.
ZIP_EPOCH = (1980, 1, 1, 0, 0, 0)
#: What a bundle's archive is called: `robot/` travels as `example_robot.app`.
#: What a bundle's archive is called: `<bundle_id>/` travels as `<bundle_id>.app`.
#:
#: The bytes are an ordinary zip, and any zip reader opens one. The name says
#: what the file is rather than how it is packed, as `.jar` does for a zip of
+11 -12
View File
@@ -11,10 +11,10 @@ choices for both. The backend comes from `--backend` / `--device`, or is
auto-detected, exactly as in train.
The environment is built in **replay mode** (`play=True`): external disturbances
are off and episodes run on rather than timing out (the one-shot jumps keep
theirs, so a replay loops whole attempts), so what you see is the policy rather
than the randomisation. Observation noise is the exception: `--obs-noise`, on by
default, puts training's back, because a clean replay flatters the policy.
are off and episodes run on rather than timing out, so what you see is the
policy rather than the randomisation. Observation noise is the exception:
`--obs-noise`, on by default, puts training's back, because a clean replay
flatters the policy.
A replay is **one environment** unless `--num_envs` or `MJRL_PLAY_NUM_ENVS` says
otherwise. `MJRL_NUM_ENVS` is training's batch size, and play does not read it.
@@ -43,14 +43,13 @@ without a display needs ``MUJOCO_GL=egl`` set before Python starts):
python scripts/play.py --checkpoint <path>/model_N.pt --headless \
--steps 500 --video replay.mp4 --video-fps 30
**It is the one MP4 recorder** (`mjrl/viewer/video.py`): the README clips, the
dance export and the Colab notebook all run this command rather than drawing for
themselves. The camera is placed from the robot's first frame (`--video-azimuth`,
`--video-elevation`, `--no-video-follow`), `--stop-on-done` records one attempt
of a one-shot motion rather than looping it, and `--command-script` hands the
command terms a script of time where the README clips need a walk that starts and
a posture that changes -- written where the operator writes, so the pad does not
drive a scripted term.
**It is the one MP4 recorder** (`mjrl/viewer/video.py`): evaluation clips and
the Colab notebook all run this command rather than drawing for themselves. The
camera is placed from the robot's first frame (`--video-azimuth`,
`--video-elevation`, `--no-video-follow`), `--stop-on-done` stops when an
episode terminates, and `--command-script` hands the command terms a script of
time -- written where the operator writes, so a connected pad does not drive a
scripted term.
"""
from __future__ import annotations
+1 -2
View File
@@ -13,8 +13,7 @@ from pathlib import Path
#: The repository root. This file lives in `tasks/`, hence one level up.
REPO_ROOT: Path = Path(__file__).resolve().parents[1]
#: The model asset root. One subdirectory per asset, each with its own `tools/`
#: for generation and calibration scripts.
#: The model asset root. One subdirectory per robot asset.
ASSETS_DIR: Path = REPO_ROOT / "assets"
#: The training log root directory name. Relative to the **current working
+2 -2
View File
@@ -283,12 +283,12 @@ def test_usage_doc_matches_the_code() -> None:
for name in ("def register(", "def load_env_cfg(", "def load_agent_cfg("):
assert name in registry, f"{name}, mentioned in USAGE, is not in the registry"
# The .env keys in the manual must match the repository's .env
# The .env keys in the manual must match the repository's .env.example
import re
doc_keys = set(re.findall(r"^(MJRL_[A-Z_]+)=", usage, re.M))
env_keys = set(
re.findall(r"^(MJRL_[A-Z_]+)=", (REPO / ".env").read_text(encoding="utf-8"), re.M)
re.findall(r"^(MJRL_[A-Z_]+)=", (REPO / ".env.example").read_text(encoding="utf-8"), re.M)
)
assert doc_keys == env_keys, (
f"USAGE and .env keys disagree.\nExtra in the document: "
+1 -1
View File
@@ -220,7 +220,7 @@ def velocity_replay_configs(monkeypatch):
)
training = SimpleNamespace(commands={"twist": command}, curriculum={
"command": SimpleNamespace(params={
"levels": (.25, .35, .5, .5), "ang_levels": (.3, .5, .75, .75),
"fractions": (.5, .7, 1.0, 1.0), "ceilings": (.5, .5, .6),
}),
})
replay = SimpleNamespace(commands={"twist": copy.deepcopy(command)})
+1 -1
View File
@@ -222,7 +222,7 @@ def test_scene_selection_is_wired_to_the_cli_and_env() -> None:
cli = (REPO / "scripts" / "_cli.py").read_text(encoding="utf-8")
assert '_env("MJRL_SCENE")' in cli
assert "def apply_scene(" in cli
assert "MJRL_SCENE=" in (REPO / ".env").read_text(encoding="utf-8")
assert "MJRL_SCENE=" in (REPO / ".env.example").read_text(encoding="utf-8")
# Only where it can do something. export.py writes an ONNX file and a
# contract, and nothing a scene changes reaches either; it took --scene from
+1 -1
View File
@@ -497,7 +497,7 @@ def test_strip_visual_config_is_wired() -> None:
cli = read(REPO / "scripts" / "_cli.py")
assert "MJRL_STRIP_VISUAL" in cli
assert "strip_visual=" in cli, "the resolve() call does not pass it"
env_keys = (REPO / ".env").read_text(encoding="utf-8")
env_keys = (REPO / ".env.example").read_text(encoding="utf-8")
assert "MJRL_STRIP_VISUAL=" in env_keys
+1 -1
View File
@@ -118,7 +118,7 @@ def test_an_ancient_card_is_referred_upward_rather_than_guessed() -> None:
def test_the_repo_is_found_by_content_not_by_name() -> None:
"""The checkout is routinely named something else.
`kk-rl-mjlab` on the training machine, a hashed path inside `.claude/
`mjrl-lab` on the training machine, or a hashed path inside `.claude/
worktrees/` here. Matching on the directory name would fail on exactly the
machines this is needed for.
"""
+1 -1
View File
@@ -398,7 +398,7 @@ def test_config_is_actually_wired() -> None:
# to contain `_env(`, so the looser check passed either way.)
assert '_bool_env("MJRL_TENSORBOARD"' in cli
assert '_int_env("MJRL_TB_PORT"' in cli
env = (REPO / ".env").read_text(encoding="utf-8")
env = (REPO / ".env.example").read_text(encoding="utf-8")
assert "MJRL_TENSORBOARD=" in env and "MJRL_TB_PORT=" in env
train = (REPO / "scripts" / "train.py").read_text(encoding="utf-8")
+2 -2
View File
@@ -7,9 +7,9 @@
A scene that generates cube textures declares them in a module-level
`CUBEMAPS = {prefix: colour_fn}` beside its `scene()` factory, where each
`colour_fn(dirs) -> rgb` is a function of direction; this writes the six faces of
each into `assets/scenes/<id>/`. The convention is that the skybox is called
each into `scenes/assets/<id>/`. The convention is that the skybox is called
`sky`; a football's panels are just another function of direction. Colours are code and live with the scene; the PNGs are
data and live under `assets/`, which is the same split as models.
data and live under `scenes/assets/`, which is the same split as models.
Re-run it after changing a sky's colours, or the scene will keep loading the
faces that were written last time -- they are committed, not built on demand.