The Flag is a unit spawned with a `Class.FlagStand` object, and will respawn
when captured. When a player touches this object's Handle, which must be a
child of the Flag object, which is a Part named "Handle", the flag will be
added to the player's backpack and will appear in their hand. A player cannot
select other weapons while carrying a flag, and can drop the flag at anytime
by pressing "Backspace" on the keyboard. If the player carrying a flag steps
onto another FlagStand of a different team color, the flag will be removed
from the player's backpack and a point will be added to the user's
leaderstats, if provided. The flag will then regenerate at the originating
flag stand.


Flag

The `Class.Team` this flag is for. Corresponds with the TeamColors in the
`Class.Teams` service.

The `Class.Flag` and `Class.FlagStand` objects were created to allow
developers to make 'capture the flag' style games quickly.


Flag.TeamColor

The `Class.Team` this flag is for. Corresponds with the TeamColors in the
`Class.Teams` service.


The Flag object helps you make 'capture the flag' style games.


This code is meant to be placed in a Script within a Tool. It allows a player
to spawn explosions by equipping the tool and clicking on the ground. It does
so by defining a function, `explode`, which creates a non-deadly explosion at
a given point. Then, it defines a function, `onActivated`, that runs when the
tool is activated. Finally, it connects the Activated event of the tool to the
`onActivated` function.

To test this code out, try creating a Tool and put a Part inside it. Name the
Part "Handle". Put a Script inside the Tool next, and paste the code into it.
Finally, put the Tool in the StarterPack.

This code sample is for a Tool object with a Part named Handle. It detects
when Humanoids other than the current holder hit the handle, and deals some
damage to them. In addition, when the Tool is activated, it triggers a slash
animation in the default character animation scripts. Try out this script by
creating a Tool object in the StarterPack. Put a Part inside it, and name it
Handle. Paste this code into a Script inside the Tool, then try slashing at
another Humanoid!

