raycasting.md

title	Raycasting
description	Raycasting allows you to detect collisions and determine the position of objects.

At its most basic level, raycasting is the act of sending out an invisible ray from a Datatype.Vector3 point in a specific direction with a defined length. Once cast, you can detect if the ray hits a Class.BasePart or Class.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 Class.WorldRoot:Raycast() method (Class.Workspace:Raycast()) from a Datatype.Vector3 origin in a Datatype.Vector3 direction.

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.

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

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

2. Subtract $\text{rayOrigin}$ from both sides of the equation:

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

3. 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)

Filter options

Class.WorldRoot:Raycast() accepts an optional Datatype.RaycastParams object which tells the raycast to selectively include or exclude certain Class.BasePart|BaseParts, ignore the Water material for Class.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. `Enum.RaycastFilterType|Exclude` — Every `Class.BasePart` is considered **except** those that are descendants of objects in the array. `Enum.RaycastFilterType|Include` — Only `Class.BasePart|BaseParts` that are descendants of objects in the array are considered.
`IgnoreWater`	Boolean which determines whether the **Water** material is considered when raycasting against `Class.Terrain`.
`CollisionGroup`	String name of the [collision group](../workspace/collisions.md#collision-filtering) used for the raycasting operation.

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 Class.BasePart or Class.Terrain cell, a Datatype.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
`Class.Instance`	The `Class.BasePart` or `Class.Terrain` cell that the ray intersected.
`Position`	`Datatype.Vector3` position of the intersection between the ray and the `Class.Instance`.
`Distance`	Distance between the ray origin and intersection point.
`Material`	The `Enum.Material` of the `Class.BasePart` or `Class.Terrain` at the intersection point.
`Normal`	`Datatype.Vector3` of the normal vector of the intersected face.

When used in a place with instance [streaming](../workspace/streaming.md) enabled, a client may not have streamed in distant `Class.BasePart|BaseParts`, so a raycast may not detect a hit. Additionally, low-detail "imposter" `Class.Terrain` and `Class.Model|Models` generated by the streaming system are purely visual and are not eligible raycast targets. You can exempt any `Class.BasePart` from hit detection by setting its `Class.BasePart.CanQuery` property to `false`.

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