mjcf-xml-reasoning

star 0

Master understanding and reasoning about MuJoCo MJCF XML model files. Enables accurate interpretation of robot/scene definitions, kinematic trees, physics configurations, and simulation parameters.

mzqef By mzqef schedule Updated 2/11/2026
play_arrow Run Skill in Manus View GitHub

name: mjcf-xml-reasoning description: Master understanding and reasoning about MuJoCo MJCF XML model files. Enables accurate interpretation of robot/scene definitions, kinematic trees, physics configurations, and simulation parameters.

Purpose

MJCF (MuJoCo XML Format) is the native modeling language for MuJoCo physics simulation. This skill enables:

  • Reading and understanding robot and scene XML definitions
  • Reasoning about kinematic structures, joint configurations, contact physics
  • Debugging physics issues through XML inspection
  • Designing new scenes, terrains, and robot modifications
  • Connecting XML elements to simulation behavior

MJCF Document Structure

Every MJCF file has a single root <mujoco> element with optional sections:

<mujoco model="model_name">
  <compiler .../>     <!-- Parser/compiler settings -->
  <option .../>       <!-- Physics simulation options -->
  <size .../>         <!-- Memory allocation hints -->
  <default .../>      <!-- Default attribute values (cascading) -->
  <asset .../>        <!-- Meshes, textures, materials, height fields -->
  <worldbody .../>    <!-- Kinematic tree (bodies, geoms, joints) -->
  <contact .../>      <!-- Contact pairs, exclusions -->
  <equality .../>     <!-- Equality constraints (welds, joints) -->
  <tendon .../>       <!-- Spatial/fixed tendons -->
  <actuator .../>     <!-- Motors, position servos, etc. -->
  <sensor .../>       <!-- Sensors (IMU, force, position) -->
  <keyframe .../>     <!-- Named poses/configurations -->
  <visual .../>       <!-- Rendering settings -->
</mujoco>

Core Element Reference

<compiler> - Parser Settings

Controls how the XML is parsed and compiled:

Attribute Description Example
angle Angle units (degree/radian) angle="radian"
meshdir Directory for mesh files meshdir="assets"
texturedir Directory for textures texturedir="textures"
autolimits Infer joint limits from range autolimits="true"
inertiafromgeom Compute inertia from geoms inertiafromgeom="true" 
<compiler angle="radian" meshdir="assets" texturedir="assets" autolimits="true"/>

<option> - Simulation Settings

Physics engine configuration:

Attribute Description Default
timestep Integration step (seconds) 0.002
gravity Gravity vector "0 0 -9.81"
integrator Euler, RK4, implicit Euler
cone Friction cone (pyramidal/elliptic) pyramidal
impratio Friction impedance ratio 1 
<option gravity="0 0 -9.81" timestep="0.01" integrator="RK4" cone="elliptic" impratio="100"/>

<default> - Cascading Defaults (CSS-like)

Defaults eliminate redundancy. Classes can nest and inherit:

<default class="main">
  <geom friction="0.8" contype="1" conaffinity="1"/>
  <joint damping="1" armature="0.01"/>
  
  <default class="visual">
    <geom contype="0" conaffinity="0" group="2"/>  <!-- No collision -->
  </default>
  
  <default class="collision">
    <geom group="3"/>  <!-- Collision geometry -->
    <default class="foot">
      <geom type="sphere" size="0.03" condim="6" friction="0.8 0.02 0.01"/>
    </default>
  </default>
</default>

Usage: Reference with class="classname":

<geom name="visual_body" mesh="body" class="visual"/>
<geom name="contact_foot" class="foot"/>

<asset> - Resources

Contains meshes, textures, materials, height fields:

<asset>
  <!-- Mesh files (OBJ, STL) -->
  <mesh name="body_mesh" file="body.obj" scale="1 1 1"/>
  
  <!-- Height field terrain -->
  <hfield name="terrain" file="heightmap.png" size="10 10 0.5 0"/>
  
  <!-- Textures -->
  <texture name="ground_tex" type="2d" file="ground.png"/>
  <texture name="sky" type="skybox" builtin="gradient" rgb1="0.4 0.4 0.4" rgb2="0 0 0"/>
  
  <!-- Materials -->
  <material name="ground_mat" texture="ground_tex" texrepeat="0.4 0.4"/>
  <material name="red" rgba="0.8 0.1 0.1 1" specular="0.3" shininess="0.5"/>
</asset>

<worldbody> - Kinematic Tree

The heart of the model. Bodies nest to form parent-child relationships:

