WorldRoot

ArePartsTouchingOthers returns true if at least one of the given BasePart are touching any other parts. Two parts are considered "touching" if they are within the distance threshold, overlapIgnored.

If no parts are provided, false is returned.

Parameters

Returns

local part1 = Instance.new("Part")
part1.Name = "Part1"
part1.Anchored = true
part1.Transparency = 0.5
part1.Color = Color3.fromRGB(185, 100, 38)
part1.Size = Vector3.new(2, 2, 2)
part1.Position = Vector3.new(0, 4, 0)
part1.Parent = workspace

local part2 = Instance.new("Part")
part2.Name = "Part2"
part2.Anchored = true
part2.Transparency = 0.5
part2.Color = Color3.fromRGB(200, 10, 0)
part2.Size = Vector3.new(2, 2, 2)
part2.Position = Vector3.new(0, 5, 0)
part2.Parent = workspace

local partList = { part1 }

print(workspace:ArePartsTouchingOthers(partList, 0)) -- True
print(workspace:ArePartsTouchingOthers(partList, 0.999)) -- True
print(workspace:ArePartsTouchingOthers(partList, 1)) -- False

Casts a block shape in a given direction and returns the first collision with a BasePart or Terrain cell. This is analogous to how WorldRoot:Raycast() casts a linear ray in a direction to find a collision, but it uses a 3D shape instead of a ray.

Unlike WorldRoot:GetPartsInPart(), this method does not detect BaseParts that initially intersect the shape.

If a hit is detected, a RaycastResult is returned containing the hit information. The Distance property represents the distance the shape has to travel to find a hit, and the Position property represents the intersection point that causes the hit.

This method throws an error if it is passed invalid CFrame, size, or direction inputs.

Parameters

Returns

local Workspace = game:GetService("Workspace")

local function castBlock()
	-- The initial position and rotation of the cast block shape
	local originCFrame = CFrame.new(Vector3.new(0, 50, 0))
	-- The size of the cast block shape
	local size = Vector3.new(6, 3, 9)
	-- The direction the block is cast in
	local direction = -Vector3.yAxis
	-- The maximum distance of the cast
	local distance = 50

	-- Cast the block and create a visualization of it
	local raycastResult = Workspace:Blockcast(originCFrame, size, direction * distance)

	if raycastResult then
		-- Print all properties of the RaycastResult if it exists
		print(`Block intersected with: {raycastResult.Instance:GetFullName()}`)
		print(`Intersection position: {raycastResult.Position}`)
		print(`Distance between block's initial position and result: {raycastResult.Distance}`)
		print(`The normal vector of the intersected face: {raycastResult.Normal}`)
		print(`Material hit: {raycastResult.Material.Name}`)
	else
		print("Nothing was hit")
	end
end

-- Continually cast a block every 2 seconds
while true do
	castBlock()
	task.wait(2)
end

This function moves a table of BaseParts to a table of CFrames without necessarily firing the default property Changed events. This provides a very fast way to move large numbers of parts, as you don't have to pay the cost of separate property sets for each individual part.

The third argument allows you to further optimize the movement operation. By default, the Changed event of each part fires for Position, Orientation, and CFrame. However, if you specify FireCFrameChanged as the third argument, only the Changed event for the CFrame property will fire.

Note that you should only use this function if you're sure that part movement is a bottleneck in your code. Simply setting the CFrame property of individual parts and welded models is fast enough in the majority of cases.

Parameters

Returns

FindPartOnRay uses raycasting to find the first BasePart or Terrain cell intersecting with a given 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.

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 include or exclude 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 15000 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 collision group that does not collide with the "Default" collision group are ignored implicitly.

Parameters

Returns

This function is a variant of WorldRoot:FindPartOnRay() with the addition of an ignore list. This lets you ignore certain parts or Models.

Those looking to include a specific group of objects should instead use WorldRoot:FindPartOnRayWithWhitelist().

Parameters

Returns

This function is a variant of WorldRoot:FindPartOnRay() with the addition of an inclusion list. This lets you detect only certain parts or Models and is particularly useful when, for example, looking for points of intersection between a ray and a single part.

If a nil value is given in the inclusion list, instances after it will be disregarded.

