36 min read

Source: Roblox Creator Hub · CC BY 4.0 · View source · Code samples: MIT Imported 2026-10-03. Formatting adapted for this site.

WorldRoot

Inherits from: Model → PVInstance → Instance → Object

This base class provides an API for any instance intended for handling 3D spatial queries and simulation, such as Workspace and WorldModel.

Inherits from: Model

Descendants: Workspace, WorldModel

Memory category: BaseParts

Tags: NotCreatable

Methods

Name	Type / Returns	Description
WorldRoot:ArePartsTouchingOthers	boolean	Returns true if any of the given `BasePart` are touching any other parts.
WorldRoot:Blockcast	RaycastResult?	Casts a block shape in a given direction and returns a `RaycastResult` if the shape hits a `BasePart` or `Terrain` cell.
WorldRoot:BulkMoveTo	()	Moves an array of `BaseParts` to an array of `CFrames`.
WorldRoot:CollisionGroupsAreCollidable	boolean	Returns whether the two groups will collide in this world.
WorldRoot:CollisionGroupSetCollidable	()	Sets the collision status between two groups in this world.
WorldRoot:FindPartOnRay	Tuple	Returns the first `BasePart` or `Terrain` cell intersecting with the given `Ray`.
WorldRoot:findPartOnRay	Tuple
WorldRoot:FindPartOnRayWithIgnoreList	Tuple	Returns the first `BasePart` or `Terrain` cell intersecting with the given `Ray` that isn't in, nor is a descendant of an object in, the given ignore list.
WorldRoot:FindPartOnRayWithWhitelist	Tuple	Returns the first `BasePart` or `Terrain` cell intersecting with the given `Ray` that is in, or is a descendant of an object in, the given inclusion list.
WorldRoot:FindPartsInRegion3	List	Returns an array of `BaseParts` in the given `Region3`.
WorldRoot:findPartsInRegion3	List
WorldRoot:FindPartsInRegion3WithIgnoreList	List	Returns an array of `BaseParts` in the given `Region3` that aren't in, or a descendant of an entry in, the given ignore list.
WorldRoot:FindPartsInRegion3WithWhiteList	List	Returns an array of `BaseParts` in the given `Region3` that are in, or descendant of an entry in, the given inclusion list.
WorldRoot:GetMaxCollisionGroups	int	Returns the maximum number of collision groups in this world.
WorldRoot:GetPartBoundsInBox	List	Returns an array of parts whose bounding boxes overlap a given box.
WorldRoot:GetPartBoundsInRadius	List	Returns an array of parts whose bounding boxes overlap a given sphere.
WorldRoot:GetPartsInPart	List	Returns an array of parts whose occupied space is shared with the given part.
WorldRoot:GetRegisteredCollisionGroups	Array	Returns a table with info on all of this world's collision groups.
WorldRoot:IKMoveTo	()	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.
WorldRoot:IsCollisionGroupRegistered	boolean	Checks if a collision group is registered in this world.
WorldRoot:IsRegion3Empty	boolean	Returns a bool indicating whether there are no `BaseParts` within the given `Region3`.
WorldRoot:IsRegion3EmptyWithIgnoreList	boolean	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.
WorldRoot:Raycast	RaycastResult?	Casts a ray using an origin, direction, and optional `RaycastParams`, then returns a `RaycastResult` if an eligible object or terrain intersects the ray.
WorldRoot:RegisterCollisionGroup	()	Registers a new collision group in this world with the given name.
WorldRoot:RenameCollisionGroup	()	Renames specified collision group in this world.
WorldRoot:Shapecast	RaycastResult?	Casts the shape of a given `BasePart` in a direction and returns a `RaycastResult` if the shape hits a `BasePart` or `Terrain` cell.
WorldRoot:Spherecast	RaycastResult?	Casts a spherical shape in a given direction and returns a `RaycastResult` if the shape hits a `BasePart` or `Terrain` cell.
WorldRoot:StepPhysics	()	Advances the simulation for parts in the world forward based on a specified time increment and an optional set of `BaseParts`.
WorldRoot:UnregisterCollisionGroup	()	Unregisters the collision group for the given name in this world.

