SurfaceAppearance objects allow developers to override the appearance of a
`MeshPart` with advanced graphics options. Most notably, a SurfaceAppearance
can apply a set of PBR textures to a mesh.

PBR is short for Physically Based Rendering, which refers to a common texture
format for defining extra physical details in games. Because this format is
widely used, it's easy to take meshes and textures made in 3rd party editing
software and import them into Roblox. It's also easy to find PBR format
content from various 3rd party stores such as [SketchFab][1], [TurboSquid][2],
[CGTrader][3].

For PBR textures to be visible in-game, when you change a texture property of
SurfaceAppearance you should wait until you see the "Successfully uploaded
compressed SurfaceAppearance." message in the output window. If your PBR
textures are not visible, try changing a texture property.

Here is a mesh with PBR textures [found on Turbosquid][5] imported into
Roblox.

![TextureId vs SurfaceAppearance][4]

![Pine trees][6]

SurfaceAppearance's `SurfaceAppearance/AlphaMode|AlphaMode` property can also
be to improve the look of partially transparent textures on MeshParts by
fixing various sorting issues.

How a MeshPart with a SurfaceAppearance looks to users depends on their device
and their graphics quality level. You may want to preview your content with
different quality level settings.

Note:

- Most SurfaceAppearance properties cannot be modified by scripts in-game.
  This is because the Roblox engine needs to do some pre-processing to display
  a SurfaceAppearance, and this is usually too expensive to perform in-game.

[1]:
  https://sketchfab.com/search?q=pbr%20object&sort_by=-relevance&type=models
[2]: https://www.turbosquid.com/Search/3D-Models/free/pbr
[3]: http://cgtrader.com/pbr-3d-models?polygons=lt_5k
[4]: /assets/bltd50936403ef1c135/meshpart-vs-sa.png
[5]:
  https://www.turbosquid.com/3d-models/3d-model-fantasy-sword---ready/1119210
[6]: /assets/bltab4ab6ba1c003d12/pinetrees.png


SurfaceAppearance

This property determines how the alpha channel of the
`SurfaceAppearance/ColorMap` of a `SurfaceAppearance` is used.

When AlphaMode is set to `Enum/AlphaMode|Transparency` and the
`BasePart/Transparency|MeshPart.Transparency` is set to 0, opaque pixels
in the SurfaceAppearance's ColorMap will render as completely opaque in
the 3D scene. This solves various problems for textures with different
transparent and opaque areas, such as foliage. When parts of the surface
are fully opaque, the Roblox engine can render them with proper
depth-based occlusion. Opaque surfaces also generally work better with
depth-based effects like DepthOfField, glass and water refraction, and
water reflection.

MeshPart.TextureId vs SurfaceAppearance:

![Foliage comparison][1]

Here is an example of a fern color map. Only the pixels on the leaves have
full alpha.

![Alpha fern][2]

[1]: /assets/bltc11b6d62483163b0/leaves-comparison.gif
[2]: /assets/blt1a2e3175d2522842/fern-color.png


SurfaceAppearance.AlphaMode

Determines how the alpha channel of the `SurfaceAppearance/ColorMap` of a
`SurfaceAppearance` is used.


This property determines the color and opacity of the surface. This
texture is sometimes called the albedo texture. The alpha channel of this
texture controls its opacity, which behaves differently based on the
`SurfaceAppearance/AlphaMode` setting.


SurfaceAppearance.ColorMap

Determines the color and opacity of the surface.


This property determines which parts of the surface are metal and are
non-metal. A metalness map is a grayscale image where black pixels
correspond to non-metals and white pixels correspond to metals.

Metals only reflect light the same color as the metal, and they reflect
much more light than non-metals. Most materials in the real world can be
categorized either metals or non-metals. For this reason, most pixels in a
metalness map will be either pure black or pure white. Values in between
are typically used to simulate dirt or grunge on top of an underlying
metal area.

Here's an example of a piece of metal with a layer of paint on top. Most
paints are non-metallic, so the metalness map is black everywhere except
on unpainted metal parts and spots where the paint has chipped away and
the underlying metal is visible.

![Metalness jetpack][1]

![Map explanation][2]

#### Note

- When `Lighting/EnvironmentSpecularScale` is 0, metalness has no effect.
  For the most realistic reflections, setting EnvironmentSpecularScale and
  `Lighting/EnvironmentDiffuseScale` to 1, and `Lighting/Ambient` and
  `Lighting/OutdoorAmbient` to (0,0,0) is recommended.

[1]: /assets/blt0a658c7367d5cdab/jetpack.gif
[2]: /assets/blt96558be20f7b7a1a/metalness-explained.png


SurfaceAppearance.MetalnessMap

Determines which parts of the surface are metal and are non-metal.


This property modifies the lighting of the surface by adding bumps, dents,
cracks, and curves without adding more polygons.

