Update multiccd documentation.

PiperOrigin-RevId: 902779253
Change-Id: I767cd0a230b78efe2a71f83e5f2f134268997dcb

doc/XMLreference.rst

@@ -677,7 +677,7 @@ from its default.
 
 .. _option-flag-multiccd:
 
-:at:`multiccd`: :at-val:`[disable, enable], "disable"`
+:at:`multiccd`: :at-val:`[disable, enable], "enable"`
    This flag enables multiple-contact collision detection for geom pairs that use a general-purpose convex-convex
    collider e.g., mesh-mesh collisions. This can be useful when the contacting geoms have a flat surface and the
    single contact point generated by the convex-convex collider cannot accurately capture the surface contact, leading

doc/changelog.rst

@@ -14,6 +14,14 @@ General
   number of degrees of freedom per constraint row. The equality can be associated with a specific cell with the new
   attribute ":ref:`cell <equality-flexstrain-cell>`
 
+  .. admonition:: Breaking API changes
+   :class: attention
+
+   - The feature :ref:`multiccd<coMultiCCD>` is now enabled by default. This feature has little performance overhead
+     and gives better contact behavior for stability.
+
+     **Migration:** The flag :ref:`multiccd<option-flag-multiccd>` must be explicitly disabled.
+
 Version 3.7.0 (April 14, 2026)
 ------------------------------
 

doc/computation/index.rst

@@ -1656,23 +1656,25 @@ Both pipelines are controlled by a tolerance (in units of distance) and maximum
 
 Multiple contacts
 ^^^^^^^^^^^^^^^^^
-Some colliders can return more than one contact per colliding pair to model line or surface contacts, as when two flat
+Some colliders can return more than one contact per colliding pair to model edge or surface contacts, as when two flat
 objects touch. For example the capsule-plane and box-plane colliders can return up to two or four contacts,
-respectively. Standard general-purpose convex collision algorithms like MPR and GJK always return a single contact
+respectively. Standard general-purpose convex collision algorithms like MPR and GJK/EPA always return a single contact
 point, which is problematic for surface contact scenarios (e.g., box-stacking). Both of MuJoCo's CCD pipelines can
 return multiple points per contacting pair ("multiccd"). This behavior is controlled by the
 :ref:`multiccd<option-flag-multiccd>` flag, but is implemented in different ways with different trade-offs:
 
-libccd pipeline (legacy)
+multi-run pipeline (legacy)
   Multiple contact points are found by rotating the two geoms by ±1e-3 radians around the tangential axes and
   re-running the collision routine. If a new contact is detected it is added, allowing for up to 4 additional contact
-  points. This method is effective, but increases the cost of each collision call by a factor of 5.
+  points. This method is effective, but increases the cost of each collision call by a factor of 5.  This method is
+  used when the :ref:`nativeccd<option-flag-nativeccd>` flag is disabled, and for geoms collisions involving cylinders
+  and capsules or with :ref:`positive contact margins<body-geom-margin>`.
 
-native pipeline
-  Native multiccd discovers multiple contacts using a novel analysis of the contacting surfaces at the solution,
-  avoiding full re-runs of the collision routine, and is thus effectively "free". Note that native multiccd currently
-  does not support positive contact margins. If one of the two geoms has a positive margin, native multiccd will fall
-  back to legacy algorithm.
+single-shot pipeline
+  The single-shot pipeline is used in conjunction with the native CCD pipeline, i.e., when the
+  :ref:`nativeccd<option-flag-nativeccd>` flag is enabled. As this pipeline is one-shot and most of the geom analysis
+  is done at compilation time, there is very little performance overhead. Supported geoms are boxes and meshes without
+  :ref:`positive contact margins<body-geom-margin>`.
 
 .. _coDistance:
 

doc/mjwarp/index.rst

@@ -1265,8 +1265,6 @@ is available by setting the ``NATIVECCD`` disable flag:
 The specialized collider generates up to 8 contact points, compared to up to 4 for the convex pipeline, and may improve
 contact stability for tasks involving box stacking or manipulation.
 
-.. TODO(taylorhowell): update this section once multiccd is on by default.
-
 CCD margin
 ----------
 
@@ -1283,8 +1281,8 @@ CCD colliders and will raise a ``NotImplementedError`` when calling :func:`mjw.p
      - Scenario
      - Workaround
    * - box-box, box-mesh, mesh-mesh
-     - :ref:`MULTICCD <option-flag-multiccd>` enabled
-     - Set margin to ``0`` or do not enable ``MULTICCD``
+     - :ref:`MULTICCD <option-flag-multiccd>` enabled (on by default)
+     - Set margin to ``0`` or disable ``MULTICCD``
    * - box-box
      - :ref:`NATIVECCD <option-flag-nativeccd>` enabled (on by default)
      - Set margin to ``0`` or disable ``NATIVECCD``

doc/modeling.rst

@@ -1767,10 +1767,11 @@ better visualize and understand the contact configuration and resulting forces.
 
   a. Improve the geometry of the contacting geoms in order to add more contact points, possibly with non-flat
      geometry (e.g., bumps), so slippage is prevented by the normal force and not only frictional components.
-  b. If contacts are between flat surfaces, try enabling the :ref:`multiccd<option-flag-multiccd>` flag, which allows
-     the detector to find more contacts than the single contact returned by the convex-convex collider.
-  c. Try enabling the native collision detection pipeline by setting the :ref:`nativeccd<option-flag-nativeccd>` flag,
-     which uses a more accurate and efficient convex collision detection algorithm.
+  b. If contacts are between flat surfaces, make sure that the flag :ref:`multiccd<option-flag-multiccd>` is not
+     disabled (enabled by default), as it allows the detector to find more contacts than the single contact
+     returned by the convex-convex collider.
+  c. Make sure that the flag :ref:`nativeccd<option-flag-nativeccd>` is not disabled (enabled by default),
+     as NativeCCD is a more accurate and efficient convex collision detection algorithm.
 
 **High-frequency vibration**
   High-frequency, low-amplitude vibrations are also a real-world problem in many industrial settings, but unlike in