DetachableJoint fails with TPE physics engine due to missing AttachFixedJointFeature support

[Xinyu-Sheng]

Environment

Ubuntu 22.04
ROS2 humble
Gazebo Harmonic

Description

Expected behavior:
When using the DetachableJoint system plugin with a car (chassis) and a separate object (box::box_link), publishing an empty message to /box/attach should create a fixed joint between the two links, causing the box to be rigidly attached to the chassis and move together with it—just like with standard physics engines such as gz-physics-ode-plugin or gz-physics-dart-plugin.

Actual behavior:
When the physics engine is set to gz-physics-tpe-plugin, Gazebo prints the error:
[Err] [Physics.cc:1914] Attempting to create a detachable joint, but the physics engine doesn't support feature [AttachFixedJointFeature]. Detachable joints will be ignored.
As a result, no joint is created—the box remains unaffected by the attach command and does not bind to the chassis. The DetachableJoint plugin is effectively disabled because TPE does not implement the AttachFixedJointFeature required for runtime joint creation.

[azeey]

Currently, the TPE physics engine does not support joints at all (https://gazebosim.org/api/physics/9/physicsplugin.html), #304, but it maybe possible to add the AttachFixedJointFeature without having to support all other types of joints. I'll add the help wanted label on this. If you are interested in tackling this, let us know.

[Xinyu-Sheng]

I’ve implemented only the minimal functionality needed for fixed detachable joints in TPE. Specifically, I introduced a lightweight JointInfo struct solely to store the data required to simulate fixed joints at runtime—such as parent/child links and their relative transform. Since TPE lacks a constraint solver, I manually enforce the fixed-joint constraint in each simulation step in SimulationFeatures.cc. The core logic is just ~50 lines, and only three features are truly necessary: AttachFixedJointFeature, DetachJointFeature, and SetJointTransformFromParentFeature.

However, because DetachableJointFeatureList inherits from JointFeatureList, gz-sim forces TPE to implement 18 unrelated joint query/state methods (e.g., GetBasicJointState), even though they serve no purpose for fixed detachable joints. To satisfy the interface requirements, I had to add ~130 lines of empty stubs.

// gz-sim/src/systems/physics/Physics.cc
struct JointFeatureList : physics::FeatureList<
   MinimumFeatureList,
   physics::GetJointFromModel,        
   physics::GetBasicJointProperties,  
   physics::GetBasicJointState,       
   physics::SetBasicJointState>{};    

struct DetachableJointFeatureList : physics::FeatureList<
   JointFeatureList, 
   physics::AttachFixedJointFeature,
   physics::DetachJointFeature,
   physics::SetJointTransformFromParentFeature>{};

A better design would decouple detachable joint features from the full JointFeatureList, allowing lightweight engines like TPE to support dynamic attachment without having to pretend they support a full joint API.

@azeey

[iche033]

A better design would decouple detachable joint features from the full JointFeatureList, allowing lightweight engines like TPE to support dynamic attachment without having to pretend they support a full joint API.

I think that makes sense. Given that the DetachableJointFeatureList is defined in the physics system in gz-sim and not public exposing, it should be fine to remove the inheritance from JointFeatureList without introducing breaking changes.

[Xinyu-Sheng]

I tried to remove the inheritance from JointFeatureList in DetachableJointFeatureList, but encountered a compilation error in Physics.cc:

error: static assertion failed: YOU CANNOT IMPLICITLY UPCAST TO THIS ENTITY TYPE, 
BECAUSE IT CONTAINS A FEATURE THAT IS NOT INCLUDED IN THE ENTITY THAT YOU ARE CASTING FROM.

The issue is that EntityJointMap is defined as:

public: using EntityJointMap = EntityFeatureMap3d<
          physics::Joint,
          JointFeatureList,  // Base type requires these features
          DetachableJointFeatureList,
          ...
          >;

When a detachable joint is created, it's stored in entityJointMap via AddEntity(). Since EntityJointMap uses JointFeatureList as its base type, the joint entity must support all features in JointFeatureList (GetJointFromModel, GetBasicJointProperties, GetBasicJointState, SetBasicJointState).
To properly decouple DetachableJointFeatureList, it seems we would need to either:

1. Create a separate EntityDetachableJointMap that doesn't depend on JointFeatureList
2. Or modify how detachable joints are stored

I'll first try to merge a gz-physics PR (with stub implementations).

[azeey]

The intent of DetachableJoint was to eventually support detaching/attaching all kinds of joints, not just fixed joints, so it makes sense for it to require the JointFeatureList. However, since it's useful to allow just fixed joints to be supported, it makes sense to go with creating a separate EntityDetachableJointMap. But how do we make sure we still have a path forward to support different types of joints for physics engines that suppor them?

[Xinyu-Sheng]

@azeey

Thanks for the suggestion about creating a separate EntityDetachableJointMap. I've implemented Scheme 2 as discussed, which takes a similar approach but with minimal architectural changes.

Scheme Evaluation

Before implementing, I evaluated three potential approaches to decouple detachable joints from the full joint API:

Scheme 1: Hierarchical Feature List Design

Approach: Create BasicJointFeatureList, FullJointFeatureList, and DetachableJointFeatureList in a layered architecture
Impact: 8-10 files modified, high breaking changes, refactor all physics engine plugins
Drawback: Too disruptive, requires updating all existing engines simultaneously

Scheme 2: Joint Mapping Design (Chosen)

Approach: Separate EntityDetachableJointMap while maintaining existing EntityJointMap unchanged
Impact: 3 files modified (gz-sim/Physics.cc + 2 TPE plugin files), minimal changes, zero breaking changes
Advantage: Clean separation, backward compatible, easy to extend

This provides the architectural benefits you suggested (separate mapping) while minimizing risk and avoiding complex runtime logic. The approach allows future joint types to follow the same pattern without disrupting existing code.

Details

Architecture Changes

// Before
struct DetachableJointFeatureList : physics::FeatureList<
    JointFeatureList,  // Forced all joint features
    physics::AttachFixedJointFeature,
    physics::DetachJointFeature,
    physics::SetJointTransformFromParentFeature>{};

// After
struct DetachableJointFeatureList : physics::FeatureList<
    MinimumFeatureList,  // Only minimal requirements
    physics::AttachFixedJointFeature,
    physics::DetachJointFeature,
    physics::SetJointTransformFromParentFeature>{};

New Mapping System

// Added separate mapping for detachable joints
public: using EntityDetachableJointMap = EntityFeatureMap3d<
    physics::Joint,
    DetachableJointFeatureList
>;

Code Improvements

• TPE plugin: Reduced from ~180 lines to ~50 lines of joint code
• Eliminated: 100+ lines of stub implementations
• Maintained: Full detachable joint functionality

Validation Results

• ✅ Compilation: gz-sim8 and gz-physics7 build successfully
• ✅ Functionality: Detachable joints work correctly in gz-sim
• ✅ Tests: All physics engine tests pass
• ✅ Backward compatibility: Existing code unchanged

PS: I have already implemented stub methods in PR #832, which do not require changes to gz-sim's code. And I’m curious—why was the DetachableJoint originally designed with the intention of eventually supporting detachment and reattachment for all types of joints, not just fixed joints? What kinds of scenarios would really benefit from being able to dynamically detach and reattach more complex joint types？

[Xinyu-Sheng]

Suggest merging PR #832 (with stubs) first to enable detachable joint support in TPE as soon as possible. The stubs have negligible performance impact and require no changes to gz-sim core. Architectural decoupling can follow later.