Instance

Instance : InstanceBase

Overview

Instance is the top-level base class for all objects that can belong to the DataModel tree, such as Workspace, ReplicatedStorage, and ServerStorage

Using the Instance.new() constructor, specified objects like Part or ParticleEmitter can be dynamically created at runtime. However, a top-level Instance object cannot be created directly.

Properties

Parent

Instance

The Parent property is a key property that determines the hierarchical position of the current instance.

This property serves as the basis for structural navigation methods such as GetChildren() and FindFirstChild().

If Destroy() is called on a parent object, the Parent property of the parent and all of its descendants is set to nil, after which the Parent property cannot be changed.

Objects newly created with Clone() or Instance.new() have their Parent set to nil by default. In this state, they remain invisible or non-functional until a Parent is assigned.

Objects created on the server are not sent to the client until they are parented to a replicable hierarchy. When creating objects and setting multiple properties, it's recommended to set the Parent property last.

Code Samples

local Part = Instance.new("Part")
local Workspace = game:GetService("Workspace")

Part.Parent = Workspace
print(Part.Parent)

Archivable

bool

Currently not supported.

Code Samples

ClassName

string

This read-only property indicates the class of the current instance as a string.

This is useful for directly checking the object's class. However, for a type check that also considers its inheritance hierarchy, it is recommended to use the IsA() method.

Code Samples

local Part = script.Parent

print(Part.ClassName)

Name

string

This property names the instance.

This name is used to distinguish and organize instances within the hierarchy and is also used when referencing the object using scripts.

To access an object using dot (.) notation in scripts, the name must start with a letter or underscore (_), followed by letters, numbers, or underscores only. Otherwise, dot notation cannot be used.

If multiple objects share the same name in the same hierarchy, accessing by name returns only one object, which may not be the one you want. Therefore, assigning unique names and avoiding duplicates is a safe practice if you want to reference a specific object precisely.

Code Samples

local Part = script.Parent

Part.Name = "NewPart"

Mobility

Enum.MobilityMode

The Mobility option categorizes instances placed in the world as either Static or Movable to support performance optimization.

The Mobility option cannot be changed at runtime.

• Static

  • Ideal for objects that do not change in position, rotation, or scale

  • Processes with minimal computation by utilizing precomputed data (e.g., lightmaps).

  • Cannot be moved, rotated, or scaled at runtime.

• Movable

  • Ideal for objects that need translation, rotation, animation, or player interaction

  • Computes state changes every frame to provide dynamic presentation and interactivity

  • Recommended for core gameplay elements or objects where expression is important, as it comes with performance costs

Code Samples

Methods

Clone

Duplicates the specified instance and all of its descendants, returning the top-level duplicated instance.

The Parent property of the returned instance is set to nil.

Parameters

Return

Instance	The duplicated instance.

Code Samples

local Workspace = game:GetService("Workspace")
local Part = Workspace.Part

local NewPart = Part:Clone()
NewPart.Position = Part.Position + Vector3.new(300, 0, 0)
NewPart.Parent = Workspace

Destroy

Completely removes the specified instance and all of its descendants by calling Destroy().

Instances with Destroy() executed cannot be reused because their Parent property is locked, so to temporarily remove an object without fully deleting it, set its Parent to nil instead.

This method is the key to cleaning up unnecessary objects, as it disconnects all events and removes unused objects to effectively prevent memory leaks and long-term performance degradation.

After calling Destroy(), any variables referencing the object or its descendants must be reset to nil, which is recommended to prevent accessing already deleted objects in code.

Parameters

Return

void

Code Samples

local Workspace = game:GetService("Workspace")
local Part = Workspace.Part

Part:Destroy()

FindFirstAncestor

Returns the first ancestor instance that matches the specified name, found by searching upward along the parent hierarchy.

The search starts from the current instance's Parent and continues up to the DataModel, returning nil if no matching object is found.

Parameters

string InName	The name of the ancestor instance to search for.

Return

Instance	The instance searched for.

Code Samples

local Part = script.Parent

local Ancestor = Part:FindFirstAncestor("ParentPart")
print(Ancestor)

FindFirstAncestorOfClass

Returns the first ancestor instance that matches the specified class name, found by searching upward along the parent hierarchy.

The search starts from the current instance's Parent and continues up to the DataModel, returning nil if no matching object is found.

This is mainly used to find a Model containing a BasePart.

Parameters

string InClassName	The class name of the ancestor instance to search for.

Return

Instance	The instance searched for.