Those looking to exclude a specific group of objects should instead use WorldRoot:FindPartOnRayWithIgnoreList().

Parameters

Returns

Returns an array of BaseParts in the given Region3.

This function takes an optional maxParts parameter (default 20) which limits the number of BaseParts that can be returned. Once this number has been reached, the search for BaseParts will stop. This means some BaseParts may not be returned even if they are within the Region3

The optional ignoreDescendantsInstance parameter can be used to specify a specific instance for whom itself and all of its descendants should be ignored by this function. This can be useful when, for example, looking to see if any BaseParts are inside a BasePart other than the BasePart itself.

local min = part.Position - (0.5 * part.Size)
local max = part.Position + (0.5 * part.Size)
local region = Region3.new(min, max)
local parts = worldroot:FindPartsInRegion3(region, part)  -- Ignore part

The WorldRoot:FindPartsInRegion3WithIgnoreList() and WorldRoot:FindPartsInRegion3WithWhiteList() variants of this method exist to provide specific exclusion and inclusion functionality.

If no BaseParts are found, an empty array will be returned.

Parameters

Returns

Returns an array of BaseParts in the given Region3 that aren't in, or a descendant of an entry in, the given ignore list.

If a nil value is given in the ignore list, instances after this value will not be ignored. If no BaseParts are found, an empty array will be returned.

This function is a variant of WorldRoot:FindPartsInRegion3() with the addition of an ignore list. This allows the developer to exclude certain BaseParts or Models from the search. Those looking to find BaseParts in a Region3 using an inclusion list should use WorldRoot:FindPartsInRegion3WithWhiteList().

Parameters

Returns

Returns an array of BaseParts in the given Region3 that are in, or descendant of an entry in, the given inclusion list.

If a nil value is given in the inclusion list, instances after this value will not be ignored. If no BaseParts are found, an empty array will be returned.

This function is a variant of WorldRoot:FindPartsInRegion3() with the addition of an inclusion list. This allows the developer to include only certain BaseParts or Models in the search. Those looking to find BaseParts in a Region3 using an exclusion list should use WorldRoot:FindPartsInRegion3WithIgnoreList().

Parameters

Returns

WorldRoot:GetPartBoundsInBox() returns an array of parts whose bounding boxes overlap a box whose volume is described using the given center (CFrame) and size (Vector3).

As emphasized, this spatial query method efficiently considers the volume of parts' bounding boxes rather than their actual occupied volume. This may be important when considering cylinders, spheres, unions, and MeshParts which have non-block shapes. For cases where accuracy especially matters, use WorldRoot:GetPartsInPart() instead, or further filter the results of this method yourself.

This method uses a OverlapParams object to describe reusable portions of the spatial query, such as an inclusion or exclusion list, the maximum number of parts to query, what collision group to use, and whether the query favors an intersected part's BasePart.CanCollide value over its BasePart.CanQuery value.

Parameters

Returns

WorldRoot:GetPartBoundsInRadius() returns an array of parts whose bounding boxes overlap a sphere whose volume is described using the given center (Vector3) and radius (number).

As emphasized, this spatial query method efficiently considers the volume of parts' bounding boxes rather than their actual occupied volume. This may be important when considering cylinders, spheres, unions, and MeshParts which have non-block shapes. For cases where accuracy especially matters, use WorldRoot:GetPartsInPart() instead, or further filter the results of this method yourself.

This method uses a OverlapParams object to describe reusable portions of the spatial query, such as an inclusion or exclusion list, the maximum number of parts to query, what collision group to use, and whether the query favors an intersected part's BasePart.CanCollide value over its BasePart.CanQuery value.

Parameters

Returns

WorldRoot:GetPartsInPart() returns an array of parts whose occupied space is shared with the given part (which must exist in the same WorldRoot as the parts to be queried). This method can be used in place of BasePart:GetTouchingParts() and is generally a better choice.

As noted, this spatial query method considers the exact volume occupied by the given part using a full geometric collision check. As an example, a concave/hollow part won't match queried parts within it unless they actually overlap/touch such a part. For simpler volumes, consider using WorldRoot:GetPartBoundsInBox() or WorldRoot:GetPartBoundsInRadius(), as they are less accurate but perform more efficiently.

