3.11.0

Version 3.11.0 (July 27, 2026)

Engine

1. 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.

   

2. 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.

   

3. 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.

4. 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.

5. 14c0b0c9 mj_setConst now recomputes the mjModel.{body,geom,site}_sameframe flags, to account for changes in body/geom/site frames after compilation.

6. 2444defc Added support for multiccd with arbitrarily large meshes.

7. 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.

8. 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

9. ff629889 Changed the default value of sleep_tolerance from 1e-4 to 1e-3 (1mm/sec in SI units).
10. 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.
11. 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).
12. 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.
13. fa36015b Removed unneeded mjvScene argument from mjv_moveCamera.
14. 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.
15. ba9a6503 Removed bytes field from mjrVertexAttribute.

Caution

Breaking ABI changes

16. 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.
17. d43c3ed4 Added texid, texuniform and texrepeat fields to mjvGeom.
18. a264d0bc The mjContact struct gained an adhesion member, changing its size and layout.

Note

Bug fixes

19. 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

20. 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.

21. 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 actuators it defaults to "auto", so activation clamping is enabled by specifying actrange. Unclamped integrated setpoints are well-behaved on rotational transmissions, where they wrap.

22. 072e963f Added the orientation actuator: a geodesic servo on a new SO(3) transmission (ball joints, or a site with a refsite), acting jointly on the full relative orientation with an exact equilibrium at every commanded orientation. This is the first actuator with multiple force outputs (3), and, with input="quat", the first with different input and output dimensions (4 controls, 3 outputs). The input signature is recorded in the new mjModel.actuator_ctrlspec, exposed as the input attribute.

23. 072e963f Added mj_actuatorInputName, returning the name of an actuator input (e.g. "qw" for the first control of a quaternion-commanded orientation actuator). The control sliders in simulate and MuJoCo Studio are now generated per control and labeled with the actuator name plus the input name suffix.

24. 072e963f Viewer control sliders now use a defined ctrlrange even when ctrllimited is "false": the range sets the slider span, while clamping remains controlled by ctrllimited.

25. 072e963f Added mj_resetCtrl, setting controls to neutral values: zero, except quaternion inputs which reset to the identity quaternion. Called by mj_resetData and the viewers' "Clear All".

Solvers

26. ea230a95 Flex elasticity (stretch, bending, interpolation stiffness) is now integrated implicitly inside the CG constraint solver via an effective metric: the mass matrix is augmented with the stiffness Hessian, so contact and elastic forces are solved against one consistent metric. This replaces the previous post-hoc CG correction, which modified qacc after the constraint solve. The gate is solver="CG" with an implicit integrator and flex stiffness present; Newton and PGS are unaffected. Bending-only models pay zero per-step factorization cost (the factor is precomputed in mj_setConst). Inverse dynamics (mj_inverse) is now discrete-consistent with forward dynamics for gated models.

27. c499f7f2 Added Nesterov momentum extrapolation with adaptive gradient restart (O'Donoghue-Candès) to the PGS solver, significantly improving convergence. Overall PGS now requires ~2x fewer iterations.

28. 1e66efd1 Added the Newton decrement -- the quadratic model's predicted cost improvement of the next iteration -- as a third early-termination criterion of the Newton solver, alongside cost improvement and gradient norm. This reduces iteration counts at no accuracy cost. Proposed by @adenzler-nvidia in MJWarp pull request 1520.

29. c69ef030 The CG and Newton solvers now terminate with zero iterations when a duality-gap certificate proves that the warmstarted solution already satisfies the tolerance. The certificate requires only the existing mass-matrix factorization, so quiescent scenes skip Hessian construction, factorization and the line search entirely. Newton zero-iteration exits additionally require the gradient criterion, preserving Newton's characteristic force-level accuracy. See Warmstart in the Computation chapter for details.

Compiler

30. 4e1795b9 mj_encode now supports encoding of MJB and TXT files.

31. c6c3ec31 The attach element now supports self-attachment (attaching elements of the current model to itself) by omitting the model attribute. It also supports attaching a frame via the new frame attribute, which is mutually exclusive with body.

32. 040872fd Fixed loading of .mjz archives in simulate: the archive was unmounted before model compilation, so assets failed to load. Failures in the mjz decoder now emit a warning with the underlying error instead of the generic "could not decode content" message.

33. ebd4abae The mjz decoder now searches for model.xml and <stem>/model.xml as a fallback if <stem>.xml and <stem>/<stem>.xml are not found.

34. dc7581ac Added support for resource writing via mju_writeResource and the write callback in mjpResourceProvider.

Warning

Breaking API changes

35. d83ef0b6 The return type of mj_encode and the mjfEncode callback changed from int to mjtSize (64-bit).

Note

Bug fixes

36. f5f9d9ef Fixed a bug in the mesh compiler where normals were scaled as vectors rather than covectors.

Python bindings

37. a07ae6f8 The bindings now support free threading (PEP 703) for Python 3.14.

Documentation

38. 1f1bfa9e Expanded documentation for spec.encode workflows and added detailed documentation for the MJZ Archive format (.mjz / .zip).