Crate bevy_mod_raycast

A small bevy plugin for raycasting against [Mesh]es.

The plugin provides two ways of raycasting:

• An “immediate-mode” API, which allows you to raycast into the scene on-demand in any system.
• A “retained-mode” API, where raycasts are performed once every frame based on entities tagged with specific components.

Immediate Mode API

See the immediate example for reference.

This is the simplest way to get started. Add the Raycast SystemParam to your system, and call Raycast::cast_ray, to get a list of intersections. Raycasts are performed immediately when you call the cast_ray method. See the Raycast documentation for more details. You don’t even need to add a plugin to your application.

Retained Mode API

See the minimal example for reference.

This API requires you add a RaycastSource to the entity that will be generating rays, and a RaycastMesh to all meshes that you want to raycast against. The RaycastSource has some built in modes for common use cases. You can set this entity to cast based on where it is pointing, using RaycastMethod::Transform, or you can use RaycastMethod::Screenspace along with a screenspace coordinate if the entity is a camera.

These components are both generic, and raycasts will only happen between entities with the same generic parameter. For example, RaycastSource<Foo> can cast rays against meshes with RaycastMesh<Foo>, but not against meshes that instead only have a RaycastMesh<Bar> component.

Comparison to Immediate Mode

While the retained mode API requires adding components on entities, in return it’s generally more “hands-off”. Once you add the components to entities, the plugin will run raycasts for you every frame, and you can query your RaycastSources to see what they have intersected that frame.

You can also think of this as being the “declarative” API. Instead of defining how the raycast happens, you instead describe what you want. For example, “this entity should cast rays in the direction it faces”, and you can then query that entity to find out what it hit.

By comparison, the immediate mode API is more imperative. You must define the raycast directly, but in return you are immediately given the results of the raycast without needing to wait for the scheduled raycasting system to run and query the results.

Use Cases

This plugin is well suited for use cases where you don’t want to use a full physics engine, you are putting together a simple prototype, or you just want the simplest-possible API. Using the Raycast system param requires no added components or plugins. You can just start raycasting in your systems.

Limitations

This plugin runs entirely on the CPU, with minimal acceleration structures, and without support for skinned meshes. However, there is a good chance that this simply won’t be an issue for your application. The provided stress_test example is a worst-case scenario that can help you judge if the plugin will meet your performance needs. Using a laptop with an i7-11800H, I am able to reach 110-530 fps in the stress test, raycasting against 1,000 monkey meshes.

Re-exports

• pub use debug::*;

Modules

• debug
• prelude
• rays
  Encapsulates Ray3D, preventing use of struct literal syntax. This allows us to guarantee that the Ray3d direction is normalized, because it can only be instantiated with the constructor.
• system_param

Structs

• DefaultRaycastingPlugin
• IntersectionData
• NoBackfaceCulling
• PrimitiveIntersection
• Ray3d
  A 3D ray, with an origin and direction. The direction is guaranteed to be normalized.
• RayHit
• RaycastMesh
  Marks an entity as pickable, with type T.
• RaycastPluginState
  Global plugin state used to enable or disable all ray casting for a given type T.
• RaycastSource
  The RaycastSource component is used to generate rays with the specified cast_method. A ray is generated when the RaycastSource is initialized, either by waiting for update_raycast system to process the ray, or by using a with_ray function.`
• SimplifiedMesh
• Triangle

Enums

• Backfaces
• Primitive3d
• RaycastMethod
  Specifies the method used to generate rays.
• RaycastSystem

Traits

• IntoUsize
• TriangleTrait

Functions

• build_rays
• ray_intersection_over_mesh
  Cast a ray on a mesh, and returns the intersection
• ray_mesh_intersection
  Checks if a ray intersects a mesh, and returns the nearest intersection if one exists.
• ray_triangle_intersection
  Takes a ray and triangle and computes the intersection and normal
• raycast_moller_trumbore
  Implementation of the Möller-Trumbore ray-triangle intersection test
• update_raycast
  Iterates through all entities with the RaycastMesh component, checking for intersections. If these entities have bounding volumes, these will be checked first, greatly accelerating the process.
• update_target_intersections