This method uses a OverlapParams object to describe reusable portions of the spatial query, such as an inclusion or exclusion list, the maximum number of parts to query, what collision group to use, and whether the query favors an intersected part's BasePart.CanCollide value over its BasePart.CanQuery value.

Parameters

Returns

This function moves the specified part to the specified location via inverse kinematics rather than moving it there directly, to ensure any joints, constraints, or collisions that part is participating in remain physically satisfied. Currently this function is only available in Studio to plugins, as it currently conflicts with the physics of a running game.

Translate stiffness is a number between 0 and 1 specifying how aggressively to match the part's position to the position part of the target CFrame. Rotate stiffness is a number between 0 and 1 specifying how aggressively to match the part's rotation to the rotation part of the target CFrame.

For example:

• If translate stiffness and rotate stiffness are both equal to 1, then the part will be moved exactly to the target CFrame regardless of what physical constraints there are on it.
• If translate stiffness and rotate stiffness are both equal to 0.5, then the part will try to move to exactly the target CFrame, but may be pushed out of the way by physical constraints on it.
• If translate stiffness and rotate stiffness are both equal to 0, then the target CFrame will be ignored and physical constraints will be solved for the object at the position where it was.

Parameters

Returns

IsRegion3Empty returns a bool indicating whether there are no BaseParts within the given Region3.

The optional ignoreDescendantsInstance parameter can be used to specify a specific instance for whom itself and all of its descendants should be ignored by this function. This can be useful when, for example, looking to see if any BaseParts are inside a BasePart other than the BasePart itself.

local min = part.Position - (0.5 * part.Size)
local max = part.Position + (0.5 * part.Size)
local region = Region3.new(min, max)
local isPartEmpty = worldroot:IsRegion3Empty(region, part)  -- Ignore part

If more than one object and its descendants need to be excluded from the search, developers should use WorldRoot:IsRegion3EmptyWithIgnoreList().

This function only returns if a region is empty or not. Developers looking to find BaseParts in a region should use WorldRoot:FindPartsInRegion3().

How do Region3 checks work?

Checking if a part overlaps a Region3 is not a simple process. It actually is time consuming and complicated. Instead it checks if parts are roughly in the same area. When this function is called, it figures out which voxels contain the Region3. It then figures out which parts might be in those voxels. It does this by comparing the axis-aligned bounding box (sometimes called the AABB) of the part with the voxels. The axis-aligned bounding box can be seen in Roblox Studio when a part is selected.

This means that the area that is inspected by the function may be larger than the Region3. For this reason it is recommended to make sure that the Region3 is on the voxel grid. The best way to do this is by setting the coordinates of the Region3 to multiples of 4 (since voxels are 4 x 4 x 4 studs).

This method is a fairly quick and easy way to see if any parts are in a general area. If a game needs to know if parts are exactly in an area, then BasePart:GetTouchingParts() should be used. There is a higher cost to using BasePart:GetTouchingParts() since a part is needed in the WorldRoot and the function takes more time to run.

Parameters

Returns

Returns a boolean indicating whether there are no BaseParts within the given Region3, ignoring any BaseParts that are descendants of the objects within the given ignore list. If a nil value is given in the ignore list, instances after this value will not be ignored.

This function only returns if a region is empty or not. Developers looking to find specific BaseParts in a region should use WorldRoot:FindPartsInRegion3WithIgnoreList().

This function is a variant of WorldRoot:IsRegion3Empty() with the addition of an ignore list. In cases where an inclusion list is required instead, developers should check to see if any parts are returned by WorldRoot:FindPartsinRegion3WithWhitelist().

Parameters

Returns

Casts a ray using an origin, direction, and optional RaycastParams. If it finds an eligible BasePart or Terrain cell, a RaycastResult is returned containing the results of the operation. If no RaycastParams object is provided, the defaults are used (all parts are considered and Terrain water is not ignored).

Note that the length (magnitude) of the directional vector is important, as objects/terrain further away than its length will not be tested. If you're using a CFrame to help create the ray components, consider using CFrame.LookVector as the directional vector and multiply it by the desired length as shown in the example below. The maximum length of the direction vector is 15,000 studs.

