Opportunity for documentation improvement?

[GPeye]

Hello. I've been learning and discovering how bevy_rapier2d works and was introduced on the discord to a really good pattern that is arguably the ideal bevy ecs collision behavior handling pattern because it allows breaking things up into separate concern. Essentially it involves setting ActiveEvents::COLLISION_EVENTS on the colliding entities and then using a Query<&CollidingEntities, With<MyComponent>> to get active collisions that can be filters via other components to create systems that focus on specific behaviors related to the collision of specific components.

This seemed great until I tried to implement it and my query was returning nothing. The CollisionEvents were firing and and I could read them from the EventReader but nothing was getting set for the CollidingEntities. It had worked for others in discord but as I looked around for any examples or information in the docs, there are zero examples and zero information in the rapier.rs docs and only a very brief description of the function on docs.rs about CollidingEntities. If you google 'Bevy "CollidingEntities"' there a whopping 4 results and they don't show anything helpful. So I had to poke around the source to find this function and I see that it's basically looking for entities with that component. I was told on the discord that all I needed was ActiveEvents::COLLISION_EVENTS for it to work so I had assumed the application of the CollidingEntities component was automatic? I guess I was wrong. As soon as I added .insert(CollidingEntities::default()) also to my entity, suddenly now it was able to query for CollidingEntities properly. The problem is, the other person never mentioned needing to insert that manually so I have no idea if it's a new bug or just a missing detail. The other person had used this with bevy 0.7 and I was trying it in 0.8. Some or any amount of documentation about CollidingEntities would have really helped clear this up.

So that was my experience of luckily being given some nice but incomplete information from a random helpful person on discord that has zero documentation or really reference to it's existence on github or the rapier.rs and stumbling my way through into making it work. Being able to tell what two things are colliding is pretty important and even just that doesn't have any examples. While it can be done fairly easily with a system that uses EventReader<CollisionEvent>, it's hard to avoid having your handler not know way too much about the logic and interaction of different system that may be in different plugins entirely. Using a query on CollidingEntities matched with components that identify types of entities lets you create behavior specific systems that are much cleaner and contained. So perhaps it would be very beneficial to the community to document how it's supposed to work and perhaps include a working example to reference?

[sebcrozet]

Hi! Thank you for your feedback. I agree we should add an entry to the user-guide about CollidingEntities and how its works. The docs of CollidingEntities should also be improved by mentioning ActiveEvents::COLLISION_EVENTS too.