The WorldModel provides some physics features to a `Class.ViewportFrame`.

More specifically, you can make a WorldModel a child of a ViewportFrame, and
then parent geometry to the WorldModel. This will then allow you to use
raycasts in the ViewportFrame through the WorldModel. Furthermore you can put
`Class.Humanoid` characters in the WorldModel and their joints will be set-up
correctly, and you can animate them.


WorldModel

Provides some physics features to a `Class.ViewportFrame`.


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

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 a table of `Class.BasePart|BaseParts` to a table 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.

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

cframeList

eventMode

Moves a table of `Class.BasePart|BaseParts` to a table of
`Datatype.CFrame|CFrames`.


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

ignoreDescendantsInstance

terrainCellsAreCubes

ignoreWater

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


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

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

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


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.


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


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.


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


WorldRoot:Shapecast

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


WorldRoot:findPartOnRay

WorldRoot:findPartsInRegion3

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


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.

If there is no `Class.Model.PrimaryPart|PrimaryPart` for the model, the
bounding box will be aligned to the world axes.

```lua
local Workspace = game:GetService("Workspace")

local model = Workspace.Model
local part = Workspace.Part
local orientation, size = model:GetBoundingBox()

-- Resize and position part equal to bounding box of model
part.Size = size
part.CFrame = orientation
```


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`. If
`Class.Model.PrimaryPart` exists then the bounding box will be aligned to
that part. If a primary part has not been set then the function will chose
a part in the model to align the bounding box to. As the selection of this
part is not deterministic it is recommended to set a
`Class.Model.PrimaryPart` to get consistent results with this function.

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

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

When this method is called from a `Class.Script`, it returns all the
`Class.Player` objects that this model is persistent for. When called from
a `Class.LocalScript`, this method only checks if this model is persistent
for the `Class.Players.LocalPlayer|LocalPlayer`.


Model:GetPersistentPlayers

A table with all the `Class.Player` objects that this model object is
persistent for.


Returns all the `Class.Player` objects that this model object is
persistent for. Behavior varies based on whether this method is called
from a `Class.Script` or a `Class.LocalScript`.


The following code demonstrates how GetPrimaryPartCFrame and
SetPrimaryPartCFrame can be used to rotate a model.

A simple model is created in the Workspace and a loop is started that will
rotate the model 10 degrees around the Y axis every 0.2 seconds.

This function has been superseded by `Class.PVInstance:GetPivot()` which
acts as a replacement and does not change your code's behavior. Use
`Class.PVInstance:GetPivot()` for new work and migrate your existing
`Class.Model:GetPrimaryPartCFrame()` calls when convenient.

Returns the `Datatype.CFrame` of the model's `Class.Model.PrimaryPart`.

This function is equivalent to the following.

    Model.PrimaryPart.CFrame

Note this function will throw an error if no primary part exists for the
`Class.Model`. If this behavior is not desired developers can do the
following, which will be equal to `nil` if there is no primary part.

    local cFrame = Model.PrimaryPart and Model.PrimaryPart.CFrame


Model:GetPrimaryPartCFrame

Returns the `Datatype.CFrame` of the model's `Class.Model.PrimaryPart`.
This function will throw an error if no primary part exists for the
`Class.Model`.


This code sample demonstrates substituting in a replacement for all the copies of a tree model using PivotTo and ScaleTo. The pivot and scale of the models are used as a reference ensuring that the relative sizes and locations of the replacement models match those of the originals.

Models contain a persistent canonical scale factor, which starts out at 1
for newly created models and changes as the model is scaled by calling
`Model/ScaleTo`. This function returns the current canonical scale factor
of the model.

The current scale factor does not _directly_ impact the size of Instances
under the model. It is used for content authoring and scripting purposes
to remember how the model has been scaled relative to its original size.

Within a given session, the model will cache the precise original size
information of the descendant Instances after the first `Model/ScaleTo`
call. This means that calling `ScaleTo(x)` followed by `ScaleTo(1)` will
get you back _exactly_ the original configuration of the model with no
floating point drift. Avoiding floating point drift is the motivation for
having a Scale**To** function instead of a Scale**By** function.

The scale factor does impact engine behavior in one way: The scale factor
of a model will be applied to joint offsets of
`Class.Animation|animations` played on an `Class.AnimationController`
under that model, so that animated rigs will correctly play back
animations even when scaled.


Model:GetScale

The current canonical scale factor of the model.


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


This code sample demonstrates how joints can be made using the
Model:MakeJoints function.

A model is instanced, with two parts on top of each other. The top part is
anchored and the bottom part is not. Normally, when parented to the Workspace
the bottom part would fall to the Baseplate.

However, as TopSurface property of the bottom part is set to
Enum.SurfaceType.Weld, this means that when Model:MakeJoints is ran a
connection is made between them.

Therefore the bottom part does not drop until the joints in the model are
broken. This is often done using Model:BreakJoints, but in this example the
connection is broken using an explosion.

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

SurfaceType based joining is deprecated. Don't use MakeJoints for new
projects. Use `Class.WeldConstraint|WeldConstraints` and
`Class.HingeConstraint|HingeConstraints` instead.

Goes through all `Class.BasePart|Parts` in the `Class.Model` and creates
joints between the specified Parts and any planar touching surfaces,
depending on the parts' surfaces.

- Smooth surfaces will not create joints
- Glue surfaces will create a `Class.Glue` joint
- Weld will create a `Class.Weld` joint with any surface except for
  Unjoinable
- Studs, Inlet, or Universal will each create a `Class.Snap` joint with
  either of other the other two surfaces (e.g. Studs with Inlet and
  Universal)
- Hinge and Motor surfaces create `Class.Rotate` and `Class.RotateV` joint
  instances

This function doesn't work if the Part is not a descendant of
`Class.Workspace`. Therefore, you must first ensure the Model is parented
to Workspace before using MakeJoints.


Model:MakeJoints

Goes through all `Class.BasePart|BaseParts` in the `Class.Model`. If any
part's side has a SurfaceType that can make a joint it will create a joint
with any adjacent parts.


This sample demonstrates how Model:MoveTo avoids collisions.

A simple two part Model is created, and its PrimaryPart is set. An large
obstruction part is placed next to it.

After 5 seconds Model:MoveTo is used to direct the model to move inside the
obstruction part. However, as MoveTo will not move a model inside of an
obstruction the Model is moved up on the Y axis and placed above the
obstruction.

Moves the `Class.Model.PrimaryPart|PrimaryPart` to the given position. If
a primary part has not been specified, the root part of the model will be
used, but the root part is not deterministic and it is recommended that
you always set a primary part when using `Class.Model:MoveTo()|MoveTo()`.

If there are any obstructions where the model is to be moved, such as
`Class.Terrain` or other `Class.BasePart|BaseParts`, the model will be
moved vertically upward until there is nothing in the way. If this
behavior is not desired, `Class.PVInstance:PivotTo()` should be used
instead.

Note that rotation is not preserved when moving a model with
`Class.Model:MoveTo()|MoveTo()`. It is recommended to use either
`Class.Model:TranslateBy()|TranslateBy()` or `Class.PVInstance:PivotTo()`
if the current rotation of the model needs to be preserved.


Model:MoveTo

The `Datatype.Vector3` the `Class.Model` is moved to.


Moves the `Class.Model.PrimaryPart|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 the specified player. This does
not guarantee the model will immediately be removed for the player; after
calling this method, the model will be treated as
`Enum.ModelStreamingMode|Atomic` for that player and will remain present
as long as it is within the target streaming radius.

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