This method does not use a Ray object, but its origin and direction components can be borrowed from Ray.Origin and Ray.Direction.

Parameters

Returns

local Workspace = game:GetService("Workspace")

local function castRay()
	-- The origin point of the ray
	local originPosition = Vector3.new(0, 50, 0)
	-- The direction the ray is cast in
	local direction = -Vector3.yAxis
	-- The maximum distance of the ray
	local distance = 50

	-- Cast the ray and create a visualization of it
	local raycastResult = Workspace:Raycast(originPosition, direction * distance)

	if raycastResult then
		-- Print all properties of the RaycastResult if it exists
		print(`Ray intersected with: {raycastResult.Instance:GetFullName()}`)
		print(`Intersection position: {raycastResult.Position}`)
		print(`Distance between ray origin and result: {raycastResult.Distance}`)
		print(`The normal vector of the intersected face: {raycastResult.Normal}`)
		print(`Material hit: {raycastResult.Material.Name}`)
	else
		print("Nothing was hit")
	end
end

-- Continually cast a ray every 2 seconds
while true do
	castRay()
	task.wait(2)
end

Parameters

Returns

Casts a spherical shape in a given direction and returns the first collision with a BasePart or Terrain cell. This is analogous to how WorldRoot:Raycast() casts a linear ray in a direction to find a collision, but it uses a 3D shape instead of a ray.

Unlike WorldRoot:GetPartsInPart(), this method does not detect BaseParts that initially intersect the shape.

If a hit is detected, a RaycastResult is returned containing the hit information. The Distance property represents the distance the shape has to travel to find a hit, and the Position property represents the intersection point that causes the hit.

This method throws an error if it is passed invalid radius or direction inputs.

Parameters

Returns

local Workspace = game:GetService("Workspace")

local function castSphere()
	-- The initial position of the cast spherical shape
	local originPosition = Vector3.new(0, 50, 0)
	-- The radius of the cast spherical shape in studs
	local radius = 10
	-- The direction the sphere is cast in
	local direction = -Vector3.yAxis
	-- The maximum distance of the cast
	local distance = 50

	-- Cast the sphere and create a visualization of it
	local raycastResult = Workspace:Spherecast(originPosition, radius, direction * distance)

	if raycastResult then
		-- Print all properties of the RaycastResult if it exists
		print(`Sphere intersected with: {raycastResult.Instance:GetFullName()}`)
		print(`Intersection position: {raycastResult.Position}`)
		print(`Distance between sphere's initial position and result: {raycastResult.Distance}`)
		print(`The normal vector of the intersected face: {raycastResult.Normal}`)
		print(`Material hit: {raycastResult.Material.Name}`)
	else
		print("Nothing was hit")
	end
end

-- Continually cast a sphere every 2 seconds
while true do
	castSphere()
	task.wait(2)
end

Advances the simulation for parts in the world forward based on a specified time increment and an optional set of BasePart. When a set of parts is specified, only these parts will be simulated and all other parts in the world will be treated as anchored. When this argument is left out, all parts in the world will be included in the simulation. The specified time increment can be any positive number, with larger values increasing the runtime of the function. Depending on the value of the time increment, the physics system may subdivide it into multiple individual steps to maintain the accuracy and stability of the simulation. Even if the function performs multiple substeps, the results of the simulation will only be seen once the function completes. To visualize the individual steps of a simulation, the function can be called once per RenderStep via the RunService.RenderStepped event.

Parameters

Returns

local RunService = game:GetService("RunService")

-- Optional array of parts to simulate; otherwise all parts will be simulated
local partsToSimulate = {
	workspace.Part
}

local function simulateParts(duration)
	local time = 0.0
	local stepJob

	stepJob = RunService.RenderStepped:Connect(function(dt)
		if time + dt > duration then
			dt = duration - time
		end

		workspace:StepPhysics(dt, partsToSimulate)
		time = time + dt
		if time >= duration then
			stepJob:Disconnect()
		end
	end)
end

-- Simulate workspace parts for 5 seconds, stepping the parts once per frame
simulateParts(5.0)

Parameters

Returns

Parameters

Returns