WorldRoot

Show Deprecated
Not Creatable

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

Summary

Properties

Events

Methods

ArePartsTouchingOthers(partList: Objects, overlapIgnored: number): boolean  

Returns true if any of the given BasePart are touching any other parts.

BulkMoveTo(partList: Objects, cframeList: Array, eventMode: BulkMoveMode): void  

Moves a table of parts to CFrames in a table of CFrames, without firing property changed events.

CacheCurrentTerrain(id: string, center: Vector3, radius: number): string  


GetPartBoundsInBox(cframe: CFrame, size: Vector3, overlapParams: OverlapParams): Objects  

Returns an array of parts whose bounding boxes overlap a given box.

GetPartBoundsInRadius(position: Vector3, radius: number, overlapParams: OverlapParams): Objects  

Returns an array of parts whose bounding boxes overlap a given sphere.

GetPartsInPart(part: BasePart, overlapParams: OverlapParams): Objects  

Returns an array of parts whose occupied space is shared with the given part.

IKMoveTo(part: BasePart, target: CFrame, translateStiffness: number, rotateStiffness: number, collisionsMode: IKCollisionsMode): void  

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.

Raycast(origin: Vector3, direction: Vector3, raycastParams: RaycastParams): RaycastResult  

Casts a ray using an origin, direction, and optional RaycastParams, then returns a RaycastResult if an eligible object or terrain intersects the ray.

RaycastCachedTerrain(id: string, origin: Vector3, direction: Vector3, ignoreWater: boolean): RaycastResult  


SetInsertPoint(point: Vector3, ignoreGrid: boolean): void  


Properties

Events

Methods

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

partList: Objects

A list of parts checks to see if any parts in the list are touching any parts not in the list.

overlapIgnored: number

The part overlap threshold in studs that is ignored before parts are considered to be touching.

Default Value: "0.000199999995"

Returns

True iff any of the parts in partList are touching any other parts (parts not in the partList). False if no parts are passed.

Code Samples

Checking for Touching Parts

1local part1 = Instance.new("Part")
2part1.Name = "Part1"
3part1.Anchored = true
4part1.Transparency = 0.5
5part1.Color = Color3.fromRGB(185, 100, 38)
6part1.Size = Vector3.new(2, 2, 2)
7part1.Position = Vector3.new(0, 4, 0)
8part1.Parent = workspace
9
10local part2 = Instance.new("Part")
11part2.Name = "Part2"
12part2.Anchored = true
13part2.Transparency = 0.5
14part2.Color = Color3.fromRGB(200, 10, 0)
15part2.Size = Vector3.new(2, 2, 2)
16part2.Position = Vector3.new(0, 5, 0)
17part2.Parent = workspace
18
19local partList = { part1 }
20
21print(workspace:ArePartsTouchingOthers(partList, 0)) -- True
22print(workspace:ArePartsTouchingOthers(partList, 0.999)) -- True
23print(workspace:ArePartsTouchingOthers(partList, 1)) -- False

BulkMoveTo

void

Warning: You should only use this function if you are sure that part movement is a bottleneck in your code, simply setting the CFrame property of the individual parts / welded models you want to move will be fast enough in the vast majority of cases.

This function moves a table of parts to the location specified in a table of CFrames. This makes it 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 of BulkMoveTo allows you to further speed up movement of the parts by specifying the Position and Orientation. Changed events should not be fired on the parts. If you specify FireCFrameChanged as the BulkMoveMode then only CFrame.Changed be fire, rather than changed firing for Position, Orientation, and CFrame like it normally does.

Parameters

partList: Objects
cframeList: Array
eventMode: BulkMoveMode
Default Value: "FireAllEvents"

Returns

void

CacheCurrentTerrain

Roblox Script Security

Parameters

id: string
center: Vector3
radius: number

Returns

ClearCachedTerrain

Roblox Script Security

Parameters

id: string

Returns

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 instance whitelist/blacklist, 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

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

Contains reusable portions of the spatial query parameters.

Default Value: "OverlapParams{MaxParts=false, BruteForceAllSlow=false, RespectCanCollide=false, CollisionGroup=Default, FilterDescendantsInstances={}}"

Returns

An array of BaseParts which matched the spatial query.

GetPartBoundsInRadius

WorldRoot:GetPartBoundsInRadius() returns an array of parts whose bounding boxes overlap a sphere whose volume is described using the given center (CFrame) 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 instance whitelist/blacklist, 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

position: Vector3

The location of the center of the given sphere volume to be queried.

radius: number

The radius of the given sphere volume to be queried.

overlapParams: OverlapParams

Contains reusable portions of the spatial query parameters.

Default Value: "OverlapParams{MaxParts=false, BruteForceAllSlow=false, RespectCanCollide=false, CollisionGroup=Default, FilterDescendantsInstances={}}"

Returns

An array of BaseParts which matched the spatial query.

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.

This method uses a OverlapParams object to describe reusable portions of the spatial query, such as an instance whitelist/blacklist, 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

part: BasePart

The part whose volume is to be checked against other parts.

overlapParams: OverlapParams

Contains reusable portions of the spatial query parameters.

Default Value: "OverlapParams{MaxParts=false, BruteForceAllSlow=false, RespectCanCollide=false, CollisionGroup=Default, FilterDescendantsInstances={}}"

Returns

An array of BaseParts which matched the spatial query.

IKMoveTo

void
Plugin Security

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 agressively 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 agresively to match the part's rotation to 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

part: BasePart

The part being moved.

target: CFrame

The location to move the specified part.

translateStiffness: number

A number between 0 and 1 specifying how aggressively to match the part's position to the position part of the target CFrame.

Default Value: "0.5"
rotateStiffness: number

A number between 0 and 1 specifying how aggresively to match the part's rotation to to the rotation part of the target CFrame.

Default Value: "0.5"
collisionsMode: IKCollisionsMode

Allows you to specify what objects should be effected by the physical resolution.

Default Value: "OtherMechanismsAnchored"

Returns

void

No return.

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

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

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.

Default Value: "RaycastParams{IgnoreWater=false, BruteForceAllSlow=false, RespectCanCollide=false, CollisionGroup=Default, FilterDescendantsInstances={}}"

Returns

Contains the results of a raycast operation, or nil if no eligible BasePart or Terrain cell was hit.

Code Samples

Basic Raycasting

1local raycastParams = RaycastParams.new()
2raycastParams.FilterType = Enum.RaycastFilterType.Whitelist
3raycastParams.FilterDescendantsInstances = { workspace.Model }
4raycastParams.IgnoreWater = true
5
6local part = workspace.Part
7local raycastResult = workspace:Raycast(part.Position, part.CFrame.LookVector * 50, raycastParams)
8
9if raycastResult then
10 print("Object/terrain hit:", raycastResult.Instance:GetFullName())
11 print("Hit position:", raycastResult.Position)
12 print("Surface normal at the point of intersection:", raycastResult.Normal)
13 print("Material hit:", raycastResult.Material.Name)
14else
15 print("Nothing was hit!")
16end
17

RaycastCachedTerrain

Roblox Script Security

Parameters

id: string
origin: Vector3
direction: Vector3
ignoreWater: boolean

SetInsertPoint

void
Roblox Script Security

Parameters

point: Vector3
ignoreGrid: boolean
Default Value: "false"

Returns

void