Inherited from Model

Name	Type / Returns	Description
Model:AddPersistentPlayer	()	Sets this model to be persistent for the specified player. `ModelStreamingMode` must be set to `PersistentPerPlayer` for behavior to be changed as a result of addition.
Model:BreakJoints	()	Breaks connections between `BaseParts`, including surface connections with any adjacent parts, `WeldConstraints` and all `Welds` and other `JointInstances`.
Model:breakJoints	()
Model:GetBoundingBox	Tuple	Returns a description of a volume that contains all parts of a Model.
Model:GetExtentsSize	Vector3	Returns the size of the smallest bounding box that contains all of the `BaseParts` in the `Model`, aligned with the `Model.PrimaryPart` if it is set.
Model:GetModelCFrame	CFrame	This value historically returned the CFrame of a central position in the model.
Model:GetModelSize	Vector3	Returns the Vector3 size of the Model.
Model:GetPersistentPlayers	List	Returns all the `Player` objects that this model object is persistent for. Behavior varies based on whether this method is called from a `Script` or a `LocalScript`.
Model:GetPrimaryPartCFrame	CFrame	Returns the `CFrame` of the model's `Model.PrimaryPart`. This function will throw an error if no primary part exists for the `Model`.
Model:GetScale	float	Returns the canonical scale of the model, which defaults to 1 for newly created models and will change as it is scaled via `Model:ScaleTo()`.
Model:MakeJoints	()	Goes through all `BaseParts` in the `Model`. If any part's side has a SurfaceType that can make a joint it will create a joint with any adjacent parts.
Model:makeJoints	()
Model:move	()
Model:MoveTo	()	Moves the `PrimaryPart` to the given position. If a primary part has not been specified, the root part of the model will be used.
Model:moveTo	()
Model:RemovePersistentPlayer	()	Makes this model no longer persistent for the specified player. `ModelStreamingMode` must be set to `PersistentPerPlayer` for behavior to be changed as a result of removal.
Model:ResetOrientationToIdentity	()	Resets the rotation of the model's parts to the previously set identity rotation, which is done through the `Model:SetIdentityOrientation()` method.
Model:ScaleTo	()	Sets the scale factor of the model, adjusting the sizing and location of all descendant Instances such that they have that scale factor relative to their initial sizes and locations when scale factor was 1.
Model:SetIdentityOrientation	()	Sets the identity rotation of the given model, allowing you to reset the rotation of the entire model later, through the use of the `ResetOrientationToIdentity` method.
Model:SetPrimaryPartCFrame	()	Sets the `BasePart.CFrame` of the model's `Model.PrimaryPart`. All other parts in the model will also be moved and will maintain their orientation and offset respective to the `Model.PrimaryPart`.
Model:TranslateBy	()	Shifts a `Model` by the given `Vector3` offset, preserving the model's orientation. If another `BasePart` or `Terrain` already exists at the new position then the `Model` will overlap said object.

Inherited from PVInstance

Name	Type / Returns	Description
PVInstance:GetPivot	CFrame	Gets the pivot of a `PVInstance`.
PVInstance:PivotTo	()	Transforms the `PVInstance` along with all of its descendant `PVInstances` such that the pivot is now located at the specified `CFrame`.

Inherited from Instance