A `Tool` is an object that a `Class.Humanoid` object can equip. For players,
they are stored in a `Class.Backpack` object parented to a `Class.Player`
object. In-experience, players may have multiple tools which appear as icons
at the bottom of the screen. Equipping a tool moves it from the
`Class.Backpack` and into a `Class.Player.Character` model in the
`Class.Workspace`. By default, tools are held in the right hand and have a
handle in them, which is a `Class.BasePart` named `Handle` inside (although
one isn't required if `Class.Tool.RequiresHandle` is `false`). Tools that are
to be provided to (re)spawning players should be stored in the
`Class.StarterPack`.


This event fires when the player clicks while the `Class.Tool` is
equipped. It is **not** fired if the <kbd>Ctrl</kbd> key is pressed during
the click.

This event is typically used to perform an action when the player uses the
tool, for instance to launch a rocket from a rocket launcher weapon tool.

The below code, when placed in a `Class.LocalScript`, creates a tool in
the local player's `Class.Backpack` and prints "Tool activated" when the
player clicks while the created tool is equipped.

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

local tool = Instance.new("Tool")
tool.RequiresHandle = false
tool.Parent = Players.LocalPlayer.Backpack

function onActivation()
	print("Tool activated")
end

tool.Activated:Connect(onActivation)
```


Tool.Activated

Fires when the player clicks while the tool is equipped.


This event fires when the player releases their click while the
`Class.Tool` is equipped and activated. It is typically used to perform an
action when the player stops using a tool.

The below code, when placed in a `Class.LocalScript`, creates a tool in
the local player's `Class.Backpack` and prints "Tool deactivated" when the
player releases their click while the tool is equipped and activated.

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

local tool = Instance.new("Tool")
tool.RequiresHandle = false
tool.Parent = Players.LocalPlayer.Backpack

function toolDeactivated()
	print("Tool deactivated")
end

tool.Deactivated:Connect(toolDeactivated)
```


Tool.Deactivated

Fires when the player releases their click while the tool is equipped and
activated.


The example shown below will print "A tool was equipped" each time the tool is
equipped by the player. Please note that the below example assumes that you've
already defined what "Tool" is.

This event fires when a player equips the `Class.Tool` (takes it out of
their `Class.Backpack`).

The opposite of this event, `Class.Tool.Unequipped`, can be used to
determine when the player unequips the tool by putting it in their
backpack.

Note that this event does **not** fire when `Class.Tool.RequiresHandle` is
enabled and no handle is present.


Tool.Equipped

mouse

This event fires when a player unequips the `Class.Tool` (puts it in their
`Class.Backpack`).

The opposite of this event, `Class.Tool.Equipped`, can be used to
determine when the player equips the tool by taking it out of their
backpack.

Note that this event does **not** fire when `Class.Tool.RequiresHandle` is
enabled and no handle is present.


Tool.Unequipped

The code below creates a `Class.Tool` in the local player's `Class.Backpack`
that turns the player invisible when activated and visible when deactivated.

When equipped, the script simulates the tool being activated and turns the
player invisible for 3 seconds and then simulates the tool being deactivated.
Holding the left mouse button down turns the player invisible for up to 3
seconds, with a cooldown period of 1 second, or until the player releases
their left mouse button.

This function simulates activation of the `Class.Tool`. The tool must be
equipped for this function to work.


Tool:Activate

Simulates activation of the `Class.Tool`.


This function simulates deactivation of the `Class.Tool`. The tool must be
equipped for this function to work.


Tool:Deactivate

Simulates deactivation of the `Class.Tool`.


Tool

The CanBeDropped property controls whether the player can drop the
`Class.Tool`.

If true, when the backspace button is pressed, the tool will be parented
to `Class.Workspace` and removed from the player's `Class.Backpack`. If
false, nothing will happen when backspace is pressed, and the tool will
remain equipped.


Tool.CanBeDropped

Controls whether the player can drop the tool.


The code sample below creates `Class.Tool` in the local player's
`Class.Backpack` that increases their `Class.Humanoid.JumpPower|JumpPower`
from `50` to `150` for 5 seconds.

This example uses the tool's `Class.Tool.Enabled` property as a debounce by
setting the property to `true` when the player jumps and back to `false` after
the 5 second duration.

Unequipping the tool also stops the player from super jumping by changing the
`Class.Humanoid.JumpPower|JumpPower` back to `50`.

The **Enabled** property relates to whether or not the `Class.Tool` can be
used. This is useful if you want to prevent a player from using a tool,
but don't want to remove it from their `Class.Backpack`.

When set to `true`, the player can use the tool. When set to `false`, the
tool is disabled and the player cannot use it; this prevents the tool from
being activated or deactivated by the `Class.Tool:Activate()` and
`Class.Tool:Deactivate()` methods, and it prevents the
`Class.Tool.Activated` and `Class.Tool.Deactivated` events from firing.


Tool.Enabled

Relates to whether or not the tool can be used.


The code below insert's a `Class.Tool` named **Stick** into the local player's
`Class.BackPack`. When the player activates the tool, the code prints the
values of the tool's grip properties.

The `Grip` property stores the tool's "grip" properties as a single
`Datatype.CFrame`. These properties position how the player holds the tool
and include `Class.Tool.GripUp|GripUp`, `Class.Tool.GripRight|GripRight`,
`Class.Tool.GripForward|GripForward`, and `Class.Tool.GripPos|GripPos`.


Tool.Grip

Stores the tool's "grip" properties as one `Datatype.CFrame`.


One of the properties that specifies a tool's orientation in a character's
hand. This represents the `R02`, `R12`, and `R22` values of the grip
`Datatype.CFrame` rotation matrix.

Other tool properties that control how a character holds a tool include
`Class.Tool.GripUp`, `Class.Tool.GripRight`, and `Class.Tool.GripPos`. All
of these properties are stored in a single `Datatype.CFrame` in the
`Class.Tool.Grip` property.


Tool.GripForward

Represents the `R02`, `R12`, and `R22` values of the grip
`Datatype.CFrame` rotation matrix.


This property controls the positional offset of the tool's weld matrix. It
is one of several properties used to position how the player character
holds the tool.

Other properties that control how a character holds a tool include
`Class.Tool.GripUp`, `Class.Tool.GripRight`, and `Class.Tool.GripForward`.
All of these properties are stored in a single `Datatype.CFrame` in the
`Class.Tool.Grip` property.


Tool.GripPos

The positional offset of the tool's weld matrix.


One of the properties that specifies a tool's orientation in a character's
hand. This represents the `R00`, `R10`, and `R20` values of the grip
`Datatype.CFrame` rotation matrix.

Other tool properties that control how a character holds a tool include
`Class.Tool.GripUp`, `Class.Tool.GripForward`, and `Class.Tool.GripPos`.
All of these properties are stored in a single `Datatype.CFrame` in the
`Class.Tool.Grip` property.


Tool.GripRight

Represents the `R00`, `R10`, and `R20` values of the grip
`Datatype.CFrame` rotation matrix.


One of the properties that specifies a tool's orientation in a character's
hand. This represents the `R01`, `R11`, and `R21` values of the grip
`Datatype.CFrame` rotation matrix.

Other tool properties that control how a character holds a tool include
`Class.Tool.GripRight`, `Class.Tool.GripForward`, and
`Class.Tool.GripPos`. All of these properties are stored in a single
`Datatype.CFrame` in the `Class.Tool.Grip` property.


Tool.GripUp

Represents the `R01`, `R11`, and `R21` values of the grip
`Datatype.CFrame` rotation matrix.


The code sample below creates `Class.Tool` in the local player's
`Class.Backpack` that increases their `Class.Humanoid.Walkspeed|WalkSpeed`
from `16` to `30` for 5 seconds.

This example uses the tool's `Class.Tool.ManualActivationOnly` property as a
debounce by setting the property to `true` when the player begins sprinting
and to `false` when the player stops sprinting. As a result, when the player
is sprinting, the tool cannot be re-activated.

Unequipping the tool also stops the player from sprinting by changing the
`Class.Humanoid.Walkspeed|WalkSpeed` to `16`.

This property controls whether the `Class.Tool` can be activated without
explicitly executing `Class.Tool:Activate()` in a script.

When set to `true`, the tool will only fire `Class.Tool.Activated` when
`Class.Tool:Activate()` is called. This also suppresses the
`Class.ContextActionService:BindActivate()` function.

When set to `false`, mouse clicks (when the tool is equipped) will also
fire `Class.Tool.Activated`.


Tool.ManualActivationOnly

Controls whether the `Class.Tool` can be activated without executing
`Class.Tool:Activate()`.


This property determines whether a `Class.Tool` functions without a
handle.

A tool has a handle when it contains a child part named **Handle**. Tools
with handles typically require the player equipping them to hold an object
to use them, for instance weapons. Tools without handles typically don't
require the player equipping them to hold anything to use them, for
instance "fly" or "summon" tools.

When set to `true`, the tool will function only with a handle. When set to
`false`, the tool will function even without a handle.


Tool.RequiresHandle

Determines whether a `Class.Tool` functions without a handle.


The ToolTip property controls the message that will be displayed when the
player's `Class.Mouse` hovers over the `Class.Tool` in their
`Class.Backpack`.

Generally, the value of this property should describe the what the tool is
or its use. For instance, for a shovel tool, you may choose to set the
ToolTip to:

```lua
tool.ToolTip = "Shovel"
```

or

```lua
tool.ToolTip = "Use to dig"
```

or

```lua
tool.ToolTip = "Shovel - Use to dig"
```


Tool.ToolTip

Controls the message displayed when the player's mouse hovers over the
tool in their backpack.


An object, such as a weapon, that can be equipped by a `Class.Humanoid`.


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.

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


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

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.


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

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 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:moveTo

Model

Sets the level of detail on the model for experiences with instance
[streaming](/workspace/streaming) enabled.

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.

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 `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 `Script` or `LocalScript`. `Model/ScaleTo` and `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 `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` ("Position Velocity Instance") is an abstract class that
cannot be created. It is the base for all objects that have a physical
location in the world, specifically `Class.BasePart|BaseParts` and
`Class.Model|Models`.


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,
specifically `Class.BasePart|BaseParts` and `Class.Model|Models`.


`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 the `Class.Instance.Parent` property of the object or one of
its ancestors is changed.

This event includes two parameters: `child` refers to the `Class.Instance`
whose `Class.Instance.Parent` was actually changed, while `parent` refers
to this instance's new `Class.Instance.Parent`.

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 `Class.Instance` whose `Class.Instance.Parent` has been changed.


parent

The new `Class.Instance.Parent` of the `Class.Instance` whose
`Class.Instance.Parent` was changed.


Fires when the `Class.Instance.Parent` property of the 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 function 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 function only works for immediate children of the
`Class.Instance`. For a function 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`.


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 function only works for immediate children of the `Class.Instance`.
For a function 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`.


Instance

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


Flag

Summary

Properties

Methods

Events

Properties

TeamColor

Methods

Events