Geometry & Limitations
Documents which resources a rigid-body ray can hit and which geometric details are intentionally unavailable.
The current raycasting API queries Jolt narrow-phase rigid bodies. Its public contract is body-oriented: it returns the closest surface point for each managed body, not complete triangle or compound-child metadata.
Supported body types#
| Resource | Raycast behaviour |
|---|---|
| Dynamic / Static / Kinematic body | Included, whether active or sleeping. |
| Sensor body | Included and filtered by its assigned user layer. |
| Primitive / Convex shape | Returns its closest surface intersection. |
| Compound shape | Returns at most one closest result for the whole body. |
| Mesh / HeightField | Triangle back faces are ignored by the current native default settings. |
| Plane | Uses the shape's solid-side and boundary behaviour. |
| CharacterVirtual | Not returned; it has no rigid Body in this API. |
| Cloth | Not returned; it is managed separately as a SoftBody resource. |
| BBMOD | Visual geometry needs a physics body to participate in Jolt queries. |
One-sided triangles#
A ray approaching the back of a Mesh or HeightField triangle can miss even when the surface is visible from that side. Keep collision winding consistent, cast from the intended solid side, or create collision geometry appropriate for two-sided gameplay. The current wrapper does not expose a back-face mode option.
Starting inside or on a shape#
Boundary behaviour depends on the underlying Jolt shape and its default ray settings. Do not build self-filtering around an assumed exit hit. Ignore the source body, move the origin outside its collider when suitable, and verify the exact primitive, compound, mesh or Plane configuration used by the game.
Body-oriented results#
- jolt_raycast_all() returns at most one result per body.
- Multiple children of a compound do not produce separate public entries.
- Multiple triangles of a mesh do not produce separate public entries.
- Sub-shape, triangle and material identifiers are not exposed.
Thin-ray limitations#
- A ray has no radius and can pass beside small or thin targets.
- A ray does not describe the swept volume of a projectile or character.
- A single ground ray does not provide stable support across ledges or wide feet.
- Use Shape Casts or multiple probes when a gameplay volume matters.