Raycasting

At its most basic level, raycasting is the act of sending out an invisible ray from a Vector3 point in a specific direction with a defined length. Once cast, you can detect if the ray hits a BasePart or Terrain cell.

Lasers are fired by floating orbs, and raycasting determines whether a laser hits a platform. Platforms touched by the lasers are temporarily destroyed.

You can cast a ray with the WorldRoot:Raycast() method (Workspace:Raycast()) from a Vector3 origin in a Vector3 direction.

Basic Raycast
local Workspace = game:GetService("Workspace")

local rayOrigin = Vector3.new(0, 0, 0)
local rayDirection = Vector3.new(0, -100, 0)

local raycastResult = Workspace:Raycast(rayOrigin, rayDirection)

When casting a ray, the direction parameter should encompass the desired length of the ray. For instance, if the magnitude of the direction is 10, the resulting ray will also be of length 10. The maximum length is 15,000 studs.

When applicable, you can calculate an unknown directional vector (rayDirection) using a known origin and destination. This is useful when casting a ray between two points that can change, such as from one player character to another.

The origin plus a directional vector indicate the ray's destination:

$\text{rayOrigin} + \text{rayDirection} = \text{rayDestination}$
Subtract $\text{rayOrigin}$ from both sides of the equation:

$\text{rayOrigin} + \text{rayDirection} - \text{rayOrigin} = \text{rayDestination} - \text{rayOrigin}$
The ray's direction equals the destination minus the origin:

$\text{rayDirection} = \text{rayDestination} - \text{rayOrigin}$


local Workspace = game:GetService("Workspace")

local rayOrigin = Workspace.TestOrigin.Position
local rayDestination = Workspace.TestDestination.Position

local rayDirection = rayDestination - rayOrigin

local raycastResult = Workspace:Raycast(rayOrigin, rayDirection)

WorldRoot:Raycast() accepts an optional RaycastParams object which tells the raycast to selectively include or exclude certain BaseParts, ignore the Water material for Terrain, or use a collision group.

Key	Description
FilterDescendantsInstances	Array of objects whose descendants are used in filtering raycasting candidates.
FilterType	Enum.RaycastFilterType enum which determines how the FilterDescendantsInstances array is used in the raycast operation. Exclude — Every BasePart is considered except those that are descendants of objects in the array. Include — Only BaseParts that are descendants of objects in the array are considered.
IgnoreWater	Boolean which determines whether the Water material is considered when raycasting against Terrain.
CollisionGroup	String name of the collision group used for the raycasting operation.

Raycast Filtering
local Workspace = game:GetService("Workspace")

local rayOrigin = Vector3.zero
local rayDirection = Vector3.new(0, -100, 0)

local raycastParams = RaycastParams.new()
raycastParams.FilterDescendantsInstances = {script.Parent}
raycastParams.FilterType = Enum.RaycastFilterType.Exclude
raycastParams.IgnoreWater = true

local raycastResult = Workspace:Raycast(rayOrigin, rayDirection, raycastParams)

Hit detection

If the raycasting operation hits an eligible BasePart or Terrain cell, a RaycastResult object is returned containing the results. To test for a hit, confirm that the result is not nil and utilize the following properties as needed.

Property	Description
Instance	The BasePart or Terrain cell that the ray intersected.
Position	Vector3 position of the intersection between the ray and the Instance.
Distance	Distance between the ray origin and intersection point.
Material	The Enum.Material of the BasePart or Terrain at the intersection point.
Normal	Vector3 of the normal vector of the intersected face.

When used in a place with instance streaming enabled, a client may not have streamed in distant BaseParts, so a raycast may not detect a hit. Additionally, low-detail "imposter" Terrain and Models generated by the streaming system are purely visual and are not eligible raycast targets.

You can exempt any BasePart from hit detection by setting its BasePart.CanQuery property to false.

Raycast Hit Detection
local Workspace = game:GetService("Workspace")

local rayOrigin = Vector3.zero
local rayDirection = Vector3.new(0, -100, 0)

local raycastResult = Workspace:Raycast(rayOrigin, rayDirection)

if raycastResult then
	print("Instance:", raycastResult.Instance)
	print("Position:", raycastResult.Position)
	print("Distance:", raycastResult.Distance)
	print("Material:", raycastResult.Material)
	print("Normal:", raycastResult.Normal)
else
	warn("No raycast result!")
end

English

Raycasting

Filter options

Hit detection