Normal maps are RGB images that modify the surface's normal vector used
for lighting calculations. The R, G, and B channels of the NormalMap
correspond to the X, Y, and Z components of the local surface vector
respectively, and byte values of 0 and 255 for each channel correspond
linearly to normal vector components of -1 and 1.016 respectively. This
range is stretched slightly from -1 to 1 so that a byte value of 127 maps
to exactly 0. The normal vector's Z axis is always defined as the
direction of the underlying mesh's normal. A uniform (127,127,255) image
translates to a completely flat normal map where the normal is everywhere
perpendicular to the mesh surface. This format is called “tangent space”
normal maps. Roblox does not support world space or object space normal
maps.

Incorrectly flipped normal components can make bumps appear like indents.
If you import a normal map and notice the lighting looks off, you may need
to invert the G channel of the image. The X and Y axes of the tangent
space frame correspond to the X and Y directions in the image after it's
transformed by the mesh UVs. If you view your normal map in an image
editor as if it were displayed on a surface, normals pointing towards the
right side of the screen should appear more red, and normals pointing
towards the top side of your screen should appear more green.

![Bread normal map][1]

The terms “DirectX format” and “OpenGL format” are sometimes used to
describe whether the G channel of the normal map is inverted or not.
Roblox expects the OpenGL format.

#### Note

Roblox expects imported meshes to include tangents. Modeling software may
also refer to this as “tangent space” information. If you apply a normal
map and it does not seem to make any visual difference, you may need to
re-export your mesh along with its tangent information from modeling
software.

[1]: /assets/blt013e67a5f211cd0d/bread-nmap.png


SurfaceAppearance.NormalMap

Modifies the lighting of the surface by adding bumps, dents, cracks, and
curves without adding more polygons.


This property determines the apparent roughness across the surface. A
roughness map is a grayscale image where black pixels correspond to a
maximally smooth surface, and white pixels correspond to a maximally rough
surface.

Roughness refers to how much variation the surface has on a very small
scale. Reflections on smooth surfaces are sharp and concentrated.
Reflections on rough surfaces are more blurry and dispersed.


SurfaceAppearance.RoughnessMap

Determines the apparent roughness across the surface.


An object that allows developers to override the appearance of a MeshPart with
advanced graphics options.


Instance is the base class for all classes in the Roblox class hierarchy.
Every other class that the Roblox engine defines inherits all of the members
of Instance. It is not possible to directly create Instance objects.

Instance has a special function called `Instance.new` which is used to create
objects via code. This function takes the name of the class as a parameter and
returns the created object. Abstract classes and services cannot be created
with the Instance.new function.


The below example would print "Part is now a child of Model".


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

This event includes two parameters, _child_ and _parent_. _Child_ refers
to the `Instance` whose `Instance/Parent` was actually changed. _Parent_
refers to this `Instance`'s new `Instance/Parent`.

If you need to detect when an instance is destroyed via
`Instance/Destroy`, consider the `Instance/Destroying` event instead. This
event fires when an object is deleted in Studio with `nil` as the `parent`
argument.


Instance.AncestryChanged

child

The `Instance` whose `Instance/Parent` has been changed.


parent

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


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


This event fires whenever an attribute is changed on the instance. This
includes when an attribute is set to nil. The name of the attribute that
has been changed is passed to the connected function.

For example, the following code snippet will connect the
`AttributeChanged` function to fire whenever one of `Instance`'s
attributes changes. Note that this code sample does not define `Instance`:

```lua
local function attributeChanged(attributeName)
    print(attributeName, “changed”)
end

instance.AttributeChanged:Connect(attributeChanged)
```

See also:

- `Instance/SetAttribute`, sets the attribute with the given name to the
  given value
- `Instance/GetAttribute`, returns the attribute which has been assigned
  to the given name
- `Instance/GetAttributes`, returns a dictionary of string → variant pairs
  for each of the instance's attributes
- `Instance/GetAttributeChangedSignal`, returns an event that fires when
  the given attribute changes


Instance.AttributeChanged

attribute

The name of the attribute that has been changed.


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


This code sample demonstrates the Changed event firing within a parent object.


This sample demonstrates the subtleties of the Changed event on normal objects
and "-Value" objects.


The Changed event fires right after most properties change on objects. It
is possible to find the present value of a changed property by using
`object[property]`. To get the value of a property before it changes, you
must have stored the value of the property before it changed.

If you are only interested in listening to the change of a specific
property, consider using the `GetPropertyChangedSignal` method instead to
get an event that only fires when a given property changes.

This event does not fire for physics-related changes, like when the
`CFrame`, `Velocity`, `RotVelocity`, `Position`, `Orientation` and
`CFrame` properties of a `BasePart` change due to gravity. To detect
changes in these properties, consider using a physics-based event like
`RunService.Stepped` or `BasePart.Touched`. A while-true-do loop can also
work.

For "-Value" objects, this event behaves differently: it only fires when
the `Value` property changes. See individual pages for `IntValue`,
`StringValue`, etc for more information. To detect other changes in these
objects, you must use `GetPropertyChangedSignal` instead.


Instance.Changed

property

Fired immediately after a property of an object changes.


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


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

