Intro to Raycasting

10 min

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 BasePart or Terrain cell.

local raycastResult = workspace:Raycast(rayOrigin, rayDirection)

When casting a ray, the distance between the origin and directional datatype/Vector3 is the functional length (magnitude) of the ray. Anything past the directional vector will not be detected.

Sample Project

The remainder of this article shows one solution for finding origin and direction vectors. To follow along, open the Laser Maze sample project in Studio before proceeding.

In this game, lasers are fired by floating orbs. Platforms touched by the lasers are temporarily destroyed.

Once the place is open:

In the Explorer window, locate one of the LaserCaster models.

Expand the model’s tree, locate the CasterMain script, and open it.

Casting a Ray

All of the raycasting logic in the CasterMain script is handled in the fireLaser() function on line 39.

				
					Expected Output
				
					Expand
					
			local function fireLaser()
	-- Set an origin and directional vector
	local rayOrigin = caster.Position
	local rayDirection = Vector3.new(0, -100, 0)

	-- Build a "RaycastParams" object and cast the ray
	local raycastParams = RaycastParams.new()
	raycastParams.FilterDescendantsInstances = {caster.Parent}
	raycastParams.FilterType = Enum.RaycastFilterType.Blacklist
	local raycastResult = workspace:Raycast(rayOrigin, rayDirection, raycastParams)

	if raycastResult then
		local hitPart = raycastResult.Instance
		-- Check if the part resides in a folder, that it's fully visible, and not locked
		if hitPart.Parent == workspace.Tiles and hitPart.Transparency == 0 and not hitPart.Locked then
			hitPart.Locked = true
			-- Position beam ending attachment at hit point
			caster.BeamEndAttachment.Position = Vector3.new(0, (hitPart.Position.Y-caster.Position.Y)+raycastResult.Position.Y, 0)
			-- Start beam and burn effect
			caster.Beam.Enabled = true
			caster.BeamEndAttachment.BurnEffect.Enabled = true
			-- After a delay, trigger tile "melt"
			wait(TILE_MELT_DELAY)
			tweenTile(hitPart, 1)
		end
	end
	-- Trigger next caster cycle
	moveCaster()
end
		
				Copy Code
			
				Light Theme

Origin

A ray’s origin is simply a datatype/Vector3 point in the world. In this case, caster.Position is the origin of the ray.

				
					Expected Output
				
					Expand
					
			local function fireLaser()
	-- Set an origin and directional vector
	local rayOrigin = caster.Position
	local rayDirection = Vector3.new(0, -100, 0)
		
				Copy Code
			
				Light Theme

Direction

A ray’s direction is a datatype/Vector3 with a defined length (magnitude). In this sample project, rays are cast directly downward from the caster, so rayDirection is a datatype/Vector3 pointing 100 studs down on the Y axis.

				
					Expected Output
				
					Expand
					
			local function fireLaser()
	-- Set an origin and directional vector
	local rayOrigin = caster.Position
	local rayDirection = Vector3.new(0, -100, 0)
		
				Copy Code
			
				Light Theme

Calculating Direction From an Origin and Destination »

When applicable, an unknown direction vector can be calculated using a known origin and destination as follows:

The origin plus a directional vector indicate the ray’s destination.

rayOrigin + rayDirection = rayDestination

The origin is subtracted from both sides of the equation:

rayOrigin + rayDirection - rayOrigin = rayDestination - rayOrigin

The ray’s direction is the destination minus the origin:

rayDirection = rayDestination - rayOrigin

Casting

Once the origin and direction are determined, the ray is cast with the WorldRoot/Raycast|WorldRoot:Raycast() function. This function also accepts an optional datatype/RaycastParams object which, in this sample, tells the ray to ignore (blacklist) the caster’s parent (LaserCaster model) and all of its descendants.

				
					Expected Output
				
					Expand
					
			local function fireLaser()
	-- Set an origin and directional vector
	local rayOrigin = caster.Position
	local rayDirection = Vector3.new(0, -100, 0)

	-- Build a "RaycastParams" object and cast the ray
	local raycastParams = RaycastParams.new()
	raycastParams.FilterDescendantsInstances = {caster.Parent}
	raycastParams.FilterType = Enum.RaycastFilterType.Blacklist
	local raycastResult = workspace:Raycast(rayOrigin, rayDirection, raycastParams)
		
				Copy Code
			
				Light Theme

Hit Detection

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

Property	Description
RaycastResult.Instance	The `BasePart` or `Terrain` cell that the ray intersected.
RaycastResult.Position	The world space point at which the intersection occurred, usually a point directly on the surface of the instance.
RaycastResult.Material	The `enum/Material` at the intersection point. For normal parts this is the `BasePart/Material`; for `Terrain` this can vary depending on terrain data.
RaycastResult.Normal	The normal vector of the intersected face.

				
					Expected Output
				
					Expand
					
			local function fireLaser()
	-- Set an origin and directional vector
	local rayOrigin = caster.Position
	local rayDirection = Vector3.new(0, -100, 0)

	-- Build a "RaycastParams" object and cast the ray
	local raycastParams = RaycastParams.new()
	raycastParams.FilterDescendantsInstances = {caster.Parent}
	raycastParams.FilterType = Enum.RaycastFilterType.Blacklist
	local raycastResult = workspace:Raycast(rayOrigin, rayDirection, raycastParams)

	if raycastResult then
		local hitPart = raycastResult.Instance
		-- Check if the part resides in a folder, that it's fully visible, and not locked
		if hitPart.Parent == workspace.Tiles and hitPart.Transparency == 0 and not hitPart.Locked then
		
				Copy Code
			
				Light Theme

Tags:

raycast
detection
hit
sight

Intro to Raycasting

Intro to Raycasting

Sample Project

Casting a Ray

Origin

Direction

Calculating Direction From an Origin and Destination »

Casting

Hit Detection

Related Articles

Detecting Collisions

Collision Filtering