Module collision

Collision detection for Colliders.

Collision detection involves determining pairs of objects that may currently be in contact (or are expected to come into contact), and computing contact data for each intersection. These contacts are then used by the solver to generate ContactConstraints and finally resolve overlap.

Plugins

In Avian, collision detection is split into two plugins:

• BroadPhasePlugin: Finds pairs of entities with overlapping AABBs to reduce the number of potential contacts for the narrow phase.
• NarrowPhasePlugin: Updates and manages contact pairs in the ContactGraph, and generates ContactConstraints for the solver.

Spatial queries are handled separately by the SpatialQueryPlugin.

You can also find several utility methods for computing contacts in the contact_query module.

Accessing Collisions

Contact pairs found by Avian are stored in the ContactGraph resource. It contains all contacs between entities with overlapping ColliderAabbs, including contacts where the colliders themselves may not be touching.

To make it easier to access relevant collision data, Avian provides a Collisions system parameter that only provides touching contacts. This is a light wrapper around the ContactGraph that can often be more convenient to use.

See the documentation of Collisions for more information and usage examples.

Collision Events

Collision events can be used for detecting when colliders start or stop touching.

Avian provides two collision event types:

• CollisionStart: Triggered when two colliders start touching.
• CollisionEnd: Triggered when two colliders stop touching.

Depending on your use case, you may want to read them as Messages with a MessageReader, or observe them as Events with an observer. Avian supports both options.

Collision events are only sent or triggered for entities that have the CollisionEventsEnabled component.

See the documentation of the event types and the collision_events module for more information and usage examples.

Contact Filtering and Modification

Some advanced contact scenarios may need to filter or modify contacts with user-defined logic. This can include:

• One-way platforms
• Conveyor belts
• Non-uniform friction and restitution

In Avian, this can be done by defining CollisionHooks. They let you hook into the collision pipeline, and filter or modify contacts with (almost) full ECS access.

See the documentation of CollisionHooks for more information and usage examples.

Modules

broad_phase

Finds pairs of entities with overlapping ColliderAabbs to reduce the number of potential contacts for the narrow phase.

collider

Components, traits, and plugins related to collider functionality.

collision_events

Collision events for detecting when colliders start or stop touching.

contact_types

Contact types and data structures used in the collision pipeline.

hooks

Collision hooks for filtering and modifying contacts.

narrow_phase

Manages contacts and generates contact constraints.

prelude

Re-exports common types related to collision detection functionality.

Structs

CollisionDiagnostics

Diagnostics for collision detection.