avian3d::collision

Module collision_events

Source
Expand description

Collision events for detecting when colliders start or stop touching.

Depending on your use case, you may want to use either buffered events read using an EventReader or observable events triggered for specific entities. Avian provides both options using separate event types.

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

§Buffered Events

Avian provides two different buffered collision event types:

These events are sent when two colliders start or stop touching, and can be read using an EventReader. This can be useful for efficiently processing large numbers of collision events between pairs of entities, such as for detecting bullet hits or playing impact sounds when two objects collide.

The events are only sent if one of the entities has the CollisionEventsEnabled component.

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

fn print_started_collisions(mut collision_event_reader: EventReader<CollisionStarted>) {
    for CollisionStarted(entity1, entity2) in collision_event_reader.read() {
        println!("{entity1} and {entity2} started colliding");
    }
}

§Observable Events

Avian provides two observable collision event types:

These events are triggered for observers when two colliders start or stop touching. This makes them good for entity-specific collision scenarios, such as for detecting when a player steps on a pressure plate or enters a trigger volume.

The events are only triggered if the target entity has the CollisionEventsEnabled component.

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

#[derive(Component)]
struct Player;

#[derive(Component)]
struct PressurePlate;

fn setup_pressure_plates(mut commands: Commands) {
    commands.spawn((
        PressurePlate,
        Collider::cuboid(1.0, 0.1, 1.0),
        Sensor,
        // Enable collision events for this entity.
        CollisionEventsEnabled,
    ))
    .observe(|trigger: Trigger<OnCollisionStart>, player_query: Query<&Player>| {
        let pressure_plate = trigger.target();
        let other_entity = trigger.collider;
        if player_query.contains(other_entity) {
            println!("Player {other_entity} stepped on pressure plate {pressure_plate}");
        }
    });
}

Structs§