Instance

Instance
Not creatableThis class cannot be instantiated. Not browsableThis class is not visible in documentation for end-users.
Memory category	Instances
Subclasses
Inheritance
Object Instance

See also: Instantiation

The Instance class is the base class of instances. All other instance classes inherit, either directly or indirectly, from this class and Instance itself inherits from Object. The members that are common to all classes belong to the Instance class, which is why many of the most important and most used members belong to this class.

Prior to version 647 (October 2024), the Instance class was the highest base class, inheriting only from <<<ROOT>>>, which does not have any of its own API. Version 647 added Object, which is now the highest base class underneath <<<ROOT>>>.

Properties

Archivable: bool

Determines whether or not an Instance can be saved when the game closes/attempts to save the game. Note: this only applies to games that use AssetService:SavePlaceAsync or, historically, data persistence.

• Category: Behavior.
• Serialization: cannot load or save.
• Thread safety: read safe

Capabilities: SecurityCapabilities

This class member is missing documentation. Create or add to its subpage at Class:Instance/Capabilities.

• Category: Permissions.
• Read security: RobloxScriptSecurity.
• Write security: RobloxScriptSecurity.
• Serialization: can save and load.
• Thread safety: read safe

DataCost: int

• HiddenThis property is not shown in the object browser and properties window.
• Read-onlyThis property is capable of being read but not written.
• Not replicatedThis member is not replicated across the network boundary.
• DeprecatedThis member will be phased out and should be avoided while it is still available.

This property was used with data persistence but is no longer useful.

• Category: Data.
• Read security: LocalUserSecurity.
• Write security: LocalUserSecurity.
• Serialization: cannot load or save.
• Thread safety: read safe

Name: string

The name of the instance. Used to access it in the game hierarchy. All class's default name matches their ClassName, with the exceptions of various services, as well as every descendant of ValueBase and PostEffect.

• Category: Data.
• Serialization: can save and load.
• Thread safety: read safe

Parent: Instance

• Not replicatedThis member is not replicated across the network boundary.

Parent is a property of an instance that refers to one other instance as its parent and, in turn, becomes the child of the parent. This allows any child to be indexed from its parent. However, indexing a missing child will error, which is avoided by using the FindFirstChild method to return nil instead. The Parent property is often used in reusable scripts that depend on their parent.

The instances' parent relationships creates a tree-like data structure. If an instance does not have a parent, it is considered as a root. The structure is described by the parent-child-ancestor-descendant terminology used in the Instance API. The property avoids circular references to reinforce this structure.

The DataModel represents the root instance of the structure of a place. This structure is referred to as the hierarchy, which is displayed by the Explorer in Roblox Studio. Models also share the data structure but do not have a root. Instead, any model can have more than one instances.

See also: Parents and Children on the Roblox Creator Documentation.

• Category: Data.
• Serialization: can load only.
• Thread safety: read safe

RobloxLocked: bool

• HiddenThis property is not shown in the object browser and properties window.

See also: Security context § Additional restrictions

If this property is true, only scripts with the Plugin permission will be able to index signals and children of the object, set its properties or assign its callbacks, call yielding functions of the object, change the parent of the object's children, or create objects with the object as the parent using Instance.new(class, parent). Furthermore, scripts that do not have this permission will not be able to call non-yielding functions of the object unless it is not a descendant of CoreGui.

This property is used, among other things, for GUI objects created by CoreScripts.

• Category: Data.
• Read security: PluginSecurity.
• Write security: PluginSecurity.
• Serialization: cannot load or save.
• Thread safety: read safe

Sandboxed: bool

• Not replicatedThis member is not replicated across the network boundary.

This class member is missing documentation. Create or add to its subpage at Class:Instance/Sandboxed.

• Category: Permissions.
• Read security: RobloxScriptSecurity.
• Write security: RobloxScriptSecurity.
• Serialization: cannot load or save.
• Thread safety: read safe

SourceAssetId: int64

• HiddenThis property is not shown in the object browser and properties window.

This property marks the AssetID of the model which the Instance was inserted from. If not added using the Toolbox, it is set to -1. Can be modified or cleared by text editing a .rbxlx format game file.

• Category: Data.
• Read security: RobloxScriptSecurity.
• Write security: RobloxScriptSecurity.
• Serialization: can save and load.
• Thread safety: read safe

UniqueId: UniqueId

• Not replicatedThis member is not replicated across the network boundary.
• Not scriptableThis member cannot be accessed by Lua code.

This class member is missing documentation. Create or add to its subpage at Class:Instance/UniqueId.

• Category: Data.
• Read security: RobloxSecurity.
• Write security: RobloxSecurity.
• Serialization: can save and load.
• Thread safety: read safe

archivable: bool

