Struct MeshRayCast 

pub struct MeshRayCast<'w, 's> { /* private fields */ }

Add this ray casting SystemParam to your system to cast rays into the world with an immediate-mode API. Call cast_ray to immediately perform a ray cast and get a result.

Under the hood, this is a collection of regular bevy queries, resources, and local parameters that are added to your system.

Usage

The following system casts a ray into the world with the ray positioned at the origin, pointing in the X-direction, and returns a list of intersections:

fn ray_cast_system(mut ray_cast: MeshRayCast) {
    let ray = Ray3d::new(Vec3::ZERO, Dir3::X);
    let hits = ray_cast.cast_ray(ray, &MeshRayCastSettings::default());
}

Configuration

You can specify the behavior of the ray cast using MeshRayCastSettings. This allows you to filter out entities, configure early-out behavior, and set whether the Visibility of an entity should be considered.

fn ray_cast_system(mut ray_cast: MeshRayCast, foo_query: Query<(), With<Foo>>) {
    let ray = Ray3d::new(Vec3::ZERO, Dir3::X);

    // Only ray cast against entities with the `Foo` component.
    let filter = |entity| foo_query.contains(entity);

    // Never early-exit. Note that you can change behavior per-entity.
    let early_exit_test = |_entity| false;

    // Ignore the visibility of entities. This allows ray casting hidden entities.
    let visibility = RayCastVisibility::Any;

    let settings = MeshRayCastSettings::default()
        .with_filter(&filter)
        .with_early_exit_test(&early_exit_test)
        .with_visibility(visibility);

    // Cast the ray with the settings, returning a list of intersections.
    let hits = ray_cast.cast_ray(ray, &settings);
}

Implementations

impl<'w, 's> MeshRayCast<'w, 's>

