mujocolab/mjlab

📦 Per-World Mesh Variants

• ```python
• VariantEntityCfg(
• variants={
• "cube": make_cube_spec,
• "sphere": make_sphere_spec,
• "bunny": make_bunny_spec,
• },
• assignment={"cube": 0.5, "sphere": 0.3, "bunny": 0.2},
• + 9 more

📦 BuiltinPdActuator

• `BuiltinPdActuator` provides native MuJoCo PD control with both position and velocity targets.
• `BuiltinPdActuator` is implemented as paired `<position>` and `<velocity>` actuators:
• ```text
• kp * (p_target - q) + kd * (v_target - qdot)
• ```
• `effort_limit` is enforced as a clamp on the summed PD force through `jnt_actfrcrange` or `tendon_actfrcrange`. `dr.pd_gains` and `dr.effort_limits` both support the new actuator.

🐛 Fixes

• Actuator command delay now applies to all targets. `IdealPdActuator` and `DcMotorActuator` use velocity and effort targets as well as position, and those targets were previously not delayed. Zero-reference setups are unaffected.
• Multi-node training seeds now use global `RANK` instead of `LOCAL_RANK`, so seeds do not repeat across nodes. Contribution by @bd-pdomanico.
• Reward entries written to `extras["log"]` are no longer dropped on reset. The log dict is cleared at the top of `step()` and `reset()`, before reward computation writes into it.
• `ContactSensor(global_frame=True)` now rotates contact-frame values with columns ordered `[normal, tangent, tangent2]`. The previous order projected normal force onto a tangent axis. Contribution by @bd-pdomanico.
• Rough-terrain offscreen videos no longer flicker when the terrain curriculum mutates `env_origins` on reset. The renderer now computes the neighboring robot set once and reuses it.
• `apply_body_impulse` no longer fires on the first step or immediately after every reset. Cooldown is sampled lazily on first use.

📋 Other Changes

• `ContactSensor.primary_names` exposes resolved primary names in per-contact tensor order, so contact-data columns can be mapped back to primaries.
• `DebugVisualizer.add_box` draws axis-oriented boxes in the native and Viser viewers.
• `train`, `play`, and `evaluate` now accept `--log-root` for routing logs to a scratch disk or shared mount. Contribution by @louislelay.
• `CameraSensorData.segmentation` now stores typed `(object_id, object_type)` pairs with shape `[B, H, W, 2]`, matching mujoco-warp's output. Contribution by @tkelestemur.
• `RayCaster` post-processing avoids CUDA syncs by replacing boolean-mask indexing with `masked_fill_` and a clamped-distance formulation of `hit_pos_w`. Contribution by @bd-pdomanico.
• Tracking evaluation now snapshots the reference before each step, raises on unknown end-effector body names, computes MPKPE against the global reference, re-anchors root-relative MPKPE to the robot root each step, and reports joint velocity error as per-joint RMS instead of an L2 norm.
• `Entity` now raises during construction if its spec contains more than one freejoint.
• Event helpers now share `resolve_env_ids`; `push_by_setting_velocity` and `apply_external_force_torque` accept `env_ids=None` for global-time interval terms.
• + 4 more

💥 Breaking Changes

• Remove `"multiccd"` from `MujocoCfg.enableflags`.
• `CameraSensorData.segmentation` changed from legacy `[B, H, W]` geom IDs to `[B, H, W, 2]` typed `(object_id, object_type)` pairs.

📦 Contributors

• First-time contributors: @CodingCatMountain, @paLeziart, @bd-pdomanico, @tkelestemur.
• Returning contributors: @rdeits, @louislelay, @omarrayyann, @saikishor, @XiangruiJiang.
• Full Changelog: https://github.com/mujocolab/mjlab/compare/v1.3.0...v1.4.0

📦 Physics engine bump

• mjlab 1.3.0 uses mujoco-warp 3.7.0.1 and mujoco 3.7.0.

📦 Viewer: Rebuilt on mjviser

• https://github.com/user-attachments/assets/b42b33a6-bdbf-4e08-b956-3569083073f3
• New panels and tabs:
• Reward bar panel showing horizontal bars for each reward term with a running mean over ~1 second
• W&B run tab for browsing recent runs and pulling checkpoints
• Checkpoints tab in play for hot-swapping checkpoints without restarting, with support for local directories and W&B runs
• Motion reference scrubber for tracking tasks
• Per-pixel segmentation camera data type for geom ID output alongside RGB and depth, with a new `Mjlab-Multi-Cube-Seg-Yam` task that uses it

📦 Terrain System, Revamped

• https://github.com/user-attachments/assets/32cf84e8-a398-497e-88ab-ecf2ae14fccb
• *A Go1 velocity policy trained on the new stair terrain*
• `RayCastSensor` itself was generalized: pass a tuple of `ObjRef` to `frame` for multi-frame, per-site raycasting, and use the new `RingPatternCfg` for concentric ring sampling around each frame.

📦 Actuator Configuration, Simplified

• Actuator delay is now configured inline on any `ActuatorCfg` subclass:
• ```python
• DelayedActuatorCfg(BuiltinPositionActuatorCfg(...), delay_min_lag=2, delay_max_lag=5)
• BuiltinPositionActuatorCfg(..., delay_min_lag=2, delay_max_lag=5)
• ```
• `DelayedActuator`, `DelayedActuatorCfg`, and `DelayedBuiltinActuatorGroup` are removed. Delay always applies to the actuator's `command_field` automatically, so `delay_target` is no longer needed.
• Two new behaviors on `ActuatorCfg`:
• `viscous_damping` for passive velocity proportional damping (`f = -b·v`), distinct from the PD derivative gain `damping` used by position and velocity actuators. Maps to `<joint damping>` for JOINT transmission and `<tendon damping>` for TENDON transmission.
• + 1 more

✨ New MDP Primitives

• Several additions to the manager and MDP APIs:
• `RecorderManager` for logging observations, actions, or arbitrary environment data during rollouts. Implement a `RecorderTerm` subclass and register it in the `recorders` dict on `ManagerBasedRlEnvCfg`. The manager provides `record_pre_reset`, `record_post_reset`, and `record_post_step` lifecycle hooks with no opinion on how data is stored.
• `termination_curriculum` for scheduling changes to termination term parameters during training, matching the existing `reward_curriculum` pattern. Both now share a single internal engine with init-time validation of stage ordering, field existence, and param keys.
• `MetricsTermCfg.reduce` field with a `"last"` option that reports the final step of the episode rather than the episode mean. Useful for binary success metrics.
• `RelativeJointPositionAction` for joint position control relative to the current configuration. The target is `current_pos + action * scale`, so a zero action holds the current configuration rather than commanding the default pose.
• `dr.pair_friction` for randomizing geom-pair friction overrides, with an `isotropic=True` option that mirrors the symmetric tangent and roll axes so single-axis randomization does not leave the paired axis stale.
• `ActionTermCfg.clip` for clamping processed actions after scale and offset.
• `qfrc_actuator` and `qfrc_external` generalized force accessors on `EntityData`. `qfrc_actuator` gives actuator forces in joint space (projected through the transmission); `qfrc_external` recovers the generalized force from body external wrenches (`xfrc_applied`).

📦 Also In This Release

• Mujoco 3.7.0 and mujoco-warp 3.7.0.1 are now the minimum supported versions
• Motion imitation documentation with preprocessing instructions, replacing the BeyondMimic link that produced incompatible NPZ files
• `margin`, `gap`, `solmix` fields on `CollisionCfg` for per geom contact parameter configuration
• `ManagerBasedRlEnvCfg.auto_reset` flag for custom training loops that need access to the true terminal state
• Top-level `--help` for `train` and `play` that points users at `list-envs` and `<TASK> --help`
• `list_envs` renamed to `list-envs` for consistency with other hyphenated entry points
• RNN model support in `RslRlModelCfg`
• NaN guard now captures mocap body poses, enabling full state reconstruction in the dump viewer for fixed-base entities
• + 4 more

💥 Breaking Changes

• `DelayedActuator`, `DelayedActuatorCfg`, `DelayedBuiltinActuatorGroup` are removed. Configure delay inline on any `ActuatorCfg` subclass.
• `delay_target` is removed. Delay always applies to the actuator's `command_field`.
• `XmlPositionActuatorCfg`, `XmlVelocityActuatorCfg`, `XmlMotorActuatorCfg`, `XmlMuscleActuatorCfg` are replaced by a single `XmlActuatorCfg`.
• `TerrainImporter` and `TerrainImporterCfg` aliases are removed. Use `TerrainEntity` and `TerrainEntityCfg`.
• `EntityData.generalized_force` is removed. Use `qfrc_actuator` or `qfrc_external`.
• `ActuatorCfg.armature` and `.frictionloss` default to `None` instead of `0.0`.
• `Entity.clear_state()` is deprecated. Use `Entity.reset()`.
• `out_of_terrain_bounds` is replaced with `terrain_edge_reached`.

🐛 Bug Fixes

• `SceneEntityCfg` names and IDs ordering mismatch with `preserve_order=False` (#876)
• ONNX export path resolution when a parent directory name contains `"model"` (#867)
• `export-scene` writing assets to the wrong location and allowing path traversal in asset keys (#858)
• `electrical_power_cost` now uses joint space forces, correct for actuators with non-unit gear ratios (#776)
• `create_velocity_actuator` no longer sets `ctrllimited=True` with `inheritrange=1.0`, which crashed on continuous joints such as wheels (#787)
• `write_root_com_velocity_to_sim` with tensor `env_ids` on floating base entities (#793)
• `dr.pseudo_inertia` 4 GB GPU memory overhead (#753)
• Contact force visualization for non-builtin actuators (#786)
• + 8 more

✨ New Contributors

• Thank you to @cjyyx, @omarrayyann, @gokulp01, @cmjang, @jsw7460, and @lzyang2000 for their first contributions to mjlab!
• Full Changelog: https://github.com/mujocolab/mjlab/compare/v1.2.0...v1.3.0

📦 Domain Randomization, Redesigned

• ```python
• import mjlab.envs.mdp.dr as dr
• dr.geom_friction(env, cfg, operation=dr.scale, distribution=dr.uniform, ranges=(0.8, 1.2))
• dr.pseudo_inertia(env, cfg, alpha_range=(-0.3, 0.3), d_range=(-0.3, 0.3))
• dr.mat_rgba(env, cfg, operation=dr.add, distribution=dr.gaussian, ranges=(-0.1, 0.1))
• ```

📦 Viewer Overhaul

• https://github.com/user-attachments/assets/345bde31-30b9-4466-8fe5-d5a54aad37e6
• New in both viewers:
• Single step mode to advance exactly one physics step while paused
• Error recovery that pauses and logs the traceback instead of crashing
• Force arrows that visualize `apply_body_impulse` events in real time
• Realtime factor displayed alongside FPS
• New in Viser:
• Velocity joystick for manual command override
• + 2 more

📦 Step Events and Body Impulses

• https://github.com/user-attachments/assets/5999a0b1-a874-43e4-843b-40abfbf4691b

📦 Also In This Release

• `export-scene` CLI to dump any task scene or asset zoo entity to a directory or zip for inspection and debugging
• `rsl-rl-lib` upgraded to 5.0.1 with automatic checkpoint migration for the new distribution config format
• Contact sensor history across decimation substeps for more reliable self collision and illegal contact detection
• Docker images published on every push to main
• `joint_torques_l2` now accepts `actuator_ids` for penalizing a subset of actuators

💥 Breaking Changes

• `randomize_field` is removed. Use typed functions from the `dr` module (e.g. `dr.geom_friction`, `dr.body_mass`).
• `EventTermCfg` no longer accepts `domain_randomization`.
• `RslRlModelCfg` uses `distribution_cfg` dict instead of `stochastic`/`init_noise_std`/`noise_std_type`. Existing checkpoints are migrated automatically on load.

🐛 Bug Fixes

• Viewer FPS drops from physics starving the renderer (#694, #705)
• `height_scan` returning ~0 for missed rays (#646)
• Ghost mesh rendering for fixed base entities (#645)
• Actuator target resolution for entities with internal attach prefixes (#714)
• Offscreen rendering artifacts in large vectorized scenes (#682)
• Viser viewer crashing on scenes with no mocap bodies (#662)
• Bundled `ffmpeg` via `imageio-ffmpeg`, no more system install required (#650)

✨ New Contributors

• Thank you to @Msornerrrr, @rdeits-bd, @jonzamora, @jgueldenstein, @saikishor, @ax-anoop, @chengruiz, @ManuelActisCassa, and @etaoxing!
• Full Changelog: https://github.com/mujocolab/mjlab/compare/v1.1.1...v1.2.0

📋 What's Changed

• Enable reward plots in the native viewer. by @kevinzakka in https://github.com/mujocolab/mjlab/pull/629
• Extend Viser plotting to plot metrics by @saikishor in https://github.com/mujocolab/mjlab/pull/625
• Fix viser depth image display for vision example tasks by @pthangeda in https://github.com/mujocolab/mjlab/pull/627
• Add differential IK action space. by @kevinzakka in https://github.com/mujocolab/mjlab/pull/632
• fix(play): use MjlabOnPolicyRunner as default runner by @griffinaddison in https://github.com/mujocolab/mjlab/pull/626
• Remove unsafe body fields from domain randomization by @kevinzakka in https://github.com/mujocolab/mjlab/pull/631
• Replace moviepy with mediapy for video recording by @kevinzakka in https://github.com/mujocolab/mjlab/pull/637
• Use bleeding edge mujoco and mujoco_warp for dev. by @kevinzakka in https://github.com/mujocolab/mjlab/pull/638

✨ New Contributors

• @pthangeda made their first contribution in https://github.com/mujocolab/mjlab/pull/627
• @griffinaddison made their first contribution in https://github.com/mujocolab/mjlab/pull/626
• Full Changelog: https://github.com/mujocolab/mjlab/compare/v1.1.0...v1.1.1

✨ What's new

• RGB and depth camera sensors with BVH-accelerated raycasting
• MetricsManager for logging custom metrics during training
• Terrain visualizer and many new terrain types
• Site group visualization in the Viser viewer
• Upgraded rsl-rl-lib to 4.0.0 with native ONNX export
• Various bug fixes
• See the full [changelog](https://mujocolab.github.io/mjlab/source/changelog.html#version-1-1-0-february-12-2026) for details.

📋 Changes

• RayCastSensor: Terrain and obstacle detection for navigation tasks
• ContactSensor improvements: History tracking for better contact dynamics
• Muscle actuator support: Biomechanical simulation capabilities
• Sensor caching: Performance optimizations for large-scale training
• Better NaN handling: Easier debugging with detection in observations and sensor data

📦 Quick Demo

• See `mjlab` in action with a pre-trained motion imitation policy on the Unitree G1 humanoid:
• ```bash
• uvx --from mjlab --with "mujoco-warp @ git+https://github.com/google-deepmind/mujoco_warp" demo
• ```

📦 Beta Release

• Thanks!