Name	Type / Returns	Description
Instance:AddTag	()	Applies a tag to the instance.
Instance:children	Instances	Returns an array of the object's children.
Instance:ClearAllChildren	()	This method destroys all of an instance's children.
Instance:Clone	Instance	Create a copy of an instance and all its descendants, ignoring instances that are not `Archivable`.
Instance:clone	Instance
Instance:Destroy	()	Sets the `Instance.Parent` property to `nil`, locks the `Instance.Parent` property, disconnects all connections, and calls `Destroy()` on all children.
Instance:destroy	()
Instance:FindFirstAncestor	Instance?	Returns the first ancestor of the `Instance` whose `Instance.Name` is equal to the given name.
Instance:FindFirstAncestorOfClass	Instance?	Returns the first ancestor of the `Instance` whose `Object.ClassName` is equal to the given className.
Instance:FindFirstAncestorWhichIsA	Instance?	Returns the first ancestor of the `Instance` for whom `Object:IsA()` returns true for the given className.
Instance:FindFirstChild	Instance?	Returns the first child of the `Instance` found with the given name.
Instance:findFirstChild	Instance
Instance:FindFirstChildOfClass	Instance?	Returns the first child of the `Instance` whose `ClassName` is equal to the given class name.
Instance:FindFirstChildWhichIsA	Instance?	Returns the first child of the `Instance` for whom `Object:IsA()` returns true for the given className.
Instance:FindFirstDescendant	Instance?	Returns the first descendant found with the given `Instance.Name`.
Instance:GetActor	Actor?	Returns the `Actor` associated with the Instance, if any.
Instance:GetAttribute	Variant	Returns the value which has been assigned to the given attribute name.
Instance:GetAttributeChangedSignal	RBXScriptSignal	Returns an event that fires when the given attribute changes.
Instance:GetAttributes	Dictionary	Returns a dictionary of the instance's attributes.
Instance:GetChildren	Instances	Returns an array containing all of the instance's children.
Instance:getChildren	Instances
Instance:GetDebugId	string	Returns a coded string of the debug ID used internally by Roblox.
Instance:GetDescendants	Instances	Returns an array containing all of the descendants of the instance.
Instance:GetFullName	string	Returns a string describing the instance's ancestry.
Instance:GetStyled	Variant	Returns the styled or explicitly modified value of the specified property, or else the default property value if it hasn't been styled/modified.
Instance:GetStyledPropertyChangedSignal	RBXScriptSignal	Returns an event that fires when the given style property changes on the instance.
Instance:GetTags	Array	Gets an array of all tags applied to the instance.
Instance:HasTag	boolean	Check whether the instance has a given tag.
Instance:IsAncestorOf	boolean	Returns true if an `Instance` is an ancestor of the given descendant.
Instance:IsDescendantOf	boolean	Returns `true` if an `Instance` is a descendant of the given ancestor.
Instance:isDescendantOf	boolean
Instance:IsPropertyModified	boolean	Returns `true` if the value stored in the specified property is not equal to the code-instantiated default.
Instance:QueryDescendants	Instances	Returns an array containing all descendants of the instance that match the `selector` string.
Instance:Remove	()	Sets the object's `Parent` to `nil`, and does the same for all its descendants.
Instance:remove	()
Instance:RemoveTag	()	Removes a tag from the instance.
Instance:ResetPropertyToDefault	()	Resets a property to its default value.
Instance:SetAttribute	()	Sets the attribute with the given name to the given value.
Instance:WaitForChild	Instance	Returns the child of the `Instance` with the given name. If the child does not exist, it will yield the current thread until it does.

Inherited from Object

Name	Type / Returns	Description
Object:GetPropertyChangedSignal	RBXScriptSignal	Get an event that fires when a given property of the object changes.
Object:IsA	boolean	Returns true if an object's class matches or inherits from a given class.
Object:isA	boolean

WorldRoot:ArePartsTouchingOthers

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

Name	Type	Default	Description
partList	Instances		A list of parts checks to see if any parts in the list are touching any parts not in the list.
overlapIgnored	float	0.000199999995	The part overlap threshold in studs that is ignored before parts are considered to be touching.

Returns

Type	Description
boolean	True if and only if any of the `parts` in `partList` are touching any other parts (parts not in the partList). False if no parts are passed.

Field	Value
security	None
thread safety	Unsafe
simulationAccess	true

Code samples: View on Creator Hub (checking-for-touching-parts).

WorldRoot:Blockcast

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

Name	Type	Default	Description
cframe	CFrame		The initial position and rotation of the cast block shape.
size	Vector3		The size of the cast block shape in studs. The maximum size is 512 studs.
direction	Vector3		Direction of the shapecast, with the magnitude representing the maximum distance the shape can travel. The maximum distance is 1024 studs.
params	RaycastParams	RaycastParams{IgnoreWater=false, BruteForceAllSlow=false, RespectCanCollide=false, CollisionGroup=Default, FilterDescendantsInstances={}}	An object used to specify hit eligibility in the shapecast operation. If not provided, default values are used where all parts are considered and `Terrain` water is not ignored.