pub fn cast_ray( &mut self, ray: Ray3d, settings: &MeshRayCastSettings<'_>, ) -> &[(Entity, RayMeshHit)]

Casts the ray into the world and returns a sorted list of intersections, nearest first.

Examples found in repository

examples/3d/mesh_ray_cast.rs (line 52)

fn bounce_ray(mut ray: Ray3d, ray_cast: &mut MeshRayCast, gizmos: &mut Gizmos, color: Color) {
    let mut intersections = Vec::with_capacity(MAX_BOUNCES + 1);
    intersections.push((ray.origin, Color::srgb(30.0, 0.0, 0.0)));

    for i in 0..MAX_BOUNCES {
        // Cast the ray and get the first hit
        let Some((_, hit)) = ray_cast
            .cast_ray(ray, &MeshRayCastSettings::default())
            .first()
        else {
            break;
        };

        // Draw the point of intersection and add it to the list
        let brightness = 1.0 + 10.0 * (1.0 - i as f32 / MAX_BOUNCES as f32);
        intersections.push((hit.point, Color::BLACK.mix(&color, brightness)));
        gizmos.sphere(hit.point, 0.005, Color::BLACK.mix(&color, brightness * 2.0));

        // Reflect the ray off of the surface
        ray.direction = Dir3::new(ray.direction.reflect(hit.normal)).unwrap();
        ray.origin = hit.point + ray.direction * 1e-6;
    }
    gizmos.linestrip_gradient(intersections);
}

examples/ui/render_ui_to_texture.rs (line 206)

fn drive_diegetic_pointer(
    mut cursor_last: Local<Vec2>,
    mut raycast: MeshRayCast,
    rays: Res<RayMap>,
    cubes: Query<&Mesh3d, With<Cube>>,
    ui_camera: Query<&Camera, With<Camera2d>>,
    primary_window: Query<Entity, With<PrimaryWindow>>,
    windows: Query<(Entity, &Window)>,
    images: Res<Assets<Image>>,
    manual_texture_views: Res<ManualTextureViews>,
    mut window_events: MessageReader<WindowEvent>,
    mut pointer_inputs: MessageWriter<PointerInput>,
) -> Result {
    // Get the size of the texture, so we can convert from dimensionless UV coordinates that span
    // from 0 to 1, to pixel coordinates.
    let target = ui_camera
        .single()?
        .target
        .normalize(primary_window.single().ok())
        .unwrap();
    let target_info = target
        .get_render_target_info(windows, &images, &manual_texture_views)
        .unwrap();
    let size = target_info.physical_size.as_vec2();

    // Find raycast hits and update the virtual pointer.
    let raycast_settings = MeshRayCastSettings {
        visibility: RayCastVisibility::VisibleInView,
        filter: &|entity| cubes.contains(entity),
        early_exit_test: &|_| false,
    };
    for (_id, ray) in rays.iter() {
        for (_cube, hit) in raycast.cast_ray(*ray, &raycast_settings) {
            let position = size * hit.uv.unwrap();
            if position != *cursor_last {
                pointer_inputs.write(PointerInput::new(
                    CUBE_POINTER_ID,
                    Location {
                        target: target.clone(),
                        position,
                    },
                    PointerAction::Move {
                        delta: position - *cursor_last,
                    },
                ));
                *cursor_last = position;
            }
        }
    }

    // Pipe pointer button presses to the virtual pointer on the UI texture.
    for window_event in window_events.read() {
        if let WindowEvent::MouseButtonInput(input) = window_event {
            let button = match input.button {
                MouseButton::Left => PointerButton::Primary,
                MouseButton::Right => PointerButton::Secondary,
                MouseButton::Middle => PointerButton::Middle,
                _ => continue,
            };
            let action = match input.state {
                ButtonState::Pressed => PointerAction::Press(button),
                ButtonState::Released => PointerAction::Release(button),
            };
            pointer_inputs.write(PointerInput::new(
                CUBE_POINTER_ID,
                Location {
                    target: target.clone(),
                    position: *cursor_last,
                },
                action,
            ));
        }
    }

    Ok(())
}

Trait Implementations

impl SystemParam for MeshRayCast<'_, '_>

type State = FetchState

Used to store data which persists across invocations of a system.

type Item<'w, 's> = MeshRayCast<'w, 's>

The item type returned when constructing this system param. The value of this associated type should be Self, instantiated with new lifetimes.

fn init_state(world: &mut World) -> <MeshRayCast<'_, '_> as SystemParam>::State

Creates a new instance of this param’s State.

fn init_access( state: &<MeshRayCast<'_, '_> as SystemParam>::State, system_meta: &mut SystemMeta, component_access_set: &mut FilteredAccessSet, world: &mut World, )

Registers any World access used by this SystemParam

fn apply( state: &mut <MeshRayCast<'_, '_> as SystemParam>::State, system_meta: &SystemMeta, world: &mut World, )

Applies any deferred mutations stored in this SystemParam’s state. This is used to apply Commands during ApplyDeferred.

fn queue( state: &mut <MeshRayCast<'_, '_> as SystemParam>::State, system_meta: &SystemMeta, world: DeferredWorld<'_>, )

Queues any deferred mutations to be applied at the next ApplyDeferred.

unsafe fn validate_param<'w, 's>( state: &'s mut <MeshRayCast<'_, '_> as SystemParam>::State, _system_meta: &SystemMeta, _world: UnsafeWorldCell<'w>, ) -> Result<(), SystemParamValidationError>

Validates that the param can be acquired by the get_param.

unsafe fn get_param<'w, 's>( state: &'s mut <MeshRayCast<'_, '_> as SystemParam>::State, system_meta: &SystemMeta, world: UnsafeWorldCell<'w>, change_tick: Tick, ) -> <MeshRayCast<'_, '_> as SystemParam>::Item<'w, 's>

Creates a parameter to be passed into a SystemParamFunction.

impl<'w, 's> ReadOnlySystemParam for MeshRayCast<'w, 's>

where Res<'w, Assets<Mesh>>: ReadOnlySystemParam, Local<'s, Vec<(FloatOrd, (Entity, RayMeshHit))>>: ReadOnlySystemParam, Local<'s, Vec<(Entity, RayMeshHit)>>: ReadOnlySystemParam, Local<'s, Vec<(FloatOrd, Entity)>>: ReadOnlySystemParam, Query<'w, 's, (&'static InheritedVisibility, &'static ViewVisibility, &'static Aabb, &'static GlobalTransform, Entity), Or<(With<Mesh3d>, With<Mesh2d>, With<SimplifiedMesh>)>>: ReadOnlySystemParam, Query<'w, 's, (Option<&'static Mesh2d>, Option<&'static Mesh3d>, Option<&'static SimplifiedMesh>, Has<RayCastBackfaces>, &'static GlobalTransform), Or<(With<Mesh3d>, With<Mesh2d>, With<SimplifiedMesh>)>>: ReadOnlySystemParam,