Collision Filtering and Modification

[datael]

Future features in the readme lists Collision Filtering as something not yet implemented and I would like to get the ball rolling if possible.

Topics discussed in the xpbd help channel on Discord

Some topics that were discussed on Discord included:

1. Global physics hooks that can iterate over all collisions
2. Per-entity filter components
   • Filtering collisions with entities by EntityId
   • Filtering collisions by predicate
3. Being able to modify the individual contacts
4. The possibility of being able to use one-shot systems in the future
5. The possibility of being able to use entity relations to allow more efficient filtering

Global Physics hooks

Adding a schedule after the SubstepSet::NarrowPhase, and exposing a way to filter collisions from the Collisions resource gives a very open-ended and straightforward way to allow for modifying collisions.
I've got a working example on this fork here.

I'm in two minds about whether it's worth the schedule to have built-in sets (e.g. First, Filter, Modify, Last), or whether that complexity should be left up to the user. I can see a potential want to pre-filter collisions with faster filters before any slower ones execute, for example.

Per-entity filter components

@Jondolf suggested something in the following form:

ContactFilter::new()
        .with_excluded_entities([...])
        .with_predicate(|mut contact: ContactData| {
            // Modify contact (optional)
            contact.penetration = 0.1;
            // Return the contact or use None to ignore contact
            Some(contact)
        }),

It was also suggested that some form of combination rule may be needed to handle when two entities with conflicting filter predicates are present.

Modifying individual contacts

Being able to modify the individual contacts is desirable. Therefore, being able to return Some(contact) from a post-processing step is more useful than only being able to remove or keep collisions.

One-shot systems

@Jondolf showed the following code on Discord as something that it would be nice to be able to do. There was discussion about how this may not be possible with one-shot systems, but using run_system_with* may allow it as long as the overhead was acceptable.

* run_system_with was added to bevy with this merged but unreleased-at-the-time-of-writing pull request.

fn setup(mut commands: Commands, contact_hook_pipeline: ContactHookPipeline) {
    commands.spawn((
        ContactHook::new(
            &contact_hook_pipeline,
            |In(mut contact): In<ContactData>, query: Query<&MyBundle>| {
                // Modify contact, query for entities, do whatever
                // Return new contact data to narrow phase; if None, skip contact
                Some(contact)
            }
        ),
    ));
}

Entity Relations

Something along the lines of (Body1, CollidesWith(Contacts), Body2) was suggested by @Jondolf.

Bevy currently has a tracking issue for entity relations here: bevyengine/bevy#3742

Other notes/questions

Should filtering be treated as a separate issue from modification?

My current personal needs for collision filtering are very simplistic: I just want to implement one-way platforms, which is easily solved by the first bullet point above. I therefore have a very narrow view of what needs exist when it comes to being able to filter/modify collisions, and so would like to get input from other interested parties.

One shortfall of bevy_rapier that I would like to avoid was that it seemed impossible to register more than one set of query params to use with collision hooks because the parameters are registered on the plugin itself as a generic type. Being able to access queries while filtering and modifying collisions seems very important in an ECS.

Where to go from here

I've started work on global filters and entity-entity collision exclusion in a fork here, but am looking for input. I'd be interested in creating a pull request at some point, even if it's only for the global collision hook, as it's a small enough change that gives quite a bit of power from the get-go.

[Jondolf]

Thanks for such a thorough issue!

I would say that we should kick things off in the initial PR with "global physics hooks/filters" and excluding specific entities. This is probably the easiest and least controversial part, and it should already be enough for a lot of use cases.

Below are some of my current thoughts.

Global physics hooks (edit: done in #155)

For now, I would just add a custom schedule like you're currently doing. In my opinion, the separate system sets are unnecessary, since users can just use .after, .before and .chain to order the systems or create their own set. The schedule is basically empty by default, so there is nothing to order your systems relative to other than your own systems.

The main caveat with the approach of using a custom schedule and iterating over Collisions is that it adds a lot of iteration. We would iterate over all collisions once in the narrow phase, and however many times users iterate over them in their custom filter systems. With Rapier's approach, the filter is applied directly in the narrow phase, so it only iterates through all collisions once per physics frame (+ once in the solver).

The two main solutions I can currently come up with:

1. Rapier's approach of storing physics hooks in a resource and allowing users to implement the filtering logic. Fast, but not very flexible, ergonomic or ECS-like, and only allows one global filter.
2. Something like callbacks based on one-shot systems (again). Allows access to the ECS world, and could allow multiple (ordered) filters if the filtering systems are stored in e.g. a vector. Probably has extra overhead, needs to be benchmarked.

For now though, I think the approach of using a custom schedule like you're doing is perfectly fine for the initial implementation. Even if we eventually implemented some other approach, the filtering could still be done in the custom schedule.

Excluding specific entities

For excluding specific entities, I recommend moving the logic into the broad phase, next to the collision layer filtering. It's unnecessary and expensive to compute contacts in the narrow phase between entities that will be ignored later.

In terms of the component name, I'm a bit torn. CollisionFilter looks nice, but if it only contains excluded entities, some other name might make more sense. We also already have CollisionLayers, which is a type of collision filter but is under a separate component, so there might be some confusion.

I would say that it feels more ECS-like to have separate components for different types of filter/hook components, like ExcludedCollisionEntities (for the excluded entities), CollisionHook (for future predicate-based filtering) and ActiveCollisionTypes (for filtering by RigidBody type or whether a collider is a sensor, like Rapier). This would also play nicer with change detection, and if we really wanted to group the filters for querying ergonomics, we could instead have CollisionFilter be a world query. These names are just examples though, I'm open to other names.

Entity-level contact hooks

Component-based contact hooks/filters using something like one-shot systems would definitely be nice to have, and they would allow for ergonomic entity-specific logic without having to iterate over all of Collisions.

However, this will require some experimentation to discover potential caveats and find the best approach. I'm not sure if using callbacks like this is considered good or bad practise in the context of an ECS, as it hasn't really been possible before. I also suspect that one-shot systems would have extra overhead which might be significant if many entities have custom contact hooks.

[datael]

Apologies I've been a while getting back to you. I had some personal stuff come up so I haven't had much time to look at this.

Of the things above, I think adding a global filter is the one we're in agreement with, so I've created a pull request just implementing that. It includes an example in 2d of using the filter to implement a one-way platform.

Edit:
It would probably help if I linked it: #155