Lumberyard
User Guide (Version 1.16)

Casting Rays in an Environment

The RayWorldIntersection physical world function casts rays into the environment.

Depending on the material that the ray hits and the ray properties, a hit can be pierceable or solid.

A pierceable hit is a hit that has a material pierceability higher than the ray's pierceability. Material pierceability and ray pierceability occupy the lowest 4 bits of material flags and RayWorldIntersection flags.

Pierceable hits don't stop the ray and are accumulated as a list sorted by hit distance. The caller provides the function with an array for the hits. A solid hit (if any) always takes the slot with index 0 and pierceable hits slots from 1 to the end.

Optionally, the function can separate between 'important' and 'unimportant' pierceable hits (importance is indicated by sf_important in material flags) and can make important hits have a higher priority (regardless of hit distance) than unimportant ones when competing for space in the array.

By default, RayWorldIntersection checks only entity parts with the geom_colltype_ray flag. You can specify another flag or combination of flags by setting flags |= geom_colltype_mask<<rwi_colltype_bit. In this case, all flags should be set in part so that the specified flag can be tested.

RayTraceEntity is a more low-level function and checks ray hits for one entity only. RayTraceEntity returns only the closest hit.

Alternatively, CollideEntityWithBeam can perform a sweep-check within a sphere of the specified radius. In order to detect collisions reliably, the sphere specified should be outside of the object. The org parameter corresponds to the sphere center.