WorldRoot

Mostrar obsoleto
No creable

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

Resumen

Propiedades

Propiedades heredados de ModelPropiedades heredados de PVInstance

Métodos

Métodos heredados de 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.

Métodos heredados de PVInstance

Propiedades

Métodos

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.

Parámetros

partList: Instances

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.

Valor predeterminado: 0.000199999995

Devuelve

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.

Muestras de código

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

Escribir paralelo

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.

Parámetros

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.

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

Devuelve

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

Muestras de código

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.

Parámetros

partList: Instances
cframeList: Array
Valor predeterminado: "FireAllEvents"

Devuelve

void

GetPartBoundsInBox

Instances
Escribir paralelo

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.

Parámetros

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.

Valor predeterminado: "OverlapParams{MaxParts=0, Tolerance=0, BruteForceAllSlow=false, RespectCanCollide=false, CollisionGroup=Default, FilterDescendantsInstances={}}"

Devuelve

Instances

An array of BaseParts which matched the spatial query.

GetPartBoundsInRadius

Instances
Escribir paralelo

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.

Parámetros

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.

Valor predeterminado: "OverlapParams{MaxParts=0, Tolerance=0, BruteForceAllSlow=false, RespectCanCollide=false, CollisionGroup=Default, FilterDescendantsInstances={}}"

Devuelve

Instances

An array of BaseParts which matched the spatial query.

GetPartsInPart

Instances
Escribir paralelo

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.

Parámetros

part: BasePart

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

overlapParams: OverlapParams

Contains reusable portions of the spatial query parameters.

Valor predeterminado: "OverlapParams{MaxParts=0, Tolerance=0, BruteForceAllSlow=false, RespectCanCollide=false, CollisionGroup=Default, FilterDescendantsInstances={}}"

Devuelve

Instances

An array of BaseParts which matched the spatial query.

IKMoveTo

void
Seguridad del plugin

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.

Parámetros

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.

Valor predeterminado: 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.

Valor predeterminado: 0.5
collisionsMode: Enum.IKCollisionsMode

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

Valor predeterminado: "OtherMechanismsAnchored"

Devuelve

void
Escribir paralelo

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.

Parámetros

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.

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

Devuelve

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

Muestras de código

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

Parámetros

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

Devuelve

Spherecast

Escribir paralelo

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.

Parámetros

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.

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

Devuelve

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

Muestras de código

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
Seguridad del plugin

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.

Parámetros

dt: number

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.

Valor predeterminado: "{}"

Devuelve

void

Muestras de código

StepPhysics

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)

Eventos