Struct bevy_xpbd_3d::plugins::spatial_query::RayCaster

pub struct RayCaster {
    pub enabled: bool,
    pub origin: Vector,
    pub direction: Direction3d,
    pub max_time_of_impact: Scalar,
    pub max_hits: u32,
    pub solid: bool,
    pub ignore_self: bool,
    pub query_filter: SpatialQueryFilter,
    /* private fields */
}

A component used for raycasting.

Raycasting is a type of spatial query that finds one or more hits between a ray and a set of colliders.

Each ray is defined by a local origin and a direction. The RayCaster will find each hit and add them to the RayHits component. Each hit has a time_of_impact property which refers to how long the ray travelled, i.e. the distance between the origin and the point of intersection.

The RayCaster is the easiest way to handle simple raycasts. If you want more control and don’t want to perform raycasts every frame, consider using the SpatialQuery system parameter.

Hit count and order

The results of a raycast are in an arbitrary order by default. You can iterate over them in the order of time of impact with the RayHits::iter_sorted method.

You can configure the maximum amount of hits for a ray using max_hits. By default this is unbounded, so you will get all hits. When the number or complexity of colliders is large, this can be very expensive computationally. Set the value to whatever works best for your case.

Note that when there are more hits than max_hits, some hits will be missed. To guarantee that the closest hit is included, you should set max_hits to one or a value that is enough to contain all hits.

Example

use bevy::prelude::*;
use bevy_xpbd_3d::prelude::*;

fn setup(mut commands: Commands) {
    // Spawn a ray at the center going right
    commands.spawn(RayCaster::new(Vec3::ZERO, Direction3d::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,
            );
        }
    }
}

Fields

enabled: bool

Controls if the ray caster is enabled.

origin: Vector

The local origin of the ray relative to the Position and Rotation of the ray entity or its parent.

To get the global origin, use the global_origin method.

direction: Direction3d

The local direction of the ray relative to the Rotation of the ray entity or its parent.

To get the global direction, use the global_direction method.

max_time_of_impact: Scalar

The maximum distance the ray can travel. By default this is infinite, so the ray will travel until all hits up to max_hits have been checked.

max_hits: u32

The maximum number of hits allowed.

When there are more hits than max_hits, some hits will be missed. To guarantee that the closest hit is included, you should set max_hits to one or a value that is enough to contain all hits.

solid: bool

Controls how the ray behaves when the ray origin is inside of a collider.

If solid is true, the point of intersection will be the ray origin itself.
If solid is false, the collider will be considered to have no interior, and the point of intersection will be at the collider shape’s boundary.

ignore_self: bool

If true, the ray caster ignores hits against its own Collider. This is the default.

query_filter: SpatialQueryFilter

Rules that determine which colliders are taken into account in the query.

Implementations

impl RayCaster

pub fn new(origin: Vector, direction: Direction3d) -> Self

Creates a new RayCaster with a given origin and direction.

pub fn from_ray(ray: Ray3d) -> Self

Creates a new RayCaster from a ray.

pub fn with_origin(self, origin: Vector) -> Self

Sets the ray origin.

pub fn with_direction(self, direction: Direction3d) -> Self

Sets the ray direction.

pub fn with_solidness(self, solid: bool) -> Self

Sets if the ray treats colliders as solid.

If solid is true, the point of intersection will be the ray origin itself.
If solid is false, the collider will be considered to have no interior, and the point of intersection will be at the collider shape’s boundary.

pub fn with_ignore_self(self, ignore: bool) -> Self

Sets if the ray caster should ignore hits against its own Collider. The default is true.

pub fn with_max_time_of_impact(self, max_time_of_impact: Scalar) -> Self

Sets the maximum time of impact, i.e. the maximum distance that the ray is allowed to travel.

pub fn with_max_hits(self, max_hits: u32) -> Self

Sets the maximum number of allowed hits.

pub fn with_query_filter(self, query_filter: SpatialQueryFilter) -> Self

Sets the ray caster’s query filter that controls which colliders should be included or excluded by raycasts.

pub fn enable(&mut self)

Enables the RayCaster.

pub fn disable(&mut self)

Disables the RayCaster.

pub fn global_origin(&self) -> Vector

Returns the global origin of the ray.

pub fn global_direction(&self) -> Direction3d

Returns the global direction of the ray.

Trait Implementations

impl Component for RayCaster

where Self: Send + Sync + 'static,

type Storage = TableStorage

A marker type indicating the storage type used for this component. This must be either [TableStorage] or [SparseStorage].

impl Default for RayCaster

fn default() -> Self

Returns the “default value” for a type.

impl From<Ray3d> for RayCaster

fn from(ray: Ray3d) -> Self

Converts to this type from the input type.