Release list

3.13.0 Latest

Latest

mmossg released this 09 Sep 15:03

3.13.0

123347c

Version 3.13.0 (September 8, 2026)

General

eb18d77ca The .mjz encoder now writes the root file as model.xml in the archive as
this is less susceptible to breakage due to file renaming.
4affbb64a Site geometries can now also be associated with meshes (type="mesh" with
mesh="name"), supporting visualization, the insidesite
sensor, and the new mj_insideSite function.
b59b07fae Added support for Python 3.15 (GIL and Free-Threading).

Engine

5660353ec Added a new integrator discrete: the constraint solve and the implicit velocity update merge
into one operation, performed in the effective metric $\widehat{M} = M + hD + h^2K$, which incorporates both
implicit damping $hD$ and implicit position stiffness $h^2 K$. Under this integrator mjData.qacc is
the discrete step map $(v^+ - v)/h$, and joint, tendon and actuator stiffness and damping join the solver's
metric, making passive springs and actuator position gains stable at timesteps far beyond the explicit stability
limit. Constraint rows are treated implicitly as well: solref spring--dampers are evaluated at the end of the
step, so constraints are stable at any timeconst; under this integrator the refsafe
flag replaces contact and limit rows stiffer than the timestep can resolve by the stiffest zero-restitution row
instead of clamping timeconst. The actuator-gain treatment resolves the stiff-servo timestep limitation of
#3443 (analysis contributed by @qiayuanl). See the
integrator documentation for semantics and current limitations.

Warning

Breaking API changes

Removed the implicit flex effective-metric special case under implicit/implicitfast with the CG
solver, introduced in 3.11.0. This behavior now requires integrator="discrete" (with a primal solver:
CG or Newton), which additionally treats joint damping and stiffness implicitly inside the solve. Models
relying on the old behavior should set integrator to discrete; models with flex
elasticity or passive flex contact under implicit/implicitfast now raise a runtime error carrying this
migration note.

0b4e17747 Restored clamping of non-positive pivots in the sparse inertia factorization, along with the
associated mjWARN_INERTIA warning. The guard was inadvertently dropped in the 3.3.0 conversion of qLD to CSR
format; since then, models with singular mass matrices silently produced non-finite accelerations, typically
surfacing as divergence warnings and automatic resets.
c9d997610 Added single-shot multicontact for collisions with cylinder geoms.
10eeb8289 The Newton solver with elliptic cones now rebuilds the cone-augmented Hessian
factor with a single refactorization instead of per-contact rank-1 updates when a flop-count model predicts this is
faster. Scenes with many simultaneously sliding contacts speed up by 1.4-2x on average and 3-4x on the slowest steps.
Contribution by @kevinzakka.

Compiler

2a3957558 Custom text fields (custom/text) in MJCF now accept their values inside a
<![CDATA[ ... ]]> block in addition to the data attribute. When saving a model via mj_saveXML, custom
text containing newlines or XML characters is exported as CDATA.
47ebfe48a Added cutoff attribute to sensor/tactile.

Samples

834983fbb Added render.cc: a headless offscreen rendering sample that saves an image to a
PNG image. Supports both the Filament and classic OpenGL backends, with command-line options for camera, resolution,
keyframe, simulation steps, geom/site groups, visualization and rendering flags, labels, and frames.

Bug fixes

67562d95f Rewrote the Plane-Mesh collider to fix bugs and improve performance. Fixes #3524.

Models

f6c1004b7 Added house of cards
example model and three free-standing arch
models: roman, gothic, and hyperbolic. Inspired by Song et al.

Rendering

Warning

Breaking API changes

cb57b526f For materials with physically-based rendering parameters that do not provide a metallic
texture the fallback is now white. Previously the fallback was black, which caused scalar metallic values to be
discarded when multiplied in the PBR shader.

Assets 10

3.12.0

mmossg released this 20 Aug 11:11

3.12.0

13827e9

Version 3.12.0 (August 20, 2026)

General

3f8db4c1 The MJCF grammar is now defined in a single source of truth schema file, src/xml/mjcf.schema. The parser's grammar table, presence constraints, keyword maps, typed attribute bindings and save policies are generated from it and gated by tests, as are the schema's enum keywords and declared defaults against the C headers and default-constructors.

Warning

Breaking API changes
2. 6fe04aa8 Removed the custom binary texture format (image/vnd.mujoco.texture) and the automatic fallback to custom textures when loading files with unrecognized extensions. Textures can now only be loaded from PNG (image/png) and KTX (image/ktx) files.

Actuation

