When parented to a `Class.ViewportFrame`, `WorldModel` extends limited physics
for its children on to that `Class.ViewportFrame`. For example,
`Class.BasePart|BaseParts` that are parented to the `WorldModel` can be
animated and spatially queried (for example by raycasts) but those parts are
**not** simulated. Furthermore, you can put `Class.Humanoid` characters in the
`WorldModel` and their joints will be set up correctly for animation.

`WorldModel` also exposes the
`Class.WorldModel.UseWorkspaceCollisionGroups|UseWorkspaceCollisionGroups`
property to determine whether it uses `Class.Workspace` collision groups or
its own independent collision groups for queries.

To avoid possible performance issues, make sure to only create `WorldModels`
when you want to show them and to delete `WorldModels` that are currently not
in use.


WorldModel

When `false` (default), this `WorldModel` uses its own collision groups
for all collision-related behavior.

When `true`, this `WorldModel` uses `Class.Workspace` collision groups.
Additionally, the collision group state of this `WorldModel` can continue
to be modified.


WorldModel.UseWorkspaceCollisionGroups

Determines whether this `WorldModel` uses `Class.Workspace` collision
groups or its own independent collision groups for queries.


Extends limited physics to its children.


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


The code block below demonstrates how to use
`Class.WorldRoot:ArePartsTouchingOthers()` to check if parts in a list are
touching any parts in the workspace not in the list.

First the script creates two square parts that overlap 1 stud, `Part1` and
`Part2`. Then, it prints the value returned by ArePartsTouchingOthers() when
Part1 is passed in `partList` at three different overlap values: `0`, `0.999`,
and `1`. The first two times ArePartsTouchingOthers() is called return `false`
because the overlap values are less than the distance that Part1 and Part2
overlap. The third call returns `true` because the overlap value is equal to
the distance that the parts overlap.


**ArePartsTouchingOthers** returns true if at least one of the given
`Class.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.


WorldRoot:ArePartsTouchingOthers

partList

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


overlapIgnored

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


True if and only if any of the `Class.Part|parts` in `partList` are
touching any other parts (parts not in the partList). False if no
parts are passed.


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


Casts a block and returns the first collision with a `Class.BasePart` or
`Class.Terrain`. Prints the properties of the RaycastResult if a result was
hit.


Casts a block shape in a given direction and returns the first collision
with a `Class.BasePart` or `Class.Terrain` cell. This is analogous to how
`Class.WorldRoot:Raycast()` casts a linear ray in a direction to find a
collision, but it uses a 3D shape instead of a ray.

Unlike `Class.WorldRoot:GetPartsInPart()`, this method does not detect
`Class.BasePart|BaseParts` that **initially** intersect the shape.

If a hit is detected, a `Datatype.RaycastResult` is returned containing
the hit information. The `Datatype.RaycastResult.Distance|Distance`
property represents the distance the shape has to travel to find a hit,
and the `Datatype.RaycastResult.Position|Position` property represents the
intersection point that causes the hit.

This method throws an error if it is passed invalid `Datatype.CFrame`,
size, or direction inputs.


WorldRoot:Blockcast

cframe

The initial position and rotation of the cast block shape.


size

The size of the cast block shape in studs. The maximum size is 512
studs.


direction

Direction of the shapecast, with the magnitude representing the
maximum distance the shape can travel. The maximum distance is 1024
studs.


params

An object used to specify hit eligibility in the shapecast operation.
If not provided, default values are used where all parts are
considered and `Class.Terrain` water is not ignored.


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


Casts a block shape in a given direction and returns a
`Datatype.RaycastResult` if the shape hits a `Class.BasePart` or
`Class.Terrain` cell.


This function moves an array of `Class.BasePart|BaseParts` to an array of
`Datatype.CFrame|CFrames` without necessarily firing the default property
`Class.Object.Changed|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 `Datatype.CFrame|CFrame` at index `i` in
`cframeList`. The arrays must contain the same number of entries.

