Add per-shape collision filtering to the 3D physics system

[aaronfranke]

Describe the project you are working on

I am working on GLTF support in Godot.

Describe the problem or limitation you are having in your project

The Khronos group had a meeting about physics the day I am writing this proposal, and decided that GLTF collision filtering should be per-shape. The opinion of the Khronos group is that per-shape filtering is important, should be in the base GLTF physics extension spec, and the spec should require implementations to support this.

Godot currently only has per-body filtering, so if a GLTF file has a body with multiple shapes and each has per-shape filtering, it's not possible to import that file and have it behave the same. Technically you could import the data as multiple bodies, but that would likely break other things.

Describe the feature / enhancement and how it helps to overcome the problem or limitation

The enhancement is to add the collision filtering properties (layers and masks) to the CollisionShape3D node. This would allow us to have per-shape filtering, which allows us to import the Khronos group's proposed GLTF physics filtering.

Note that aside from GLTF compatibility, per-shape filtering may also be useful for Godot users in general. Many other engines have per-shape filtering, including Jolt, so adding this to Godot's physics nodes would help with using the full capabilities of third-party physics engines in Godot. During the Khronos group meeting they mentioned that most engines they've worked with had this feature and Godot is the odd one out here.

The same may wish to be done in 2D as well for feature parity - but for the moment, I am primarily interested in 3D.

Describe how your proposal will work, with code, pseudo-code, mock-ups, and/or diagrams

Add new properties to CollisionShape3D: collision_mask and collision_layer. These would work similarly to the properties on CollisionObject3D.

We also want to be careful not break compatibility by keeping this feature optional and to keep the per-body filtering working. How would the shape-based filtering interact with the body-based filtering? I see a few options. We could make the default be 0, and if non-zero it will override the body's filtering for that shape. Or maybe we could make the default be 2^32 - 1 and use it as a bitmask to compare against the body.

If this enhancement will not be used often, can it be worked around with a few lines of script?

It can't be worked around in script - at least, not without multiple bodies, which would likely break other things.

Is there a reason why this should be core and not an add-on in the asset library?

This is a core part of the physics system.

[webredraptors]

Is there a reason this is duplicated here: #7401 ?

[AThousandShips]

Separate topic, this is about filtering, that one is about materials, just part of the text is the same because the inspiration is the same, note the parts that are different not the parts that are the same

[mihe]

Many other engines have per-shape filtering, including Jolt, so adding this to Godot's physics nodes would help with using the full capabilities of third-party physics engines in Godot.

As mentioned here this ShapeFilter class in Jolt that you linked is only used for collision queries and not for general collision detection. As far as I'm aware it's only possible to (generally) filter on a per-body level in Jolt at the moment, using the per-body object layers coupled with ObjectLayerPairFilter and ObjectVsBroadPhaseLayerFilter. I can't speak to whether that's a fundamental design decision or something that could be added in a day, but that's how things are right now at least.

I can certainly see per-shape filtering being a useful feature though.

[jrouwe]

I don't think it's terribly complicated to add this. All the low level collision functions (which are used by the simulation too) support it, so it would be a matter of exposing this.

[jrouwe]

Per shape filtering has been implemented in Jolt in jrouwe/JoltPhysics#1362

[Avantir-Chaosfire]

This would be a useful feature in 2D too, particularly for CharacterBody2D. It would enable a single CharacterBody2D to move once with with move_and_collide but use different hitbox shapes for different environmental objects it could collide with. I believe right now, the only way to do this is to use two separate CharacterBody2Ds and have them always move in sync, and rollback movement on one if the other has a collision, which is very messy.

[eSavag]

This would be incredibly useful for raycast wheel based vehicles. These need wheels with separate collision layers to the vehicle body, which means that, currently, the wheels can only be attached to the vehicle via the physics joint system, which is currently lacking a clear and dependable solution for fixed joints. End result - wheels bending and flexing away from the vehicle body, unless you start adjusting collision shape positions every frame, not just every physics_process.

Raycast wheel vehicles are a common gamedev staple, so the above proposal would be a fantastic addition.

[tutabot]

I also need this for 2D.

[venilark]

I have a usecase in mind for this because right now inside a CharacterBody3D (and that's still waiting on this being merged godotengine/godot#77937) everything has to share the same layers and masks. If Jolt implemented it last year and other engines already have this feature...👀