WorldRoot
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 ModelSets the level of detail on the model for experiences with instance streaming enabled.
Controls the model streaming behavior on Models when instance streaming is enabled.
The primary part of the Model, or nil if not explicitly set.
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.
Determines where the pivot of a Model which does not have a set Model.PrimaryPart is located.
Methods
Returns true if any of the given BasePart are touching any other parts.
Casts a block shape in a given direction and returns a RaycastResult if the shape hits a BasePart or Terrain cell.
Returns an array of parts whose bounding boxes overlap a given box.
Returns an array of parts whose bounding boxes overlap a given sphere.
Returns an array of parts whose occupied space is shared with the given part.
- IKMoveTo(part : BasePart,target : CFrame,translateStiffness : number,rotateStiffness : number,collisionsMode : Enum.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.
Casts a ray using an origin, direction, and optional RaycastParams, then returns a RaycastResult if an eligible object or terrain intersects the ray.
- Spherecast(position : Vector3,radius : number,direction : Vector3,params : RaycastParams):RaycastResult?
Casts a spherical shape in a given direction and returns a RaycastResult if the shape hits a BasePart or Terrain cell.
Advances the simulation for parts in the world forward based on a specified time increment and an optional set of BaseParts.
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.
Moves the PrimaryPart to the given position. If a primary part has not been specified, the root part of the model will be used.
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.
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.
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.
Gets the pivot of a PVInstance.
Transforms the PVInstance along with all of its descendant PVInstances such that the pivot is now located at the specified CFrame.
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
A list of parts checks to see if any parts in the list are touching any parts not in the list.
The part overlap threshold in studs that is ignored before parts are considered to be touching.
Returns
Code Samples
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
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
The initial position and rotation of the cast block shape.
The size of the cast block shape in studs. The maximum size is 512 studs.
Direction of the shapecast, with the magnitude representing the maximum distance the shape can travel. The maximum distance is 1024 studs.
Returns
Code Samples
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
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
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
The location of the center of the given box volume to be queried.
The size of the given box volume to be queried.
Contains reusable portions of the spatial query parameters.
Returns
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).
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
The location of the center of the given sphere volume to be queried.
The radius of the given sphere volume to be queried.
Contains reusable portions of the spatial query parameters.
Returns
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 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
The part whose volume is to be checked against other parts.
Contains reusable portions of the spatial query parameters.
Returns
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
The part being moved.
The location to move the specified part.
A number between 0 and 1 specifying how aggressively to match the part's position to the position part of the target CFrame.
A number between 0 and 1 specifying how aggressively to match the part's rotation to the rotation part of the target CFrame.
Allows you to specify what objects should be effected by the physical resolution.
Returns
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
The origin point of the ray.
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.
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
Code Samples
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
Returns
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.
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
The initial position of the cast spherical shape.
The radius of the cast spherical shape in studs. The maximum radius is 256 studs.
Direction of the shapecast, with the magnitude representing the maximum distance the shape can travel. The maximum distance is 1024 studs.
Returns
Code Samples
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
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
The amount of time that will be simulated. This argument must be a positive number. Larger values will increase the runtime of this function.
Returns
Code Samples
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)