Returns

Type	Description
RaycastResult?	Contains the result of the shapecast operation, or `nil` if no eligible `BasePart` or `Terrain` cell was hit.

Field	Value
security	None
thread safety	Safe
simulationAccess	true

Code samples: View on Creator Hub (worldroot---blockcast).

WorldRoot:BulkMoveTo

This function moves an array of BaseParts to an array 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.

Both partList and cframeList are sequential arrays (Luau tables with integer indices starting at 1), not dictionaries. Each part at index i in partList is moved to the CFrame at index i in cframeList. The arrays must contain the same number of entries.

local Workspace = game:GetService("Workspace")

local partList = { Workspace.Part1, Workspace.Part2 }
local cframeList = { CFrame.new(0, 5, 0), CFrame.new(10, 5, 0) }
Workspace:BulkMoveTo(partList, cframeList, Enum.BulkMoveMode.FireCFrameChanged)

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

Name	Type	Default	Description
partList	Instances		An array of `BaseParts` to be moved. Each entry is matched by index to the corresponding entry in `cframeList`.
cframeList	Array		An array of `CFrames` that the parts will be moved to, matched by index to `partList`. Both arrays must be the same length.
eventMode	BulkMoveMode	FireAllEvents	An `BulkMoveMode` enum specifying which `Changed` events fire during the move. Default is `FireAllEvents`.

Returns

Type	Description
()

Field	Value
security	None
thread safety	Unsafe
simulationAccess	true

WorldRoot:CollisionGroupsAreCollidable

Returns whether the two specified collision groups will collide in this world. This method will also return true if either of the groups are unregistered in this world, as the default collision mask collides with all groups.

Parameters

Name	Type	Default	Description
name1	string
name2	string

Returns

Type	Description
boolean

Field	Value
security	None
thread safety	Unsafe
capabilities	["Physics"]
simulationAccess	true

WorldRoot:CollisionGroupSetCollidable

Sets the collision status between two groups in this world. This method will throw an error if either of the groups is unregistered in this world, so it's recommended that you confirm each group's registration through WorldRoot:IsCollisionGroupRegistered() before making this call.

Parameters

Name	Type	Default	Description
name1	string
name2	string
collidable	boolean

Returns

Type	Description
()

Field	Value
security	None
thread safety	Unsafe
capabilities	["Physics"]
simulationAccess	true

WorldRoot:FindPartOnRay

Deprecated. This function has been deprecated. Use WorldRoot:Raycast() along with RaycastParams for new work.

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 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

Name	Type	Default	Description
ray	Ray		A `Ray` whose origin and direction define the raycast.
ignoreDescendantsInstance	Instance	nil	An `Instance` whose descendants are ignored in the raycast.
terrainCellsAreCubes	boolean	false	Whether `Terrain` cells are treated as full cubes when calculating intersection. Default is false.
ignoreWater	boolean	false	Whether `Terrain` water cells are ignored by the ray. Default is false.

Returns

Type	Description
Tuple	The `BasePart` or `Terrain` cell hit, the `Vector3` point of intersection, the `Vector3` surface normal at the point of intersection, and the `Material` of the `BasePart` or terrain cell hit.

Field	Value
tags	["Deprecated"]
security	None
thread safety	Unsafe

WorldRoot:findPartOnRay

Deprecated. This deprecated function is a variant of WorldRoot:FindPartOnRay() which should be used instead.

Parameters

Name	Type	Default
ray	Ray
ignoreDescendantsInstance	Instance	nil
terrainCellsAreCubes	boolean	false
ignoreWater	boolean	false

Returns

Type	Description
Tuple

Field	Value
tags	["Deprecated"]
security	None
thread safety	Unsafe

WorldRoot:FindPartOnRayWithIgnoreList

Deprecated. This function has been deprecated. Use WorldRoot:Raycast() along with RaycastParams for new work.

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

Name	Type	Default	Description
ray	Ray		A `Ray` whose origin and direction define the raycast.
ignoreDescendantsTable	Instances		An array of objects whose descendants are excluded from the raycast.
terrainCellsAreCubes	boolean	false	Whether `Terrain` cells are treated as full cubes when calculating intersection. Default is false.
ignoreWater	boolean	false	Whether `Terrain` water cells are ignored by the ray. Default is false.

