HopperBins are an outdated system for creating tools that can be used by a
player. In place of HopperBins, please use `Class.Tool` instead.

Historically, only HopperBins worked without a 'Handle' `Class.Part`, but this
is no longer the case thanks to the `Class.Tool.RequiresHandle` property of
Tools.


HopperBin.Deselected

HopperBin.Selected

mouse

HopperBin

HopperBin.Active

HopperBin.BinType

BackpackItem is an abstract class for backpack items such as HopperBins and
Tools.


BackpackItem

The texture icon that is displayed for a tool in the player's backpack.

This property should be set to the content ID of an image uploaded to the
Roblox website. Only asset URIs are supported for this property.

If this property is left blank, the `Class.Backpack` GUI will display the
name of the tool instead.


BackpackItem.TextureContent

The texture icon that is displayed for a tool in the player's backpack.
Only supports asset URIs.


The texture icon that is displayed for a tool in the player's backpack.

This property should be set to the content ID of an image uploaded to the
Roblox website.

If this property is left blank, the `Class.Backpack` GUI will display the
name of the tool instead.


BackpackItem.TextureId

The texture icon that is displayed for a tool in the player's backpack.


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

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.

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

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 `Class.Model:PivotTo()` and `Class.Model: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
`Class.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
`Class.Model:ScaleTo()` call. This means that calling
`Class.Model:ScaleTo()|ScaleTo(x)` followed by
`Class.Model:ScaleTo()|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
`Class.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.


Model:makeJoints

Model:move

location

This sample demonstrates how `Class.Model:MoveTo()` avoids collisions.

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

After 5 seconds `Class.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 `Class.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

position

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.


Model:moveTo

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.RopeConstraint`
- Physical velocities and forces like `Class.HingeConstraint`
- Visual properties like sizes of particle emitters
- Other length properties like `Class.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

cframe

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 `Class.Model:TranslateBy()` ignores collisions
and respects the orientation of the model.

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