Code Samples

local Part = script.Parent

local AncestorOfClass = Part:FindFirstAncestorOfClass("Model")
print(AncestorOfClass)

FindFirstAncestorWhichIsA

CReturns the first ancestor instance where Object:IsA() returns true for the specified class name, found by searching upward along the parent hierarchy.

Unlike Instance:FindFirstAncestorOfClass(), which matches the exact class name, this method considers inheritance. Therefore, objects such as MeshPart or Part, which inherit from BasePart, are all included in the search.

The search starts from the current instance's Parent and continues up to the DataModel, returning nil if no matching object is found.

Parameters

string InClassName	The class name of the ancestor instance to search for.

Return

Instance	The instance searched for.

Code Samples

local Part = script.Parent

local AncestorWhichIsA = Part:FindFirstAncestorWhichIsA("BasePart")
print(AncestorWhichIsA)

FindFirstChild

Returns the first child instance with the specified name, or nil if the child matching that name doesn't exist.

Setting the recursive value to true allows searching not only direct children but also all descendants.

Referencing a child via dot (.) notation causes an error if the object doesn't exist, but you can safely check for the presence without errors by using FindFirstChild(). By leveraging this, you can first check for the presence of a specific Part with FindFirstChild() before searching, and then execute the necessary code through an if statement, which is a safer practice.

However, as FindFirstChild() is slower than dot (.) notation, it is recommended to store the result in a variable rather than calling it directly in performance-critical loops or functions associated with the RunService event.

Parameters

string InName	The name of the child instance to search for.
bool recursive	This option specifies whether to search all descendants (default: false).

Return

Instance	The instance searched for.

Code Samples

local Workspace = game:GetService("Workspace")

local Part = Workspace:FindFirstChild("Part")
print(Part)

FindFirstChildOfClass

Returns the first instance whose class name exactly matches the specified value among the children of the specified instance, or nil if the matching child doesn't exist.

Parameters

string InClassName	The class name of the child instance to search for.
bool recursive	This option specifies whether to search all descendants (default: false).

Return

Instance	The instance searched for.

Code Samples

local Workspace = game:GetService("Workspace")

local Part = Workspace:FindFirstChildOfClass("Part")
print(Part)

GetAttribute

Returns the value that matches the specified property name in the instance, or nil if the property doesn't exist.

You can use SetAttribute() to manually set a property's name and value, or use GetAttributes() to retrieve all properties and values of an instance as a dictionary.

Parameters

string attribute	The name of the attribute to check.

Return

Value	The value assigned to the attribute.

Code Samples

local AttributeName = "Number"
local SetValue = 1
Part:SetAttribute(AttributeName, SetValue)

local GetValue = Part:GetAttribute(AttributeName)
print(GetValue)

GetAttributes

Returns all properties set on the instance as a dictionary of key-value pairs.

This method allows you to check all properties and values of an instance at once.

Parameters

Return

Dictionary	This dictionary consists of attribute names and values.

Code Samples

Part:SetAttribute("Number", 1)
Part:SetAttribute("Text", "Hello")

local AttributeList = Part:GetAttributes()
for attributeName, attributeValue in pairs(AttributeList) do
    print(attributeName, " : ", attributeValue)
end

GetAttributeChangedSignal

Unlike the AttributeChanged event, which detects any changes to properties, this method returns an event that triggers only when the specified property changes.

Parameters

string InAttributeName	The name of the attribute whose changes to detect.

Return

ScriptSignal	The triggered event.

Code Samples

local SomeValue = "SomeValue"

local function OnChangedSomeValue()
    print(Part:GetAttribute(SomeValue))
end
Part:GetAttributeChangedSignal(SomeValue):Connect(OnChangedSomeValue)

Part:SetAttribute(SomeValue, 150)

GetChildren

Returns an array of all direct children parented to the specified object.

The returned array has numerical indices and can be iterated with general for loop or numeric for loop. The order of children in the array is determined by the order in which their Parent property was set to this object.

To retrieve all descendants, use the GetDescendants() method.

Parameters

Return

Array	An array of child instances.

Code Samples

local Workspace = game:GetService("Workspace")

local Children = Workspace:GetChildren() 
for _, child in ipairs(Children) do
    print(child.Name)
end

GetChildrenNum

Returns the number of direct children parented to the specified object.

Parameters

Return

number	The number of child instances.

Code Samples

local Object = script.Parent

print(Object:GetChildrenNum())

GetDescendants