```lua
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 `Class.Object.Changed|Changed` event of each part fires
for `Class.BasePart.Position|Position`,
`Class.BasePart.Orientation|Orientation`, and
`Class.BasePart.CFrame|CFrame`. However, if you specify
`Enum.BulkMoveMode|FireCFrameChanged` as the third argument, only the
`Class.Object.Changed|Changed` event for the
`Class.BasePart.CFrame|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
`Class.BasePart.CFrame|CFrame` property of individual parts and welded
models is fast enough in the majority of cases.


WorldRoot:BulkMoveTo

An array of `Class.BasePart|BaseParts` to be moved. Each entry is
matched by index to the corresponding entry in `cframeList`.


cframeList

An array of `Datatype.CFrame|CFrames` that the parts will be moved to,
matched by index to `partList`. Both arrays must be the same length.


eventMode

An `Enum.BulkMoveMode` enum specifying which
`Class.Object.Changed|Changed` events fire during the move. Default is
`Enum.BulkMoveMode|FireAllEvents`.


Moves an array of `Class.BasePart|BaseParts` to an array of
`Datatype.CFrame|CFrames`.


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.


WorldRoot:CollisionGroupsAreCollidable

name1

name2

Returns whether the two groups will collide in this world.


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
`Class.WorldRoot:IsCollisionGroupRegistered()` before making this call.


WorldRoot:CollisionGroupSetCollidable

collidable

Sets the collision status between two groups in this world.


**FindPartOnRay** uses [raycasting](/workspace/raycasting) to
find the first `Class.BasePart` or `Class.Terrain` cell intersecting with
a given `Datatype.Ray`. This function returns the `Class.BasePart` or
terrain cell hit, the point of intersection, the surface normal at the
point of intersection, and the associated `Enum.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 `Class.Mouse.TargetFilter` property.

The `terrainCellsAreCubes` and `ignoreWater` parameters determine whether
`Class.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 `Class.WorldRoot:FindPartOnRayWithWhitelist()` and
`Class.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](/workspace/collisions#collision-filtering)
  that does not collide with the "Default" collision group are ignored
  implicitly.


WorldRoot:FindPartOnRay

A `Datatype.Ray` whose origin and direction define the raycast.


ignoreDescendantsInstance

An `Class.Instance` whose descendants are ignored in the raycast.


terrainCellsAreCubes

Whether `Class.Terrain` cells are treated as full cubes when
calculating intersection. Default is false.


ignoreWater

Whether `Class.Terrain` water cells are ignored by the ray. Default is
false.


The `Class.BasePart` or `Class.Terrain` cell hit, the
`Datatype.Vector3` point of intersection, the `Datatype.Vector3`
surface normal at the point of intersection, and the `Enum.Material`
of the `Class.BasePart` or terrain cell hit.


Returns the first `Class.BasePart` or `Class.Terrain` cell intersecting
with the given `Datatype.Ray`.


WorldRoot:findPartOnRay

This function is a variant of `Class.WorldRoot:FindPartOnRay()` with the
addition of an ignore list. This lets you ignore certain parts or
`Class.Model|Models`.

Those looking to **include** a specific group of objects should instead
use `Class.WorldRoot:FindPartOnRayWithWhitelist()`.


WorldRoot:FindPartOnRayWithIgnoreList

ignoreDescendantsTable

An array of objects whose descendants are excluded from the raycast.


Returns the first `Class.BasePart` or `Class.Terrain` cell intersecting
with the given `Datatype.Ray` that isn't in, nor is a descendant of an
object in, the given ignore list.


This function is a variant of `Class.WorldRoot:FindPartOnRay()` with the
addition of an inclusion list. This lets you detect only certain parts or
`Class.Model|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 `Class.WorldRoot:FindPartOnRayWithIgnoreList()`.


WorldRoot:FindPartOnRayWithWhitelist

whitelistDescendantsTable

An array of objects whose descendants are the only candidates
considered in the raycast.