<worldbody>
  <!-- Static ground (child of world) -->
  <geom name="floor" type="plane" size="0 0 0.01" material="ground_mat"/>
  <light pos="0 0 3" dir="0 0 -1" directional="true"/>
  
  <!-- Robot root body -->
  <body name="base" pos="0 0 0.5">
    <freejoint name="root"/>  <!-- 6-DOF floating base -->
    <inertial mass="10" pos="0 0 0" diaginertia="0.5 0.5 0.3"/>
    <geom name="torso" type="box" size="0.2 0.15 0.1" class="collision"/>
    
    <!-- Child body: leg -->
    <body name="thigh" pos="0.2 0 -0.1">
      <joint name="hip" type="hinge" axis="0 1 0" range="-1.57 1.57"/>
      <geom name="thigh_geom" type="capsule" fromto="0 0 0  0 0 -0.3" size="0.04"/>
      
      <!-- Grandchild: shank -->
      <body name="shank" pos="0 0 -0.3">
        <joint name="knee" type="hinge" axis="0 1 0" range="-2.8 0"/>
        <geom name="shank_geom" type="capsule" fromto="0 0 0  0 0 -0.3" size="0.03"/>
        <geom name="foot" type="sphere" size="0.03" pos="0 0 -0.3" class="foot"/>
      </body>
    </body>
  </body>
</worldbody>

Body Elements Deep Dive

<body> - Rigid Body

Attribute Description
name Unique identifier
pos Position relative to parent (x y z)
quat Orientation quaternion (w x y z)
euler, axisangle, xyaxes, zaxis Alternative orientation specs
childclass Default class for all children

<joint> - Degrees of Freedom

Joints connect a body to its parent. Multiple joints in one body create composite joints.

Type DOF Description
free 6 Floating base (translation + rotation)
ball 3 Ball-and-socket (3D rotation)
hinge 1 Rotation around axis
slide 1 Translation along axis 
<!-- Hinge joint with limits -->
<joint name="hip_pitch" type="hinge" axis="0 1 0" pos="0 0 0" 
       limited="true" range="-1.57 1.57" damping="1" armature="0.01"/>

<!-- Free joint for floating base -->
<freejoint name="root"/>   <!-- Equivalent to <joint type="free"/>, fully unconstrained 6-DOF -->

Key joint attributes:

Attribute Description
axis Rotation/translation axis (normalized)
pos Joint position in body frame
range Limits (min max)
damping Velocity damping coefficient
armature Rotor inertia (stabilizes simulation)
stiffness Spring stiffness toward qpos0
frictionloss Dry friction torque

<geom> - Collision & Visual Geometry

Type Description Size Parameters
plane Infinite ground plane half-sizes for rendering
sphere Sphere radius
capsule Cylinder with hemispherical caps radius, half-length
cylinder Cylinder radius, half-length
box Rectangular box x, y, z half-sizes
ellipsoid Ellipsoid x, y, z radii
mesh Triangle mesh from mesh asset
hfield Height field terrain from hfield asset 
<!-- Box collision geom -->
<geom name="torso" type="box" size="0.2 0.15 0.1" rgba="0.8 0.2 0.2 1"/>

<!-- Capsule leg segment using fromto -->
<geom name="thigh" type="capsule" fromto="0 0 0  0 0 -0.3" size="0.04"/>

<!-- Mesh visual (no collision) -->
<geom type="mesh" mesh="body_visual" contype="0" conaffinity="0" group="2"/>

<!-- Height field terrain -->
<geom name="terrain" type="hfield" hfield="terrain_hfield" pos="0 0 0"/>

Contact attributes:

Attribute Description
contype Collision type bitmask
conaffinity Collision affinity bitmask
condim Contact DOF (1=frictionless, 3=sliding, 4=+torsional, 6=+rolling)
friction Friction coefficients (sliding torsional rolling)
solimp Solver impedance (softness)
solref Solver reference (stiffness, damping)
priority Higher wins in parameter conflicts

Contact occurs when: (contype1 & conaffinity2) || (contype2 & conaffinity1)

<site> - Reference Points

Sites are massless markers for sensors, actuators, and tendons:

<site name="imu_site" pos="0 0 0" size="0.01"/>
<site name="ee_site" pos="0 0 -0.3" size="0.02"/>  <!-- End effector -->

<inertial> - Mass Properties

Explicit inertia (overrides geom-based inference):

<inertial mass="10" pos="0 0.01 0.02" 
          quat="1 0 0 0" diaginertia="0.5 0.4 0.3"/>
Attribute Description
mass Body mass (kg)
pos Center of mass position
diaginertia Principal moments (Ixx Iyy Izz)
fullinertia Full 6-element inertia (Ixx Iyy Izz Ixy Ixz Iyz)

Actuators

Types

