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.

Casting a Ray

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

Basic Raycast
local rayOrigin = Vector3.new(0, 0, 0)

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



local raycastResult = workspace:Raycast(rayOrigin, rayDirection)

Filtering

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.

KeyDescription
FilterDescendantsInstancesArray of objects whose descendants are used in filtering raycasting candidates.
FilterTypeEnum.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.
IgnoreWaterBoolean which determines whether the Water material is considered when raycasting against Terrain.
CollisionGroupString name of the collision group used for the raycasting operation.
Raycast Filtering
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)

Calculating Direction

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.

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

    rayOrigin + rayDirection = rayDestination

  2. Subtract rayOrigin from both sides of the equation:

    rayOrigin + rayDirection − rayOrigin = rayDestination − rayOrigin

  3. The ray's direction equals the destination minus the origin:

    rayDirection = rayDestination − rayOrigin

local rayOrigin = workspace.TestOrigin.Position

local rayDestination = workspace.TestDestination.Position



local rayDirection = rayDestination - rayOrigin



local raycastResult = workspace:Raycast(rayOrigin, rayDirection)

Detecting Hits

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.

PropertyDescription
InstanceThe BasePart or Terrain cell that the ray intersected.
PositionVector3 position of the intersection between the ray and the Instance.
DistanceDistance between the ray origin and intersection point.
MaterialThe Enum.Material of the BasePart or Terrain at the intersection point.
NormalVector3 of the normal vector of the intersected face.
Raycast Hit Detection
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