Returns

Type	Description
Tuple	The `BasePart` or `Terrain` cell hit, the `Vector3` point of intersection, the `Vector3` surface normal at the point of intersection, and the `Material` of the `BasePart` or terrain cell hit.

Field	Value
tags	["Deprecated"]
security	None
thread safety	Unsafe

WorldRoot:FindPartOnRayWithWhitelist

Deprecated. This function has been deprecated. Use WorldRoot:Raycast() along with RaycastParams for new work.

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

Name	Type	Default	Description
ray	Ray		A `Ray` whose origin and direction define the raycast.
whitelistDescendantsTable	Instances		An array of objects whose descendants are the only candidates considered in the raycast.
ignoreWater	boolean	false	Whether `Terrain` water cells are ignored by the ray. Default is false.

Returns

Type	Description
Tuple	The `BasePart` or `Terrain` cell hit, the `Vector3` point of intersection, the `Vector3` surface normal at the point of intersection, and the `Material` of the `BasePart` or terrain cell hit.

Field	Value
tags	["Deprecated"]
security	None
thread safety	Unsafe

WorldRoot:FindPartsInRegion3

Deprecated. This function has been deprecated. Use WorldRoot:GetPartBoundsInBox() along with OverlapParams for new work.

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

Name	Type	Default	Description
region	Region3		The `Region3` to be checked.
ignoreDescendantsInstance	Instance	nil	An `Instance` to be ignored.
maxParts	int	20	The maximum amount of `BaseParts` to be returned.

Returns

Type	Description
List	An array of `BaseParts` within the `Region3`.

Field	Value
tags	["Deprecated"]
security	None
thread safety	Unsafe

WorldRoot:findPartsInRegion3

Deprecated. This deprecated function is a variant of WorldRoot:FindPartsInRegion3() which should be used instead.

Parameters

Name	Type	Default
region	Region3
ignoreDescendantsInstance	Instance	nil
maxParts	int	20

Returns

Type	Description
List

Field	Value
tags	["Deprecated"]
security	None
thread safety	Unsafe

WorldRoot:FindPartsInRegion3WithIgnoreList

Deprecated. This function has been deprecated. Use WorldRoot:GetPartBoundsInBox() along with OverlapParams for new work.

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

Name	Type	Default	Description
region	Region3		The `Region3` to be checked.
ignoreDescendantsTable	Instances		An array of objects to be ignored.
maxParts	int	20	The maximum number of `BaseParts` to be returned.

Returns

Type	Description
List	An array of `BaseParts` found within the `Region3`.

Field	Value
tags	["Deprecated"]
security	None
thread safety	Unsafe

WorldRoot:FindPartsInRegion3WithWhiteList

Deprecated. This function has been deprecated. Use WorldRoot:GetPartBoundsInBox() along with OverlapParams for new work.

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

Name	Type	Default	Description
region	Region3		The `Region3` to be checked.
whitelistDescendantsTable	Instances		An array of objects to check.
maxParts	int	20	The maximum number of `BaseParts` to be returned.

Returns

Type	Description
List	An array of `BaseParts` within the `Region3`.

Field	Value
tags	["Deprecated"]
security	None
thread safety	Unsafe

WorldRoot:GetMaxCollisionGroups

Returns the maximum number of collision groups the engine supports per world. This value is currently 32.

Returns

Type	Description
int

Field	Value
security	None
thread safety	Unsafe
capabilities	["Physics"]
simulationAccess	true

WorldRoot:GetPartBoundsInBox

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

Name	Type	Default	Description
cframe	CFrame		The location of the center of the given box volume to be queried.
size	Vector3		The size of the given box volume to be queried.
overlapParams	OverlapParams	OverlapParams{MaxParts=0, Tolerance=0, BruteForceAllSlow=false, RespectCanCollide=false, CollisionGroup=Default, FilterDescendantsInstances={}}	Contains reusable portions of the spatial query parameters.

Returns

