Index of every page on this site: llms.txt
All skills
google-deepmind avatar

/specediting

@eb1ff5e
by Google DeepMindgoogle-deepmind/mujoco18k stars
2,221
Run it yourself

MuJoCo procedural model authoring, editing, and tuning with MjSpec (`mujoco.MjSpec` in Python and `mjSpec` in C++): bodies, geoms, joints, sites, cameras, sub-model attachment with prefix namespaces, actuators (position servos, motors, velocity drives, trntype), baseline option/default overrides (implicitfast, elliptic cones, solref, solimp, armature, damping), collision bitmasks (contype, conaffinity), friction (condim), default classes (MjsDefault), procedural meshes, deletion, spec recompilation (spec.recompile). Use only for authoring or tuning MuJoCo MJCF/MjSpec models, adding bodies/geoms/actuators, and attaching sub-models. Don't use for designing custom non-MuJoCo XML/scene-graph APIs when MuJoCo `MjSpec` is not used, deformable flex/cloth/cable modeling (mujoco-deformables), stepping simulations (mujoco-python), or rendering (mujoco-rendering).

  • 1 file
  • 17.2 KB
  • Updated 4 days ago
  • GitHub
Use this Skill: https://skilld.dev/gh/google-deepmind/mujoco/specediting

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈220 tokens for metadata: the name and description. ≈4.2k when used: this file.

Description uses 11.1% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈887 characters, or 11.1%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

MuJoCo Spec Editing: Building & Modifying Models

[!TIP]