Note, when using this function on a client to detect objects created by
the server it is necessary to use `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:

```
workspace.ChildAdded:Connect(function(child)
	-- need to use WaitForChild as descendants may not have replicated yet
	local head = child:WaitForChild("Head")
end)
```

Note, this function only works for immediate children of the `Instance`.
For a function that captures all descendants, use
`Instance/DescendantAdded`.

See also, `Instance/ChildRemoved`.


Instance.ChildAdded

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


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


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

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

This function only works for immediate children of the `Instance`. For a
function that captures all descendants, use `Instance/DescendantRemoved`.

See also `Instance/ChildAdded`.


Instance.ChildRemoved

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


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


The DescendantAdded event fires after a descendant is added to the
`Instance`.

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

Developers only concerned with the immediate children of the `Instance`
should use `Instance/ChildAdded` instead.

See also `Instance/DescendantRemoving`.


Instance.DescendantAdded

descendant

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


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


DescendantRemoving fires **immediately before** the
`Instance/Parent|Parent` of a descendant of the `Instance` changes such
that the object is no longer a descendant of the Instance.
`Instance/Destroy|Destroy` and `Instance/Remove|Remove` change an object's
Parent to nil, so calling these on a descendant of an object will
therefore cause this event to fire.

Since this event fires before the the descendant's removal, the Parent of
the descendant will be unchanged, i.e., it will still be a descendant at
the time of this event firing. If the descendant is also a child of the
object, It will also fire before ChildRemoved. There is no similar event
called "DescendantRemoved".

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

#### Example

The example below should help clarify how DescendantRemoving fires when
there are several objects involved.

![A cropped screenshot of the Explorer window. A Model contains ModelA and ModelB, which each contain a Part, PartA and PartB respectively. PartA contains a Fire object named FireA.][1]

- Calling `Instance/Remove|Remove` on **PartA** would cause
  DescendantRemoving to fire on both **ModelA** and **Model**, in that
  order.
- Setting the `Instance/Parent|Parent` of **PartA** to **ModelB** would
  cause DescendantRemoving to fire on **ModelA** but not **Model** (as
  Model would still be an ancestor of PartA).
- Calling `Instance/Destroy|Destroy` on **ModelA** would cause
  DescendantRemoving to fire multiple times on several objects:
  1.  On **Model** with **ModelA**, **PartA** then **FireA**.
  2.  On **ModelA**, with **PartA** then **FireA**.
  3.  On **PartA** with **FireA**.

#### Warning

This event fires with the descendant object that is being removed.
Attempting to set the `Instance/Parent|Parent` of the descendant being
removed to something else **will fail** with the following warning:
"Something unexpectedly tried to set the parent of X to Y while trying to
set the parent of X. Current parent is Z", where X is the removing
descendant, Y is the ignored parent setting, and Z is the original parent
of X. Below is an example that demonstrates this:

```
workspace.DescendantRemoving:Connect(function(descendant)
	-- Don't manipulate the parent of descendant in this function!
	-- This event fires BECAUSE the parent of descendant was manipulated,
	-- and the change hasn't happened yet, i.e. this function fires before that happens.
	-- 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 -- This triggers DescendantRemoving on Workspace:
--> Something unexpectedly tried to set the parent of Part to NULL while trying to set the parent of Part. Current parent is Workspace.
```

See also `Instance/DescendantAdded|DescendantAdded`.

[1]: /assets/blte4c2d8d1b0fe590c/DescendantRemoving2.png


Instance.DescendantRemoving

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


This sample demonstrates how an Instance being destroyed remains in place
until the connected function yields.


The Destroying event fires immediately before the Instance or one of its
ancestors is destroyed.

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

This event doesn't fire when an Instance is deleted in Studio. To detect
this, use `Instance/AncestryChanged`.


Instance.Destroying

Fires immediately before the instance is destroyed via `Instance/Destroy`.


Instance.childAdded

This example creates a Part and adds a few sparkle objects to the part. Then
it calls Part:ClearAllChildren() to remove all of the children.


This function destroys all of an `Instance`'s children.

As `Instance/Destroy` also calls itself on the children of an object it is
used on, this function will destroy all descendants.

#### Alternatives to ClearAllChildren

If the developer does not wish to destroy all descendants, they should use
`Instance/GetChildren` or `Instance/GetDescendants` to loop through an
object and select what to destroy. For example, the following code sample
will destroy all parts in an object.

```
for _, instance in pairs(object:GetDescendants()) do
	if instance:IsA("BasePart") then
		instance:Destroy()
	end
end
```


Instance:ClearAllChildren

This function destroys all of an `Instance`'s children.


This code first references an existing object in the `original` variable.
Then, it makes a copy of the object, sets the parent to that of the original,
and finally moves the copy to (0, 50, 0).


**Clone** creates a copy of an object and all of its descendants, ignoring
all objects that are not `Instance/Archivable|Archivable`. The copy of the
root object is returned by this function and its `Instance/Parent|Parent`
is set to nil.

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

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

This function is typically used to create models that can be regenerated.
First, get a reference to the original object. Then, make a copy of the
object and insert the copy by setting its `Instance/Parent|Parent` to the
`Workspace` or one of its descendants. Finally, when it's time to
regenerate the model, `Instance/Destroy|Destroy` the copy and clone a new
one from the original like before.


Instance:Clone

Create a copy of an object and all its descendants, ignoring objects that
are not `Instance/Archivable|Archivable`.


Sets the `Instance/Parent` property to nil, locks the `Instance/Parent`
property, disconnects all connections, and calls Destroy on all children.
This function 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 (this is called a
**memory leak**) which can lead to serious performance issues over time.

**Tip:** 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 `Instance` has been destroyed by this method it cannot be reused
because the `Instance/Parent` property is locked. To temporarily remove an
object, set `Instance/Parent|Parent` it to nil instead. For example:

```
object.Parent = nil
wait(2)
object.Parent = workspace
```

To Destroy an object after a set amount of time, use `Debris/AddItem`.


Instance:Destroy

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


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

This function works upwards, meaning it starts at the `Instance`'s
immediate `Instance/Parent` and works up towards the `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 function that find ancestors of a specific class,
please see `Instance/FindFirstAncestorOfClass` and
`Instance/FindFirstAncestorWhichIsA`.


Instance:FindFirstAncestor

name

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


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

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

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

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

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


Instance:FindFirstAncestorOfClass

className

The `Instance/ClassName` to be looked for.


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


Returns the first ancestor of the `Instance` for whom `Instance/IsA`
returns true for the given className.

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

Unlike `Instance/FindFirstAncestorOfClass`, this function uses
`Instance/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 `BasePart`
ancestor, regardless of if it is a `WedgePart`, `MeshPart` or `Part`.

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

See also, `Instance/FindFirstAncestor`.


Instance:FindFirstAncestorWhichIsA

Returns the first ancestor of the `Instance` for whom `Instance/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 `Instance` found with the given name. If no
child exists with the given name, this function returns nil. If the
optional recursive argument is true, this function searches all
descendants rather than only the immediate children of the `Instance`. Use
this function if your code cannot guarantee the existence of an object
with a given name.

#### Checking the Existence of An Object

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

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

Use FindFirstChild to first check for Part, then use an if-statement to
run code that needs it.

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

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

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

In the following example, a `Folder` called "Color" is added to a `Part`,
which also has the `Part/Color` property. `Part.Color` refers to the
`datatype/Color3`, not the Folder.

```lua
local part = Instance.new("Part")
local folder = Instance.new("Folder")
folder.Name = "Color"
folder.Parent = part
local c = part.Color --> A Color3
local c2 = part:FindFirstChild("Color") --> The Folder
```

A benefit of using FindFirstChild in this way is that the introduction of
new properties does not impose a risk on your code.

**Tip:** If you only need to use the result of a FindFirstChild call once,
such as getting the property of a child if it exists, you can use the
following syntax with the `and` operator:

```lua
local myColor = workspace:FindFirstChild("SomePart") and workspace.SomePart.Color
```

If SomePart exists, `myColor` will contain the Color of SomePart.
Otherwise, it'll be nil without throwing an error. This works due to
short-circuiting: Lua ignores the right side if the left is nil/false

#### Performance Note

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


Instance:FindFirstChild

recursive

Whether or not the search should be conducted recursively.


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


Returns the first child of the `Instance` whose
`Instance/ClassName|ClassName` is equal to the given className.

If no matching child is found, this function returns nil.

Unlike `Instance/FindFirstChildWhichIsA` this function uses only returns
objects whose class matches the given className, ignoring class
inheritance.

Developers looking for a child by name should use
`Instance/FindFirstChild` instead.


Instance:FindFirstChildOfClass

Returns the first child of the `Instance` whose
`Instance/ClassName|ClassName` is equal to the given className.


Returns the first child of the `Instance` for whom `Instance/IsA` returns
true for the given className.

If no matching child is found, this function returns nil. If the optional
recursive argument is true, this function searches all descendants rather
than only the immediate children of the `Instance`.

Unlike `Instance/FindFirstChildOfClass`, this function uses `Instance/IsA`
which respects class inheritance. For example:

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

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

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

Developers looking for a child by name, should use
`Instance/FindFirstChild` instead.


Instance:FindFirstChildWhichIsA

The `Instance/ClassName` to be searched for.


Returns the first child of the `Instance` for whom `Instance/IsA` returns
true for the given className.


Returns the first descendant found with the given `Instance/Name`.


Instance:FindFirstDescendant

Returns the `Actor` associated with the Instance or `nil` if the Instance
is not associated with an Actor.

An Instance is associated with the Actor it's parented to. If the Instance
is nested within multiple Actors, it is associated with the closest
ancestor.


Instance:GetActor

Returns the `Actor` associated with the Instance, if any.


This function returns the attribute which has been assigned to the given
name. If no attribute has been assigned then nil is returned.

For example, the following code snippet will set the value of the
instance's `InitialPostion` attribute. Note that this code sample does not
define `Instance`:

```lua
local initialPosition = instance:GetAttribute("InitialPosition")
```

See also:

- `Instance/SetAttribute`, sets the attribute with the given name to the
  given value
- `Instance/GetAttributes`, returns a dictionary of string → variant pairs
  for each of the instance's attributes
- `Instance/AttributeChanged`, fires whenever an attribute is changed on
  the instance
- `Instance/GetAttributeChangedSignal`, returns an event that fires when
  the given attribute changes


Instance:GetAttribute

The name of the attribute being retrieved.


The attribute which has been assigned to the given name. If no
attribute has been assigned then nil is returned.


Returns the attribute which has been assigned to the given name.


This function returns an event that behaves exactly like the `Changed`
event, except that the event only fires when the given attribute changes.
It's generally a good idea to use this method instead of a connection to
Changed with a function that checks the attribute name. Subsequent calls
to this method on the same object with the same attribute name return the
same event.

It is similar to `Instance/GetPropertyChangedSignal` but for attributes.

For example, the following code snippet will return a signal that fires
the function `Instance/AttributeChanged` when the instance's
`InitialPosition` attribute changes. Note that this code sample does not
define `Instance`:

```lua
local function attributeChanged()
    print(“Attribute changed”)
end

instance:GetAttributeChangedSignal("InitialPosition"):Connect(attributeChanged)
```

See also:

- `Instance/SetAttribute`, sets the attribute with the given name to the
  given value
- `Instance/GetAttribute`, returns the attribute which has been assigned
  to the given name
- `Instance/GetAttributes`, returns a dictionary of string → variant pairs
  for each of the instance's attributes
- `Instance/AttributeChanged`, fires whenever an attribute is changed on
  the instance


Instance:GetAttributeChangedSignal

The name of the specified attribute for which the change signal is
being returned.


An event that fires when the given attribute changes.


Returns an event that fires when the given attribute changes.


This function returns a dictionary of string → variant pairs for each
attribute where the string is the name of the attribute and the variant is
a non-nil value.

For example, the following code snippet will print an instance's
attributes and values. Note that this code sample does not define
`Instance`:

```lua
local attributes = instance:GetAttributes()
for name, value in pairs(attributes) do
    print(name .. “ “ .. value)
end
```

See also:

- `Instance/SetAttribute`, sets the attribute with the given name to the
  given value
- `Instance/GetAttribute`, returns the attribute which has been assigned
  to the given name
- `Instance/AttributeChanged`, fires whenever an attribute is changed on
  the instance
- `Instance/GetAttributeChangedSignal`, returns an event that fires when
  the given attribute changes


Instance:GetAttributes

A dictionary of string → variant pairs for each attribute where the
string is the name of the attribute and the variant is a non-nil
value.


Returns a dictionary of string → variant pairs for each of the
`Instance|Instance`'s attributes.


The below would print the name of all objects currently in Workspace when ran.


Returns an array (a numerically indexed table) containing all of the
`Instance`'s direct children, or every `Instance` whose
`Instance/Parent|Parent` is equal to the object. The array can be iterated
upon using either a numeric or generic for-loop:

```lua
-- Numeric for-loop example
local children = workspace:GetChildren()
for i = 1, #children do
	local child = children[i]
	print(child.Name .. " is child number " .. i)
end
```

```lua
-- Generic for-loop example
local children = workspace:GetChildren()
for i, child in ipairs(children) do
	print(child.Name .. " is child number " .. i)
end
```

The children are sorted by the order in which their
`Instance/Parent|Parent` property was set to the object.

See also the `Instance/GetDescendants|GetDescendants` function.


Instance:GetChildren

An array containing the `Instance`'s children.


Returns an array containing all of the `Instance`'s children.


Returns a coded string of the `Instance`s DebugId used internally by
Roblox.

Note:

- This item is protected. Attempting to use it in a `Script` or
  `LocalScript` will cause an error
- A debug ID is an ID used in debugging processes. It allows a debugger to
  read each instruction before an application processes it. All objects in
  Roblox act like processes and each run instructions (or 'code') that can
  be debugged if needed
- This can be helpful for plugins which need to distinguish similar
  objects from one-another (such as objects that share the same name)


Instance:GetDebugId

scopeLength

Returns a coded string of the `Instance`s DebugId used internally by
Roblox.


GetDescendants is often used to do something to all the descendants that are a
particular type of object. The code in this example uses GetDescendants and
`/Instance/IsA` to find all of the parts in the workspace and turns them
green.


The **GetDescendants** function of an object returns an array that
contains all of the descendants of that object. Unlike
`Instance/GetChildren`, which only returns the immediate children of an
object, GetDescendants will find every child of the object, every child of
those children, and so on.

The arrays returned by GetDescendants are arranged so that parents come
earlier than their children. Refer to the following example of a `Model`
in the `Workspace`:

![Workspace Descendants][1]

Inside this model are three parts (C, D, and E) and another model
(InnerModel). Inside the inner model are two more parts (A and B). Calling
GetDescendants on the first model and printing the contents of the
returned array would print the first level of children (InnerModel, C, D,
and E) before A and B.

```lua
local descendants = game.Workspace.Model:GetDescendants()

-- Loop through all of the descendants of the model and
-- print out their name
for index, descendant in pairs(descendants) do
	print(descendant.Name)
end

-- Prints:
-- C
-- D
-- E
-- InnerModel
-- A
-- B
```

[1]: /assets/blt0c3edf2a368c36c8/GetDescendantsExample.png


Instance:GetDescendants

An array containing the `Instance`'s descendants.


Returns an array containing all of the descendants of the instance.


This code sample demonstrates the behavior of `Instance/GetFullName`. It shows
how the function behaves when called on an object not in the `DataModel`
hierarchy, and it also shows how the return value does not escape special
characters.


This code sample re-implements the `Instance/GetFullName` function in Lua.


Returns a string describing the `Instance`'s ancestry. The string is a
concatenation of the `Instance/Name|Name` of the object and its ancestors,
separated by periods. The `DataModel` (`game`) is not considered. For
example, a `Part` in the `Workspace` may return `Workspace.Part`.

When called on an `Instance` that is not a descendant of the `DataModel`,
this function considers all ancestors up to and including the topmost one
without a `Instance/Parent|Parent`.

This function is useful for logging and debugging. You shouldn't attempt
to parse the returned string for any useful operation; this function does
not escape periods (or any other symbol) in object names. In other words,
although its output often appears to be a valid Lua identifier, it is not
guaranteed.


Instance:GetFullName

Returns a string describing the `Instance`'s ancestry.


This code sample demonstrates the equivalence of the `Changed` event and event
returned by `GetPropertyChangedSignal`.


This code sample demonstrates how to save a value before a changed event fires
on it in order to get more information about a change.


This method returns an event that behaves exactly like the `Changed`
event, except that the event only fires when the given property changes.
It's generally a good idea to use this method instead of a connection to
`Changed` with a function that checks the property name. Subsequent calls
to this method on the same object with the same property name return the
same event.

`print(object:GetPropertyChangedSignal("Name") == object:GetPropertyChangedSignal("Name")) --> always true`

`ValueBase` objects, such as `IntValue` and `StringValue`, use a modified
`Changed` event that fires with the contents of the `Value` property. As
such, this method provides a way to detect changes in other properties of
those objects. For example, to detect changes in the `Name` property of an
`IntValue`, use
`IntValue:GetPropertyChangedSignal("Name"):Connect(someFunc)` since the
`Changed` event of `IntValue` objects only detect changes on the `Value`
property.


Instance:GetPropertyChangedSignal

A signal that fires whenever the property changes.


Get an event that fires when a given property of an object changes.


IsA returns true if the `Instance`'s class is **equivalent to** or a
**subclass** of a given class. This function is similar to the
**instanceof** operators in other languages, and is a form of
[type introspection](https://en.wikipedia.org/wiki/Type_introspection). To
ignore class inheritance, test the `Instance/ClassName|ClassName` property
directly instead. For checking native Lua data types (number, string, etc)
use the functions `type` and `typeof`.

Most commonly, this function is used to test if an object is some kind of
part, such as `Part` or `WedgePart`, which inherits from `BasePart` (an
abstract class). For example, if your goal is to change all of a
`Player/Character|Character`'s limbs to the same color, you might use
`Instance/GetChildren|GetChildren` to iterate over the children, then use
IsA to filter non-`BasePart` objects which lack the `BrickColor` property:

```lua
local function paintFigure(character, color)
	-- Iterate over the child objects of the character
	for _, child in pairs(character:GetChildren()) do
		-- Filter out non-part objects, such as Shirt, Pants and Humanoid
		-- R15 use MeshPart and R6 use Part, so we use BasePart here to detect both:
		if child:IsA("BasePart") then
			child.BrickColor = color
		end
	end
end
paintFigure(game.Players.Player.Character, BrickColor.new("Bright blue"))
```

Since all classes inherit from `Instance`, calling
`object:IsA("Instance")` will always return true.


Instance:IsA

The class against which the Instance's class will be checked.
Case-sensitive.


Describes whether the Instance's class matched or is a subclass of the
given class.


Returns true if an `Instance`'s class matches or inherits from a given
class.


Returns true if an `Instance` is an ancestor of the given descendant.

An `Instance` is considered the ancestor of an object if the object's
`Instance/Parent` or one of it's parent's `Instance/Parent` is set to the
`Instance`.

See also, `Instance/IsDescendantOf`.


Instance:IsAncestorOf

True if the `Instance` is an ancestor of the given descendant.


Returns true if an `Instance` is an ancestor of the given descendant.


Returns true if an `Instance` is a descendant of the given ancestor.

An `Instance` is considered the descendant of an object if the
`Instance`'s parent or one of its parent's parent is set to the object.

Note, `DataModel` is a descendant of nil. This means IsDescendantOf cannot
be used with a parameter of nil to check if an object has been removed.

See also, `Instance/IsAncestorOf`.


Instance:IsDescendantOf

ancestor

True if the `Instance` is a descendant of the given ancestor.


Returns true if an `Instance` is a descendant of the given ancestor.


The following code demonstrates how a part can be re-added to the DataModel
after being removed:


The Remove function sets the object's `Instance/Parent` to nil, and does
the same for all its descendants.

If the object is referenced before being removed it is possible to
retrieve the object at a later point.


Instance:Remove

Sets the object's Parent to nil, and does the same for all its
descendants.


This function sets the attribute with the given name to the given value.
If the value given is nil, then the attribute will be removed (since nil
is returned by default).

For example, the following code snippet will set the instance's
`InitialPosition` attribute to `DataType/Vector3|Vector3.new(0, 0, 0)`.
Note that this code sample does not define `Instance`:

```lua
instance:SetAttribute("InitialPosition", Vector3.new(0, 0, 0))
```

#### Limitations

Naming requirements and restrictions:

- Names must only use alphanumeric characters and underscore
- No spaces or unique symbols are allowed
- Strings must be 100 characters or less
- Names are not allowed to start with RBX unless the caller is a Roblox
  core-script (reserved for Roblox)

When attempting to set an attribute to an unsupported type, an error will
be thrown.

See also:

- `Instance/GetAttribute`, returns the attribute which has been assigned
  to the given name
- `Instance/GetAttributes`, returns a dictionary of string → variant pairs
  for each of the instance's attributes
- `Instance/AttributeChanged`, fires whenever an attribute is changed on
  the instance
- `Instance/GetAttributeChangedSignal`, returns an event that fires when
  the given attribute changes


Instance:SetAttribute

value

The value that the specified attribute is being set to.


Sets the attribute with the given name to the given value.


The following code waits for an instance named "Part" to be added to
Workspace.


Returns the child of the `Instance` with the given name. If the child does
not exist, it will yield the current thread until it does.

If the _timeOut_ parameter is specified, this function will return nil and
time out after _timeOut_ seconds elapsing without the child being found.

#### Where should WaitForChild be used?

WaitForChild is extremely important when working on code ran by the client
(in a `LocalScript`). Roblox does not guarantee the time or order in which
objects are replicated from the server to the client. This can cause
scripts to break when indexing objects that do not exist yet.

For example, a `LocalScript` may access a `Model` in the `Workspace`
called 'Ship' like so:

```
local ship = workspace.Ship
-- Will error if ship hasn't replicated
```

However if the model 'Ship' has not replicated to the client when this
code is ran an error will be returned breaking the `LocalScript`.

Another alternative is using `Instance/FindFirstChild`. Not only is this
good practice when indexing objects in the `DataModel` (as it avoids
accidentally accessing properties) but it does not break if the object
does not exist. For example:

```
local ship = workspace:FindFirstChild("Ship")
-- Won't error, but ship will be nil if the ship hasn't replicated
```

Here, if the model doesn't exist the code will not error. Instead the
value ship will be equal to nil. This is better, but still not much good
if we want to use the ship model.

Instead WaitForChild should be used:

```
local ship = workspace:WaitForChild("Ship")
-- Will wait until the ship has replicated before continuing
```

Here, the thread will be yielded until the ship model has been found. This
means the ship model can be used as soon as it is ready.

Note:

- If a call to this function exceeds 5 seconds without returning, and no
  _timeOut_ parameter has been specified, a warning will be printed to the
  output that the thread may yield indefinitely; this warning takes the
  form `Infinite yield possible on 'X:WaitForChild("Y")'`, where X is the
  parent name and Y is the child object name.
- This function does not yield if a child with the given name exists when
  the call is made.
- This function is less efficient than `Instance/FindFirstChild` or the
  dot operator. Therefore, it should only be used when the developer is
  not sure if the object has replicated to the client. Generally this is
  only the first time the object is accessed


Instance:WaitForChild

childName

timeOut

Returns the child of the `Instance` with the given name. If the child does
not exist, it will yield the current thread until it does.


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


Instance:children

Returns an array of the object's children.


Instance:clone

Instance:destroy

Instance:findFirstChild

Instance:getChildren

Instance:isA

Instance:isDescendantOf

Instance:remove

Instance

This property determines whether an `Instance|object` should be included
when the game is published or saved, or when `Instance/Clone` is called on
one of the object's ancestors. Calling Clone directly on an object will
return nil if the cloned object is not archivable. Copying an object in
Studio (using the 'Duplicate' or 'Copy' options) will ignore the
Archivable property and set Archivable to true for the copy.

```
local part = Instance.new("Part")
print(part:Clone())  --> Part
part.Archivable = false
print(part:Clone())  --> nil
```


Instance.Archivable

Determines if an `Instance` can be cloned using `Instance/Clone` or saved
to file.


A read-only string representing the class this `Instance` belongs to.

This property can be used with various other functions of Instance that
are used to identify objects by type, such as `Instance/IsA` or
`Instance/FindFirstChildOfClass`.

Note this property is read only and cannot be altered by scripts.
Developers wishing to change an `Instance`'s class will instead have to
create a new `Instance`.

Unlike `Instance/IsA`, ClassName can be used to check if an object belongs
to a specific class ignoring class inheritance. For example:

```
for _, child in ipairs(game.Workspace:GetChildren()) do
    if child.ClassName == "Part" then
        print("Found a Part")
        -- will find Parts in model, but NOT TrussParts, WedgeParts, etc
    end
end
```


Instance.ClassName

A read-only string representing the class this `Instance` belongs to.


A non-unique identifier of the `Instance`.

This property is an identifier that describes an object. Names are not
necessarily unique identifiers however; multiple children of an object may
share the same name. Names are used to keep the object hierarchy
organized, along with allowing scripts to access specific objects.

The name of an object is often used to access the object through the data
model hierarchy using the following methods:

```
local baseplate = workspace.Baseplate
local baseplate = workspace["Baseplate"]
local baseplate = workspace:FindFirstChild("BasePlate")
```

In order to make an object accessible using the dot operator, an object's
Name must follow a certain syntax. The objects name must start with an
underscore or letter. The rest of the name can only contain letters,
numbers, or underscores (no other special characters). If an objects name
does not follow this syntax it will not be accessible using the dot
operator and Lua will not interpret its name as an identifier.

If more than one object with the same name are siblings then any attempt
to index an object by that name will return the only one of the objects
found similar to `Instance/FindFirstChild`, but not always the desired
object. If a specific object needs to be accessed through code, it is
recommended to give it a unique name, or guarantee that none of its
siblings share the same name as it.

Note, a full name showing the instance's hierarchy can be obtained using
`Instance/GetFullName`.


Instance.Name

A non-unique identifier of the `Instance`.


The Parent property determines the hierarchical parent of the `Instance`.
The following terminology is commonly used when talking about how this
property is set:

- An object is a **child** (**parented to**) another object when its
  Parent is set to that object.
- The **descendants** of an `Instance` are the children of that object,
  plus the descendants of the children as well.
- The **ancestors** of an `Instance` are all the objects that the Instance
  is a descendant of.

It is from this property that many other API members get their name, such
as `Instance/GetChildren|GetChildren` and
`Instance/FindFirstChild|FindFirstChild`.

The `Instance/Remove|Remove` function sets this property to nil. Calling
`Instance/Destroy|Destroy` will set the Parent of an `Instance` and all of
its descendants to `nil`, and also **lock** the Parent property. An error
is raised when setting the Parent of a destroyed object.

This property is also used to manage whether an object exists in the game
or needs be be removed. As long as an objects parent is in the
`DataModel`, is stored in a variable, or is referenced by another objects
property, then the object remains in the game. Otherwise, the object will
automatically be removed. The top level `DataModel` object (the one
referred to as the `game` by scripts) has no parent, but always has a
reference held to it by the game engine, and exists for the duration of a
session.

Newly created objects using `Instance.new` will not have a parent, and
usually will not be visible or function until one is set. The most
elementary creation of an object has two steps: creating the object, then
setting its parent.

```
-- Create a part and parent it to the workspace
local part = Instance.new("Part")
part.Parent = workspace
-- Instance new can also take Parent as a second parameter
Instance.new("NumberValue", workspace)
```

#### Object Replication

An object created by server will not replicate to clients until it is
parented to some object that is replicated. When creating an object then
setting many properties, it's recommended to **set Parent last**. This
ensures the object replicates once, instead of replicating many property
changes.

```lua
local part = Instance.new("Part") -- Avoid using the second parameter here
part.Anchored = true
part.BrickColor = BrickColor.new("Really red")
-- Potentially many other property changes could go here here...
-- Always set parent last!
part.Parent = workspace
```

However, if you were parenting your parts to a `Model` whose parent hasn't
been set yet, then setting the parent first would not matter as the model
would not have replicated yet.


Instance.Parent

Determines the hierarchical parent of the `Instance`.


Instance.className

Instance is the base class for all classes in the Roblox class hierarchy.


Default Value: {defaultValueStart}{defaultValueEnd}

This function returns immediately if possible, but can yield the thread that called it until it can return a value.

This member doesn’t appear in the object browser and is not intended for widespread use.

This member is only accessible only through the command bar. Attempting to access this member from scripts causes an error.

This function can’t pause the Lua thread that called it.

Attempting to access this member in scripts causes an error. You might be able to access this member from Roblox Studio's property window.

This member doesn’t appear in Roblox Studio’s Object Browser.

You can’t create an instance of this class with the Instance.new constructor.

Roblox does not replicate this member across its server-client boundary.

Lua code can’t access this member. You might be able to change its value from the property window in Roblox Studio.

This object’s replication behavior is dependent on the player who owns it.

This member is accessible only through the command bar and plugins only. Attempting to access this member from scripts causes an error.

This property is read-only and is safe to read in unsynchronized threads. Attempting to write to it causes an error.

This member is read only. Attempting to write to this member causes an error.

This member is accessible only in CoreScripts.

Only Roblox CoreScripts can access this member, and it isn’t usable by Players.

You can read and write to this property safely from multiple threads.

This class is a top-level singleton. Retrieve an instance of this class with the GetService function.

Multiple threads can potentially write to this property, so it’s unsafe to read from unsynchronized threads.

This function pauses the Lua thread that called it until it returns a result. This doesn’t interrupt other scripts.

SurfaceAppearance

Summary

Properties

Events

Methods

Properties

AlphaMode

ColorMap

MetalnessMap

NormalMap

RoughnessMap

Inherited From Instance

Events

Inherited From Instance

Methods

Inherited From Instance