66Leslie · Aug 27, 2026 · Aug 28, 2026
diff --git a/.gitignore b/.gitignore
@@ -14,6 +14,11 @@ logs/
 wandb/
 *.pt
 *.onnx
+*.pkl
+*.pickle
+*.npz
+src/mjlab_playground/asset_zoo/motions/retargeted/*
+!src/mjlab_playground/asset_zoo/motions/retargeted/README.md
 
 scripts/
 

diff --git a/NOTICE b/NOTICE
@@ -0,0 +1,19 @@
+mjlab_playground Booster locomotion extensions
+Copyright 2026 66Leslie and contributors
+
+This product includes software developed by the mjlab_playground contributors:
+https://github.com/mujocolab/mjlab_playground
+
+The Booster T1 velocity task contains adapted and modified work from
+KaydenKnapik/BoosterT1mjlab:
+https://github.com/KaydenKnapik/BoosterT1mjlab
+
+Booster K1 asset and configuration work references NishB17/MJLabModified:
+https://github.com/NishB17/MJLabModified
+
+Parts of the competition-compatible Booster K1 MJCF lineage reference
+RCSSServerMJ. Its MIT license is reproduced in
+third_party_licenses/RCSSServerMJ-MIT.txt.
+
+Motion datasets and locally generated retargeted files are not included in, and
+are not relicensed by, this distribution.
diff --git a/README.md b/README.md
@@ -1,45 +1,113 @@
-# mjlab playground
+# mjlab playground: Booster locomotion tasks
+
+This fork extends [mujocolab/mjlab_playground](https://github.com/mujocolab/mjlab_playground) with Booster T1/K1 locomotion tasks while keeping the upstream task-registration and configuration style.
+
+## Demo
+
+### Booster T1 velocity tracking
+
+![Booster T1 velocity tracking](docs/media/t1_velocity_tracking.gif)
+
+The dark-blue arrow is the commanded linear velocity and the cyan arrow is the
+measured linear velocity. Dark/light green show commanded/measured yaw motion.
+This five-second clip was recorded with MJLab's built-in `play --video` support
+using the compatible `2026-04-15_10-04-41/model_10100.pt` checkpoint. The later
+`2026-04-27_10-05-04/model_13900.pt` run has a known low-response command region
+and is intentionally not used for this demo.
+
+## Repository layout
+
+```text
+src/mjlab_playground/
+├── amp/                         # Shared AMP algorithm, runner, observations, loaders
+├── asset_zoo/robots/            # Robot-specific MJCF and constants
+│   ├── booster_t1/
+│   └── booster_k1/
+└── tasks/                       # Environment/task implementations
+    ├── common/                  # Small helpers shared by task families
+    ├── getup/
+    │   └── config/{go1,k1,t1}/
+    ├── velocity/
+    │   └── config/t1/
+    ├── tracking/
+    │   └── config/t1/
+    └── target_location_amp/
+        └── config/{k1,t1}/
+```
 
-A collection of tasks built with [mjlab](https://github.com/mujocolab/mjlab), starting with ports from [MuJoCo Playground](https://playground.mujoco.org/).
+Task-independent AMP code lives in `amp/`; target-location commands, rewards, termination rules and robot-specific configuration stay in `tasks/target_location_amp/`. This avoids coupling the AMP implementation to a single task and leaves a clear place for future robots.
 
 ## Tasks
 
-| Task ID | Robot | Description | Preview |
-|---------|-------|-------------|---------|
-| **Getup** | | | |
-| `Mjlab-Getup-Flat-Unitree-Go1` | Unitree Go1 | Fall recovery on flat terrain | <img src="https://raw.githubusercontent.com/mujocolab/mjlab_playground/assets/go1_getup_teaser.gif" width="200"/> |
-| `Mjlab-Getup-Flat-Booster-T1` | Booster T1 | Fall recovery on flat terrain | <img src="https://raw.githubusercontent.com/mujocolab/mjlab_playground/assets/t1_getup_teaser.gif" width="200"/> |
-
-## Getting Started
+| Task ID | Robot | Description |
+|---|---|---|
+| `Mjlab-Getup-Flat-Unitree-Go1` | Unitree Go1 | Upstream flat-ground get-up |
+| `Mjlab-Getup-Flat-Booster-T1` | Booster T1 | Upstream flat-ground get-up |
+| `Mjlab-Getup-Flat-Booster-K1` | Booster K1 | Flat-ground get-up |
+| `Mjlab-Velocity-Flat-Booster-T1` | Booster T1 | Flat-ground velocity tracking |
+| `Mjlab-Tracking-Flat-Booster-T1` | Booster T1 | Reference-motion tracking |
+| `Mjlab-TargetLocationAmp-Flat-Booster-K1` | Booster K1 | Target-location locomotion with AMP |
+| `Mjlab-TargetLocationAmp-Flat-Booster-T1` | Booster T1 | Target-location locomotion with AMP |
+
+There is one public Booster velocity task: `Mjlab-Velocity-Flat-Booster-T1`.
+Rough-terrain, raw-observation, and yaw-only builders remain implementation
+details rather than separately advertised environments. There is currently no
+K1 tracking task in this fork. The two additional T1 target-location task IDs
+ending in `CompetitionFoot` and `CompetitionCollision` are deployment-oriented
+contact/collision variants.
+
+## Getting started
 
 ```bash
-git clone https://github.com/mujocolab/mjlab_playground.git && cd mjlab_playground
+git clone https://github.com/66Leslie/mjlab_playground.git
+cd mjlab_playground
 uv sync
 ```
 
-Train a task:
+List registered tasks:
+
+```bash
+uv run list-envs
+```
+
+Train and play a task:
 
 ```bash
-uv run train <task-id> --num_envs 4096
+uv run train Mjlab-Velocity-Flat-Booster-T1 --env.scene.num-envs 4096
+uv run play Mjlab-Velocity-Flat-Booster-T1
 ```
 
-Play back a trained policy:
+Record a short clip from a local checkpoint:
 
 ```bash
-uv run play <task-id>
+uv run play Mjlab-Velocity-Flat-Booster-T1 \
+  --checkpoint-file /path/to/model_10100.pt \
+  --num-envs 1 --video True --video-length 250
 ```
 
-### Getup training
+The tracking and AMP tasks require separately prepared motion data. See [Motion data](docs/motion_data.md) before running them.
+
+## Motion-data policy
+
+Retargeted files are generated artifacts, but their redistribution rights still depend on the original motion dataset. Consequently, this repository does **not** include LAFAN1-, AMASS-, or BMLrub-derived `.npz`, `.pkl`, or `.pickle` files. Retarget them locally from data you are licensed to use, then point the task to the local output. The expected paths, environment variables and pickle schema are documented in [docs/motion_data.md](docs/motion_data.md).
+
+## Sources and attribution
+
+- Base repository: [mujocolab/mjlab_playground](https://github.com/mujocolab/mjlab_playground), Apache-2.0.
+- The T1 velocity task is adapted from [KaydenKnapik/BoosterT1mjlab](https://github.com/KaydenKnapik/BoosterT1mjlab), Apache-2.0, and has been substantially modified for this repository layout and current MJLab APIs.
+- K1 MJLab asset/configuration work references [NishB17/MJLabModified](https://github.com/NishB17/MJLabModified), Apache-2.0. The competition-compatible K1 MJCF lineage also references [RCSSServerMJ](https://github.com/YiranWang2004/RCSSServerMJ), MIT.
+- The shared AMP implementation was reorganized for this fork. [ccrpRepo/AMP_mjlab](https://github.com/ccrpRepo/AMP_mjlab) was consulted for high-level directory organization only; no source code or motion files were copied from it because the repository does not currently publish a root license.
+- Motion retargeting is compatible with [YanjieZe/GMR](https://github.com/YanjieZe/GMR), MIT. GMR's software license does not replace the license of the source motion dataset.
+
+See [NOTICE](NOTICE) and [THIRD_PARTY.md](THIRD_PARTY.md) for details.
 
-On a single NVIDIA 5090, the Go1 getup task converges in ~2 minutes and T1 in ~8 minutes, but we continue training with a curriculum that progressively tightens action rate, joint velocity, and power penalties to produce smoother, safer policies.
+## Checkpoints
 
-<p align="center">
-  <img src="https://raw.githubusercontent.com/mujocolab/mjlab_playground/assets/training_curves.png" width="80%"/>
-</p>
+Checkpoint files are intentionally ignored by Git. Publish reviewed weights as versioned GitHub Release assets instead of committing them to repository history. Each released checkpoint should identify the task ID, repository commit, complete training configuration, motion-data provenance, training command, observation/action contract and weight license. See [docs/checkpoints.md](docs/checkpoints.md).
 
 ## Citation
 
-If you use this repository in your research, consider citing mjlab:
+If you use this repository in research, consider citing MJLab:
 
 ```bibtex
 @misc{zakka2026mjlablightweightframeworkgpuaccelerated,
@@ -55,4 +123,4 @@ If you use this repository in your research, consider citing mjlab:
 
 ## License
 
-This repository is released under an [Apache-2.0 License](LICENSE).
+Code in this repository is released under the [Apache-2.0 License](LICENSE), except where a bundled third-party component is identified with its own license. Motion datasets and locally generated retargeted files are not covered by this repository's Apache-2.0 license.
diff --git a/THIRD_PARTY.md b/THIRD_PARTY.md
@@ -0,0 +1,12 @@
+# Third-party components
+
+| Component | Use in this repository | License |
+|---|---|---|
+| [mujocolab/mjlab_playground](https://github.com/mujocolab/mjlab_playground) | Base repository, get-up tasks, package/CLI style | Apache-2.0 |
+| [KaydenKnapik/BoosterT1mjlab](https://github.com/KaydenKnapik/BoosterT1mjlab) | Starting point for the T1 velocity task; adapted and modified | Apache-2.0 |
+| [NishB17/MJLabModified](https://github.com/NishB17/MJLabModified) | Reference/source lineage for Booster K1 MJLab assets and configuration | Apache-2.0 |
+| [RCSSServerMJ](https://github.com/YiranWang2004/RCSSServerMJ) | Competition-compatible Booster K1 MJCF lineage | MIT; bundled text in `third_party_licenses/RCSSServerMJ-MIT.txt` |
+| [YanjieZe/GMR](https://github.com/YanjieZe/GMR) | Recommended local motion-retargeting tool; not vendored | MIT |
+| [ccrpRepo/AMP_mjlab](https://github.com/ccrpRepo/AMP_mjlab) | Directory organization consulted only; no code or data copied | No root license found as of 2026-08-28 |
+
+The licenses above apply to software and assets supplied by those projects. They do not grant rights to separately downloaded motion datasets. See [docs/motion_data.md](docs/motion_data.md).
diff --git a/docs/checkpoints.md b/docs/checkpoints.md
@@ -0,0 +1,40 @@
+# Checkpoint releases
+
+Model checkpoints may be released separately from the source repository after a provenance and reproducibility review. The `.gitignore` excludes `*.pt` and `*.onnx`, so accidental weight commits—and another large-file push failure—are less likely.
+
+## Release layout
+
+Use a versioned GitHub Release rather than storing binary weights in Git history:
+
+```text
+<task-id>-v<version>/
+├── model.pt
+├── policy.onnx                 # optional deployment export
+├── env_cfg.yaml
+├── agent_cfg.yaml
+├── model_card.md
+└── SHA256SUMS
+```
+
+The release tag should point at the exact source commit used for training.
+
+## Required model-card fields
+
+Every checkpoint release should state:
+
+1. Task ID and robot model/version.
+2. Source commit and clean/dirty training-tree state.
+3. Exact `uv run train ...` command and random seed.
+4. Environment and agent configuration, including any command curriculum.
+5. Observation names/order, action names/order, control frequency and action scaling.
+6. Motion data: dataset, clip IDs, license URLs, retargeting tool/commit and whether the data itself is redistributed.
+7. Training duration, hardware and headline evaluation metrics.
+8. Known limitations and the tested deployment/runtime contract.
+9. License applied to the checkpoint and any attribution requirements.
+10. SHA-256 hashes for every binary artifact.
+
+## Motion-trained weights
+
+A checkpoint does not contain the original `.npz` or `.pkl` file, but it is still an output of a motion-trained pipeline. Before releasing one, review the source dataset's terms for restrictions on trained models, derived outputs, commercial use and attribution. If the terms are unclear, release the source/configuration first and keep the checkpoint private until permission is confirmed.
+
+Do not claim that the repository's Apache-2.0 license automatically covers a checkpoint trained from third-party data. State the checkpoint license explicitly in its release notes.
diff --git a/docs/media/t1_velocity_tracking.gif b/docs/media/t1_velocity_tracking.gif
diff --git a/docs/motion_data.md b/docs/motion_data.md
@@ -0,0 +1,91 @@
+# Motion data
+
+Motion data is deliberately kept outside Git. Both `.npz` tracking files and GMR-style `.pkl`/`.pickle` AMP files are ignored so a local licensed dataset cannot be committed accidentally.
+
+## Why retargeted files are not committed
+
+Retargeting changes a motion's robot representation; it does not automatically erase the source dataset's copyright or license conditions.
+
+- [LAFAN1](https://github.com/ubisoft/ubisoft-laforge-animation-dataset/blob/master/LICENSE) is distributed under CC BY-NC-ND 4.0. Retargeting is reasonably treated as creating adapted material, which that license does not permit users to share.
+- [AMASS](https://amass.is.tue.mpg.de/license.html) access is subject to its own terms, and AMASS aggregates datasets with additional source-specific conditions. BMLrub-derived clips should therefore not be published here without explicit redistribution permission.
+- [GMR](https://github.com/YanjieZe/GMR) is MIT-licensed software, but its license covers the retargeting code—not the motion inputs or the resulting adapted dataset.
+
+This is a conservative repository policy, not legal advice. A motion file may be published only when its complete provenance and redistribution rights are documented.
+
+## Recommended local layout
+
+Set one root for local retargeted data:
+
+```bash
+export MJLAB_PLAYGROUND_MOTION_ROOT=/absolute/path/to/mjlab_motions
+```
+
+Arrange locomotion files as follows:
+
+```text
+$MJLAB_PLAYGROUND_MOTION_ROOT/
+└── lafan/
+    ├── k1_lafan1_fk_pkl/
+    │   ├── walk1_subject5.pkl
+    │   ├── run1_subject5.pkl
+    │   └── sprint1_subject4.pkl
+    └── booster_t1_lafan1_locomotion/
+        ├── walk....pkl
+        ├── run....pkl
+        └── sprint....pkl
+```
+
+The K1 AMP loader selects `walk*.pkl`, `run*.pkl`, and `sprint*.pkl`. The T1 loader also accepts names prefixed by `lafan1_`.
+
+The T1 locomotion directory can be overridden independently:
+
+```bash
+export MJLAB_PLAYGROUND_T1_LOCOMOTION_MOTION_DIR=/absolute/path/to/t1_locomotion_pkls
+```
+
+## AMP pickle schema
+
+Each `.pkl`/`.pickle` file must contain at least:
+
+| Key | Shape/type | Meaning |
+|---|---|---|
+| `dof_pos` | `[T, num_dof]` float array | Joint positions in the robot's configured joint order |
+| `root_pos` | `[T, 3]` float array | Root position |
+| `root_rot` | `[T, 4]` float array | Root quaternion in `xyzw` order |
+| `local_body_pos` | `[T, B, 3]` float array | GMR forward-kinematics body positions |
+| `link_body_list` | sequence of `B` names | Names corresponding to `local_body_pos` |
+| `fps` | number | Source frame rate; defaults to 30 if absent |
+
+For target-location AMP, the configured `expected_dof` is 22 for K1 and 23 for T1. The required key-body names are defined in `src/mjlab_playground/amp/amp_schema.py`.
+
+## T1 reference tracking
+
+Reference tracking uses the MJLab `.motion.npz` format expected by `MotionCommandCfg`. Point directly to a locally generated file:
+
+```bash
+export MJLAB_TRACKING_MOTION_FILE=/absolute/path/to/reference.booster_t1_23dof.motion.npz
+uv run play Mjlab-Tracking-Flat-Booster-T1
+```
+
+Without that variable, the code checks this intentionally untracked package-relative placeholder:
+
+```text
+src/mjlab_playground/asset_zoo/motions/retargeted/
+└── tracking/booster_t1_23dof/
+    └── 0026_kicking2_stageii.booster_t1_23dof.motion.npz
+```
+
+The example filename documents the expected location only; the file is not distributed.
+
+## Before publishing a motion
+
+Record all of the following in a data manifest before considering a motion artifact for release:
+
+1. Original dataset and exact clip identifier.
+2. Original dataset version and license URL.
+3. Whether derivative/adapted material may be redistributed.
+4. Retargeting tool and commit.
+5. Robot model and joint order.
+6. Any attribution, noncommercial, or share-alike requirements.
+
+If item 3 is unclear or negative, keep the file local and publish only the conversion instructions.
diff --git a/pyproject.toml b/pyproject.toml
@@ -3,7 +3,7 @@ name = "mjlab-playground"
 version = "0.1.0"
 description = "Extra tasks for mjlab"
 readme = "README.md"
-requires-python = ">=3.13"
+requires-python = ">=3.13,<3.14"
 dependencies = [
     "mjlab[cu128]",
     "torch>=2.7.0,<2.10.0",
@@ -14,13 +14,11 @@ requires = ["uv_build>=0.8.18,<0.9.0"]
 build-backend = "uv_build"
 
 [tool.uv.sources]
-mjlab = { git = "https://github.com/mujocolab/mjlab", rev = "f7fdb163b590e980865e59a5633ff5e1143553bd" }
+mjlab = { git = "https://github.com/mujocolab/mjlab", rev = "9298ba5691858dec9f0fa7c53c0ffb453192da67" }
 warp-lang = { index = "nvidia", marker = "sys_platform != 'darwin'" }
 torch = [
   { index = "pytorch-cu128", marker = "sys_platform != 'darwin'" },
 ]
-mujoco = { index = "mujoco" }
-mujoco-warp = { git = "https://github.com/google-deepmind/mujoco_warp", rev = "875c4caf06d71b12b2036c327e7a07ce08a78b9a" }
 
 [[tool.uv.index]]
 url = "https://pypi.org/simple"
@@ -35,15 +33,6 @@ name = "pytorch-cu128"
 url = "https://download.pytorch.org/whl/cu128"
 explicit = true
 
-[[tool.uv.index]]
-name = "mujoco"
-url = "https://py.mujoco.org"
-explicit = true
-
-# The nightly index (py.mujoco.org) only has dev builds.
-[tool.uv]
-override-dependencies = ["mujoco>=3.6.0.dev0"]
-
 [tool.ruff]
 indent-width = 2
 src = ["src/mjlab_playground"]
@@ -54,6 +43,8 @@ select = ["E4", "E7", "E9", "F", "I", "B"]
 
 [tool.pyright]
 pythonVersion = "3.13"
+include = ["src"]
+exclude = ["tests", "typings"]
 ignore = ["./typings"]
 stubPath = "typings"
 reportWildcardImportFromLibrary = false

diff --git a/src/mjlab_playground/__init__.py b/src/mjlab_playground/__init__.py
@@ -1,4 +1,9 @@
 """A collection of tasks built on mjlab."""
 
-from mjlab_playground.getup.config.go1 import *  # noqa: F401, F403
-from mjlab_playground.getup.config.t1 import *  # noqa: F401, F403
+from mjlab_playground.tasks.getup.config.go1 import *  # noqa: F401, F403
+from mjlab_playground.tasks.getup.config.k1 import *  # noqa: F401, F403
+from mjlab_playground.tasks.getup.config.t1 import *  # noqa: F401, F403
+from mjlab_playground.tasks.target_location_amp.config.k1 import *  # noqa: F401, F403
+from mjlab_playground.tasks.target_location_amp.config.t1 import *  # noqa: F401, F403
+from mjlab_playground.tasks.tracking.config.t1 import *  # noqa: F401, F403
+from mjlab_playground.tasks.velocity.config.t1 import *  # noqa: F401, F403
diff --git a/src/mjlab_playground/amp/__init__.py b/src/mjlab_playground/amp/__init__.py
@@ -0,0 +1 @@
+"""Reusable adversarial motion-prior components."""
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		"""Reusable adversarial motion-prior components."""