After 5 seconds `Class.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

Sets the level of detail on the model for experiences with instance
[streaming](/workspace/streaming) enabled. Composite or
imposter meshes do not support physics, collision detection, or
raycasting.

When set to `Enum.ModelLevelOfDetail|StreamingMesh`, a lower resolution
"imposter" mesh (colored, coarse mesh that wraps around all child parts of
the model) renders outside the streaming radius. Does not support
textures.

When set to `Enum.ModelLevelOfDetail|SLIM`, a **SLIM** model (Scalable
Lightweight Interactive Model) renders a composite of all child parts at
progressively lower resolutions at distances based on the streaming
radius. This greatly improves visual quality over
`Enum.ModelLevelOfDetail|StreamingMesh`.

When set to `Enum.ModelLevelOfDetail|Disabled` or
`Enum.ModelLevelOfDetail|Automatic`, lower resolution meshes will not be
displayed.


Model.LevelOfDetail

Sets the level of detail on the model for experiences with instance
streaming enabled.


Controls how `Class.Model|Models` are streamed in and out when instance
[streaming](/workspace/streaming) is enabled. Behavior
depends on the selected enum. Has no effect when streaming is not enabled.

This property should only be changed in Studio via the
[Properties](/studio/properties) window when streaming is
enabled, or in `Class.Script|Scripts`, but never in
`Class.LocalScript|LocalScripts` (doing so can result in undefined
behavior).


Model.ModelStreamingMode

Controls the model streaming behavior on `Class.Model|Models` when
instance streaming is enabled.


This code sample creates and throws a dice model, then outputs whether it
landed with the blue side facing up. If `Class.Model.PrimaryPart` was not set,
the pivot / bounding box of the dice would rotate, as the parts inside of it
are physically simulated during the roll.


Points to the primary part of the `Class.Model`. The primary part is the
`Class.BasePart` that acts as the physical reference for the pivot of the
model. That is, when parts within the model are moved due to physical
simulation or other means, the pivot will move in sync with the primary
part.

Note that `Class.Model|Models` do not have `PrimaryPart` set by default.
If you are creating a model that needs to be acted upon by physics, you
should manually set this property in Studio or within a script. If the
primary part is **not** set, the pivot will remain at the same location in
world space, even if parts within the model are moved.

Also note that when setting this property, it must be a `Class.BasePart`
that is a descendant of the model. If you try to set
`Class.Model.PrimaryPart` to a `Class.BasePart` that is **not** a
descendant of the model, it will be set to that part but reset to `nil`
during the next simulation step &mdash; this is legacy behavior to support
scripts which assume they can temporarily set the primary part to a
`Class.BasePart` which isn't a descendant of the model.

The general rule for models is that:

- Models whose parts are joined together via physical joints such as
  `Class.WeldConstraint|WeldConstraints` or `Class.Motor6D|Motor6Ds`
  should have a primary part assigned. For example, Roblox character
  models have their `Class.Model.PrimaryPart` set to the
  **HumanoidRootPart** by default.
- Static (usually `Class.BasePart.Anchored|Anchored`) models which stay in
  one place unless a script explicitly moves them don't require a
  `Class.Model.PrimaryPart` and tend not to benefit from having one set.


Model.PrimaryPart

The primary part of the `Class.Model`, or `nil` if not explicitly set.


Setting this property in the Properties window will scale the model as
though `Class.Model:ScaleTo()` was called on it, scaling all descendant
Instances in the model, such as materials, images, and the 3D geometry of
parts, so that the model has the specified scale factor relative to its
original size.

This property is only available in Studio and will throw an error if used
in a `Class.Script` or `Class.LocalScript`. `Class.Model:ScaleTo()` and
`Class.Model:GetScale()` should be used from scripts.


Model.Scale

Editor-only property used to scale the model around its pivot. Setting
this property will move the scale as though `Class.Model:ScaleTo()` was
called on it.


This code sample shows a custom function for resetting the pivot of a model
back to the center of that model's bounding box.


This property determines where the pivot of a `Class.Model` which does
**not** have a set `Class.Model.PrimaryPart` is located. If the
`Class.Model` **does** have a `Class.Model.PrimaryPart|PrimaryPart`, the
pivot of the `Class.Model` is equal to the pivot of that primary part
instead, and this `Class.Model.WorldPivot|WorldPivot` property is ignored.

For a newly created `Class.Model`, its pivot will be treated as the center
of the bounding box of its contents until the **first time** its
`Class.Model.WorldPivot` property is set. Once the world pivot is set for
the first time, it is impossible to restore this initial behavior.

Most commonly, moving the model with the Studio tools, or with model
movement functions such as `Class.PVInstance:PivotTo()` and
`Class.Model:MoveTo()`, will set the world pivot and thus end this new
model behavior.

The purpose of this behavior is to allow Luau code to get a sensible pivot
simply by creating a new model and parenting objects to it, avoiding the
need to explicitly set `Class.Model.WorldPivot` every time you create a
model in code.

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

local model = Instance.new("Model")
Workspace.BluePart.Parent = model
Workspace.RedPart.Parent = model
model.Parent = Workspace

print(model:GetPivot())  -- Currently equal to the center of the bounding box containing "BluePart" and "RedPart"

model:PivotTo(CFrame.new(0, 10, 0))  -- This works without needing to explicitly set "model.WorldPivot"
```


Model.WorldPivot

Determines where the pivot of a `Class.Model` which does **not** have a
set `Class.Model.PrimaryPart` is located.


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.


A `Class.PVInstance` is an abstract class that cannot be created. It is the
base for all objects that have a physical location in the world.


This code sample is a simple teleport script that moves your character
10&nbsp;studs forwards in the direction you're currently facing when you press
the <kbd>F</kbd> key. It does so by getting the current pivot with
`Class.PVInstance:GetPivot()` and calling `PVInstance|PivotTo` to move the
character forwards.


This function gets the pivot of a `Class.PVInstance`. This is often used
with `Class.PVInstance:PivotTo()` to move a model.

`Class.Model|Models` and `Class.BasePart|BaseParts` are both
`Class.PVInstance|PVInstances` ("Position Velocity Instances") and so both
have this function.


PVInstance:GetPivot

Transforms the `Class.PVInstance` along with all of its descendant
`Class.PVInstance|PVInstances` such that the pivot is now located at the
specified `Datatype.CFrame`. This is the primary function that should be
used to move `Class.Model|Models` via scripting.

`Class.BasePart|BaseParts` are moved in this way by having their
`Datatype.CFrame` transformed by the necessary offset.
`Class.Model|Models` are moved in this way by having their
`Class.Model.WorldPivot` transformed by the necessary offset.

Note that for efficiency purposes, `Class.Object.Changed` events are not
fired for `Class.BasePart.Position|Position` and
`Class.BasePart.Orientation|Orientation` of `Class.BasePart|BaseParts`
moved in this way; they are only fired for `Datatype.CFrame`.