Type	Description
List	An array of `BaseParts` which matched the spatial query.

Field	Value
tags	["CustomLuaState"]
security	None
thread safety	Safe
simulationAccess	true

WorldRoot:GetPartBoundsInRadius

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

Parameters

Name	Type	Default	Description
position	Vector3		The location of the center of the given sphere volume to be queried.
radius	float		The radius of the given sphere volume to be queried.
overlapParams	OverlapParams	OverlapParams{MaxParts=0, Tolerance=0, BruteForceAllSlow=false, RespectCanCollide=false, CollisionGroup=Default, FilterDescendantsInstances={}}	Contains reusable portions of the spatial query parameters.

Returns

Type	Description
List	An array of `BaseParts` which matched the spatial query.

Field	Value
tags	["CustomLuaState"]
security	None
thread safety	Safe
simulationAccess	true

WorldRoot:GetPartsInPart

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.

Parameters

Name	Type	Default	Description
part	BasePart		The part whose volume is to be checked against other parts.
overlapParams	OverlapParams	OverlapParams{MaxParts=0, Tolerance=0, BruteForceAllSlow=false, RespectCanCollide=false, CollisionGroup=Default, FilterDescendantsInstances={}}	Contains reusable portions of the spatial query parameters.

Returns

Type	Description
List	An array of `BaseParts` which matched the spatial query.

Field	Value
tags	["CustomLuaState"]
security	None
thread safety	Safe
simulationAccess	true

WorldRoot:GetRegisteredCollisionGroups

Returns a table with info on all of this world's collision groups. Each value in the returned table is itself a table and containing two members:

Member	Type	Description
mask	integer	The collision group's mask; only for internal use.
name	string	Name of the collision group.

Returns

Type	Description
Array

Field	Value
security	None
thread safety	Unsafe
capabilities	["Physics"]
simulationAccess	true

WorldRoot:IKMoveTo

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

Name	Type	Default	Description
part	BasePart		The part being moved.
target	CFrame		The location to move the specified part.
translateStiffness	float	0.5	A number between 0 and 1 specifying how aggressively to match the part's position to the position part of the target `CFrame`.
rotateStiffness	float	0.5	A number between 0 and 1 specifying how aggressively to match the part's rotation to the rotation part of the target `CFrame`.
collisionsMode	IKCollisionsMode	OtherMechanismsAnchored	Allows you to specify what objects should be effected by the physical resolution.

Returns

Type	Description
()

Field	Value
security	PluginSecurity
thread safety	Unsafe
simulationAccess	true

WorldRoot:IsCollisionGroupRegistered

Checks if a collision group is registered in this world. It's recommended that you call this method before calling methods that throw errors for unregistered collision groups, such as WorldRoot:CollisionGroupSetCollidable().

Parameters

Name	Type	Default	Description
name	string

Returns

Type	Description
boolean

Field	Value
security	None
thread safety	Unsafe
capabilities	["Physics"]
simulationAccess	true

WorldRoot:IsRegion3Empty

Deprecated. This function has been deprecated. Use WorldRoot:GetPartBoundsInBox() along with OverlapParams for new work.

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

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

Name	Type	Default	Description
region	Region3		The `Region3` to be checked.
ignoreDescendentsInstance	Instance	nil	An `Instance` to be ignored.

Returns

Type	Description
boolean	True if the `Region3` is empty.

Field	Value
tags	["Deprecated"]
security	None
thread safety	Unsafe

WorldRoot:IsRegion3EmptyWithIgnoreList

Deprecated. This function has been deprecated. Use WorldRoot:GetPartBoundsInBox() along with OverlapParams for new work.

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

Name	Type	Default	Description
region	Region3		The `Region3` to be checked.
ignoreDescendentsTable	Instances		An array of objects to be ignored.

Returns

Type	Description
boolean	True if the `Region3` is empty.

Field	Value
tags	["Deprecated"]
security	None
thread safety	Unsafe

WorldRoot:Raycast

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