Model:RemovePersistentPlayer

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


Makes this model no longer 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 removal.


Resets the rotation of the model's parts to the previously set identity
rotation, which is done through the `Class.Model:SetIdentityOrientation()`
method.


Model:ResetOrientationToIdentity

Models contain a persistent canonical scale factor, which starts out at 1
for newly created models. This function scales the model, around the pivot
location, relative to how it would look at a scale factor of 1. To
accomplish this it does two things:

- Sets the current scale factor of the model to the specified value
- Resizes and repositions all descendant Instances accordingly

The scaling of locations is done around the pivot location.

All "geometric" properties of descendant Instances will be scaled. That
obviously includes the sizes of parts, but here are some other examples of
properties which are scaled:

- The length of joints like `Class.WeldConstraint|WeldConstraints`, and
  `Class.Rope|Ropes`
- Physical velocities and forces like `Hinge.MaxServoTorque`
- Visual properties like sizes of particle emitters
- Other length properties like `Sound.RollOffMinDistance`


Model:ScaleTo

newScaleFactor

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.


Sets the identity rotation of the given model, allowing you to reset the
rotation of the entire model later, through the use of the
`ResetOrientationToIdentity` method.


Model:SetIdentityOrientation

This function has been superseded by `Class.PVInstance:PivotTo()` which
acts as a more performant replacement and does not change your code's
behavior. Use `Class.PVInstance:PivotTo()` for new work and migrate your
existing `Class.Model:SetPrimaryPartCFrame()` calls when convenient.

Sets the `Class.BasePart.CFrame` of the model's `Class.Model.PrimaryPart`.
All other parts in the model will also be moved and will maintain their
orientation and offset respective to the `Class.Model.PrimaryPart`.

Note, this function will throw an error if no `Class.Model.PrimaryPart`
exists for the model. This can cause issues if, for example, the primary
part was never set or has been destroyed.


Model:SetPrimaryPartCFrame

Sets the `Class.BasePart.CFrame` of the model's `Class.Model.PrimaryPart`.
All other parts in the model will also be moved and will maintain their
orientation and offset respective to the `Class.Model.PrimaryPart`.


This sample demonstrates how Model:TranslateBy ignores collisions and respects
the orientation of the model.

A simple two part Model is created, rotated 45 degrees on the Y axis, and its
PrimaryPart is set. An large obstruction part is placed next to it.

After 5 seconds Model:TranslateBy is used to direct the model to move inside
the obstruction part. The model will move inside of the obstruction and
maintain it's current orientation.

Shifts a `Class.Model` by the given `Datatype.Vector3` offset, preserving
the model's orientation. If another `Class.BasePart` or `Class.Terrain`
already exists at the new position then the `Class.Model` will overlap
said object.

The translation is applied in world space rather than object space,
meaning even if the model's parts are orientated differently it will still
move along the standard axis.


Model:TranslateBy

delta

The `Datatype.Vector3` to translate the `Class.Model` by.


Shifts a `Class.Model` by the given `Datatype.Vector3` offset, preserving
the model's orientation. If another `Class.BasePart` or `Class.Terrain`
already exists at the new position then the `Class.Model` will overlap
said object.


Model:breakJoints

Model:makeJoints

Model:move

location

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

WorldModel

Summary

Properties

Methods

Events

Properties

Methods

Events