When calling `Class.PVInstance:PivotTo()|PivotTo` on `Class.Model|Models`,
the offsets of the descendant parts and models are cached, such that
subsequent calls to `Class.PVInstance:PivotTo()|PivotTo` on the same model
do not accumulate floating point drift between the parts making up the
model.

`Class.Model|Models` and `Class.BasePart|BaseParts` are both
`Class.PVInstance|PVInstances` ("Position Velocity Instances") and so both
have this function.


PVInstance:PivotTo

targetCFrame

The `Datatype.CFrame` that the `Class.PVInstance` pivot should equal
after moving it.


Transforms the `Class.PVInstance` along with all of its descendant
`Class.PVInstance|PVInstances` such that the pivot is now located at the
specified `Datatype.CFrame`.


PVInstance

PVInstance.Origin

PVInstance.Pivot Offset

Abstract class for all objects that have a physical location in the world.


`Instance` is the base class for all classes in the Roblox class hierarchy
which can be part of the `Class.DataModel` tree.

It is not possible to directly create root `Instance` objects, but the special
`Datatype.Instance.new()` constructor creates objects via code, taking the
name of the class as a parameter and returning the created object.


Demonstrates detecting changes to an instance's ancestry by connecting to the
`Class.Instance.AncestryChanged` event.

The ChangingPart's Parent is set to different values overtime. The parent of
the part is the part's ancestor, so the `Class.Instance.AncestryChanged` event
will fire whenever it changes.


Fires when this instance is reparented or when any of its ancestors is
reparented.

You can use this event to track the deletion of an instance in Studio,
such as manual deletion in the Explorer or through a plugin. If you need
to detect when an instance is destroyed using `Class.Instance:Destroy()`,
use the `Class.Instance.Destroying` event instead.


Instance.AncestryChanged

child

The instance whose `Class.Instance.Parent|Parent` property changed,
which can be this instance or a more distant ancestor, **not**
necessarily the instance the handler is connected to.


parent

The new parent of the `child` parameter.


Fires when the `Class.Instance.Parent` property of this object or one of
its ancestors is changed.


This event fires whenever any attribute is changed on the instance,
including when an attribute is set to `nil`. The name of the changed
attribute is passed to the connected function.

For example, the following code snippet connects the `attributeChanged()`
function to fire whenever one of the part's attributes changes:

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

local part = Workspace.Part

local function attributeChanged(attributeName)
	print(attributeName, "changed")
end

part.AttributeChanged:Connect(attributeChanged)
```

See also `Class.Instance:GetAttributeChangedSignal()` which returns an
event that fires when a specific given attribute changes.


Instance.AttributeChanged

attribute

The name of the attribute that has been changed.


Fires whenever an attribute is changed on the `Class.Instance`.


This snippet prints the names of objects as they are added to the Workspace:


Fires after an object is parented to this `Class.Instance`.

Note, when using this method on a client to detect objects created by the
server it is necessary to use `Class.Instance:WaitForChild()` when
indexing these object's descendants. This is because the object and its
descendants are not guaranteed to replicate from the server to the client
simultaneously. For example:

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

Workspace.ChildAdded:Connect(function(child)
	-- Use WaitForChild() since descendants may not have replicated yet
	local head = child:WaitForChild("Head")
end)
```

Note, this event only operates for immediate children of the
`Class.Instance`. For an event that captures all descendants, use
`Class.Instance.DescendantAdded`.

See also `Class.Instance.ChildRemoved`.


Instance.ChildAdded

The `Class.Instance` that has been added.


Fires after an object is parented to this `Class.Instance`.


Instance.childAdded

This snippet prints the names of objects as they are removed from the
Workspace:


Fires after a child is removed from this `Class.Instance`.

Removed refers to when an object's parent is changed from this
`Class.Instance` to something other than this `Class.Instance`. Note, this
event will also fire when a child is destroyed (using
`Class.Instance:Destroy()`) as the destroy function sets an object's
parent to `nil`.

This event only operates for immediate children of the `Class.Instance`.
For an event that captures all descendants, use
`Class.Instance.DescendantRemoving`.

See also `Class.Instance.ChildAdded`.


Instance.ChildRemoved

The `Class.Instance` that has been removed.


Fires after a child is removed from this `Class.Instance`.


This following example will print the name of any object that is added to the
Workspace:


This event fires after a descendant is added to the `Class.Instance`.