Returns the first `Class.BasePart` or `Class.Terrain` cell intersecting
with the given `Datatype.Ray` that is in, or is a descendant of an object
in, the given inclusion list.


Returns an array of `Class.BasePart|BaseParts` in the given
`Datatype.Region3`.

This function takes an optional maxParts parameter (default 20) which
limits the number of `Class.BasePart|BaseParts` that can be returned. Once
this number has been reached, the search for `Class.BasePart|BaseParts`
will stop. This means some `Class.BasePart|BaseParts` may not be returned
even if they are within the `Datatype.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 `Class.BasePart|BaseParts` are inside a `Class.BasePart` other
than the `Class.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 `Class.WorldRoot:FindPartsInRegion3WithIgnoreList()` and
`Class.WorldRoot:FindPartsInRegion3WithWhiteList()` variants of this
method exist to provide specific exclusion and inclusion functionality.

If no `Class.BasePart|BaseParts` are found, an empty array will be
returned.


WorldRoot:FindPartsInRegion3

region

maxParts

The maximum amount of `Class.BasePart|BaseParts` to be returned.


An array of `Class.BasePart|BaseParts` within the `Datatype.Region3`.


Returns an array of `Class.BasePart|BaseParts` in the given
`Datatype.Region3`.


WorldRoot:findPartsInRegion3

Returns an array of `Class.BasePart|BaseParts` in the given
`Datatype.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 `Class.BasePart|BaseParts` are found, an empty
array will be returned.

This function is a variant of `Class.WorldRoot:FindPartsInRegion3()` with
the addition of an ignore list. This allows the developer to exclude
certain `Class.BasePart|BaseParts` or `Class.Model|Models` from the
search. Those looking to find `Class.BasePart|BaseParts` in a
`Datatype.Region3` using an inclusion list should use
`Class.WorldRoot:FindPartsInRegion3WithWhiteList()`.


WorldRoot:FindPartsInRegion3WithIgnoreList

The maximum number of `Class.BasePart|BaseParts` to be returned.


An array of `Class.BasePart|BaseParts` found within the
`Datatype.Region3`.


Returns an array of `Class.BasePart|BaseParts` in the given
`Datatype.Region3` that aren't in, or a descendant of an entry in, the
given ignore list.


Returns an array of `Class.BasePart|BaseParts` in the given
`Datatype.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 `Class.BasePart|BaseParts` are found, an
empty array will be returned.

This function is a variant of `Class.WorldRoot:FindPartsInRegion3()` with
the addition of an inclusion list. This allows the developer to include
only certain `Class.BasePart|BaseParts` or `Class.Model|Models` in the
search. Those looking to find `Class.BasePart|BaseParts` in a
`Datatype.Region3` using an exclusion list should use
`Class.WorldRoot:FindPartsInRegion3WithIgnoreList()`.


WorldRoot:FindPartsInRegion3WithWhiteList

Returns an array of `Class.BasePart|BaseParts` in the given
`Datatype.Region3` that are in, or descendant of an entry in, the given
inclusion list.


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


WorldRoot:GetMaxCollisionGroups

Returns the maximum number of collision groups in this world.