Returns an array of all descendants of the specified object.

Unlike GetChildren(), which retrieves only direct children, this method searches and includes all descendants.

Parameters

Return

array	This array includes all descendants of child instances.

Code Samples

local Workspace = game:GetService("Workspace")

local Descendants = Workspace:GetDescendants()
for _, descendant in ipairs(Descendants) do
    print(descendant.Name)
end

IsDescendantOf

Returns true if the current instance is included in the descendant hierarchy of the specified ancestor object.

Parameters

Instance InAncestor	The ancestor instance to check.

Return

bool	Specifies whether it is included in the ancestor's hierarchy.

Code Samples

local Workspace = script.Parent.Parent
local Part = script.Parent
local IsDescendantOf = script:IsDescendantOf(Workspace)

print(IsDescendantOf)

IsA

Returns true if the current instance is of the specified class or inherits from the class.

This method is particularly useful for determining whether an object belongs to a specific part type. For example, to check if an object inherits from BasePart, such as Part or MeshPart, you can first get all children using GetChildren() and then check using IsA().

It is ideal for type checking that also considers inheritance hierarchy, and it is recommended to compare the ClassName property directly to ignore inheritance hierarchy.

Also, to check Luau's basic data types, such as number or string, the type() or typeof() function should be used.

Parameters

string InClassName	The name of the class to search for.

Return

bool	Specifies whether it is included.

Code Samples

local Part = script.Parent

print("Instance : ", Part:IsA("Instance")) -- true
print("Part : ", Part:IsA("BasePart"))     -- true
print("BasePart : ", Part:IsA("BasePart")) -- true
print("MeshPart : ", Part:IsA("MeshPart")) -- false

if Part:IsA("Part") then
    print("Part")
else
    
end

SetAttribute

Sets the value of the property with the specified name for the current instance.

A Property name can only contain letters, numbers, and underscores (_), and spaces or special characters are not allowed. If the value is set to nil, the corresponding property is deleted.

It supports not only Luau’s basic data types, such as string, number, and boolean, but also a range of other types, including Instance and CFrame. However, setting a property with an unsupported type will cause an error.

Values set on the server are automatically replicated to the client, enabling script-to-script communication without using RemoteEvent.

Unlike value objects, attributes do not create or destroy separate instances. As a result, they are processed much faster than using Instance.new() or Destroy(), which makes attributes particularly advantageous in scenarios that involve high-frequency operations, control of many objects, or repeated synchronization—such as dynamically adding or removing values across many objects.

To retrieve a property with a specific name, use GetAttribute(). To retrieve all properties, use GetAttributes().

Parameters

string attribute	The name of the attribute to set.
Value value	The value to assign.

Return

void

Code Samples

local AttributeName = "Number"
local SetValue = 1
Part:SetAttribute(AttributeName, SetValue)

WaitForChild

Returns the child instance with the specified name. If it does not exist, the execution is suspended until the object is created.

After the timeOut value is specified, it waits for the specified time (in seconds) and returns nil if the child still does not exist. Waiting for 5 seconds or more without timeOut triggers a warning about potential infinite waiting.

Since the timing and order of object transmission from the server to the client are not guaranteed, this is required when handling client-side objects in LocalScript to prevent reference failures due to loading sequence.

Parameters

string InChildName	The name of the child instance to search for.
number InTimeOut	The maximum wait time (in seconds). If left blank, it waits indefinitely until the object exists.

Return

Instance	The instance searched for.

Code Samples

local Workspace = game:GetService("Workspace")

local Part = Workspace:WaitForChild("Part")
print(Part)

AddTag

Adds a tag with the specified name to the current instance.

Parameters

FName tag	The name of the tag to assign.

Return

void

Code Samples

Part:AddTag("SomeTag")

RemoveTag

Removes the tag with the specified name from the current instance, and operates without errors even if the tag does not exist.

Parameters

FName tag	The name of the tag to remove.

Return

void

Code Samples

Part:RemoveTag("SomeTag")

HasTag

Returns true if the tag with the specified name is found in the current instance.

Parameters

FName tag	The name of the tag to check.

Return

bool	Specifies whether the tag exists.

Code Samples

if Part:HasTag("SomeTag") then
    
else
    
end

GetTags

Returns the list of tags applied to the current instance as a string array.

Unlike HasTag(), which checks for a specific tag, it is ideal for retrieving all tags applied to an instance.

Parameters

Return

Array	An array of strings.

Code Samples

Part:AddTag("SomeTag")