Type Description Key Params
motor Direct torque/force gear
position Position servo (PD) kp, kv
velocity Velocity servo kv
intvelocity Integrated velocity kp, actrange
general Fully configurable gaintype, biastype 
<actuator>
  <!-- Direct motor -->
  <motor name="hip_torque" joint="hip" gear="100" ctrlrange="-3 3"/>
  
  <!-- Position servo with PD gains -->
  <position name="hip_pos" joint="hip" kp="200" kv="10" 
            ctrlrange="-1.57 1.57" forcerange="-100 100"/>
  
  <!-- Using defaults class -->
  <position class="servo" joint="knee" name="knee_pos"/>
</actuator>

Transmission Types

Transmission Description
joint Direct joint actuation
tendon Tendon-based transmission
site Force/torque at site
body Adhesion forces (gecko feet)

Sensors

<sensor>
  <!-- Joint state -->
  <jointpos name="hip_pos" joint="hip"/>
  <jointvel name="hip_vel" joint="hip"/>
  <actuatorfrc name="hip_force" actuator="hip_motor"/>
  
  <!-- Body state -->
  <framepos name="base_pos" objtype="body" objname="base"/>
  <framelinvel name="base_vel" objtype="body" objname="base"/>
  <framequat name="base_quat" objtype="body" objname="base"/>
  
  <!-- IMU at site -->
  <gyro name="imu_gyro" site="imu_site"/>
  <accelerometer name="imu_accel" site="imu_site"/>
  
  <!-- Contact/force -->
  <touch name="foot_touch" site="foot_site"/>
  <force name="ankle_force" site="ankle_site"/>
</sensor>

Contact Control

Exclude Collisions

<contact>
  <exclude body1="base" body2="thigh"/>  <!-- Prevent self-collision -->
  <exclude body1="thigh" body2="shank"/>
</contact>

Explicit Contact Pairs

<contact>
  <pair geom1="foot" geom2="ground" condim="6" friction="1 0.05 0.01"/>
</contact>

Equality Constraints

<equality>
  <!-- Weld two bodies together -->
  <weld body1="gripper" body2="object"/>
  
  <!-- Lock joint to fixed angle -->
  <joint joint1="finger" polycoef="0 1 0 0 0"/>
  
  <!-- Connect bodies with offset -->
  <connect body1="arm" body2="tool" anchor="0 0 0.1"/>
</equality>

MotrixLab Project XML Patterns

Scene XML Structure (Navigation Tasks)

<mujoco>
  <asset>
    <hfield name="hfield_terrain" file="assets/heightmap.png" size="5 1.5 0.3 0"/>
    <material name="CollisionBlue" rgba="0.2 0.4 1.0 0.6"/>
  </asset>

  <default>
    <default class="collision">
      <geom type="mesh" contype="1" conaffinity="1"/>
      <default class="boundary">
        <geom type="box" rgba="0.2 0.4 1.0 0.6"/>
      </default>
    </default>
  </default>

  <worldbody>
    <body name="ground_root">
      <!-- Boundary walls -->
      <body name="boundaries" pos="0 0 0">
        <geom name="wall_left" class="boundary" size="0.25 10 1" pos="-5 0 1"/>
        <geom name="wall_right" class="boundary" size="0.25 10 1" pos="5 0 1"/>
      </body>
      
      <!-- Terrain heightfield -->
      <body name="terrain">
        <geom type="hfield" hfield="hfield_terrain" pos="0 0 0" 
              contype="1" conaffinity="1" friction="0.8"/>
      </body>
    </body>
  </worldbody>
</mujoco>

Robot XML Structure (ANYmal/VBot)

<mujoco model="quadruped">
  <compiler angle="radian" meshdir="assets" autolimits="true"/>
  <option cone="elliptic" impratio="100"/>

  <default class="robot">
    <joint damping="1" frictionloss="0.1"/>
    <default class="visual">
      <geom contype="0" conaffinity="0" group="2"/>
    </default>
    <default class="collision">
      <geom group="3"/>
    </default>
    <default class="foot">
      <geom type="sphere" size="0.03" condim="6" friction="0.8 0.02 0.01"/>
    </default>
    <default class="servo">
      <position kp="200" kv="1" ctrlrange="-6.28 6.28" forcerange="-140 140"/>
    </default>
  </default>

  <worldbody>
    <body name="base" pos="0 0 0.5" childclass="robot">
      <freejoint/>
      <site name="imu_site"/>
      <geom class="collision" type="box" size="0.3 0.1 0.1"/>
      
      <!-- Leg: LF (Left Front) -->
      <body name="LF_hip" pos="0.3 0.1 0">
        <joint name="LF_HAA" type="hinge" axis="1 0 0" range="-0.7 0.5"/>
        <body name="LF_thigh" pos="0.06 0.07 0">
          <joint name="LF_HFE" type="hinge" axis="0 1 0"/>
          <body name="LF_shank" pos="0.1 0 -0.28">
            <joint name="LF_KFE" type="hinge" axis="0 1 0"/>
            <geom name="LF_FOOT" class="foot" pos="0.01 0.08 -0.31"/>
          </body>
        </body>
      </body>
      <!-- ... RF, LH, RH legs similar ... -->
    </body>
  </worldbody>

  <sensor>
    <framelinvel name="base_linvel" objtype="body" objname="base"/>
    <gyro name="base_gyro" site="imu_site"/>
  </sensor>

  <actuator>
    <position class="servo" joint="LF_HAA" name="LF_HAA"/>
    <position class="servo" joint="LF_HFE" name="LF_HFE"/>
    <position class="servo" joint="LF_KFE" name="LF_KFE"/>
    <!-- ... 12 total for quadruped ... -->
  </actuator>
