Crate bevy_mod_raycast
source ·Expand description
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 RaycastSource
s 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
- 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.
Structs
- A 3D ray, with an origin and direction. The direction is guaranteed to be normalized.
- Marks an entity as pickable, with type T.
- Global plugin state used to enable or disable all ray casting for a given type T.
- The
RaycastSource
component is used to generate rays with the specifiedcast_method
. Aray
is generated when the RaycastSource is initialized, either by waiting for update_raycast system to process the ray, or by using awith_ray
function.`
Enums
- Specifies the method used to generate rays.
Traits
Functions
- Cast a ray on a mesh, and returns the intersection
- Checks if a ray intersects a mesh, and returns the nearest intersection if one exists.
- Takes a ray and triangle and computes the intersection and normal
- Implementation of the Möller-Trumbore ray-triangle intersection test
- 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.