DetachableJoint: allow physics constraint properties to be set

[srmainwaring]

🎉 New feature

Allow joint constraint physics parameters to be set for detachable joints.

Depends on:

• DetachableJoint: allow physics constraint properties to be set gz-physics#754

Summary

• Add a parameter block with and sub elements.
• Update the Physics system to use the feature physics::SetDynamicJointConstraintPropertiesFeature
• Add optional fields to the detachable joint component.

Test it

Add a SDF parameter block to a model using a detachable joint:

    <plugin name="gz::sim::systems::DetachableJoint"
      filename="libgz-sim-detachable-joint-system.so">
      <parent_link>blade_rod_1a_link</parent_link>
      <child_link>blade_rod_1b_link</child_link>
      <child_model>rotor_head_cw</child_model>
      <joint_type>fixed</joint_type>
      <physics>
        <cfm>1.0e-6</cfm>
        <erp>0.8</erp>
      </physics>
    </plugin>

Inspect the console when running with verbose output:

(2025-06-30 15:16:29.373) [debug] [Physics.cc:1942] Creating detachable joint [318]
(2025-06-30 15:16:29.373) [debug] [Physics.cc:1956] SetConstraintForceMixing: 1e-06
(2025-06-30 15:16:29.373) [debug] [JointFeatures.cc:746] SetConstraintForceMixing: 1e-06
(2025-06-30 15:16:29.373) [debug] [Physics.cc:1964] SetErrorReductionParameter: 0.8
(2025-06-30 15:16:29.373) [debug] [JointFeatures.cc:760] SetErrorReductionParameter: 0.8

The default values of cfm and erp may result in simulation that is unable to constrain joints in a closed kinematic chain - resulting in the model flying apart (often followed by a segmentation fault). Increasing these parameters may result in a stable simulation.

Checklist

• Signed all commits for DCO
• Added tests
• Added example and/or tutorial
• Updated documentation (as needed)
• Updated migration guide (as needed)
• Consider updating Python bindings (if the library has them)
• codecheck passed (See contributing)
• All tests passed (See test coverage)
• While waiting for a review on your PR, please help review another open pull request to support the maintainers
• Was GenAI used to generate this PR? If so, make sure to add "Generated-by" to your commits. (See this policy for more info.)

Note to maintainers: Remember to use Squash-Merge and edit the commit message to match the pull request summary while retaining Signed-off-by and Generated-by messages.

[ntfshard]

Proposal: keep sdf structure similar to sdf joint definition http://sdformat.org/spec?ver=1.9&elem=joint
e.g. physics -> ode -> (new fields)
And also possible to use defaults from sdf instead of optional for consistency

[srmainwaring]

Proposal: keep sdf structure similar to sdf joint definition http://sdformat.org/spec?ver=1.9&elem=joint
e.g. physics -> ode -> (new fields)

I thought about this, but decided it was a little overkill adding another 2 or 3 layers of nesting. It's also a little confusing as the engine in use is dartsim not ode, and here and in some other places fields from one engine are used in another. Keeping the fields flat is more in line with the reworked physics libraries strategy of using typelists of features - if a library supports a feature it uses it, otherwise it is ignored.

And also possible to use defaults from sdf instead of optional for consistency

The question then is what defaults to use in SDF, and how to ensure that they are the same as what the physics engine is using? Using optional leaves the definition of defaults in one place - the physics engine, rather than placing them across the system.

[ntfshard]

Proposal: keep sdf structure similar to sdf joint definition http://sdformat.org/spec?ver=1.9&elem=joint
e.g. physics -> ode -> (new fields)

I thought about this, but decided it was a little overkill adding another 2 or 3 layers of nesting. It's also a little confusing as the engine in use is dartsim not ode, and here and in some other places fields from one engine are used in another. Keeping the fields flat is more in line with the reworked physics libraries strategy of using typelists of features - if a library supports a feature it uses it, otherwise it is ignored.

And also possible to use defaults from sdf instead of optional for consistency

The question then is what defaults to use in SDF, and how to ensure that they are the same as what the physics engine is using? Using optional leaves the definition of defaults in one place - the physics engine, rather than placing them across the system.

I guess in a perfect way it should be as same as original joint so using the same structure can allow to switch to existing parser(at least potentially). In future I want to add other joints types to this plugin tbh

[iche033]

I thought about this, but decided it was a little overkill adding another 2 or 3 layers of nesting. It's also a little confusing as the engine in use is dartsim not ode, and here and in some other places fields from one engine are used in another. Keeping the fields flat is more in line with the reworked physics libraries strategy of using typelists of features - if a library supports a feature it uses it, otherwise it is ignored.

there was a proposal related to this in gazebosim/sdformat#508, which proposes that we move away from engine-specific tags.