Where Are the MJCF Robot Models Located in Microduck RL? A Complete File Guide

The MJCF robot models in the Microduck RL repository are located under src/mjlab_microduck/robot/microduck/, which contains the core XML definitions, scene files, JSON asset configurations, and supporting geometry assets.

The pollen-robotics/microduck_rl repository organizes its MuJoCo-compatible robot descriptions in a centralized Python package to streamline simulation training and ONNX export workflows. Understanding exactly where these MJCF robot models reside is essential for modifying physics parameters, adding sensors, or debugging collision geometry.

Core MJCF Directory Structure

All robot-related MJCF files are grouped under the src/mjlab_microduck/robot/microduck/ package. This co-location ensures that kinematic definitions, scene wrappers, and asset references remain synchronized during development.

Robot Definition Files

The primary robot MJCF files define the kinematic hierarchy, joint limits, actuators, and sensor tags. According to the source code, the repository maintains several variants optimized for different physics fidelity levels:

• robot_walk.xml — The standard walking model used for general locomotion training.
• robot_allcollisions.xml — A high-fidelity variant with full collision geometry for precise contact physics.
• robot_walk_backlash.xml — Derived from the walk model but includes backlash joint definitions.
• robot_allcollisions_rollers.xml — The all-collisions variant augmented with roller mechanisms.

Scene Configuration Files

Scene files provide a minimal simulation world (floor, lights, cameras) and embed the robot MJCF via the <include> tag. This separation allows the same robot definition to be instantiated in different contexts:

• scene_walk.xml — Minimal scene embedding the standard robot_walk.xml model.
• scene_backlash.xml — Scene configured for the backlash-variant robot.

Asset Mapping and JSON Configs

The MJCF XML files reference geometry assets indirectly through JSON configuration files rather than hardcoded paths. This abstraction allows the same XML to be reused across different asset root directories:

• config_mjcf_walk.json — Maps logical asset names to STL/PART files for the standard walk model.
• config_mjcf_allcollisions.json — Asset mapping for the all-collisions variant.

These JSON files are read at runtime to resolve the actual geometry locations under the assets/ subdirectory.

Key MJCF Files and Their Roles

When working with the Microduck RL codebase, you will interact with these specific files:

• src/mjlab_microduck/robot/microduck/robot_walk.xml — Core MJCF definition containing the standard walking robot's body hierarchy and default actuators.
• src/mjlab_microduck/robot/microduck/robot_allcollisions.xml — Comprehensive collision geometry version used when precise contact detection is required.
• src/mjlab_microduck/robot/microduck/scene_walk.xml — Entry point for simulations; includes the robot MJCF and defines global lighting and ground planes.
• src/mjlab_microduck/robot/microduck/assets/ — Directory containing all STL and PART component files (e.g., leg.stl, head_part.stl) referenced by the JSON configs.

Loading MJCF Models in Python

Training scripts load these MJCF files through the environment configuration factory. The paths are resolved internally using constants defined in microduck_constants.py.

# Example: loading a Microduck MJCF environment

from mjlab_microduck.tasks.microduck_velocity_env_cfg import make_microduck_velocity_env_cfg
from mjlab_microduck.robot.microduck_constants import MICRODUCK_ASSETS_ROOT

# Build the environment configuration (this internally loads the MJCF)

cfg = make_microduck_velocity_env_cfg(play=False)

# The `cfg` contains a `robot_mjcf_path` pointing to e.g. robot_walk.xml

print("Robot MJCF:", cfg.robot_mjcf_path)  

# → src/mjlab_microduck/robot/microduck/robot_walk.xml

print("Scene MJCF:", cfg.scene_mjcf_path)  

# → src/mjlab_microduck/robot/microduck/scene_walk.xml

When exporting a trained policy, the scripts/export.py utility reads the same MJCF paths from the configuration to bake the observation normalizer into the ONNX graph:

uv run scripts/export.py <TASK_ID> --wandb-run-path <entity/project/run_id>

# Internally uses `robot_mjcf_path` from the env cfg to resolve model structure

Backlash Variants and Model Augmentation

The repository includes a utility script for generating modified MJCF models without manually editing XML:

• src/mjlab_microduck/robot/microduck/add_backlash.py — Injects backlash joints into an existing MJCF model, creating the "Backlash" task variants programmatically.

This script reads the base MJCF (e.g., robot_walk.xml), adds compliance and damping parameters to specified joints, and writes out the variant files (e.g., robot_walk_backlash.xml).

Summary

• Primary Location: All MJCF robot models reside in src/mjlab_microduck/robot/microduck/.
• Core Definitions: robot_walk.xml and robot_allcollisions.xml provide the base kinematic and collision models.
• Scene Wrappers: scene_walk.xml and scene_backlash.xml embed the robots into simulation environments.
• Asset Resolution: JSON configs (config_mjcf_walk.json) map logical names to STL files in the assets/ subdirectory.
• Programmatic Modification: Use add_backlash.py to generate physics variants without manual XML editing.

Frequently Asked Questions

Where exactly are the main MJCF XML files stored in the repository?

The main MJCF XML files are stored in the src/mjlab_microduck/robot/microduck/ directory of the pollen-robotics/microduck_rl repository. This location contains robot_walk.xml, robot_allcollisions.xml, and their respective scene definitions.

How does Microduck RL reference robot geometry assets?

Rather than embedding hardcoded paths in the XML, Microduck RL uses JSON configuration files (config_mjcf_walk.json, config_mjcf_allcollisions.json) to map logical asset names to actual STL and PART files located in the assets/ subdirectory. These JSON files are parsed at runtime to resolve geometry locations.

What is the difference between robot_walk.xml and robot_allcollisions.xml?

robot_walk.xml defines the standard locomotion model with essential collision geometry for training efficiency, while robot_allcollisions.xml contains comprehensive collision meshes for all links, providing higher fidelity physics simulation at the cost of computational performance.

How can I create custom MJCF variants with backlash joints?

Use the src/mjlab_microduck/robot/microduck/add_backlash.py utility script. This script programmatically injects backlash joint parameters into an existing MJCF file (such as robot_walk.xml) and outputs a new variant (e.g., robot_walk_backlash.xml) suitable for training policies robust to mechanical compliance.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}