• HiddenThis property is not shown in the object browser and properties window.
• Not replicatedThis member is not replicated across the network boundary.
• DeprecatedThis member will be phased out and should be avoided while it is still available.

Deprecated. Use Archivable instead.

• Category: Behavior.
• Serialization: can load only.
• Thread safety: read safe

Methods

AddTag(tag: string): null

Adds a CollectionService tag with the provided name to the Instance.

• Thread safety: unsafe

ClearAllChildren(): null

Calls Destroy on all the children of this instance.

• Thread safety: unsafe

Clone(): Instance

Returns a copy of this Object and all its children. The copy's Parent is nil.

• Thread safety: unsafe

Destroy(): null

The Destroy method moves an Instance to nil and locks it, preventing the Instance from being moved or modified. This also allows the garbage collector to collect the Instance, freeing previously-used resources.

Once an Instance is destroyed, it should not be used anymore, and all references of it should no longer exist.

• Thread safety: unsafe

FindFirstAncestor(name: string): Instance

Parameters

Name	Type	Description
name	string	The name to search for.

Returns the first ancestor with the name of name, or nil if none is found.

• Thread safety: safe

FindFirstAncestorOfClass(className: string): Instance

Parameters

Name	Type	Description
className	string	The class name to search for.

Similar to FindFirstAncestor, but searches for an instance with the ClassName property equal to className rather than the name property.

• Thread safety: safe

FindFirstAncestorWhichIsA(className: string): Instance

Parameters

Name	Type	Description
className	string	The class name to search for.

Similar to FindFirstAncestorOfClass, but searches for an instance which satisfies an IsA condition.

• Thread safety: safe

FindFirstChild(name: string, recursive: bool = false): Instance

Parameters

Name	Type	Default	Description
name	string		Name of the instance to search for.
recursive	bool	false	Whether to search all descendants instead of only direct children.

Returns the first child of this Instance that matches the first argument name. The second argument recursive is an optional boolean (defaults to false) that will force the call to traverse down thru all of this Instance's descendants until it finds an object with a name that matches the name argument. The function will return nil if no Instance is found.

• Thread safety: safe

FindFirstChildOfClass(className: string): Instance

Returns the first child of this Instance that shares the ClassName with the given class.

• Thread safety: safe

FindFirstChildWhichIsA(className: string, recursive: bool = false): Instance

Parameters

Name	Type	Default
className	string
recursive	bool	false

• Thread safety: safe

FindFirstDescendant(name: string): Instance

Parameters

Name	Type
name	string

• Thread safety: safe

GetActor(): Actor

This class member is missing documentation. Create or add to its subpage at Class:Instance/GetActor.

• Thread safety: safe

GetAttribute(attribute: string): Variant

Parameters

Name	Type
attribute	string

Returns the current value of the given attribute on an Instance.

• Thread safety: safe

GetAttributeChangedSignal(attribute: string): RBXScriptSignal

Parameters

Name	Type
attribute	string

Returns a RBXScriptSignal that is fired when the given attribute is changed using SetAttribute on an Instance.

• Thread safety: unsafe

GetAttributes(): Dictionary

• Custom Lua stateThis member uses the Lua C API directly.

This class member is missing documentation. Create or add to its subpage at Class:Instance/GetAttributes.

• Thread safety: safe

GetChildren(): Instances

Returns a table consisting of every Instance which is directly parented to this Instance.

• Thread safety: safe

GetDebugId(scopeLength: int = 4): string

• Not browsableThis member is not visible in documentation for end-users.

This API member has existing documentation in this page's Member list template.

This class member is missing documentation. Create or add to its subpage at Class:Instance/GetDebugId.

• Security: PluginSecurity.
• Thread safety: unsafe

GetDescendants(): Array

• Custom Lua stateThis member uses the Lua C API directly.

Returns an array containing every descendant of an Instance.

• Thread safety: safe

GetFullName(): string

Returns a string that shows the path from the root node (DataModel) to this Instance. This string does not include the DataModel root node.

• Thread safety: safe

GetStyled(name: string): Variant

This class member is missing documentation. Create or add to its subpage at Class:Instance/GetStyled.

• Thread safety: unsafe

GetTags(): Array

Returns an array of all CollectionService tags that the Instance has.

• Thread safety: safe

HasTag(tag: string): bool

Returns whether or not the Instance has a CollectionService tag with the provided name.

• Thread safety: safe

IsAncestorOf(descendant: Instance): bool

Returns true if the Instance is an ancestor of the provided descendant. See also IsDescendantOf.

• Thread safety: safe

IsDescendantOf(ancestor: Instance): bool

Parameters

Name	Type	Description
ancestor	Instance	The ancestor to check for.

