Struct ContactGraph

pub struct ContactGraph {
    pub internal: UnGraph<Entity, ContactPair>,
    /* private fields */
}

A resource that stores all contact pairs in the physics world in an undirected graph.

Contact pairs exist between colliders that have intersecting AABBs, even if the shapes themselves are not yet touching.

For a simpler API that only provides touching contacts, consider using the Collisions system parameter.

Usage

The following methods can be used for querying collisions:

• get and get_mut
• iter and iter_mut
• contains
• collisions_with and collisions_with_mut
• 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.collisions_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.

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

internal: UnGraph<Entity, ContactPair>

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

Implementations

impl ContactGraph

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

Returns the contact pair 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( &mut self, entity1: Entity, entity2: Entity, ) -> Option<&mut ContactPair>

Returns a mutable reference to the contact pair 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 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 iter(&self) -> impl Iterator<Item = &ContactPair>

Returns an iterator yielding immutable 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_touching instead.

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

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

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

pub fn iter_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_touching_mut instead.

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

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

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

pub fn collisions_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 ContactPair::is_touching to determine if the actual collider shapes are touching.

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

Returns an iterator yielding mutable 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 ContactPair::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_pair(&mut self, contacts: ContactPair)

Creates a contact pair between two entities.

If a pair with the same entities already exists, this will do nothing.

Warning

Creating a collision pair 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_pair_with_key(&mut self, contacts: ContactPair, pair_key: PairKey)

Creates a contact pair between two entities with the given pair key.

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

If a pair with the same entities already exists, this will do nothing.

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_pair instead.

Warning

Creating a collision pair 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 insert_pair(&mut self, contacts: ContactPair)

Inserts a contact pair between two entities.

If a pair with the same entities already exists, it will be overwritten.

Warning

Inserting a collision pair 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 insert_pair_with_key(&mut self, contacts: ContactPair, pair_key: PairKey)

Inserts a contact pair between two entities with the given pair key.

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

If a pair with the same entities already exists, it will be overwritten.

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 insert_pair instead.

Warning

Inserting a collision pair 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_pair( &mut self, entity1: Entity, entity2: Entity, ) -> Option<ContactPair>

Removes a contact pair between two entites and returns its value.

Warning

Removing a collision pair 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, pair_callback: F)

where F: FnMut(ContactPair),

Removes the collider of the given entity from the contact graph, calling the given callback for each contact pair that is removed in the process.

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.

Trait Implementations

impl Clone for ContactGraph

fn clone(&self) -> ContactGraph

Returns a copy 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,