How Microduck Robot Models Are Defined in MJCF Format

Microduck robot models are generated from Onshape CAD data via JSON configuration files that configure the onshape-to-robot exporter, producing MJCF XML files containing hierarchical body definitions, actuator classes, and sensor specifications for MuJoCo simulation.

The pollen-robotics/microduck_rl repository defines Microduck robot models using MuJoCo's MJCF (MuJoCo XML) format to enable physics-based reinforcement learning. Rather than authoring these files manually, the project uses an automated pipeline that converts Onshape CAD assemblies into simulation-ready XML through structured JSON configurations. This approach ensures that geometric changes in CAD propagate correctly to the simulation while maintaining precise control over collision properties, joint behavior, and sensor placement.

The MJCF Generation Pipeline

Microduck MJCF files are created using the onshape-to-robot exporter, which processes JSON configuration files stored in src/mjlab_microduck/robot/microduck/. These configurations bridge the gap between parametric CAD data and physics simulation by specifying how to translate Onshape assemblies into MuJoCo-compatible XML.

JSON Configuration Files

The pipeline is driven by two primary configuration files:

• config_mjcf_walk.json – Generates the walking model (robot_walk.xml) optimized for locomotion tasks
• config_mjcf_allcollisions.json – Generates a model (robot_allcollisions.xml) with comprehensive collision mesh data

Each JSON file acts as a manifest that tells the exporter which Onshape document to pull, how to simplify the geometry, and which supplemental XML fragments to inject into the final MJCF.

Export Process

When the exporter runs, it retrieves the specified CAD assembly from Onshape, converts the geometry to STL meshes, and assembles the kinematic tree. The resulting structure is then combined with hand-written XML snippets to produce the final MJCF file that MuJoCo loads.

JSON Configuration Structure

The configuration files in src/mjlab_microduck/robot/microduck/ contain specific fields that control every aspect of the MJCF generation:

• Source CAD URL – A link to the Onshape document containing the robot geometry
• Output format – Always set to "mujoco" to ensure MJCF output
• Robot name and output filename – Defines the model identifier (e.g., "microduck") and target file (e.g., "robot_walk")
• Simplification options – Parameters like simplify_stls and max_stl_size control mesh decimation for performance
• Ignore rules – A mapping of part name patterns marked as "collision" or kept as visual-only geometry (e.g., !sole_left retains the left foot as a visual mesh)
• Additional XML snippets – References to joints_properties.xml, sensors.xml, and additional.xml that get concatenated into the final output
• Post-import commands – A series of sed commands that modify the generated XML, including positioning the trunk, renaming foot collision bodies, fixing inheritance ranges, and injecting camera elements
• Joint properties – Specifications for default actuator classes (chosen_actuator) and passive joint classes (passive_joint) that determine how the robot is controlled once loaded

MJCF Composition and XML Snippets

The final MJCF files are assembled from multiple source documents that define specific simulation behaviors:

joints_properties.xml defines actuator and passive joint classes used throughout the model. This file establishes the chosen_actuator class used for trainable joints and passive_joint classes for unactuated degrees of freedom.

sensors.xml contains the sensor suite specifications, including IMU orientation, gyroscope, accelerometer, velocimeter, and subtree angular momentum sensors. These elements are injected into the MJCF's <worldbody> or <sensor> sections.

additional.xml provides miscellaneous MJCF additions such as collision groups, equality constraints, and default visual properties that are not generated automatically from the CAD data.

Structure of Generated MJCF Files

The resulting MJCF files (e.g., robot_walk.xml and robot_allcollisions.xml) contain several standardized sections:

Global MJCF settings – Compiler options, default visual classes, and timestep configurations that affect numerical stability.

Joint class definitions – Actuator classes (chosen_actuator, perfect_actuator) and passive classes (passive_wheel, passive_joint) that map to specific control modes in the training environment.

