Module collision_events

Collision events for detecting when colliders start or stop touching.

Avian provides two collision event types:

• CollisionStart: Triggered when two colliders start touching.
• CollisionEnd: Triggered when two colliders stop touching.

Depending on your use case, you may want to read them as Messages with a MessageReader, or observe them as Events with an observer. Avian supports both options.

Reading Collision Events

To enable collision events for a collider entity, add the CollisionEventsEnabled component.

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

#[derive(Component)]
struct PressurePlate;

fn setup_pressure_plates(mut commands: Commands) {
    commands.spawn((
        PressurePlate,
        Collider::rectangle(1.0, 1.0),
        Sensor,
        // Enable collision events for this entity.
        CollisionEventsEnabled,
    ));
}

The CollisionStart and CollisionEnd events will now be both written as a Message and triggered as an Event when the entity starts or stops touching another collider. It is up to you to decide which event processing method is best suited for your use case.

Collision Message

Reading collision events as Messages with a MessageReader can be very efficient for processing large numbers of collisions between pairs of entities, such as for detecting bullet hits or playing impact sounds when two objects collide.

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

fn print_started_collisions(mut collision_reader: MessageReader<CollisionStart>) {
    for event in collision_reader.read() {
        println!("{} and {} started colliding", event.collider1, event.collider2);
    }
}

Collision Event

Observing collision events as Events with an observer can be very useful 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.

fn setup_pressure_plates(mut commands: Commands) {
    commands.spawn((
        PressurePlate,
        Collider::rectangle(1.0, 1.0),
        Sensor,
        // Enable collision events for this entity.
        CollisionEventsEnabled,
    ))
    .observe(on_player_stepped_on_plate);
}

fn on_player_stepped_on_plate(event: On<CollisionStart>, player_query: Query<&Player>) {
    // `colider1` and `body1` refer to the event target and its body.
    // `collider2` and `body2` refer to the other collider and its body.
    let pressure_plate = event.collider1;
    let other_entity = event.collider2;

    if player_query.contains(other_entity) {
        println!("Player {other_entity} stepped on pressure plate {pressure_plate}");
    }
}

Structs

CollisionEnd

A collision event that is triggered when two colliders stop touching.

CollisionEventsEnabled

A marker component that enables collision events for an entity.

CollisionStart

A collision event that is triggered when two colliders start touching.

Type Aliases

OnCollisionEndDeprecated

A deprecated alias for CollisionEnd.

OnCollisionStartDeprecated

A deprecated alias for CollisionStart.