Struct ContactGraph

pub struct ContactGraph {
    pub edges: ContactGraphInternal,
    /* private fields */
}

A resource that stores all ContactEdges in the physics world in an undirected graph, and their corresponding ContactPairs.

Contact pairs exist between colliders that have intersecting AABBs, even if the shapes themselves are not yet touching. Internally, pairs for active (non-sleeping) bodies are stored separately from pairs for sleeping bodies for optimization purposes.

For a simpler API that abstracts over this complexity, consider using the Collisions system parameter.

Usage

The following methods can be used for querying collisions:

• get and get_mut
• iter_active and iter_active_mut
• iter_sleeping and iter_sleeping_mut
• contains
• contact_pairs_with
• entities_colliding_with

For example, to iterate over all collisions with a given entity:

use avian2d::prelude::*;
use bevy::prelude::*;

#[derive(Component)]
struct PressurePlate;

fn activate_pressure_plates(mut query: Query<Entity, With<PressurePlate>>, contact_graph: Res<ContactGraph>) {
    for pressure_plate in &query {
        // Compute the total impulse applied to the pressure plate.
        let mut total_impulse = 0.0;

        for contact_pair in contact_graph.contact_pairs_with(pressure_plate) {
            total_impulse += contact_pair.total_normal_impulse_magnitude();
        }

        if total_impulse > 5.0 {
            println!("Pressure plate activated!");
        }
    }
}

While mutable access is allowed, contact modification and filtering should typically be done using CollisionHooks. See the documentation for more information.

For advanced usage, there are also methods such as get_edge and get_edge_mut methods to access the ContactEdges directly, along with variants that take a ContactId to access edges by their ID.

Warning

For users, this resource is primarily for querying and reading collision data.

Directly adding, modifying, or removing contact pairs using this resource will not trigger any collision events, wake up the entities involved, or perform any other cleanup. Only make structural modifications if you know what you are doing.

For filtering and modifying collisions, consider using CollisionHooks instead.

Fields

edges: ContactGraphInternal

The internal undirected graph where nodes are entities and edges are contact pairs.

Implementations

impl ContactGraph

pub fn entity_to_node(&self, entity: Entity) -> Option<NodeIndex>

Returns the NodeIndex of the given entity in the contact graph.

If the entity is not in the graph, None is returned.

pub fn get_edge(&self, entity1: Entity, entity2: Entity) -> Option<&ContactEdge>

Returns the ContactEdge between two entities. If the edge does not exist, None is returned.

A contact edge exists between two entities if their ColliderAabbs intersect. Use ContactEdge::is_touching to determine if the actual collider shapes are touching.

pub fn get_edge_by_id(&self, id: ContactId) -> Option<&ContactEdge>

Returns the ContactEdge between two entities based on their IDs. If the edge does not exist, None is returned.

A contact edge exists between two entities if their ColliderAabbs intersect. Use ContactEdge::is_touching to determine if the actual collider shapes are touching.

pub fn get_edge_mut( &mut self, entity1: Entity, entity2: Entity, ) -> Option<&mut ContactEdge>

Returns a mutable reference to the ContactEdge between two entities. If the edge does not exist, None is returned.

A contact edge exists between two entities if their ColliderAabbs intersect. Use ContactEdge::is_touching to determine if the actual collider shapes are touching.

pub fn get_edge_mut_by_id(&mut self, id: ContactId) -> Option<&mut ContactEdge>

Returns a mutable reference to the ContactEdge between two entities based on their IDs. If the edge does not exist, None is returned.

A contact edge exists between two entities if their ColliderAabbs intersect. Use ContactEdge::is_touching to determine if the actual collider shapes are touching.

pub fn get( &self, entity1: Entity, entity2: Entity, ) -> Option<(&ContactEdge, &ContactPair)>

Returns the ContactEdge and ContactPair between two entities. If the pair does not exist, None is returned.

A contact pair exists between two entities if their ColliderAabbs intersect. Use ContactPair::is_touching to determine if the actual collider shapes are touching.

pub fn get_by_id(&self, id: ContactId) -> Option<(&ContactEdge, &ContactPair)>

Returns the ContactEdge and ContactPair between two entities based on the contact ID. If the pair does not exist, None is returned.

A contact pair exists between two entities if their ColliderAabbs intersect. Use ContactPair::is_touching to determine if the actual collider shapes are touching.

pub fn get_mut( &mut self, entity1: Entity, entity2: Entity, ) -> Option<(&mut ContactEdge, &mut ContactPair)>

Returns a mutable reference to the ContactEdge and ContactPair between two entities. If the pair does not exist, None is returned.

A contact pair exists between two entities if their ColliderAabbs intersect. Use ContactPair::is_touching to determine if the actual collider shapes are touching.

pub fn get_mut_by_id( &mut self, id: ContactId, ) -> Option<(&mut ContactEdge, &mut ContactPair)>

