avian3d

Module spatial_query

source
Expand description

Functionality for performing ray casts, shape casts, and other spatial queries.

Spatial queries query the world for geometric information about Colliders and various types of intersections. Currently, four types of spatial queries are supported:

All spatial queries can be done using the various methods provided by the SpatialQuery system parameter.

Raycasting and shapecasting can also be done with a component-based approach using the RayCaster and ShapeCaster components. They enable performing casts every frame in a way that is often more convenient than the normal SpatialQuery methods. See their documentation for more information.

§Raycasting

Raycasting is a spatial query that finds intersections between colliders and a half-line. This can be used for a variety of things like getting information about the environment for character controllers and AI, and even rendering using ray tracing.

For each hit during raycasting, the hit entity, a distance, and a normal will be stored in RayHitData. The distance is the distance from the ray origin to the point of intersection, indicating how far the ray travelled.

There are two ways to perform raycasts.

  1. For simple raycasts, use the RayCaster component. It returns the results of the raycast in the RayHits component every frame. It uses local coordinates, so it will automatically follow the entity it’s attached to or its parent.
  2. When you need more control or don’t want to cast every frame, use the raycasting methods provided by SpatialQuery, like cast_ray, ray_hits or ray_hits_callback.

See the documentation of the components and methods for more information.

A simple example using the component-based method looks like this:

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

fn setup(mut commands: Commands) {
    // Spawn a ray caster at the center with the rays travelling right
    commands.spawn(RayCaster::new(Vec3::ZERO, Dir3::X));
    // ...spawn colliders and other things
}

fn print_hits(query: Query<(&RayCaster, &RayHits)>) {
    for (ray, hits) in &query {
        // For the faster iterator that isn't sorted, use `.iter()`
        for hit in hits.iter_sorted() {
            println!(
                "Hit entity {} at {} with normal {}",
                hit.entity,
                ray.origin + *ray.direction * hit.distance,
                hit.normal,
            );
        }
    }
}

To specify which colliders should be considered in the query, use a spatial query filter.

§Shapecasting

Shapecasting or sweep testing is a spatial query that finds intersections between colliders and a shape that is travelling along a half-line. It is very similar to raycasting, but instead of a “point” we have an entire shape travelling along a half-line. One use case is determining how far an object can move before it hits the environment.

For each hit during shapecasting, the hit entity, a distance, two world-space points of intersection and two world-space normals will be stored in ShapeHitData. The distance refers to how far the shape travelled before the initial hit.

There are two ways to perform shapecasts.

  1. For simple shapecasts, use the ShapeCaster component. It returns the results of the shapecast in the ShapeHits component every frame. It uses local coordinates, so it will automatically follow the entity it’s attached to or its parent.
  2. When you need more control or don’t want to cast every frame, use the shapecasting methods provided by SpatialQuery, like cast_shape, shape_hits or shape_hits_callback.

See the documentation of the components and methods for more information.

A simple example using the component-based method looks like this:

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

fn setup(mut commands: Commands) {
    // Spawn a shape caster with a sphere shape at the center travelling right
    commands.spawn(ShapeCaster::new(
        Collider::sphere(0.5), // Shape
        Vec3::ZERO,            // Origin
        Quat::default(),       // Shape rotation
        Dir3::X                // Direction
    ));
    // ...spawn colliders and other things
}

fn print_hits(query: Query<(&ShapeCaster, &ShapeHits)>) {
    for (shape_caster, hits) in &query {
        for hit in hits.iter() {
            println!("Hit entity {}", hit.entity);
        }
    }
}

To specify which colliders should be considered in the query, use a spatial query filter.

§Point projection

Point projection is a spatial query that projects a point on the closest collider. It returns the collider’s entity, the projected point, and whether the point is inside of the collider.

Point projection can be done with the project_point method of the SpatialQuery system parameter. See its documentation for more information.

To specify which colliders should be considered in the query, use a spatial query filter.

§Intersection tests

Intersection tests are spatial queries that return the entities of colliders that are intersecting a given shape or area.

There are three types of intersection tests. They are all methods of the SpatialQuery system parameter, and they all have callback variants that call a given callback on each intersection.

See the documentation of the components and methods for more information.

To specify which colliders should be considered in the query, use a spatial query filter.

Structs§