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

1local rayOrigin = Vector3.new(0, 0, 0)
2local rayDirection = Vector3.new(0, -100, 0)
3
4local raycastResult = workspace:Raycast(rayOrigin, rayDirection)
5

Filtering

WorldRoot:Raycast() accepts an optional RaycastParams object which tells the raycast to selectively consider or ignore 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 RaycastFilterType enum which determines how the FilterDescendantsInstances array is used in the raycast operation.
  • Blacklist - Every BasePart is considered except those that are descendants of objects in the array.
  • Whitelist - 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

1local rayOrigin = Vector3.new(0, 0, 0)
2local rayDirection = Vector3.new(0, -100, 0)
3
4local raycastParams = RaycastParams.new()
5raycastParams.FilterDescendantsInstances = {script.Parent}
6raycastParams.FilterType = Enum.RaycastFilterType.Blacklist
7raycastParams.IgnoreWater = true
8
9local raycastResult = workspace:Raycast(rayOrigin, rayDirection, raycastParams)
10

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 + rayDirectionrayOrigin = rayDestinationrayOrigin
  3. The ray's direction equals the destination minus the origin:

    rayDirection = rayDestinationrayOrigin

1local rayOrigin = workspace.TestOrigin.Position
2local rayDestination = workspace.TestDestination.Position
3
4local rayDirection = rayDestination - rayOrigin
5
6local raycastResult = workspace:Raycast(rayOrigin, rayDirection)
7

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.

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 Material of the BasePart or Terrain at the intersection point.
Normal Vector3 of the normal vector of the intersected face.
Raycast Hit Detection

1local rayOrigin = Vector3.new(0, 0, 0)
2local rayDirection = Vector3.new(0, -100, 0)
3
4local raycastResult = workspace:Raycast(rayOrigin, rayDirection)
5
6if raycastResult then
7 print("Instance:", raycastResult.Instance)
8 print("Position:", raycastResult.Position)
9 print("Distance:", raycastResult.Distance)
10 print("Material:", raycastResult.Material)
11 print("Normal:", raycastResult.Normal)
12else
13 warn("No raycast result!")
14end
15