Returns a mutable reference to the ContactEdge and ContactPair between two entities based on the contact ID. If the pair does not exist, None is returned.

A contact pair exists between two entities if their ColliderAabbs intersect. Use ContactPair::is_touching to determine if the actual collider shapes are touching.

pub fn get_pair_by_edge(&self, edge: &ContactEdge) -> Option<&ContactPair>

Returns the ContactPair between two entities based on the ContactEdge. If the pair does not exist, None is returned.

A contact pair exists between two entities if their ColliderAabbs intersect. Use ContactPair::is_touching to determine if the actual collider shapes are touching.

pub fn get_pair_mut_by_edge( &mut self, edge: &ContactEdge, ) -> Option<&mut ContactPair>

Returns a mutable reference to the ContactPair between two entities based on the ContactEdge. If the pair does not exist, None is returned.

A contact pair exists between two entities if their ColliderAabbs intersect. Use ContactPair::is_touching to determine if the actual collider shapes are touching.

pub fn get_manifold( &self, handle: ContactManifoldHandle, ) -> Option<&ContactManifold>

Returns a ContactManifold of a contact pair based on the ContactManifoldHandle. If the manifold does not exist, None is returned.

pub fn get_manifold_mut( &mut self, handle: ContactManifoldHandle, ) -> Option<&mut ContactManifold>

Returns a mutable reference to a ContactManifold of a contact pair based on the ContactManifoldHandle. If the manifold does not exist, None is returned.

pub fn contains(&self, entity1: Entity, entity2: Entity) -> bool

Returns true if the given entities have a contact pair.

A contact pair exists between two entities if their ColliderAabbs intersect, even if the shapes themselves are not yet touching.

pub fn contains_key(&self, pair_key: &PairKey) -> bool

Returns true if the given pair key is in the contact graph.

The pair key should be equivalent to PairKey::new(entity1.index(), entity2.index()).

This method can be useful to avoid constructing a new PairKey when the key is already known. If the key is not available, consider using contains instead.

pub fn active_pairs(&self) -> &[ContactPair]

Returns a slice over all active (non-sleeping) contact pairs.

pub fn sleeping_pairs(&self) -> &[ContactPair]

Returns a slice over all sleeping contact pairs.

pub fn active_pairs_mut(&mut self) -> &mut [ContactPair]

Returns a mutable slice over all active (non-sleeping) contact pairs.

pub fn sleeping_pairs_mut(&mut self) -> &mut [ContactPair]

Returns a mutable slice over all sleeping contact pairs.

pub fn iter_active(&self) -> impl Iterator<Item = &ContactPair>

Returns an iterator yielding immutable access to all active (non-sleeping) contact pairs.

A contact pair exists between two entities if their ColliderAabbs intersect, even if the shapes themselves are not yet touching.

If you only want touching contacts, use iter_active_touching instead.

pub fn iter_active_touching(&self) -> impl Iterator<Item = &ContactPair>

Returns an iterator yielding immutable access to all active (non-sleeping) contact pairs that are currently touching.

This is a subset of iter_active that only includes pairs where the colliders are touching.

pub fn iter_active_mut(&mut self) -> impl Iterator<Item = &mut ContactPair>

Returns a iterator yielding mutable access to all contact pairs.

A contact pair exists between two entities if their ColliderAabbs intersect, even if the shapes themselves are not yet touching.

If you only want touching contacts, use iter_active_touching_mut instead.

pub fn iter_active_touching_mut( &mut self, ) -> impl Iterator<Item = &mut ContactPair>

Returns an iterator yielding mutable access to all active (non-sleeping) contact pairs that are currently touching.

This is a subset of iter_active_mut that only includes pairs where the colliders are touching.

pub fn iter_sleeping(&self) -> impl Iterator<Item = &ContactPair>

Returns an iterator yielding immutable access to all sleeping contact pairs.

A contact pair exists between two entities if their ColliderAabbs intersect, even if the shapes themselves are not yet touching.

If you only want touching contacts, use iter_sleeping_touching instead.

pub fn iter_sleeping_touching(&self) -> impl Iterator<Item = &ContactPair>

Returns an iterator yielding immutable access to all sleeping contact pairs that are currently touching.

This is a subset of iter_sleeping that only includes pairs where the colliders are touching.

pub fn iter_sleeping_mut(&mut self) -> impl Iterator<Item = &mut ContactPair>

Returns an iterator yielding mutable access to all sleeping contact pairs.

A contact pair exists between two entities if their ColliderAabbs intersect, even if the shapes themselves are not yet touching.

If you only want touching contacts, use iter_sleeping_touching_mut instead.

pub fn iter_sleeping_touching_mut( &mut self, ) -> impl Iterator<Item = &mut ContactPair>

Returns an iterator yielding mutable access to all sleeping contact pairs that are currently touching.

This is a subset of iter_sleeping_mut that only includes pairs where the colliders are touching.

