Raycast

Function of:

Description:

Casts a ray using an origin, direction, and optional datatype/RaycastParams. If it finds an eligible BasePart or Terrain cell, a datatype/RaycastResult is returned containing the results of the operation. If no datatype/RaycastParams object is provided, the defaults are used (all parts are considered and Terrain water is not ignored).

Note that the length (magnitude) of the directional vector is important, as objects/terrain further away than its length will not be tested. If you’re using a datatype/CFrame to help create the ray components, consider using CFrame.LookVector as the directional vector and multiply it by the desired length as shown in the example below. The maximum length of the direction vector is 5,000 studs.

For a demonstration of how raycasting works, see the articles/Raycasting|Intro to Raycasting article.

This method does not use a datatype/Ray object, but its origin and direction components can be borrowed from Ray.Origin and Ray.Direction.

Parameters

Name	Type	Default	Description
Name origin	Type Vector3	Default	Summary The origin point of the ray.
Name direction	Type Vector3	Default	Summary The directional vector of the ray. Note that the length of this vector matters, as parts/terrain further away than its length will not be tested.
Name raycastParams	Type RaycastParams	Default RaycastParams{IgnoreWater=false, BruteForceAllSlow=false, CollisionGroup=Default, FilterDescendantsInstances={}}	Summary An object used to specify hit eligibility in the raycast operation. If not provided, default values are used where all parts are considered and `Terrain` water is not ignored.

Returns

Return Type	Summary
Return Type RaycastResult	Summary Contains the results of a raycast operation, or `nil` if no eligible `BasePart` or `Terrain` cell was hit.

Code Samples

Basic Raycasting

The following example shows how to construct a datatype/RaycastParams object, use it in a raycasting operation, and check the results. For a more in-depth demonstration of how raycasting works, see the articles/Raycasting|Intro to Raycasting article.

			
				Basic Raycasting

				Expected Output
			
				Expand
				
			-- Build a "RaycastParams" object
local raycastParams = RaycastParams.new()
raycastParams.FilterType = Enum.RaycastFilterType.Whitelist
raycastParams.FilterDescendantsInstances = {workspace.Model}
raycastParams.IgnoreWater = true

-- Cast the ray
local part = workspace.Part
local raycastResult = workspace:Raycast(part.Position, part.CFrame.LookVector*50, raycastParams)

-- Interpret the result
if raycastResult then
	print("Object/terrain hit:", raycastResult.Instance:GetFullName())
	print("Hit position:", raycastResult.Position)
	print("Surface normal at the point of intersection:", raycastResult.Normal)
	print("Material hit:", raycastResult.Material.Name)
else
	print("Nothing was hit!")
end
		
				Copy Code
			
				Light Theme