Returns true if the Instance is a descendant of the provided ancestor. See also IsAncestorOf.

• Thread safety: safe

IsPropertyModified(name: string): bool

Parameters

Name	Type
name	string

Returns whether or not the provided property name differs from its default value.

• Thread safety: unsafe

Remove(): null

• DeprecatedThis member will be phased out and should be avoided while it is still available.

Using this method is not recommended. Instead, consider using Destroy to fully destroy an object, or set the Parent to nil.

Parents the Instance and all of its descendants to nil. Objects removed with this function can be retrieved later if a reference to the object is retained.

• Thread safety: unsafe

RemoveTag(tag: string): null

Removes a CollectionService tag with the provided name from the Instance.

• Thread safety: unsafe

ResetPropertyToDefault(name: string): null

Parameters

Name	Type
name	string

Resets the given property value to its default value.

• Thread safety: unsafe

SetAttribute(attribute: string, value: Variant): null

Parameters

Name	Type
attribute	string
value	Variant

Sets the value of the given attribute to the given value on an Instance.

• Thread safety: unsafe

WaitForChild(childName: string, timeOut: double): Instance

• Custom Lua stateThis member uses the Lua C API directly.
• Can yieldThis function can yield the script it is used in.

Parameters

Name	Type
childName	string
timeOut	double

• Thread safety: unsafe

children(): Instances

• DeprecatedThis member will be phased out and should be avoided while it is still available.

Use GetChildren instead.

• Thread safety: unsafe

clone(): Instance

• DeprecatedThis member will be phased out and should be avoided while it is still available.

Use Clone instead.

• Thread safety: unsafe

destroy(): null

• DeprecatedThis member will be phased out and should be avoided while it is still available.

Use Destroy instead.

• Thread safety: unsafe

findFirstChild(name: string, recursive: bool = false): Instance

• DeprecatedThis member will be phased out and should be avoided while it is still available.

Parameters

Name	Type	Default
name	string
recursive	bool	false

Use FindFirstChild instead.

• Thread safety: unsafe

getChildren(): Instances

• DeprecatedThis member will be phased out and should be avoided while it is still available.

Use GetChildren instead.

• Thread safety: unsafe

isDescendantOf(ancestor: Instance): bool

• DeprecatedThis member will be phased out and should be avoided while it is still available.

Parameters

Name	Type
ancestor	Instance

Use IsDescendantOf instead.

• Thread safety: unsafe

remove(): null

• DeprecatedThis member will be phased out and should be avoided while it is still available.

Use Destroy instead.

• Thread safety: unsafe

Events

AncestryChanged(child: Instance, parent: Instance)

Parameters

Name	Type	Description
child	Instance	The child whom's ancestry is changing.
parent	Instance	The new parent of the child.

Fired when any of this object's ancestors change. First argument 'child' is the object whose parent changed. Second argument 'parent' is the first argument's new parent.

• Thread safety: unsafe

AttributeChanged(attribute: string)

Parameters

Name	Type
attribute	string

• Thread safety: unsafe

ChildAdded(child: Instance)

Parameters

Name	Type
child	Instance

Fired when another Instance is parented into this Instance as an immediate child.

For an event that fires for all new descendants, see DescendantAdded.

• Thread safety: unsafe

ChildRemoved(child: Instance)

Parameters

Name	Type	Description
child	Instance	The object that was removed.

Fired after a child was removed from this Instance.

• Thread safety: unsafe

DescendantAdded(descendant: Instance)

Parameters

Name	Type
descendant	Instance

Fired when another Instance becomes a descendant of this Instance.

For an event that fires for only new immediate children, see ChildAdded.

• Thread safety: unsafe

DescendantRemoving(descendant: Instance)

Parameters

Name	Type
descendant	Instance

• Thread safety: unsafe

Destroying()

Fired immediately before an Instance or one of its ancestors is destroyed using Destroy. If a child Instance is added to the Instance being destroyed, that child will not be destroyed. Child Instances of an Instance being destroyed cannot be salvaged after this event is fired, but descendants of those children can be.

In Studio, when you delete an instance, whether you do it manually through the Explorer or via a plugin, the instance is not completely destroyed. Instead, its parent is set to nil, and you can keep track of this change using the Instance.AncestryChanged property.

• Thread safety: unsafe

childAdded(child: Instance)

• DeprecatedThis member will be phased out and should be avoided while it is still available.

Parameters

Name	Type
child	Instance

Use ChildAdded instead.

• Thread safety: unsafe

Removed members

Methods

• GetPropertyChangedSignal
• isA
• IsA

Properties

• className
• ClassName
• PropertyStatusStudio

Events

• Changed

External links

• Instance in the Roblox Creator Documentation
• Instance in the Roblox API Reference