World:raycast
EditTraces a ray through the world and calls a function for each collider that was hit.
The callback can be left off, in which case the closest hit will be returned.
Arguments
| Name | Type | Default | Description |
| x1 | number | The x coordinate of the origin of the ray. | |
| y1 | number | The y coordinate of the origin of the ray. | |
| z1 | number | The z coordinate of the origin of the ray. | |
| x2 | number | The x coordinate of the endpoint of the ray. | |
| y2 | number | The y coordinate of the endpoint of the ray. | |
| z2 | number | The z coordinate of the endpoint of the ray. | |
| filter | string | nil |
An optional tag filter. Pass one or more tags separated by spaces to only return colliders with those tags. Or, put ~ in front the tags to exclude colliders with those tags.
|
| callback | function | The function to call when an intersection is detected (see notes). |
Returns
Nothing
Arguments
| Name | Type | Default | Description |
| origin | Vec3 | The origin of the ray. | |
| endpoint | Vec3 | The endpoint of the ray. | |
| filter | string | nil |
An optional tag filter. Pass one or more tags separated by spaces to only return colliders with those tags. Or, put ~ in front the tags to exclude colliders with those tags.
|
| callback | function | The function to call when an intersection is detected (see notes). |
Returns
Nothing
Arguments
| Name | Type | Default | Description |
| x1 | number | The x coordinate of the origin of the ray. | |
| y1 | number | The y coordinate of the origin of the ray. | |
| z1 | number | The z coordinate of the origin of the ray. | |
| x2 | number | The x coordinate of the endpoint of the ray. | |
| y2 | number | The y coordinate of the endpoint of the ray. | |
| z2 | number | The z coordinate of the endpoint of the ray. | |
| filter | string | nil |
An optional tag filter. Pass one or more tags separated by spaces to only return colliders with those tags. Or, put ~ in front the tags to exclude colliders with those tags.
|
Returns
| Name | Type | Description |
| collider | Collider | The Collider that was hit. |
| shape | Shape | The Shape that was hit. |
| x | number | The x coordinate of the impact point, in world space. |
| y | number | The y coordinate of the impact point, in world space. |
| z | number | The z coordinate of the impact point, in world space. |
| nx | number | The x component of the normal vector. |
| ny | number | The y component of the normal vector. |
| nz | number | The z component of the normal vector. |
| triangle | number | The index of the triangle that was hit, or nil if a MeshShape was not hit. |
Arguments
| Name | Type | Default | Description |
| origin | Vec3 | The origin of the ray. | |
| endpoint | Vec3 | The endpoint of the ray. | |
| filter | string | nil |
An optional tag filter. Pass one or more tags separated by spaces to only return colliders with those tags. Or, put ~ in front the tags to exclude colliders with those tags.
|
Returns
| Name | Type | Description |
| collider | Collider | The Collider that was hit. |
| shape | Shape | The Shape that was hit. |
| x | number | The x coordinate of the impact point, in world space. |
| y | number | The y coordinate of the impact point, in world space. |
| z | number | The z coordinate of the impact point, in world space. |
| nx | number | The x component of the normal vector. |
| ny | number | The y component of the normal vector. |
| nz | number | The z component of the normal vector. |
| triangle | number | The index of the triangle that was hit, or nil if a MeshShape was not hit. |
Notes
The callback function is passed a collider, a shape, a world-space point, a world-space normal, and a fraction:
function(collider, shape, x, y, z, nx, ny, nz, fraction)
return fraction
end
The callback can return a fraction value used to limit the range of further hits. For example:
- Returning 0.0 will abort the raycast and ignore all other hits.
- Returning 1.0 will call the callback for all hits.
- Returning
fractionwill return successively closer hits.
Raycasts will hit sensors and sleeping colliders, but will not hit disabled colliders.