PcoWSkbVqDnWTu_dm2ix
Collapse Sidebar

FindPartOnRay

FindPartOnRay uses raycasting to find the first BasePart or Terrain cell intersecting with a given DataType/Ray. This function returns the BasePart or terrain cell hit, the point of intersection, the surface normal at the point of intersection, and the associated Enum/Material hit.

local character = game.Players.LocalPlayer.Character
-- Get the head
local head = character:FindFirstChild("Head")
-- Build a ray in the direction the head is facing
local origin = head.Position
local lookDirection = head.CFrame.LookVector
local ray = Ray.new(origin, lookDirection * 500)
-- Raycast, ignoring the player's character
local hitPart, hitPosition = workspace:FindPartOnRay(ray, character)
if hitPart then
	print("Hit part: " .. hitPart:GetFullName())
else
	print("Did not hit part")
end

If the ignoreDescendantsInstance parameter is provided, the raycasting calculation will ignore the given object and all of its descendants. It behaves similar to the Mouse/TargetFilter property.

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

In order to whitelist or ignore multiple objects and their descendants, use the WorldRoot/FindPartOnRayWithWhitelist and WorldRoot/FindPartOnRayWithIgnoreList variants.

Notes

  • Theoretically, a ray extends infinitely in one direction. However, the max length of the direction vector on Roblox is 5000 studs.
  • The length (magnitude) of the directional vector is important, as parts further away than its length will not be tested.
  • If the ray does not intersect anything, the return values will be nil and the point at the end of the ray, respectively.
  • Parts that are in a articles/Collision Filtering|collision group that does not collide with the “Default” collision group are ignored implicitly.

For a demonstration of how raycasting works in Roblox, see the Intro to Raycasting article.

Parameters

Name Type Default Description

ray

Ray
nil
false
false

Returns

Return Type Summary

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