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

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

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.

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 Instance:Destroy(), use the Instance.Destroying event instead.

This property determines whether the instance should be included when the experience is published or saved, or when Clone() is called on one of the instance's ancestors. Calling Clone() directly on an instance will return nil if that instance is not Archivable.

Copying an object in Studio using the Duplicate or Copy/Paste options will ignore its own 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

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:

1
2
3
4
5
6
7

local part = workspace.Part

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

part.AttributeChanged:Connect(attributeChanged)

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

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.

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

See also Instance.ChildAdded.

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 object:GetDescendants() do
	if instance:IsA("BasePart") then
		instance:Destroy()
	end
end

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

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

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

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.

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

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

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

Warning

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

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

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

See also DescendantAdded.

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.

1
2
3
4
5
6
7

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 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().

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.

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

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

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

When deleting an Instance in Studio, such as manually deleting through the Explorer or through a plugin, the Instance isn't destroyed. Instead, the parent is set to nil which you can track with Instance.AncestryChanged.

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().

Returns the first ancestor of the Instance whose Object.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 Object.ClassName property rather than Instance.Name. Instance:FindFirstAncestorWhichIsA() also exists, using the Object:IsA() method instead to respect class inheritance.

Returns the first ancestor of the Instance for whom Object: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 Object:IsA() which respects class inheritance. For example:

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

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

local part = object:FindFirstAncestorWhichIsA("BasePart")

See also, Instance:FindFirstAncestor().

Returns the first child of the Instance with the given name,

or nil if no such child exists. If the optional recursive argument is true, this function searches all descendants rather than only the immediate children of the Instance.

Checking the Existence of an Object

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

1
2

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

1
2
3
4

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

Finding a Child Whose Name Matches a Property

Sometimes the Name of an object is the same as that of a property of its 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 Color3, not the Folder.

1
2
3
4
5
6

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.

Performance Note

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

Returns the first child of the Instance whose 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.

Returns the first child of the Instance for whom Object: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 Object:IsA() which respects class inheritance. For example:

1
2
3

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.

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

This method is disabled and cannot be used. To find the first descendant of an instance, consider using the recursive parameter on Instance:FindFirstChild() instead.

If the Instance is an Actor, the Actor itself is returned. Otherwise, its closest ancestor Actor is returned. If no ancestor is an Actor, the result is nil.

This method returns the value which has been assigned to the given attribute name. If no attribute has been assigned, nil is returned.

For example, the following code snippet sets and then gets the value of the instance's InitialPosition attribute:

1
2
3
4
5

local part = workspace.Part
part:SetAttribute("InitialPosition", part.Position)

local initialPosition = instance:GetAttribute("InitialPosition")
print(initialPosition)

See Also

• Instance:SetAttribute() which sets the attribute with the given name to the given value.
• Instance:GetAttributes() which returns a dictionary of key‑value pairs for each of the instance's attributes.

This function returns an event that behaves exactly like the Changed event, except that it only fires when the specific given attribute changes; effectively it is similar to GetPropertyChangedSignal() but for attributes.

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.

The following code example returns a signal that fires the function attributeChanged() when the part's InitialPosition attribute changes:

1
2
3
4
5
6
7
8

local part = workspace.Part
part:SetAttribute("InitialPosition", part.Position)

local function attributeChanged()
	print("Attribute changed")
end

part:GetAttributeChangedSignal("InitialPosition"):Connect(attributeChanged)

See also Instance.AttributeChanged which fires whenever any attribute is changed on the instance.

This method returns a dictionary of key‑value pairs for each attribute where the key is the attribute's name and the value is a non‑nil value.

For example, the following code snippet outputs an instance's attributes and values:

1
2
3
4
5
6
7

local part = workspace.Part
part:SetAttribute("InitialPosition", part.Position)
part:SetAttribute("CanUse", true)

for name, value in part:GetAttributes() do
	print(name .. " = " .. value)
end

See also Instance:GetAttribute() which returns the value that has been assigned to the given attribute name.

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

1
2
3
4
5
6

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

1
2
3
4
5

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

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

See also the GetDescendants function.

This object method returns an array that contains all of the descendants of that object. Unlike Instance:GetChildren(), which only returns the immediate children of an object, this method finds every child of the object, every child of those children, and so on.

Returns a string describing the instance's ancestry. The string is a concatenation of the 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 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.

This method returns an array of the tags applied to the given instance, as strings. You can add tags either in Studio in the Properties window or at runtime with AddTag().

This method is useful when you want to do something with multiple tags on an instance at once. However, it is inefficient to use this method to check for the existence of a single tag; instead, use HasTag() to check for a specific tag.

This method returns true if the provided tag has been added to the object. You can add tags either in Studio in the Properties window or at runtime with AddTag().

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().

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().

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 instance cannot exceed 100 characters in size.

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().

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 GetChildren and FindFirstChild.

The Remove function sets this property to nil. Calling 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 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, though it is not recommended
Instance.new("NumberValue", workspace)

When a change is made to certain properties while an instance is parented in the DataModel, the engine may need to perform extra work internally (for things like replication, rendering, and GUI layout). Whenever possible, change an instance's properties before you set its Parent, rather than after, to avoid performing that work redundantly.

Object Replication

An object created by the 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.

1
2
3
4
5
6

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 parenting each part to that model is okay as the model would not have replicated yet.

This method removes a tag from an instance. It will not throw an error if the object does not have the tag. Successfully removing a tag will fire a signal created by CollectionService:GetInstanceRemovedSignal() with the given tag.

Note that when tagging an instance, it's common that some resources are used to give the tag its functionality, for example event connections or tables. To prevent memory leaks, it's a good idea to clean these up (disconnect, set to nil, etc.) when no longer needed for a tag.

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

For example, the following code snippet sets the instance's InitialPosition attribute to Vector3.new(0, 10, 0):

1
2

local part = workspace.Part
part:SetAttribute("InitialPosition", Vector3.new(0, 10, 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() which returns the value that has been assigned to the given attribute name.
• Instance:GetAttributes() which returns a dictionary of key‑value pairs for each of the instance's attributes.