[FEATURE] Add support of 'contype'/'conaffinity' for primitive and mesh entities.

[Kashu7100]

Description

Extend contype and conaffinity to entity level.

How Has This Been / Can This Be Tested?

This can be used for RL setup where you only want the plane to collide with object not a hand for grasping task.

Screenshots (if appropriate):

Screen.Recording.2025-07-19.at.12.48.36.AM.mov

Note: contype and conaffinity are 32-bit integer bitmasks used for contact filtering of contact pairs.
When the contype of one geom and the conaffinity of the other geom share a common bit set to 1, two geoms can collide.

• Plane: contype=0xFFFF, conaffinity=0xFFFF (1111 1111 1111 1111) default value
• Red Cube: contype=1, conaffinity=1 (0001) -> collide with Plane and Blue Cube
• Green Cube: contype=2, conaffinity=2 (0010) -> collide with Plane and Blue Cube
• Blue Cube: contype=3, conaffinity=3 (0011) -> collide with Plane, Red Cube, and Green Cube
• Dragon: contype=4, conaffinity=4 (0100) -> collide with Plane only

Checklist:

• I read the CONTRIBUTING document.
• I followed the Submitting Code Changes section of CONTRIBUTING document.
• I tagged the title correctly (including BUG FIX/FEATURE/MISC/BREAKING)
• I updated the documentation accordingly or no change is needed.
• I tested my changes and added instructions on how to test it for reviewers.

• I have added tests to cover my changes.
• All new and existing tests passed.

[YilingQiao]

Can you add a unit test for each feature added?

[duburcqa]

Move this comment on the very top of this file.

[duburcqa]

Do not skip line between each add_entity

[duburcqa]

I'm not OK with this change. I see what you are trying to achieve and it makes sense, but it has unacceptable side-effects I think.

Typically, if you import twice the same robot, then the same mask will apply to each robot, which means that some parts of different robots will not be able to collide with each other anymore. To be more specific, if contype/conaffinity is defined on some humanoid robot in a way to prevent the hip from colliding with the tight, and if you add 2 robots, the hip of the first robot will not be able to collide with the tight of the other robot either, which is probably undesirable.

I would suggest to add is_collision_mask_local: bool = True to RigidEntity morph options. This boolean would control whether contype and conaffinity masks are entity-local and global for the entire scene. If there are global, there is nothing to do, but if there are global, you must find a way to update the masks accordingly, which seems to be tricky.

What do you think @YilingQiao ?

[Kashu7100]

Thanks for pointing out. Yes I think this can cause a problem.

[YilingQiao]

I prefer the revised version for several reasons:

1. This matches MuJoCo’s behavior (i.e., the entity is not considered when filtering based on coaffinity). We don’t need to introduce additional concepts.
   https://github.com/google-deepmind/mujoco/blob/4f43a7d08e4f1289f4d76a4c48b8f42aca5bb38b/src/engine/engine_collision_driver.c#L1479

2. Importing the same robot twice is not a common use case. We haven’t done this in our demos or applications. We might not have to increase the system complexity / divergence from mujoco to support a rare condition.

3. If users really want to use two robots, they can modify the coaffinity bitmask of the two robots—perhaps not through a well-exposed API, but by manually editing the coaffinity in the XML file—to ensure that the pair across entities is not filtered out.

4. Or we can have is_collision_mask_local, but maybe default to False to match mujoco, unless some advanced users want?

[duburcqa]

Please refrain yourself from reformatting documentation that you did not update (I mean adding or removing actual content). This is making the diff much harder to read.

[Kashu7100]

Ok, just wanted to enforce the 120 char rule for the file.