279df98c Added the pid actuator: a PID controller with real position and velocity setpoint inputs, optional integral action (ki, integrating the position error with imax anti-windup), setpoint rate limiting (slewmax), and an optional feedforward input. This subsumes the functionality of the mujoco.pid plugin with proper activation state: correct under all integrators and visible to keyframes and sensors. With a zero velocity setpoint it is identical to position. The input signature is any subset of [pos, vel, ff], selected by input; absent setpoint inputs are fixed at zero, so the control vector contains no inert entries.
2f1843f4 The dcmotor on-board controller is redesigned: the input attribute selects any subset of [pos, vel, ff, voltage], where pos and vel are setpoints for the controller, ff is a torque feedforward, and voltage is the raw terminal voltage (the default, a plain voltage-commanded motor). Controller gains are in torque space, as for pid, and the drive voltage compensates back-EMF as in a current-controlled driver: commanded torque is delivered exactly until a limit is reached. The keyword input="none" selects the empty signature: the actuator has no control inputs and is purely passive, so friction, cogging and back-EMF braking can be used as passive joint forces.

Warning

Breaking API changes
5. 2f1843f4 The mode-flag semantics of dcmotor/input ("voltage", "position", "velocity", selecting the interpretation of a single control) are replaced by input signatures, and the controller gains changed from voltage space to torque space. The old velocity mode's integral term (integrated-velocity tracking) is retired without replacement; the integrator always accumulates position error.

Migration: Voltage-commanded motors (the default) are unchanged. Replace input="position" with input="pos" and input="velocity" with input="vel", and multiply the controller gains by $K/R$ (torque per volt). The motor's back-EMF damping, previously felt in addition to the controller's damping, is now compensated: to preserve behavior when the velocity setpoint is zero, add $K^2/R$ to the converted kd.

Engine

83e621d7 Optimized large-mesh convex collision detection with up to 2x speedup in certain cases.
55d13aec Replaced the per-step sparse Cholesky factorization of the flex block of the implicit effective metric M + K with its prefactored per-vertex 3x3 diagonal blocks. The blocks precondition the CG constraint solver and drive an iterative solve for qacc_smooth, which now converges on tolerance rather than a fixed threshold. Flexes with elastic2d stretch stiffness step roughly twice as fast; bending-only flexes keep the exact constant factor and are unchanged.
86e98601 Rewrote cleaner box-box SAT collider.

Warning

Breaking API changes
9. 2a3554c8 Contacts of a flex with passive collisions are now integrated implicitly: their stiffness is carried by the effective metric rather than applied as an explicit spring, and can be far stiffer than the timestep would otherwise permit. Models using passive collisions should be re-checked: the feature now requires implicit or implicitfast with the CG solver, pyramidal cones and sleep disabled; passive handling covers flex-flex, self-, and static-geometry contact, while contact with a moving body stays on the constraint solver; and the stiffness is now a mass-scaled natural frequency rather than a fixed 1e4.
10. 55d13aec Removed mjData.efm_L_rownnz, mjData.efm_L_rowadr and mjData.efm_L_colind. They described the sparsity of the effective-metric Cholesky factor, which no longer exists; mjData.efm_L now holds dense 3x3 blocks, 9 numbers per covered vertex. mjData.efm_active no longer takes the value 2: nothing selects a solve path on preconditioner exactness, so it is now a plain 0/1 flag.
11. 1362a8bd Changed the default value of bvactive from "true" to "false". This avoids unnecessarily clearing bounding volume hierarchy visualization flags at every simulation step, which can be a bottleneck for models with large meshes.
12. ed13bf56 Mocap bodies and their dof-less descendants are now the root of their own weld group: mjModel.body_weldid of a mocap body equals its own id rather than 0. Consequences: dragging a mocap body into sleeping objects now wakes them; children of mocap bodies receive standard parent-child collision filtering; mocap bodies no longer count as static geometry for ray casting, and contact-matching sensors aggregate their contacts under the mocap body rather than the world; and geom pairs where neither body can move no longer generate contacts.

Models

2a3554c8 Added drape example model: three cloths draped over a sphere, demonstrating passive collisions. It replaces the sphere_passive model, which has been removed.
55d13aec Added bag example model: a cloth bag, held open by pinning the ring of vertices around its mouth, catching the standard humanoid dropped in from above. Unlike the poncho models, which are bending-only, this model exercises the 2D stretch elasticity of a flex.

Rendering

Warning

Breaking API changes

cc7fb98c Added explicit texture coordinates to built-in geometries (Plane, Box, Sphere, Ellipsoid, Capsule, Cylinder) in both the Classic renderer and Filament. 2D textures applied to primitive shapes will look different as textures are mapped using canonical UV parameterizations rather than projecting onto the $x,y$ plane.

For finite planes, textures are now anchored to the bottom-left corner instead of the center. This will cause the most common visual breakage, as common procedural checker textures will be phase shifted. Infinite planes continue to be anchored at the origin with no visual changes.
f9a00bd5 Added light/softness: edge softness for spotlights under physically-based lighting models, given as the fraction of the cone over which intensity falls to zero. The default of 0.2 is a semi-soft cone which delivers the full intensity everywhere inside it, ...

Assets 10

3.11.0

mmossg released this 28 Jul 01:17

3.11.0

b85fdca

Version 3.11.0 (July 27, 2026)

Engine

