Module avian3d::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 Collider
s
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 time of impact and a normal will be stored in RayHitData
.
The time of impact refers to how long the ray travelled, which is essentially the distance from the ray origin to
the point of intersection.
There are two ways to perform raycasts.
- For simple raycasts, use the
RayCaster
component. It returns the results of the raycast in theRayHits
component every frame. It uses local coordinates, so it will automatically follow the entity it’s attached to or its parent. - When you need more control or don’t want to cast every frame, use the raycasting methods provided by
SpatialQuery
, likecast_ray
,ray_hits
orray_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.time_of_impact,
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, the time of impact, two local points of intersection and two local
normals will be stored in ShapeHitData
. The time of impact refers to how long the shape travelled before the initial
hit, which is essentially the distance from the shape origin to the global point of intersection.
There are two ways to perform shapecasts.
- For simple shapecasts, use the
ShapeCaster
component. It returns the results of the shapecast in theShapeHits
component every frame. It uses local coordinates, so it will automatically follow the entity it’s attached to or its parent. - When you need more control or don’t want to cast every frame, use the shapecasting methods provided by
SpatialQuery
, likecast_shape
,shape_hits
orshape_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.
point_intersections
: Finds all entities with a collider that contains the given point.aabb_intersections_with_aabb
: Finds all entities with aColliderAabb
that is intersecting the givenColliderAabb
.shape_intersections
: Finds all entities with a collider that is intersecting the given shape.
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§
- The result of a point projection on a collider.
- A component used for raycasting.
- Data related to a hit during a raycast.
- Contains the hits of a ray cast by a
RayCaster
. - A component used for shapecasting.
- Data related to a hit during a shapecast.
- Contains the hits of a shape cast by a
ShapeCaster
. The hits are in the order of time of impact. - A system parameter for performing spatial queries.
- Rules that determine which colliders are taken into account in spatial queries.
- A resource for the spatial query pipeline.
- Initializes the
SpatialQueryPipeline
resource and handles component-based spatial queries like raycasting and shapecasting withRayCaster
andShapeCaster
.