Name	Type	Default	Description
origin	Vector3		The origin point of the ray.
direction	Vector3		The directional vector of the ray. Note that the length of this vector matters, as parts/terrain further away than its length will not be tested.
raycastParams	RaycastParams	RaycastParams{IgnoreWater=false, BruteForceAllSlow=false, RespectCanCollide=false, CollisionGroup=Default, FilterDescendantsInstances={}}	An object used to specify hit eligibility in the raycast operation. If not provided, default values are used where all parts are considered and `Terrain` water is not ignored.

Returns

Type	Description
RaycastResult?	Contains the results of a raycast operation, or `nil` if no eligible `BasePart` or `Terrain` cell was hit.

Field	Value
security	None
thread safety	Safe
simulationAccess	true

Code samples: View on Creator Hub (worldroot---raycast).

WorldRoot:RegisterCollisionGroup

Registers a new collision group in this world with the given name. The name cannot be "Default".

Note that this method has a slight performance overhead based on the number of BaseParts in the world, so it's recommended that you register all collision groups at edit time through the Studio editor and call UnregisterCollisionGroup() and RenameCollisionGroup() as infrequently as possible.

Parameters

Name	Type	Default	Description
name	string

Returns

Type	Description
()

Field	Value
security	None
thread safety	Unsafe
capabilities	["Physics"]
simulationAccess	true

WorldRoot:RenameCollisionGroup

Renames the specified registered collision group in this world, but does not rename the CollisionGroup property of parts that utilize the group. The first argument of this method is the name of the group to rename, the second argument is the new name for the group. If the specified group does not exist, this method will not do anything. The naming conventions for the new name follow the same rules as if the group was being created with RegisterCollisionGroup().

This method will throw a runtime error in the following circumstances:

Invalid or empty name provided for either argument.
The method is called from a client.

Parameters

Name	Type	Default	Description
from	string
to	string

Returns

Type	Description
()

Field	Value
security	None
thread safety	Unsafe
capabilities	["Physics"]
simulationAccess	true

WorldRoot:Shapecast

Casts the shape of the given BasePart 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:Blockcast() and WorldRoot:Spherecast(), which use a simple box or sphere, this method casts the actual geometry of the provided part.

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

This method throws an error if it is passed a non-existent part, an invalid direction, or a part with Terrain geometry.

Parameters

Name	Type	Default	Description
part	BasePart		The part whose shape is cast. The cast uses this part's geometry (block, ball, mesh, and so on) and size; excessively large parts may not be supported, and it cannot be a `Terrain` part.
direction	Vector3		Direction of the shapecast, with the magnitude representing the maximum distance the shape can travel. The maximum distance is 1024 studs.
params	RaycastParams	RaycastParams{IgnoreWater=false, BruteForceAllSlow=false, RespectCanCollide=false, CollisionGroup=Default, FilterDescendantsInstances={}}	An object used to specify hit eligibility in the shapecast operation. If not provided, default values are used where all other parts are considered and `Terrain` water is not ignored. The part being cast is always excluded from the results.

Returns

Type	Description
RaycastResult?	Contains the result of the shapecast operation, or `nil` if no eligible `BasePart` or `Terrain` cell was hit.

Field	Value
security	None
thread safety	Unsafe
simulationAccess	true

WorldRoot:Spherecast

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.

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

Parameters

Name	Type	Default	Description
position	Vector3		The initial position of the cast spherical shape.
radius	float		The radius of the cast spherical shape in studs. The maximum radius is 256 studs.
direction	Vector3		Direction of the shapecast, with the magnitude representing the maximum distance the shape can travel. The maximum distance is 1024 studs.
params	RaycastParams	RaycastParams{IgnoreWater=false, BruteForceAllSlow=false, RespectCanCollide=false, CollisionGroup=Default, FilterDescendantsInstances={}}	An object used to specify hit eligibility in the shapecast operation. If not provided, default values are used where all parts are considered and `Terrain` water is not ignored.

Returns

Type	Description
RaycastResult?	Contains the result of the shapecast operation, or `nil` if no eligible `BasePart` or `Terrain` cell was hit.

Field	Value
security	None
thread safety	Safe
simulationAccess	true

Code samples: View on Creator Hub (worldroot---spherecast).

WorldRoot:StepPhysics

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

