We use cookies on this site to enhance your user experience
Collapse Sidebar


This function returns the first BasePart intersecting with the given DataType/Ray that isn’t in, or a descendant of an object in, the given ignore list. It also returns the position of intersection, the surface normal of the intersecting part at the point of intersection, and the part’s BasePart/Material.

This function is a variant of Workspace/FindPartOnRay with the addition of an ignore list. This allows the developer to ignore certain parts or Models.

The terrainCellsAreCubes and ignoreWater parameters determine whether terrain cells should be treated as cubes, and whether water should be ignored.

Those looking to utilize a white list instead should use Workspace/FindPartOnRayWithWhitelist.

For more information on how raycasting works in Roblox, please see the articles on raycasting basics and how to make raycasting guns.


  • Theoretically, a ray extends infinitely in one direction. However, the max length of the direction vector on Roblox is 5000 studs
  • The length of the direction vector is important - parts further away than its length will not be tested
  • If the ray does not intersect a part, the return values will be nil and the point at the end of the ray, respectively
  • If a nil value is given in the ignore list, instances after this value will not be ignored
  • Parts that are in a PhysicsService/SetPartCollisionGroup|collision group that does not collide with the “Default” collision group are ignored implicitly


Name Type Default Description



The DataType/Ray.

An array of objects to be ignored.


True if terrain cells should be treated as cubes.


True if terrain water should be ignored.


Return Type Summary

The BasePart (or Terrain) hit, the DataType/Vector3 point of intersection, the DataType/Vector3 surface normal at the point of intersection and the Enum/Material of the BasePart or terrain cell hit.

Code Samples

Raycast IgnoreList

This code sample includes a relatively in-depth example of how Workspace/FindPartOnRayWithIgnoreList works. It creates a rotating turret that shoots constantly surrounded by a mixture of parts. Some of these parts will be added to the ignore list, whereas some will not.

local Debris = game:GetService("Debris")

-- create a turret part
local turret = Instance.new("Part")
turret.Anchored = true
turret.Size = Vector3.new(1, 1, 1)
turret.BrickColor = BrickColor.new("Black")
turret.FrontSurface = Enum.SurfaceType.Hinge
turret.Position = Vector3.new(0, 5, 0)
turret.Parent = workspace

-- create ignore list 
local ignoreList = {}

-- create random obstacles 
for i = 1, 20 do
	local part = Instance.new("Part")
	part.Anchored = true
	-- random size
	part.Size = Vector3.new(
		math.random(1, 20), 
		math.random(1, 20)
	-- random position
	part.Position = Vector3.new(
		math.random(-50, 50),
		math.random(-50, 50)
	local doIgnore = math.random(1, 2) == 1 
	-- randomly allocate to the ignore list or not
	if doIgnore then
		part.BrickColor = BrickColor.new("Bright green")
		part.Transparency = 0.7
		table.insert(ignoreList, part)
		part.BrickColor = BrickColor.new("Bright red")
		part.Transparency = 0
	part.Parent = workspace

-- create beam template
local beam = Instance.new("Beam")
beam.Segments = 1
beam.Width0 = 0.2
beam.Width1 = 0.2
beam.Color = ColorSequence.new(Color3.new(1, 1, 0))
beam.FaceCamera = true

-- function to draw a bullet's path
local function drawBullet(origin, hit)
	-- create attachmetns
	local attachment0 = Instance.new("Attachment")
	local attachment1 = Instance.new("Attachment")
	-- setup beam
	local beam = beam:Clone()
	beam.Attachment0 = attachment0 
	beam.Attachment1 = attachment1
	beam.Parent = attachment0 
	-- position attachments
	attachment0.Position = origin
	attachment1.Position = hit
	-- adorn attachments to terrain
	-- attachments need to be parented to an object in 3D space
	-- terrain has an origin of 0, 0, 0 making it ideal for this use
	attachment0.Parent = workspace.Terrain
	attachment1.Parent = workspace.Terrain
	-- add the attachments to debris
	Debris:AddItem(attachment0, 0.1)
	Debris:AddItem(attachment1, 0.1)

local function shoot()
	local origin = turret.Position
	local aimDirection = turret.CFrame.lookVector
	-- create a ray aiming the same way as the turret
	local ray = Ray.new(origin, aimDirection * 500)
	-- raycast
	local hit, position = workspace:FindPartOnRayWithIgnoreList(ray, ignoreList)
	-- draw bullet effect
	drawBullet(origin, position)

while wait(.15) do
	-- spin the turret
	turret.CFrame = turret.CFrame * CFrame.Angles(0, math.rad(2), 0)
	-- fire the turret