docs: add AI agent workflow guide and clean up residual single-robot references
This commit is contained in:
@@ -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",
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
|
||||
@@ -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
@@ -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
@@ -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
|
||||
|
||||
@@ -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
@@ -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):目录结构与仓库检查项。
|
||||
|
||||
@@ -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
|
||||
```
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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
@@ -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.
|
||||
|
||||
@@ -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
|
||||
|
||||
Vendored
+2
-2
@@ -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
@@ -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
@@ -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`
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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` 查看本地注册项。
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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"]
|
||||
|
||||
@@ -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`) |
|
||||
|
||||
@@ -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
@@ -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
|
||||
|
||||
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
|
||||
|
||||
@@ -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: "
|
||||
|
||||
@@ -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)})
|
||||
|
||||
@@ -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
@@ -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
|
||||
|
||||
|
||||
|
||||
@@ -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.
|
||||
"""
|
||||
|
||||
@@ -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")
|
||||
|
||||
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user