As it fires for every descendant, parenting an object to the
`Class.Instance` will fire the event for this object and all of its
descendants individually.

If you're only concerned with the **direct children** of the
`Class.Instance`, use `Class.Instance.ChildAdded` instead.

See also `Class.Instance.DescendantRemoving`.


Instance.DescendantAdded

descendant

Fires after a descendant is added to the `Class.Instance`.


The following example prints the name of any descendant as it is being removed
from the Workspace:


This event fires **immediately before** the parent `Class.Instance`
changes such that a **descendant** instance will no longer be a
descendant. `Class.Instance:Destroy()|Destroy()` changes an instance's
`Class.Instance.Parent|Parent` to `nil`, so calling that method on a
descendant of the parent will cause this event to fire.

Since this event fires **before** the descendant's removal, the parent of
the descendant will be unchanged at the time of this event firing. If the
descendant is also a **direct child** of the parent, this event will fire
before `Class.Instance.ChildRemoved`.

If a descendant has children, this event fires with the descendant first,
followed by its descendants.

#### Warning

This event fires with the descendant object that is being removed.
Attempting to set the `Class.Instance.Parent|Parent` of the descendant to
something else will fail. Below is an example that demonstrates this:

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

Workspace.DescendantRemoving:Connect(function(descendant)
	-- Do not manipulate the parent of the descendant in this function!
	-- This event fires BECAUSE the parent was manipulated, and the change hasn't happened yet
	-- Therefore, it is problematic to change the parent like this:
	descendant.Parent = game
end)

local part = Instance.new("Part")
part.Parent = Workspace
part.Parent = nil
```

See also `Class.Instance.DescendantAdded|DescendantAdded`.


Instance.DescendantRemoving

The `Class.Instance` that is being removed.


Fires immediately before a descendant of the `Class.Instance` is removed.


This sample demonstrates how, when using Immediate signal behavior, an
Instance being destroyed remains in place until the connected function yields.


This sample demonstrates how, when using Deferred signal behavior, an Instance
is destroyed before the signal fires.


The `Class.Instance` will never be deleted from memory while a connected
function is still using it. However, if the function yields at any point,
the `Class.Instance` and its descendants will be parented to `nil`.

If the `Class.Workspace.SignalBehavior` property is set to
`Enum.SignalBehavior.Immediate`, this event fires immediately before the
`Class.Instance` or one of its ancestors is destroyed with
`Class.Instance:Destroy()`.

If the `Class.Workspace.SignalBehavior` property is set to
`Enum.SignalBehavior.Deferred`, this event fires at the next resumption
point, which will be after the `Class.Instance` or one of its ancestors is
destroyed with `Class.Instance:Destroy()`.

With `Enum.SignalBehavior.Deferred|Deferred` behavior, connecting a script
to its own `Class.Instance.Destroying` event is problematic, as the script
will be destroyed before the callback can be called (meaning it will not
execute).

When deleting an `Class.Instance` in Studio, such as manually deleting
through the [Explorer](/studio/explorer) or through a plugin,
the `Class.Instance` isn't destroyed. Instead, the parent is set to `nil`
which you can track with `Class.Instance.AncestryChanged`.


Instance.Destroying

Fires immediately before (or is deferred until after) the instance is
destroyed via `Class.Instance:Destroy()`.


This event fires whenever any style property is changed on the instance,
including when a property is set to `nil`.

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

local player = Players.LocalPlayer
local playerGui = player.PlayerGui
local HUDContainer = playerGui:WaitForChild("HUDContainer")
local meterBar = HUDContainer.MeterBar

local function stylePropertyChanged()
	print("Styled properties changed")
end

meterBar:StyledPropertiesChanged():Connect(stylePropertyChanged)
```


Instance.StyledPropertiesChanged

Fires whenever any style property is changed on the instance, including
when a property is set to `nil`.


This method applies a tag to the instance, with no effect if the tag is
already applied. Successfully adding a tag will fire a signal created by
`Class.CollectionService:GetInstanceAddedSignal()` with the given tag.

#### Warnings

- An instance's tags that were added client-side will be dropped if the
  server later adds or removes a tag on that instance because the server
  replicates all tags together and overwrites previous tags.

- When tagging an instance, it is common that some resources are used to
  give the tag its functionality, for example event connections or tables.
  To prevent memory leaks, it's a good idea to clean these up (disconnect,
  set to `nil`, etc.) when no longer needed for a tag. Do this when
  calling `Class.Instance:RemoveTag()`, calling
  `Class.Instance:Destroy()`, or in a function connected to a signal
  returned by `Class.CollectionService:GetInstanceRemovedSignal()`.


