avian2d/collision/
mod.rs

1//! Collision detection for [`Collider`]s.
2//!
3//! Collision detection involves determining pairs of objects that may currently be in contact
4//! (or are expected to come into contact), and computing contact data for each intersection.
5//! These contacts are then used by the [solver](dynamics::solver) to generate [`ContactConstraint`]s
6//! and finally resolve overlap.
7//!
8//! [`ContactConstraint`]: dynamics::solver::contact::ContactConstraint
9//!
10//! # Plugins
11//!
12//! In Avian, collision detection is split into two plugins:
13//!
14//! - [`BroadPhasePlugin`]: Finds pairs of entities with overlapping [AABBs](ColliderAabb) to reduce the number of potential contacts for the [narrow phase](narrow_phase).
15//! - [`NarrowPhasePlugin`]: Updates and manages contact pairs in the [`ContactGraph`], and generates [`ContactConstraint`]s for the solver.
16//!
17//! Spatial queries are handled separately by the [`SpatialQueryPlugin`].
18//!
19//! You can also find several utility methods for computing contacts in the [`contact_query`](collider::contact_query) module.
20//!
21//! # Accessing Collisions
22//!
23//! Contact pairs found by Avian are stored in the [`ContactGraph`] resource.
24//! It contains all contacs between entities with overlapping [`ColliderAabb`]s,
25//! including contacts where the colliders themselves may not be touching.
26//!
27//! To make it easier to access relevant collision data, Avian provides a [`Collisions`]
28//! system parameter that only provides touching contacts. This is a light wrapper
29//! around the [`ContactGraph`] that can often be more convenient to use.
30//!
31//! See the documentation of [`Collisions`] for more information and usage examples.
32//!
33//! # Collision Events
34//!
35//! [Collision events](collision_events) can be used for detecting when colliders start or stop touching.
36//!
37//! Avian provides two collision event types:
38//!
39//! - [`CollisionStart`]: Triggered when two colliders start touching.
40//! - [`CollisionEnd`]: Triggered when two colliders stop touching.
41//!
42//! Depending on your use case, you may want to read them as [`Message`]s with a [`MessageReader`],
43//! or observe them as [`Event`]s with an [observer]. Avian supports both options.
44//!
45//! Collision events are only sent or triggered for entities that have the [`CollisionEventsEnabled`] component.
46//!
47//! See the documentation of the event types and the [`collision_events`] module
48//! for more information and usage examples.
49//!
50//! [`Message`]: bevy::ecs::message::Message
51//! [`MessageReader`]: bevy::ecs::message::MessageReader
52//! [`Event`]: bevy::ecs::event::Event
53//! [observer]: bevy::ecs::observer::Observer
54//!
55//! # Contact Filtering and Modification
56//!
57//! Some advanced contact scenarios may need to filter or modify contacts
58//! with user-defined logic. This can include:
59//!
60//! - One-way platforms
61//! - Conveyor belts
62//! - Non-uniform friction and restitution
63//!
64//! In Avian, this can be done by defining [`CollisionHooks`]. They let you hook into
65//! the collision pipeline, and filter or modify contacts with (almost) full ECS access.
66//!
67//! See the documentation of [`CollisionHooks`] for more information and usage examples.
68
69pub mod broad_phase;
70pub mod collider;
71pub mod collision_events;
72pub mod contact_types;
73pub mod hooks;
74pub mod narrow_phase;
75
76mod diagnostics;
77pub use diagnostics::CollisionDiagnostics;
78
79/// Re-exports common types related to collision detection functionality.
80pub mod prelude {
81    pub use super::broad_phase::{BroadPhasePlugin, BroadPhaseSystems};
82    #[cfg(all(feature = "collider-from-mesh", feature = "default-collider"))]
83    pub use super::collider::ColliderCachePlugin;
84    pub use super::collider::{
85        AabbContext, AnyCollider, ColliderAabb, ColliderBackendPlugin, ColliderDisabled,
86        ColliderMarker, CollidingEntities, CollisionLayers, CollisionMargin,
87        ContactManifoldContext, IntoCollider, LayerMask, PhysicsLayer, ScalableCollider, Sensor,
88        SimpleCollider,
89        collider_hierarchy::{ColliderHierarchyPlugin, ColliderOf, RigidBodyColliders},
90        collider_transform::{ColliderTransform, ColliderTransformPlugin},
91    };
92    #[cfg(all(
93        feature = "default-collider",
94        any(feature = "parry-f32", feature = "parry-f64")
95    ))]
96    pub use super::collider::{
97        Collider, ColliderConstructor, ColliderConstructorHierarchy,
98        ColliderConstructorHierarchyReady, ColliderConstructorReady, FillMode, TrimeshFlags,
99        VhacdParameters,
100    };
101    #[expect(deprecated)]
102    pub use super::collision_events::{
103        CollisionEnd, CollisionEventsEnabled, CollisionStart, OnCollisionEnd, OnCollisionStart,
104    };
105    pub use super::contact_types::{
106        Collisions, ContactEdge, ContactGraph, ContactManifold, ContactPair, ContactPairFlags,
107        ContactPoint,
108    };
109    pub use super::hooks::{ActiveCollisionHooks, CollisionHooks};
110    #[expect(deprecated)]
111    pub use super::narrow_phase::{
112        NarrowPhaseConfig, NarrowPhasePlugin, NarrowPhaseSet, NarrowPhaseSystems,
113    };
114}
115
116#[expect(unused_imports)]
117use crate::prelude::*;
avian2d/collision/mod.rs

avian2d/collision/
mod.rs