Name	Type	Default	Description
dt	float		The amount of time that will be simulated. This argument must be a positive number. Larger values will increase the runtime of this function.
parts	Instances	{}	Optional array of parts that will be simulated. This set must contain instances that are of type `BasePart`; any other types will be ignored.

Returns

Type	Description
()

Field	Value
security	PluginSecurity
thread safety	Unsafe

Code samples: View on Creator Hub (worldroot---stepphysics).

WorldRoot:UnregisterCollisionGroup

Unregisters the collision group for the given name in this world, with the following behaviors:

If an invalid name is provided, the method will not do anything.
If the reserved name "Default" is provided or if the method is called from a client, it will throw an error.
If there are any parts in the collision group when it is removed, those parts will still maintain the same collision group name. The physical behavior of parts in a removed group is undefined, so it's recommended to move any parts in a removed group to another group, such as the "Default" group.

Parameters

Name	Type	Default	Description
name	string

Returns

Type	Description
()

Field	Value
security	None
thread safety	Unsafe
capabilities	["Physics"]
simulationAccess	true

Properties

Inherited from Model

Name	Type / Returns	Description
Model.LevelOfDetail	ModelLevelOfDetail	Sets the level of detail on the model for experiences with instance streaming enabled.
Model.ModelStreamingMode	ModelStreamingMode	Controls the model streaming behavior on `Models` when instance streaming is enabled.
Model.PrimaryPart	BasePart	The primary part of the `Model`, or `nil` if not explicitly set.
Model.Scale	float	Editor-only property used to scale the model around its pivot. Setting this property will move the scale as though `Model:ScaleTo()` was called on it.
Model.WorldPivot	CFrame	Determines where the pivot of a `Model` which does not have a set `Model.PrimaryPart` is located.

Inherited from PVInstance

Name	Type / Returns	Description
PVInstance.Origin	CFrame	Editor-only property that reads and sets the world `CFrame` of the `PVInstance`'s pivot, moving the entire instance when changed from the Studio Properties window.
PVInstance.Pivot Offset	CFrame	Editor-only property that displays and edits the pivot's `CFrame` relative to the instance, moving only the pivot and leaving the instance in place.

Inherited from Instance

Name	Type / Returns	Description
Instance.Archivable	boolean	Determines if an `Instance` and its descendants can be cloned using `Instance:Clone()`, and can be saved/published.
Instance.archivable	boolean
Instance.Capabilities	SecurityCapabilities	The set of capabilities allowed to be used for scripts inside this container.
Instance.IsInSandbox	boolean	Indicates whether the instance is inside a sandboxed container.
Instance.Name	string	A non-unique identifier of the `Instance`.
Instance.Parent	Instance	Determines the hierarchical parent of the `Instance`.
Instance.PredictionMode	PredictionMode	Reflects the client-side prediction mode applied to the instance under server-authoritative physics.
Instance.RobloxLocked	boolean	A deprecated property that used to protect `CoreGui` objects.
Instance.Sandboxed	boolean	When enabled, the instance can only access abilities in its `Capabilities` list.
Instance.UniqueId	UniqueId	A unique identifier for the instance.

Inherited from Object

Name	Type / Returns	Description
Object.ClassName	string	A read-only string representing the class this `Object` belongs to.
Object.className	string

Events

Inherited from Instance

Name	Type / Returns	Description
Instance.AncestryChanged		Fires when the `Instance.Parent` property of this object or one of its ancestors is changed.
Instance.AttributeChanged		Fires whenever an attribute is changed on the `Instance`.
Instance.ChildAdded		Fires after an object is parented to this `Instance`.
Instance.childAdded
Instance.ChildRemoved		Fires after a child is removed from this `Instance`.
Instance.DescendantAdded		Fires after a descendant is added to the `Instance`.
Instance.DescendantRemoving		Fires immediately before a descendant of the `Instance` is removed.
Instance.Destroying		Fires immediately before (or is deferred until after) the instance is destroyed via `Instance:Destroy()`.
Instance.StyledPropertiesChanged		Fires whenever any style property is changed on the instance, including when a property is set to `nil`.

Inherited from Object

Name	Type / Returns	Description
Object.Changed		Fires immediately after a property of the object changes, with some limitations.