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

Properties inherited from ModelProperties inherited from PVInstance

Methods

Methods inherited from Model
  • AddPersistentPlayer(playerInstance: Player):void

    Sets this model to be persistent for the specified player. Model.ModelStreamingMode must be set to PersistentPerPlayer for behavior to be changed as a result of addition.

  • Returns a description of a volume that contains all parts of a Model.

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

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

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

  • MoveTo(position: Vector3):void

    Moves the PrimaryPart to the given position. If a primary part has not been specified, the root part of the model will be used.

  • RemovePersistentPlayer(playerInstance: Player):void

    Makes this model no longer persistent for specified player. Model.ModelStreamingMode must be set to PersistentPerPlayer for behavior to be changed as a result of removal.

  • ScaleTo(newScaleFactor: number):void

    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.

  • TranslateBy(delta: Vector3):void

    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.

Methods inherited from PVInstance

Properties

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

Code Samples

Checking for Touching Parts

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

Blockcast

write parallel

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

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.

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

Returns

Contains the result of the shapecast operation, or nil if no eligible BasePart or Terrain cell was hit.

Code Samples

Blockcasting

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

BulkMoveTo

void

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

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

Returns

void

GetPartBoundsInBox

write parallel

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

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

write parallel

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

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

write parallel

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

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

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

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 aggressively to match the part's rotation to the rotation part of the target CFrame.

Default Value: 0.5
collisionsMode: Enum.IKCollisionsMode

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

Default Value: "OtherMechanismsAnchored"

Returns

void
write parallel

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

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

Raycasting

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

Shapecast

Parameters

part: BasePart
direction: Vector3
Default Value: "RaycastParams{IgnoreWater=false, BruteForceAllSlow=false, RespectCanCollide=false, CollisionGroup=Default, FilterDescendantsInstances={}}"

Returns

Spherecast

write parallel

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

position: Vector3

The initial position of the cast spherical shape.

radius: number

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.

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

Returns

Contains the result of the shapecast operation, or nil if no eligible BasePart or Terrain cell was hit.

Code Samples

Spherecasting

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

StepPhysics

void

Parameters

dt: number
parts: Objects
Default Value: "{}"

Returns

void

Events