Raycasting
Raycasting Overview
Introduces rigid-body ray queries and helps you choose the correct query for a task.
A physics raycast tests one zero-thickness world-space line segment against bodies in a Jolt world. It is a synchronous, read-only query: it reports geometry that exists at the time of the call but does not advance physics, create contacts, wake bodies, or apply forces.
What a raycast answers#
- Did this segment intersect a managed rigid body?
- Which body was closest, or which bodies were crossed?
- Where did the intersection occur and what was the world-space surface normal?
- How far along the segment was the hit?
Choose the correct query#
| Task | Use |
|---|---|
| Weapon, line of sight, interaction beam or thin ground probe | jolt_raycast() |
| Penetration or finding several bodies along one line | jolt_raycast_all() |
| Sweeping a box, sphere, capsule or cylinder through space | Shape Cast |
| Testing which bodies already overlap a volume | Shape Overlap |
| Finding the nearest surface around a point | jolt_closest_point() |
What can be hit#
- Dynamic, Static and Kinematic rigid bodies, including sleeping bodies.
- Sensor bodies, unless their layer is excluded.
- Primitive, convex, compound, mesh, HeightField and Plane rigid-body shapes.
What cannot be hit#
- CharacterVirtual resources, because they do not own a rigid Body in this API.
- Cloth resources, which are managed as SoftBody resources in a separate handle table.
- BBMOD triangles that were not turned into physics bodies.
Learning path#
Start with Quick Start, then read Basic Raycast and Raycast Results. Continue with Multiple Hits and Layer Filtering when the first prototype works. Geometry & Limitations and Debugging & Performance cover production edge cases; Low-Level Raycasting is only required for explicit worlds.