Struct Collisions

pub struct Collisions<'w> { /* private fields */ }

A SystemParam for accessing and querying collision data.

This is a wrapper around the ContactGraph resource that provides a convenient API for querying touching contact pairs between entities. If you need more lower-level control and access to non-touching contact pairs, consider using the ContactGraph directly.

Usage

The following methods can be used for querying collisions:

• get
• iter
• contains
• collisions_with
• entities_colliding_with

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

use avian3d::prelude::*;
use bevy::prelude::*;

#[derive(Component)]
struct PressurePlate;

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

        for contact_pair in collisions.collisions_with(pressure_plate) {
            total_impulse += contact_pair.total_normal_impulse_magnitude();
        }

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

Contact modification and filtering should be done using CollisionHooks. See the documentation for more information.

Implementations

impl Collisions<'_>

pub fn graph(&self) -> &ContactGraph

Returns a reference to the internal ContactGraph.

Note that unlike Collisions, which only provides touching contacts, the contact graph includes both touching and non-touching contacts.

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

Returns a touching contact pair between two entities. If the pair does not exist, None is returned.

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

Returns true if the given entities have a touching contact pair.

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

Returns true if the given pair key matches a touching contact pair.

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 touching contact pairs.

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

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

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

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

Trait Implementations

impl SystemParam for Collisions<'_>

type State = FetchState

Used to store data which persists across invocations of a system.

type Item<'w, 's> = Collisions<'w>

The item type returned when constructing this system param. The value of this associated type should be Self, instantiated with new lifetimes.

fn init_state(world: &mut World, system_meta: &mut SystemMeta) -> Self::State

Registers any World access used by this SystemParam and creates a new instance of this param’s State.

unsafe fn new_archetype( state: &mut Self::State, archetype: &Archetype, system_meta: &mut SystemMeta, )

For the specified Archetype, registers the components accessed by this SystemParam (if applicable).a

fn apply(state: &mut Self::State, system_meta: &SystemMeta, world: &mut World)

Applies any deferred mutations stored in this SystemParam’s state. This is used to apply Commands during ApplyDeferred.

fn queue( state: &mut Self::State, system_meta: &SystemMeta, world: DeferredWorld<'_>, )

Queues any deferred mutations to be applied at the next ApplyDeferred.

unsafe fn validate_param<'w, 's>( state: &'s Self::State, _system_meta: &SystemMeta, _world: UnsafeWorldCell<'w>, ) -> Result<(), SystemParamValidationError>

Validates that the param can be acquired by the get_param.

unsafe fn get_param<'w, 's>( state: &'s mut Self::State, system_meta: &SystemMeta, world: UnsafeWorldCell<'w>, change_tick: Tick, ) -> Self::Item<'w, 's>

Creates a parameter to be passed into a SystemParamFunction.

impl<'w, 's> ReadOnlySystemParam for Collisions<'w>

where Res<'w, ContactGraph>: ReadOnlySystemParam,