4787c809 Added geom/surfacevel: the velocity of a geom's surface as seen by contacts, given as a velocity field with a constant component and a rotational component about the geom frame origin. This allows conveyor belts, treadmills and turntables to be modeled with static geoms and no degrees of freedom: friction drives touching bodies along the motion of the surface, with the field projected onto each contact's tangent plane. Surface velocities compose correctly with each other and with body motion. Note that the contact rows of mjData.efc_vel, and the constraint-state sensors that read them, report the velocity relative to the moving surface rather than to the geom, since that is the quantity the constraint acts on; for geoms without surfacevel the two are identical. Contact-point visualization draws an arrow along the surface velocity at contacts with moving surfaces.
a264d0bc Added geom/adhesion and pair/adhesion: an adhesive force associated with a contact, useful for modeling sticky materials. Contacts can pull with up to the given force before breaking, and the friction budget becomes $\mu(f_N + \text{adhesion})$. Combined with gap, adhesive contacts apply "adhesion at a distance", useful for modeling magnets. Resting penetration is unaffected by adhesion. mj_contactForce reports the net interface force, whose normal component can now be negative.
f0fa3d82 Replaced midpoint integration of free bodies with gyroscopic derivatives in the implicitfast integrator: the bias-force derivative of every standalone free body is applied via a local unsymmetric solve of its decoupled block, making implicitfast identical to implicit for such bodies. Unlike midpoint integration, which required vacuum and no constraints, this applies in all environments (contacts, fluid, constraints), and is compatible with discrete-time inverse dynamics. Spinning free bodies no longer gain energy, but tumbling motion is now mildly damped; models requiring long-horizon energy conservation of tumbling bodies in vacuum should use RK4. The invdiscrete flag no longer has any effect on forward dynamics.
5618666a Added body/simple attribute ("false"/"auto") to disable the simple body mass matrix optimization. This is useful for domain randomization, where model parameters may change post-compilation.
14c0b0c9 mj_setConst now recomputes the mjModel.{body,geom,site}_sameframe flags, to account for changes in body/geom/site frames after compilation.
2444defc Added support for multiccd with arbitrarily large meshes.
a04b0c5b Added flg_gravcomp and flg_surfacevel boolean flags to mjModel. These flags replace the fast-path checks as originally guarded by ngravcomp. Since the engine uses these integers as flags (zero vs. non-zero), the new flags are honest boolean properties, writeable from the Python bindings at runtime. The field ngravcomp is deprecated and will be removed in a future release.
a1f38c8e Replaced quadratic scratch in DFS flood-fill island discovery with a linear-memory Union-Find (disjoint set). Contribution by @teerthsharma.

Warning

Breaking API changes

ff629889 Changed the default value of sleep_tolerance from 1e-4 to 1e-3 (1mm/sec in SI units).
315bcfbf Removed the legacy sparse ancestor-walk inertia matrix mjData.qM. The joint-space inertia matrix is now stored exclusively in the compressed sparse row (CSR) format mjData.M.
7e9ac58f Switched mjd_inverseFD to use the CSR-format mjData.M representation instead of the legacy mjData.qM for the mass matrix derivative. This changes the shape of the DmDq parameter from (nv x nM) to (nv x nC).
1ea2d884 mju_round now breaks ties away from zero rather than towards $+\infty$. This only affects negative half-integers, e.g. mju_round(-2.5) now returns -3 rather than -2.
fa36015b Removed unneeded mjvScene argument from mjv_moveCamera.
ba9a6503 Split up mjrfMeshData into mjrfMeshData and mjrfMeshConfig to allow reuploading of mesh data without having to recreate the mesh object. Introduces mjrf_defaultMeshConfig and mjrf_setMeshData functions.
ba9a6503 Removed bytes field from mjrVertexAttribute.

Caution

Breaking ABI changes

072e963f mjModel gained the actuator_ctrlspec field (input signature of each actuator), and mjsActuator gained ctrlspec, changing their size and layout. The mjtGain and mjtBias enums gained so3 members, shifting the values of mjGAIN_USER and mjBIAS_USER.
d43c3ed4 Added texid, texuniform and texrepeat fields to mjvGeom.
a264d0bc The mjContact struct gained an adhesion member, changing its size and layout.

Note

Bug fixes

dddb2767 Fixed a bug where body_margin excluded gap, causing the mid-phase collision filter to incorrectly prune in-gap contacts on multi-geom bodies.

Actuation

d507e921 Refactored actuator infrastructure in preparation for MIMO (multi-input multi-output) actuator support. Each actuator now has ctrlnum (number of controls) and outnum (number of force outputs). The total counts nu = sum(ctrlnum) and nout = sum(outnum) dimension mjData.ctrl and mjData.actuator_force, respectively, nactuator is the number of actuators. For existing actuators ctrnum = outnum = 1, so nactuator == nu == nout and existing code is unaffected.
56a93979 Setpoints of position and intvelocity servos acting on 3D rotational transmissions (ball joints, or site transmissions with a refsite and purely rotational gear) are now interpreted on the circle: the force uses the setpoint representative nearest the current angle, so targets winding beyond half a turn are tracked continuously instead of slipping by full turns. Behavior is identical whenever the error does not exceed π. Relatedly, intvelocity actuators now expose actlimited, which was previously hardcoded to "true": as for [general](https:...