pub fn contact_edges_with( &self, entity: Entity, ) -> impl Iterator<Item = &ContactEdge>

Returns an iterator yielding immutable access to all contact edges involving the given entity.

pub fn contact_edges_with_mut( &mut self, entity: Entity, ) -> impl Iterator<Item = &mut ContactEdge>

Returns an iterator yielding mutable access to all contact edges involving the given entity.

pub fn contact_pairs_with( &self, entity: Entity, ) -> impl Iterator<Item = &ContactPair>

Returns an iterator yielding immutable access to all contact pairs involving the given entity.

A contact pair exists between two entities if their ColliderAabbs intersect, even if the shapes themselves are not yet touching.

Use ContactEdge::is_touching to determine if the actual collider shapes are touching.

pub fn entities_colliding_with( &self, entity: Entity, ) -> impl Iterator<Item = Entity> + '_

Returns an iterator yielding immutable access to all entities that have a contact pair with the given entity.

A contact pair exists between two entities if their ColliderAabbs intersect, even if the shapes themselves are not yet touching.

pub fn add_edge(&mut self, contact_edge: ContactEdge) -> Option<ContactId>

Creates a ContactEdge between two entities and adds an associated ContactPair to the list of active pairs.

Returns the ID of the contact edge if it was created, or None if the edge already exists.

Warning

Creating a contact edge with this method will not trigger any collision events or wake up the entities involved. Only use this method if you know what you are doing.

pub fn add_edge_with<F>( &mut self, contact_edge: ContactEdge, pair_callback: F, ) -> Option<ContactId>

where F: FnMut(&mut ContactPair),

Creates a ContactEdge between two entities, calling the provided callback to initialize the associated ContactPair in the list of active pairs.

Returns the ID of the contact edge if it was created, or None if the edge already exists.

Warning

Creating a contact edge with this method will not trigger any collision events or wake up the entities involved. Only use this method if you know what you are doing.

pub fn add_edge_and_key_with<F>( &mut self, contact_edge: ContactEdge, pair_key: PairKey, pair_callback: F, ) -> Option<ContactId>

where F: FnMut(&mut ContactPair),

Creates a ContactEdge between two entities with the given pair key, calling the provided callback to initialize the associated ContactPair in the list of active pairs.

The key must be equivalent to PairKey::new(contacts.entity1.index(), contacts.entity2.index()).

Returns the ID of the contact edge if it was created, or None if the edge already exists.

This method can be useful to avoid constructing a new PairKey when the key is already known. If the key is not available, consider using add_edge or add_edge_with instead.

Warning

Creating a contact edge with this method will not trigger any collision events or wake up the entities involved. Only use this method if you know what you are doing.

pub fn remove_edge( &mut self, entity1: Entity, entity2: Entity, ) -> Option<ContactEdge>

Removes a ContactEdge between two entites and returns its value.

Warning

Removing a contact edge with this method will not trigger any collision events or wake up the entities involved. Only use this method if you know what you are doing.

For filtering and modifying collisions, consider using CollisionHooks instead.

pub fn remove_edge_by_id( &mut self, pair_key: &PairKey, id: ContactId, ) -> Option<ContactEdge>

Removes a ContactEdge based on its pair key and ID and returns its value.

Warning

Removing a contact edge with this method will not trigger any collision events or wake up the entities involved. Only use this method if you know what you are doing.

For filtering and modifying collisions, consider using CollisionHooks instead.

pub fn remove_collider_with<F>(&mut self, entity: Entity, edge_callback: F)

where F: FnMut(&mut StableUnGraph<Entity, ContactEdge>, ContactId),

Removes the collider of the given entity from the contact graph, calling the given callback for each ContactEdge right before it is removed.

Warning

Removing a collider with this method will not trigger any collision events or wake up the entities involved. Only use this method if you know what you are doing.

pub fn wake_entity_with<F>(&mut self, entity: Entity, pair_callback: F)

where F: FnMut(&mut ContactGraph, &ContactPair),

Transfers touching contacts of a body from the sleeping contacts to the active contacts, calling the given callback for each ContactPair that is moved to active contacts.

pub fn sleep_entity_with<F>(&mut self, entity: Entity, pair_callback: F)

where F: FnMut(&mut ContactGraph, &ContactPair),

Transfers touching contacts of a body from the active contacts to the sleeping contacts, calling the given callback for each ContactPair that is moved to sleeping contacts.

pub fn clear(&mut self)

Clears all contact pairs and the contact graph.

Warning

Clearing contact pairs with this method will not trigger any collision events or wake up the entities involved. Only use this method if you know what you are doing.

Additionally, this does not clear the ConstraintGraph! You should additionally call ConstraintGraph::clear.

Trait Implementations

impl Clone for ContactGraph

fn clone(&self) -> ContactGraph

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for ContactGraph

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for ContactGraph

fn default() -> ContactGraph

Returns the “default value” for a type.

impl Resource for ContactGraph

where Self: Send + Sync + 'static,