</mujoco>

Common Analysis Questions

Question Where to Look
Why doesn't robot move? <actuator> - check joint names, ctrl ranges
Robot flies away? <option> timestep too large; <joint> missing damping
No foot contact? <geom> contype/conaffinity mismatch; condim too low
Wrong mass? <inertial> explicit mass; <geom> density attribute
Visual mismatch? Check meshdir, texturedir paths
Self-collision issues? Add <contact><exclude> pairs
Slippery feet? Increase friction on foot geoms
Wobbly joints? Increase damping, armature on joints
Terrain not working? Check <hfield> size param: (x_ext y_ext z_max z_min)

Height Field (hfield) Sizing

<hfield name="terrain" file="heightmap.png" size="5 1.5 0.3 0"/>
<!--                                           ↑     ↑   ↑   ↑
                                               |     |   |   z_min (usually 0)
                                               |     |   z_max (max height)
                                               |     y half-extent
                                               x half-extent
-->

The PNG grayscale maps 0→z_min, 255→z_max.

Frame Orientation Specification

Multiple ways to specify rotation:

Attribute Format Example
quat w x y z quat="1 0 0 0" (no rotation)
euler rx ry rz euler="0 0 1.57"
axisangle ax ay az angle axisangle="0 0 1 90"
xyaxes x1 x2 x3 y1 y2 y3 xyaxes="1 0 0 0 1 0"
zaxis z1 z2 z3 zaxis="0 0 1"

Only use one orientation attribute per element.

Debugging Workflow

  1. Check compiler errors - Run mj_loadXML to get error line numbers
  2. Visualize collision - Set group="3" on collision geoms, toggle in viewer
  3. Check contact - Use mjVIS_CONTACTPOINT to see contact locations
  4. Verify inertia - Use mjVIS_INERTIA to see equivalent inertia boxes
  5. Test actuators - Apply small control inputs, verify expected motion
  6. Check sensors - Print mjData.sensordata to verify readings

Quick Reference Cards

Joint Naming Convention (Quadrupeds)

Pattern Meaning
LF_, RF_, LH_, RH_ Left/Right Front/Hind
_HAA Hip Abduction/Adduction
_HFE Hip Flexion/Extension
_KFE Knee Flexion/Extension

Contact condim Values

condim Friction Type
1 Frictionless (normal only)
3 Sliding friction (tangent plane)
4 + Torsional (spin around normal)
6 + Rolling (tilt around tangents)

Geom Group Conventions

Group Purpose
0 Default
1 Primary collision
2 Visual only (high detail)
3 Collision only (simplified)

Common Fixes

Symptom Fix
Bodies explode at start Add armature to joints; reduce timestep
Robot sinks through floor Check contype/conaffinity matching
Jerky contact Increase condim; adjust solref/solimp
Mesh not found Check meshdir path in <compiler>
Limits not working Set limited="true" or autolimits="true"
Actuator does nothing Verify joint name matches; check ctrlrange

MotrixLab XML Files

Path Description
starter_kit/{task}/vbot/xmls/*.xml Navigation terrain scenes
motrix_envs/src/motrix_envs/basic/*/ Basic env XMLs (cartpole, cheetah, etc.)
motrix_envs/src/motrix_envs/common/ Shared materials, skybox, visual configs

Terrain Geometry Details (Chinese)

Detailed terrain geometry (coordinates, dimensions, obstacle positions, elevation profiles) for each competition section is documented in:

  • starter_kit_docs/navigation1/Task_Reference.md → "Terrain Description" section
  • starter_kit_docs/navigation2/Task_Reference.md → "Terrain Descriptions" section

These include per-element tables with exact coordinates, sizes, and elevation data for all platforms, stairs, obstacles, boundaries, height fields, and the full course Y-axis layout.

Install via CLI
npx skills add https://github.com/mzqef/MotrixLab --skill mjcf-xml-reasoning
Repository Details
star Stars 0
call_split Forks 0
navigation Branch main
article Path SKILL.md
Occupations
Engineers all other
More from Creator
mzqef
mzqef Explore all skills →