local Tags = Part:GetTags()
for i = 1, #Tags do
    print(Tags[i])
end

Events

AncestryChanged

This event is triggered when the Parent property of the current instance or its parent instance changes.

This is not triggered when the Parent property of child instance changes.

Parameters

Instance child	The instance whose Parent property changed.
Instance parent	The changed Parent value.

Code Samples

local Part = Instance.new("Part")

local function OnAncestryChanged(child, parent)
    print(child, "Ancestry Changed:", parent)
end
Part.AncestryChanged:Connect(OnAncestryChanged)

wait(2)
Part.Parent = game.Workspace

AttributeChanged

This event is triggered whenever a property of the current instance changes, including when a property is set to nil.

Unlike GetAttributeChangedSignal(), which detects changes to a specific property only, this detects changes to all properties, and the name of the changed property is passed to the connected function.

Parameters

string attribute	The name of the changed attribute.

Code Samples

local Part = script.Parent

local function OnAttributeChanged(attribute)
    print(attribute, "Changed:", Part:GetAttribute(attribute))
end
Part.AttributeChanged:Connect(OnAttributeChanged)

wait(2)
Part:SetAttribute("Color", "Blue")

Changed

This event is triggered whenever a property of the current instance changes.

A changed value can be directly viewed using the object[property] format.

This is mainly used to detect property changes caused by scripts, and is not triggered when properties such as CFrame or Position change by the physics engine.

Also, since properties with very short change cycles may miss some changes or fail to trigger the event, for critical properties in game logic, it is recommended to verify behavior through direct querying.

Parameters

string property	The name of the changed property.

Code Samples

local Part = script.Parent

local function OnChanged(property)
    print(property, "Changed:", Part[property])
end
Part.Changed:Connect(OnChanged)

wait(2)
Part.Name = "MyPart"

ChildAdded

This event is triggered when a child instance is added to the current instance.

This event only detects direct children. To detect additions across the entire descendant hierarchy, the DescendantAdded event should be used.

Also, when the client detects objects created on the server, WaitForChild() should be used to handling the descendants of the objects, as there is no guarantee that the objects and their descendants are transmitted simultaneously during server-client synchronization.

Parameters

Instance child	The name of the added child instance.

Code Samples

local Part = script.Parent

local function OnChildAdded(child)
    print("Child Added:", child)
end
Part.ChildAdded:Connect(OnChildAdded)

wait(2)
local ChildPart = Instance.new("Part")
ChildPart.Name = "ChildPart"
ChildPart.Parent = Part

ChildRemoved

This event is triggered when a child instance of the current instance is removed.

This is also triggered when the child's Parent property changes to another instance or the child is deleted by calling the Destroy() method.

This event only detects direct children. To detect removals across the entire descendant hierarchy, the DescendantRemoving event should be used.

Parameters

Instance child	The name of the removed child instance.

Code Samples

DescendantAdded

This event is triggered when a descendant instance is added to the current instance.

Since this event is triggered for all descendant objects, placing an object as a child of the instance triggers the event not only for that object but also for all of its descendants individually.

To detect only direct children, use the ChildAdded event.

Parameters

Instance descendant	The name of the added descendant instance.

Code Samples

local Part = script.Parent

local function OnDescendantAdded(descendant)
    print("Descendant Added:", descendant)
end
Part.DescendantAdded:Connect(OnDescendantAdded)

wait(2)
local ChildPart = Instance.new("Part")
ChildPart.Name = "ChildPart"
ChildPart.Parent = Part

DescendantRemoving

This event is triggered just before a descendant instance of the current instance is removed.

This is triggered when the descendant's Parent property changes to another instance or when the Destroy() method is called.

Since this event is triggered individually for all levels of the descendant hierarchy, removing an object triggers it not only for that object but also for all of its descendants sequentially. If the removed object is a direct child, this event is triggered before the ChildRemoved event.

At this point, the descendant's parent property has not yet changed, and it is not possible to change the Parent to another instance.

To detect only direct children, use the ChildRemoved event.

Parameters

Instance descendant	The name of the removed descendant instance.

Code Samples

Destroying

This event is triggered when the current instance is deleted by the Destroy() method.

As long as the callback function connected to this event references the instance, the instance is not released from memory. Therefore, you can safely access the object.

Parameters

Code Samples

local Part = script.Parent

local function OnDestroying()
    print(Part, "is being destroyed.")
end
Part.Destroying:Connect(OnDestroying)

wait(2)
Part:Destroy()