Official MuJoCo documentation (doc/*.rst): Read short chapters like ../../programming/modeledit.rst (.. _meOverview:) and ../../overview.rst directly when in a MuJoCo checkout; for large reference files like ../../modeling.rst (.. _ProceduralModeling:, .. _Mechanisms:, .. _CTuning:), ../../XMLreference.rst, ../../python.rst (.. _PyModelEdit:), and ../../APIreference/functions.rst, grep the literal .. _Label: anchor. Outside a checkout, the same doc/*.rst tree ships offline in pip install mujoco at pathlib.Path(mujoco.__file__).parent / 'doc'; otherwise fetch https://mujoco.readthedocs.io/en/latest/<path>.html (or /en/stable/ for released pages; functions.rst renders inside APIreference/APIfunctions.html, and Sphinx anchors lowercase the label, e.g. .. _meOverview: → #meoverview) and browse repo paths (../../../) under https://github.com/google-deepmind/mujoco/tree/main/.

Related skills:

  • mujoco-deformables — Deformable <flexcomp>, <flex>, and <skin> modeling (1D rods, 2D cloth/shells, 3D FEM soft bodies, and attachments).
  • mujoco-python — Simulation lifecycle, stepping, and diagnostics.
  • mujoco-rendering — Offscreen image rendering and camera setup.
  • mujoco-studio — Interactive viewers and Studio plugins.

1. Procedural Modeling with MjSpec

MjSpec is a mutable C++ and Python data structure that mirrors the MJCF XML schema, allowing models to be constructed and modified programmatically.

import mujoco

spec = mujoco.MjSpec()

# Add a body with a freejoint and sphere geom
body = spec.worldbody.add_body(name='ball', pos=[0, 0, 1.0])
body.add_freejoint()
body.add_geom(type=mujoco.mjtGeom.mjGEOM_SPHERE, size=[0.1], rgba=[1, 0, 0, 1])

# Compile to MjModel
model = spec.compile()

In C++:

#include <mujoco/mujoco.h>

mjSpec* spec = mj_makeSpec();
mjsBody* body = mjs_addBody(mjs_findBody(spec, "world"), nullptr);
body->pos[2] = 1.0;
mjs_addFreeJoint(body);
mjsGeom* geom = mjs_addGeom(body, nullptr);
geom->type = mjGEOM_SPHERE;
geom->size[0] = 0.1;

mjModel* model = mj_compile(spec, nullptr);
if (!model) printf("%s\n", mjs_getError(spec));
mj_deleteSpec(spec);

2. Building Hierarchies: Bodies, Geoms, Joints & Sites

Adding Elements

body = spec.worldbody.add_body(name='arm', pos=[0, 0, 0.5])

# Geom with capsule shape
geom = body.add_geom(
    name='arm_geom',
    type=mujoco.mjtGeom.mjGEOM_CAPSULE,
    size=[0.05, 0.25],
    rgba=[0.2, 0.6, 1.0, 1.0],
)

# Hinge joint
joint = body.add_joint(
    name='shoulder',
    type=mujoco.mjtJoint.mjJNT_HINGE,
    axis=[0, 1, 0],
    range=[-1.57, 1.57],
)

# Sensor site and camera
site = body.add_site(name='grip_site', pos=[0, 0, 0.25])
cam = body.add_camera(name='tool_cam', pos=[0, -0.5, 0.25], xyaxes=[1, 0, 0, 0, 0, 1])

Geom Dimensions Reference

Geom Type size Parameter Semantics
mjGEOM_SPHERE [radius]
mjGEOM_CAPSULE [radius, half_length] (or [radius] if using fromto)
mjGEOM_CYLINDER [radius, half_length] (or [radius] if using fromto)
mjGEOM_BOX [half_x, half_y, half_z]
mjGEOM_ELLIPSOID [radius_x, radius_y, radius_z]
mjGEOM_PLANE [half_x, half_y, grid_spacing]

[!WARNING]

When fromto=[x1, y1, z1, x2, y2, z2] is specified for capsules or cylinders, size takes only one value ([radius]); length is calculated from endpoints.

Orientation Keywords

Only one orientation specification can be used at a time:

  • quat=[w, x, y, z] (native representation)
  • euler=[a1, a2, a3] (sequence set by spec.compiler.eulerseq, default 'xyz')
  • axisangle=[x, y, z, angle]
  • xyaxes=[x_x, x_y, x_z, y_x, y_y, y_z]
  • zaxis=[x, y, z]

Angles in euler and axisangle are in degrees unless spec.compiler.degree = False (see modeling.rst, .. _COrientation:, and XMLreference.rst, .. _body-geom:).

3. Sub-model Composition & Attachments

Compose models modularly by attaching sub-specs with prefix namespaces (see programming/modeledit.rst, .. _meAttachment: and .. _meAttributeMerging:):

parent = mujoco.MjSpec()
child = mujoco.MjSpec()

child_body = child.worldbody.add_body(name='gripper')
child_body.add_geom(size=[0.05], type=mujoco.mjtGeom.mjGEOM_SPHERE)

# Attach child spec to a mount site on the parent
mount_site = parent.worldbody.add_site(name='mount', pos=[0, 0, 1.0])
parent.attach(child, site=mount_site, prefix='gripper_')
# Child body is renamed to 'gripper_gripper' in parent

Cross-Spec Equality Constraints

When linking bodies from two different child specs (e.g. dual-arm setups), attach both children to the common parent first, then declare constraints on the parent spec:

left_mount = parent.worldbody.add_frame(pos=[0, 0.3, 0])
right_mount = parent.worldbody.add_frame(pos=[0, -0.3, 0])
parent.attach(arm1_spec, frame=left_mount, prefix='left_')
parent.attach(arm2_spec, frame=right_mount, prefix='right_')

eq = parent.add_equality(
    type=mujoco.mjtEq.mjEQ_CONNECT,
    objtype=mujoco.mjtObj.mjOBJ_BODY,
    name1='left_hand',
    name2='right_hand',
)
eq.data[0:3] = [0, 0, 0]  # connect anchor, in name1's body frame

[!NOTE]

attach() requires exactly one of frame= or site=; omitting both raises ValueError.

4. Deleting & Dynamically Modifying Elements

Deleting Elements

Pass the element object to spec.delete(); deleting a body removes its subtree:

spec.delete(spec.body('unwanted_body'))
spec.delete(spec.geom('old_geom'))
spec.delete(spec.joint('redundant_joint'))
spec.delete(spec.actuator('motor'))

State-Preserving Recompilation

When changing model architecture at runtime, use spec.recompile to keep existing physics state:

# Add new tool to robot
spec.worldbody.add_geom(name='tool_tip', size=[0.02], type=mujoco.mjtGeom.mjGEOM_SPHERE)

# Recompile keeping positions/velocities intact
model, data = spec.recompile(model, data)

5. Actuators & Servos

Always explicitly set the transmission type (trntype):

# 1. Torque Motor
motor = spec.add_actuator(
    name='torque_actuator',
    target='shoulder',
    trntype=mujoco.mjtTrn.mjTRN_JOINT,
)
motor.set_to_motor()

# 2. Stiff Position Servo (Recommended for position control)
servo = spec.add_actuator(
    name='pos_servo',
    target='shoulder',
    trntype=mujoco.mjtTrn.mjTRN_JOINT,
)
servo.set_to_position(kp=200.0, dampratio=1.0)  # Pair with implicitfast (kv defaults to 0)
servo.forcelimited = True
servo.forcerange = [-50.0, 50.0]     # Peak torque in Nm
servo.ctrllimited = True
servo.ctrlrange = [-1.57, 1.57]      # Target angle in radians

# 3. Velocity Actuator
vel = spec.add_actuator(
    name='vel_driver',
    target='wheel_joint',
    trntype=mujoco.mjtTrn.mjTRN_JOINT,
)
vel.set_to_velocity(kv=10.0)

[!CAUTION]

The helper functions set_to_position() and set_to_motor() configure gains but do not set the transmission. You must always specify trntype=mujoco.mjtTrn.mjTRN_JOINT (or another valid transmission type). See modeling.rst (.. _CActuators:, .. _CActShortcuts:) and XMLreference.rst (.. _actuator:).

6. Default Classes (Inheritance & Styling)

Default classes (MjsDefault) provide cascaded styling and properties (see modeling.rst, .. _CDefault:, and programming/modeledit.rst, .. _meDefault:):

# Create child class under root 'main' class
main_class = spec.default
rubber = spec.add_default('rubber', main_class)
rubber.geom.friction = [1.5, 0.01, 0.001]
rubber.geom.density = 1200.0

# Assign class at creation
body.add_geom(rubber, name='tire', type=mujoco.mjtGeom.mjGEOM_CYLINDER, size=[0.1, 0.05])

# Assign class post-creation (must pass MjsDefault object, NOT a string)
other_geom.classname = rubber

Baseline Tuning Overrides (<option> & Root <default>)

Several internal defaults (Euler, pyramidal cones with impratio=1, soft solref="0.02 1", zero joint armature/damping) are kept for backwards compatibility rather than new robotics models. Override them at the top of a project (full rationale and priority-ordered parameter guide in modeling.rst, .. _CTuning:, .. _CTuningDefaults:, .. _CTuningGlobal:, .. _CTuningModel:):

spec.option.integrator = mujoco.mjtIntegrator.mjINT_IMPLICITFAST  # DISCRETE for flex elasticity
spec.option.cone = mujoco.mjtCone.mjCONE_ELLIPTIC
spec.option.impratio = 10.0

spec.default.geom.solref = [0.005, 1.0]                 # Keep solref[0] >= 2 * timestep
spec.default.joint.armature = 0.01                      # Reflected rotor inertia (I_rotor * N^2)
spec.default.joint.damping = 0.1                        # Implicit in M + h*D at zero solver cost

Keep the default solimp: raising solimp[0] (e.g. to 0.95) halves rest penetration and creep but costs solver iterations, so reach for it only after solref and elliptic cones.

7. Collisions & Friction Tuning

Collision Filtering Bitmasks

Two geoms collide if and only if: (g1.contype & g2.conaffinity) || (g2.contype & g1.conaffinity)

# Visual-only geom: never collides; set mass=0 if omitting <inertial> so it
# does not add water-density (1000 kg/m^3) mass (inertiagrouprange defaults to "0 5")
body.add_geom(size=[0.1], contype=0, conaffinity=0, group=1, mass=0)

# Team A collides only with Team B
geom_a = body.add_geom(size=[0.1], contype=1, conaffinity=2)
geom_b = body.add_geom(size=[0.1], contype=2, conaffinity=1)

Contact Dimension (condim) & Friction

condim Active Friction Components Friction Index Used
1 Normal force only (frictionless) —
3 Tangential sliding friction friction[0]
4 Tangential + torsional (twisting) friction[0:2]
6 Tangential + torsional + rolling friction[0:3]
# High-friction contact for grasping
finger.add_geom(
    type=mujoco.mjtGeom.mjGEOM_CAPSULE,
    size=[0.01, 0.03],
    condim=4,
    friction=[1.2, 0.02, 0.0001],
)

For contact softness, solver impedance/reference tuning (solref, solimp, priority/mixing), and why parent-child geoms omit collisions by default, read modeling.rst (.. _CTuning:, .. _CTuningModel:, .. _CSolver:, .. _CContact:) and overview.rst (.. _SurprisingCollisions:, .. _Soft:, .. _Units:).

8. Procedural Meshes, Materials & Sensors

Procedural Meshes

vertices = np.array([[0, 0, 0], [1, 0, 0], [0, 1, 0], [0, 0, 1]], dtype=np.float32)
faces = np.array([[0, 2, 1], [0, 1, 3], [0, 3, 2], [1, 2, 3]], dtype=np.int32)
mesh = spec.add_mesh(name='tetra', uservert=vertices.flatten(), userface=faces.flatten())
body.add_geom(type=mujoco.mjtGeom.mjGEOM_MESH, meshname='tetra')

Concave collision meshes are replaced by their convex hulls (unless using SDF plugins); prefer primitives (sphere, capsule, box, cylinder) for both speed and cleaner normals, or pre-decompose non-convex assets offline with CoACD or mjfit (see computation/index.rst, .. _coChecking: and .. _coDecomposition:).

Procedural Sensors

# IMU Accelerometer and Gyroscope
spec.add_sensor(name='torso_acc', type=mujoco.mjtSensor.mjSENS_ACCELEROMETER,
                objtype=mujoco.mjtObj.mjOBJ_SITE, objname='imu_site')
spec.add_sensor(name='torso_gyro', type=mujoco.mjtSensor.mjSENS_GYRO,
                objtype=mujoco.mjtObj.mjOBJ_SITE, objname='imu_site')

9. Common Gotchas & Best Practices

  1. Non-zero geom sizes: Geoms with radius or half-extents of zero cause immediate compilation errors.
  2. classname takes an object: geom.classname = 'rubber' raises a TypeError. Pass the MjsDefault instance: geom.classname = rubber.
  3. Always assign recompile(): spec.recompile(m, d) produces newly allocated model and data instances. Reassign them: m, d = spec.recompile(m, d) (see programming/modeledit.rst, .. _meRecompilation:).
  4. Declare high-contact "hub" bodies first (reverse-Cholesky fill-in): When a moving body with DOFs (e.g., an actuated tray, sieve, container, or robot base) contacts many independent clutter bodies, declare the hub body before the independent bodies so mju_cholFactorSparse factors the mass/Hessian arrowhead in $O(N)$ with zero fill-in rather than $O(N^3)$. Static geoms on worldbody have 0 DOFs and are unaffected — see the full derivation in modeling.rst (.. _CBodyOrdering:).
  5. Never add joints (including <freejoint/>) to the parent body of an unpinned <flexcomp> (except dof="2d" or "radial"). See mujoco-deformables for all <flexcomp>, <pin>, and <elasticity> rules.

10. Reference Models & Key References

Reference MJCF Models & Fixtures

Before authoring complex mechanisms or specialized elements from scratch, check existing models:

  • Built-in showcase models (../../../model/, or online at https://github.com/google-deepmind/mujoco/tree/main/model): model/humanoid/, model/tendon_arm/arm26.xml, model/car/car.xml, model/slider_crank/slider_crank.xml, model/flex/ (cables, cloth, soft bodies — see mujoco-deformables), model/replicate/ (newton_cradle.xml, particle.xml, bunnies.xml), model/plugin/ (actuator, sensor, SDF), model/tactile/, model/adhesion/, model/sleep/, model/speculative/, and model/plastic/.
  • MuJoCo Menagerie (models.rst, .. _Menagerie:): Production robot descriptions (Franka Panda/FR3, UR5e/UR10e, Unitree G1/H1/Go2, Spot, Barkour, Shadow Hand, Robotiq 2F-85, ALOHA 2, Skydio X2, Flybody) at https://github.com/google-deepmind/mujoco_menagerie.
  • Minimal test fixtures (../../../test/**/testdata/, or online under https://github.com/google-deepmind/mujoco/tree/main/test): Focused single-feature XMLs in test/user/testdata/ (MjSpec & compiler), test/xml/testdata/ (parent.xml / child.xml attachment fixtures, OpenUSD), and test/engine/testdata/ (collisions.xml, connect.xml, equality_site.xml, catenary.xml).

Documentation

Source Code & Notebook Examples

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No third-party reports yet.

Signed by skilld at eb1ff5e. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub yesterday.

Activeupdated 4 days ago
metadata
{
  "publisher": "google"
}

README badge

README badge for google-deepmind/mujoco/specediting