Instance:AddTag

The children function returns an array of the object's children.


Instance:children

Returns an array of the object's children.


This method destroys all of an instance's children and descendants.

```
local part = Instance.new("Part")

-- Add some sparkles
for i = 1, 3 do
	local sparkles = Instance.new("Sparkles")
	sparkles.Parent = part

  local sc = Instance.new("Sparkles")
  sc.Parent = sparkles
end

print("Children:", #part:GetChildren())  --> Children: 3

part:ClearAllChildren()

print("Children:", #part:GetChildren())  --> Children: 0
```

If you do not wish to destroy **all** children and descendants, use either
`Class.Instance:GetChildren()` or `Class.Instance:GetDescendants()` to
loop through those children/descendants and select what to destroy. For
example, the following code sample will destroy all
`Class.BasePart|BaseParts` descending from a `Class.Model`:

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

local model = Workspace:FindFirstChild("TestModel")

for _, descendant in model:GetDescendants() do
	if descendant:IsA("BasePart") then
		descendant:Destroy()
	end
end
```


Instance:ClearAllChildren

This method destroys all of an instance's children.


Demonstrates cloning a model using `Class.Instance:Clone()`.


`Clone()` creates a copy of an instance and all of its descendants,
ignoring all instances that are not
`Class.Instance.Archivable|Archivable`. The copy of the root instance is
returned by this method and its `Class.Instance.Parent|Parent` is set to
`nil`. Note that if the instance itself has
`Class.Instance.Archivable|Archivable` set to `false`, this method will
return `nil`.

If a reference property such as `Class.ObjectValue.Value` is set in a
cloned instance, the value of the copy's property depends on the
original's value:

- If a reference property refers to an instance that was **also** cloned,
  the copy will refer to the copy.
- If a reference property refers to an instance that was **not** cloned,
  the same value is maintained in the copy.


Instance:Clone

Create a copy of an instance and all its descendants, ignoring instances
that are not `Class.Instance.Archivable|Archivable`.


Instance:clone

Demonstrates destroying a Part using the `Class.Instance:Destroy()` function.

This function is the correct way to dispose of objects that are no longer
required.


Sets the `Class.Instance.Parent` property to `nil`, locks the
`Class.Instance.Parent` property, disconnects all connections, and calls
`Destroy()` on all children. This method is the correct way to dispose of
objects that are no longer required.

Disposing of unneeded objects is important, since unnecessary objects and
connections in a place use up memory which can lead to serious performance
issues over time.

As a best practice after calling `Destroy()` on an object, set any
variables referencing the object (or its descendants) to `nil`. This
prevents your code from accessing anything to do with the object.

```lua
local part = Instance.new("Part")
part.Name = "Hello, world"
part:Destroy()
-- Don't do this:
print(part.Name)  --> "Hello, world"
-- Do this to prevent the above line from working:
part = nil
```

Once an `Class.Instance` has been destroyed by this method, it cannot be
reused because the `Class.Instance.Parent` property is locked. To
**temporarily** remove an object instead of destroying it, set
`Class.Instance.Parent|Parent` to `nil`. For example:

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

object.Parent = nil
task.wait(2)
object.Parent = Workspace
```

To destroy an object after a set amount of time, use
`Class.Debris:AddItem()`.


Instance:Destroy

Sets the `Class.Instance.Parent` property to `nil`, locks the
`Class.Instance.Parent` property, disconnects all connections, and calls
`Destroy()` on all children.


Instance:destroy

Returns the first ancestor of the `Class.Instance` whose
`Class.Instance.Name` is equal to the given name.

This method works upwards, meaning it starts at the instance's immediate
`Class.Instance.Parent` and works up towards the `Class.DataModel`. If no
matching ancestor is found, it returns `nil`.

The following code snippet would find the first ancestor of the object
named `Car`.

```
local car = object:FindFirstAncestor("Car")
```

For variants of this method that find ancestors of a specific class,
please see `Class.Instance:FindFirstAncestorOfClass()` and
`Class.Instance:FindFirstAncestorWhichIsA()`.


Instance:FindFirstAncestor

name

The `Class.Instance.Name` to be looked for.


Returns the first ancestor of the `Class.Instance` whose
`Class.Instance.Name` is equal to the given name.