Sensor definitions – The complete sensor array specified in sensors.xml, enabling state estimation for reinforcement learning policies.

Collision handling – A <default class="self_collision_only"> block defines geometry used exclusively for self-collision detection, while explicit <exclude> tags (typically commented out) can suppress unwanted contact pairs between specific body pairs.

Body hierarchy – The full kinematic chain starting from the trunk, branching to hips and legs (trunk → hips → legs → feet) and the neck-head assembly. Each joint references one of the predefined classes from the joint-property map, ensuring consistent damping and actuation limits.

Loading Microduck MJCF Models in Python

Once generated, the MJCF files can be loaded directly through MuJoCo's Python API for standalone simulation:

import mujoco
from mujoco import viewer

# Load the walking robot MJCF generated by the exporter

model_path = "src/mjlab_microduck/robot/microduck/robot_walk.xml"
model = mujoco.MjModel.from_xml_path(model_path)

# Create a simulation instance

sim = mujoco.MjSim(model)

# Simple step loop that prints trunk height

for i in range(100):
    sim.step()
    qpos = sim.data.qpos.copy()
    print(f"Step {i}: trunk_z={qpos[2]:.3f}")

# Optional visualisation

viewer.launch(model, sim)

Integration with Training Environments

For reinforcement learning, the MJCF models are consumed by the RSL-RL training environment through configuration factories:

from mjlab_microduck.tasks.microduck_velocity_env_cfg import make_microduck_velocity_env_cfg

# Build the environment configuration for the walking robot

cfg = make_microduck_velocity_env_cfg(play=False, rough=False)

# The config automatically points to the MJCF model defined in

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

env = cfg.make()
obs = env.reset()

This integration allows PPO agents to control the robot through the defined actuators while respecting the collision and sensor specifications embedded in the MJCF.

Summary

• Microduck MJCF files are generated from Onshape CAD using the onshape-to-robot exporter and JSON configuration files located in src/mjlab_microduck/robot/microduck/.
• The JSON configurations specify source URLs, mesh simplification rules, ignore patterns for visual-only parts, and references to supplemental XML files.
• Three XML snippets—joints_properties.xml, sensors.xml, and additional.xml—are concatenated into the final MJCF to define joint classes, IMU sensors, and collision groups.
• Generated files like robot_walk.xml contain complete MuJoCo models with hierarchical body definitions, actuator classes (chosen_actuator), and self-collision geometry.
• The models are loaded via mujoco.MjModel.from_xml_path() for standalone simulation or integrated into RSL-RL training environments for reinforcement learning.

Frequently Asked Questions

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

The robot_walk.xml file is optimized for locomotion tasks with selective collision meshes and simplified geometry to improve simulation speed. In contrast, robot_allcollisions.xml contains comprehensive collision data for all robot parts, making it suitable for tasks requiring precise contact detection across the entire body surface but potentially slower to simulate.

How do I modify the robot's collision properties?

Collision properties are controlled through the ignore rules in the JSON configuration files and the <default class="self_collision_only"> section in the generated MJCF. To change collision behavior, edit config_mjcf_walk.json or config_mjcf_allcollisions.json to adjust which STL files are marked as collision geometry, then regenerate the XML using the onshape-to-robot exporter.

Can I use a different CAD source for the MJCF generation?

Yes. You can modify the Source CAD URL field in the JSON configuration files to point to a different Onshape document. However, the part naming conventions must remain consistent because the exporter relies on specific name patterns (like !sole_left) to apply ignore rules and joint assignments correctly.

How are joint actuators configured in the Microduck MJCF?

Joint actuators are configured through the joints_properties.xml snippet referenced in the JSON configuration. This file defines the chosen_actuator class assigned to trainable joints and passive_joint classes for unactuated degrees of freedom. When MuJoCo loads the MJCF, it instantiates actuators according to these class definitions, allowing reinforcement learning policies to interface with the robot through standardized control signals.

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