`Class.WorldRoot:GetPartBoundsInBox()` returns an array of parts whose
**bounding boxes** overlap a box whose volume is described using the given
center (`Datatype.CFrame`) and size (`Datatype.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
`Class.MeshPart|MeshParts` which have non-block shapes. For cases where
accuracy especially matters, use `Class.WorldRoot:GetPartsInPart()`
instead, or further filter the results of this method yourself.

This method uses a `Datatype.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](/workspace/collisions#collision-filtering) to
use, and whether the query favors an intersected part's
`Class.BasePart.CanCollide` value over its `Class.BasePart.CanQuery`
value.


WorldRoot:GetPartBoundsInBox

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


The size of the given box volume to be queried.


overlapParams

Contains reusable portions of the spatial query parameters.


An array of `Class.BasePart|BaseParts` which matched the spatial
query.


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


`Class.WorldRoot:GetPartBoundsInRadius()` returns an array of parts whose
**bounding boxes** overlap a sphere whose volume is described using the
given center (`Datatype.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
`Class.MeshPart|MeshParts` which have non-block shapes. For cases where
accuracy especially matters, use `Class.WorldRoot:GetPartsInPart()`
instead, or further filter the results of this method yourself.

This method uses a `Datatype.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](/workspace/collisions#collision-filtering) to
use, and whether the query favors an intersected part's
`Class.BasePart.CanCollide` value over its `Class.BasePart.CanQuery`
value.


WorldRoot:GetPartBoundsInRadius

position

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


radius

The radius of the given sphere volume to be queried.


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


`Class.WorldRoot:GetPartsInPart()` returns an array of parts whose
occupied space is shared with the given part (which must exist in the same
`Class.WorldRoot` as the parts to be queried). This method can be used in
place of `Class.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 `Class.WorldRoot:GetPartBoundsInBox()` or
`Class.WorldRoot:GetPartBoundsInRadius()`, as they are less accurate but
perform more efficiently.

This method uses a `Datatype.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](/workspace/collisions#collision-filtering) to
use, and whether the query favors an intersected part's
`Class.BasePart.CanCollide` value over its `Class.BasePart.CanQuery`
value.


WorldRoot:GetPartsInPart

part

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


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


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:

<table>
  <thead>
    <tr>
      <th>Member</th>
      <th>Type</th>
      <th>Description</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>mask</td>
      <td>integer</td>
      <td>The collision group's mask; only for internal use.</td>
    </tr>
    <tr>
      <td>name</td>
      <td>string</td>
      <td>Name of the collision group.</td>
    </tr>
  </tbody>
</table>


WorldRoot:GetRegisteredCollisionGroups

Returns a table with info on all of this world's collision groups.


This function moves the specified part to the specified location via
[inverse kinematics](https://en.wikipedia.org/wiki/Inverse_kinematics)
rather than moving it there directly, to ensure any joints,
`Class.Constraint|constraints`, or collisions that part is participating
in remain physically satisfied. Currently this function is only available
in Studio to `Class.Plugin|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.


WorldRoot:IKMoveTo

target

The location to move the specified part.


translateStiffness

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


rotateStiffness

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


collisionsMode

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


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.


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
`Class.WorldRoot:CollisionGroupSetCollidable()`.


WorldRoot:IsCollisionGroupRegistered

name

Checks if a collision group is registered in this world.


**IsRegion3Empty** returns a bool indicating whether there are no
`Class.BasePart|BaseParts` within the given `Datatype.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 `Class.BasePart|BaseParts` are inside a `Class.BasePart` other
than the `Class.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 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
`Class.WorldRoot:IsRegion3EmptyWithIgnoreList()`.

This function only returns if a region is empty or not. Developers looking
to find `Class.BasePart|BaseParts` in a region should use
`Class.WorldRoot:FindPartsInRegion3()`.

#### How do Region3 checks work?

Checking if a part overlaps a `Datatype.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 `Datatype.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 `Datatype.Region3`. For this reason it is recommended to make
sure that the `Datatype.Region3` is on the voxel grid. The best way to do
this is by setting the coordinates of the `Datatype.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 `Class.BasePart:GetTouchingParts()` should be used. There is a higher
cost to using `Class.BasePart:GetTouchingParts()` since a part is needed
in the `Class.WorldRoot` and the function takes more time to run.


WorldRoot:IsRegion3Empty

ignoreDescendentsInstance

True if the `Datatype.Region3` is empty.


Returns a bool indicating whether there are no `Class.BasePart|BaseParts`
within the given `Datatype.Region3`.


Returns a boolean indicating whether there are no
`Class.BasePart|BaseParts` within the given `Datatype.Region3`, ignoring
any `Class.BasePart|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 `Class.BasePart|BaseParts` in a region should use
`Class.WorldRoot:FindPartsInRegion3WithIgnoreList()`.

This function is a variant of `Class.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
`Class.WorldRoot:FindPartsinRegion3WithWhitelist()`.


WorldRoot:IsRegion3EmptyWithIgnoreList

ignoreDescendentsTable

Returns a boolean indicating whether there are no
`Class.BasePart|BaseParts` within the given `Datatype.Region3`, ignoring
any `Class.BasePart|BaseParts` that are descendants of the objects within
the given ignore list.


Casts a ray and returns the first collision with a `Class.BasePart` or
`Class.Terrain`. Prints the properties of the RaycastResult if a result was
hit.


Casts a ray using an origin, direction, and optional
`Datatype.RaycastParams`. If it finds an eligible `Class.BasePart` or
`Class.Terrain` cell, a `Datatype.RaycastResult` is returned containing
the results of the operation. If no `Datatype.RaycastParams` object is
provided, the defaults are used (all parts are considered and
`Class.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 `Datatype.CFrame` to help create the ray components,
consider using `Datatype.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 `Datatype.Ray` object, but its origin and
direction components can be borrowed from `Datatype.Ray.Origin` and
`Datatype.Ray.Direction`.


WorldRoot:Raycast

origin

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

An object used to specify hit eligibility in the raycast operation. If
not provided, default values are used where all parts are considered
and `Class.Terrain` water is not ignored.


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


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


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 `Class.BasePart|BaseParts` in the world, so it's recommended
that you register all collision groups at edit time through the Studio
[editor](/workspace/collisions#collision-groups) and call
`Class.WorldRoot:UnregisterCollisionGroup()|UnregisterCollisionGroup()`
and `Class.WorldRoot:RenameCollisionGroup()|RenameCollisionGroup()` as
infrequently as possible.


WorldRoot:RegisterCollisionGroup

Registers a new collision group in this world with the given name.


Renames the specified registered collision group in this world, but does
**not** rename the `Class.BasePart.CollisionGroup|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
`Class.WorldRoot:RegisterCollisionGroup()|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.

Note that this method has a slight performance overhead based on the
number of `Class.BasePart|BaseParts` in the world, so it's recommended
that you register all collision groups at edit time through the Studio
[editor](/workspace/collisions#collision-groups) and rename
them as infrequently as possible.


WorldRoot:RenameCollisionGroup

from

Renames specified collision group in this world.


Casts the shape of the given `Class.BasePart` in a given direction and
returns the first collision with a `Class.BasePart` or `Class.Terrain`
cell. This is analogous to how `Class.WorldRoot:Raycast()` casts a linear
ray in a direction to find a collision, but it uses a 3D shape instead of
a ray. Unlike `Class.WorldRoot:Blockcast()` and
`Class.WorldRoot:Spherecast()`, which use a simple box or sphere, this
method casts the actual geometry of the provided part.

Unlike `Class.WorldRoot:GetPartsInPart()`, this method does not detect
`Class.BasePart|BaseParts` that **initially** intersect the shape.

If a hit is detected, a `Datatype.RaycastResult` is returned containing
the hit information. The `Datatype.RaycastResult.Distance|Distance`
property represents the distance the shape has to travel to find a hit,
and the `Datatype.RaycastResult.Position|Position` property represents the
intersection point that causes the hit.

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


WorldRoot:Shapecast

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 `Class.Terrain` part.


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 `Class.Terrain` water is not ignored. The part being
cast is always excluded from the results.


Casts the shape of a given `Class.BasePart` in a direction and returns a
`Datatype.RaycastResult` if the shape hits a `Class.BasePart` or
`Class.Terrain` cell.


Casts a sphere and returns the first collision with a `Class.BasePart` or
`Class.Terrain`. Prints the properties of the RaycastResult if a result was
hit.


Casts a spherical shape in a given direction and returns the first
collision with a `Class.BasePart` or `Class.Terrain` cell. This is
analogous to how `Class.WorldRoot:Raycast()` casts a linear ray in a
direction to find a collision, but it uses a 3D shape instead of a ray.

Unlike `Class.WorldRoot:GetPartsInPart()`, this method does not detect
`Class.BasePart|BaseParts` that **initially** intersect the shape.

If a hit is detected, a `Datatype.RaycastResult` is returned containing
the hit information. The `Datatype.RaycastResult.Distance|Distance`
property represents the distance the shape has to travel to find a hit,
and the `Datatype.RaycastResult.Position|Position` property represents the
intersection point that causes the hit.

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


WorldRoot:Spherecast

The initial position of the cast spherical shape.


The radius of the cast spherical shape in studs. The maximum radius is
256 studs.


Casts a spherical shape in a given direction and returns a
`Datatype.RaycastResult` if the shape hits a `Class.BasePart` or
`Class.Terrain` cell.


Simulates the parts in the workspace for a fixed period of time by calling the
StepPhysics function once per frame until a specified time has elaspsed.


Advances the simulation for parts in the world forward based on a
specified time increment and an optional set of `Class.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 `Class.RunService.RenderStepped` event.


WorldRoot:StepPhysics

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

Optional array of parts that will be simulated. This set must contain
instances that are of type `Class.BasePart`; any other types will be
ignored.


Advances the simulation for parts in the world forward based on a
specified time increment and an optional set of
`Class.BasePart|BaseParts`.


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.

Note that this method has a slight performance overhead based on the
number of `Class.BasePart|BaseParts` in the world, so it's recommended
that you register all collision groups at edit time through the Studio
[editor](/workspace/collisions#collision-groups) and call this
method as infrequently as possible.


WorldRoot:UnregisterCollisionGroup

Unregisters the collision group for the given name in this world.


WorldRoot

Base class for handling physics simulation and 3D spatial queries.


The following sample includes a basic function that takes a table of objects
and parents them into a new Model, returning that Model.


Models are container objects, meaning they group objects together. They are
best used to hold collections of `Class.BasePart|BaseParts` and have a number
of functions that extend their functionality.

Models are intended to represent **geometric** groupings. If your grouping has
no geometric interpretation, for instance a collection of
`Class.Script|Scripts`, use a `Class.Folder` instead.

Models whose constituent parts are joined together with joints (so that they
can move around or be destroyed via physics simulation) usually have a
`Class.Model.PrimaryPart|PrimaryPart` set, as it specifies which part within
the model the pivot and bounding box will "follow" as the model moves. Static
models which stay in one place do not benefit from having a primary part set.

Models have a wide range of applications, including Roblox player characters.
They also have a number of unique behaviors that are important to keep in
mind:

- When a `Class.Humanoid` and a `Class.Part` named **Head** are parented under
  a model, a name/health GUI will appear over the model; see
  [Character Name/Health Display](/characters/name-health-display)
  for details.
- If a part's position on the **Y** axis hits the
  `Class.Workspace.FallenPartsDestroyHeight` value, and it was the last object
  inside of a `Class.Model`, the model will be destroyed as well.
- When used in a place with `Class.Workspace.StreamingEnabled` set to true,
  the value of `Class.Model.ModelStreamingMode|ModelStreamingMode` controls
  various behaviors around how the model and any descendants are replicated
  and/or removed from clients. In addition, the value of
  `Class.Model.LevelOfDetail|LevelOfDetail` impacts rendering of the model.

As with all `Class.Instance` types, the fact that a parent `Class.Model` is
replicated to a client does not guarantee that all its children are
replicated. This is particularly important if these instances are being
accessed by code running on the client, such as in a `Class.LocalScript`.
Using `Class.Model.ModelStreamingMode|ModelStreamingMode` with values such as
`Enum.ModelStreamingMode|Atomic` can ensure that the entire model and all of
its descendants are present if the parent model exists on the client, or you
can use `Class.Instance:WaitForChild()|WaitForChild()` when atomicity is not
desired.


Sets this model to be persistent for the specified player. Persistent
models stay present for the player regardless of streaming settings or
conditions.

`Class.Model.ModelStreamingMode|ModelStreamingMode` must be set to
`Enum.ModelStreamingMode|PersistentPerPlayer` for behavior to be changed
as a result of addition.


Model:AddPersistentPlayer

playerInstance

The `Class.Player` to make this model persistent for.


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


In this sample the joints in every Player character Model added will be broken
3 seconds after spawning. Breaking these joints will cause the Humanoid to
die.


This code sample demonstrates manual creation of joints on two parts that are
siblings of the script (PartA and PartB). It creates a joints on two touching
parts with compatible surface types (Studs and Inlet).


Breaks connections between `BaseParts`, including surface connections with
any adjacent parts, `Class.WeldConstraint|WeldConstraints`, and all
`Class.Weld|Welds` and other `Class.JointInstance|JointInstances`.

When BreakJoints is used on a Player character `Class.Model`, the
character's `Class.Humanoid` will die as it relies on the Neck joint.

Note that although joints produced by surface connections with adjacent
Parts can technically be recreated using `Class.Model:MakeJoints()`, this
will only recreate joints produced by surfaces. Developers should not rely
on this as following the joints being broken parts may no longer be in
contact with each other.


Model:BreakJoints

Breaks connections between `BaseParts`, including surface connections with
any adjacent parts, `Class.WeldConstraint|WeldConstraints` and all
`Class.Weld|Welds` and other `Class.JointInstance|JointInstances`.


Model:breakJoints

Demonstrates `Class.Model:GetBoundingBox()`.


This function returns a description of a volume that contains all
`Class.BasePart` children within a `Class.Model`. The volume's orientation
is based on the orientation of the `Class.Model.PrimaryPart|PrimaryPart`,
and matches the selection box rendered in Studio when the model is
selected. Mirroring the behavior of `Class.Terrain:FillBlock()`, it
returns a `Datatype.CFrame` representing the center of that bounding box
and a `Datatype.Vector3` representing its size. The size may be inaccurate
at runtime if physics constraints are acting upon the parts within the
`Class.Model`.

The orientation of the bounding box matches the orientation of the
`Class.PVInstance.GetPivot|Pivot` - either the pivot of the
`Class.Model.PrimaryPart|PrimaryPart` (if present) or the
`Class.Model.WorldPivot|WorldPivot` of the model.


Model:GetBoundingBox

A `Datatype.CFrame` representing the orientation of the volume
followed by a `Datatype.Vector3` representing the size of the volume.


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


The code sample below demonstrates how Model.GetExtentsSize can be used to get
the size of the bounding box containing the parts.


Returns the size of the smallest bounding box that contains all of the
`Class.BasePart|BaseParts` in the `Class.Model`. The orientation matches
the orientation of the `Class.PVInstance.GetPivot|Pivot` - either the
pivot of the `Class.Model.PrimaryPart|PrimaryPart` (if present) or the
`Class.Model.WorldPivot|WorldPivot` of the model.

Note this function only returns the size of the smallest bounding box, and
the developer must employ their own method to obtain the position of the
bounding box.


Model:GetExtentsSize

The `Datatype.Vector3` extents size of the `Class.Model`.


Returns the size of the smallest bounding box that contains all of the
`Class.BasePart|BaseParts` in the `Class.Model`, aligned with the
`Class.Model.PrimaryPart` if it is set.


This value historically returned the CFrame of a central position in the
model.


Model:GetModelCFrame

A `Datatype.CFrame` representing a central position in the model.


This code would create a model, put some parts in it, position them randomly,
and then print its size:


The GetModelSize function returns the `Datatype.Vector3` size of the
`Class.Model`.


Model:GetModelSize

Model

Models are container objects, meaning they group objects together. They are
best used to hold collections of `Class.BasePart|BaseParts` and have a number
of functions that extend their functionality.


/reference/engine/classes/WorldModel.yaml