Returns the first ancestor of the `Class.Instance` whose
`Class.Object.ClassName` is equal to the given className.

This method works upwards, meaning it starts at the instance's immediate
`Class.Instance.Parent` and works up towards the `Class.DataModel`. If no
matching ancestor is found, it returns `nil`.

A common use of this method is finding the `Class.Model` a
`Class.BasePart` belongs to. For example:

```
local model = part:FindFirstAncestorOfClass("Model")
```

This method is a variant of `Class.Instance:FindFirstAncestor()` which
checks the `Class.Object.ClassName` property rather than
`Class.Instance.Name`. `Class.Instance:FindFirstAncestorWhichIsA()` also
exists, using the `Class.Object:IsA()` method instead to respect class
inheritance.


Instance:FindFirstAncestorOfClass

className

The `Class.Object.ClassName` to be looked for.


Returns the first ancestor of the `Class.Instance` whose
`Class.Object.ClassName` is equal to the given className.


Returns the first ancestor of the `Class.Instance` for whom
`Class.Object:IsA()` returns true for the given className.

This method works upwards, meaning it starts at the instance's immediate
`Class.Instance.Parent` and works up towards the `Class.DataModel`. If no
matching ancestor is found, it returns `nil`.

Unlike `Class.Instance:FindFirstAncestorOfClass()`, this method uses
`Class.Object:IsA()` which respects class inheritance. For example:

```
print(part:IsA("Part"))  --> true
print(part:IsA("BasePart"))  --> true
print(part:IsA("Instance"))  --> true
```

Therefore, the following code sample will return the first
`Class.BasePart` ancestor, regardless of if it is a `Class.WedgePart`,
`Class.MeshPart` or `Class.Part`.

```
local part = object:FindFirstAncestorWhichIsA("BasePart")
```

See also `Class.Instance:FindFirstAncestor()`.


Instance:FindFirstAncestorWhichIsA

Returns the first ancestor of the `Class.Instance` for whom
`Class.Object:IsA()` returns true for the given className.


The below would look in Workspace for an object name "Brick". If found, it
will change the name of the object to "Foo".


Returns the first child of the `Class.Instance` with the given name, or
`nil` if no such child exists. If the optional `recursive` argument is
`true`, this method searches all descendants rather than only the
immediate children of the `Class.Instance`.

#### Checking the Existence of an Object

`FindFirstChild()` is necessary if you need to verify an object exists
before continuing. Attempting to index a child by name using the dot
operator throws an error if the child doesn't exist.

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

-- The following line errors if the part doesn't exist in the workspace
Workspace.Part.Transparency = 0.5
```

A better approach is to use `FindFirstChild()` to first check for `Part`,
then use an `if` statement to run code that needs it.

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

local part = Workspace:FindFirstChild("Part")
if part then
	part.Transparency = 0.5
end
```

#### Finding a Child Whose Name Matches a Property

Sometimes the `Class.Instance.Name|Name` of an object is the same as that
of a property of its `Class.Instance.Parent|Parent`. When using the dot
operator, properties take precedence over children if they share a name.

In the following example, a `Class.Folder` called `Color` is added to a
`Class.Part`, which also has the `Class.Part.Color` property. Notice that
`part.Color` refers to the `Datatype.Color3` property value, not the child
`Class.Folder` instance. A benefit of using
`Class.Instance:FindFirstChild()|FindFirstChild()` is that the
introduction of new properties does not impose a risk on your code.

```lua
local part = Instance.new("Part")
local folder = Instance.new("Folder")
folder.Name = "Color"
folder.Parent = part
local c1 = part.Color  -- The property
local c2 = part:FindFirstChild("Color")  -- The child folder
```

#### Performance Notes

`Class.Instance:FindFirstChild()|FindFirstChild()` takes about 20% longer
than using the dot operator and almost 8 times longer than simply storing
a reference to an object. Therefore, you should avoid calling it in
performance-dependent code such as in tight loops or functions connected
to `Class.RunService.Heartbeat` and `Class.RunService.PreRender`. Instead,
store the result in a variable, or consider using
`Class.Instance.ChildAdded|ChildAdded` or
`Class.Instance:WaitForChild()|WaitForChild()` to detect when a child of a
given name becomes available.


Instance:FindFirstChild

Returns the first child of the `Class.Instance` found with the given name.


Instance

`Instance` is the base class for all classes in the Roblox class hierarchy
which can be part of the `Class.DataModel` tree.
