Roblox API Reference

Instance On DevHub

Summary

The root class of all classes in the API.

This class is not creatable. An object of this class cannot be created with Instance.new.
This item is not browsable. It is not visible in Studio's object browser.

Tags: [NotCreatable, NotBrowsable]

Inherited by (318)

Member index (51)

Type Member History
bool Archivable
string ClassName
int DataCost 311 311 390 469
string Name
Instance Parent 329
bool RobloxLocked 83 83 84 84 85 85 151 151 469
int64 SourceAssetId 448
bool archivable 292
string className 49
void ClearAllChildren () 49
Instance Clone ()
void Destroy () 49
Instance FindFirstAncestor (string name) 298 302 301 302
Instance FindFirstAncestorOfClass (string className) 298
Instance FindFirstAncestorWhichIsA (string className) 298
Instance FindFirstChild (string name, bool recursive = false)
Instance FindFirstChildOfClass (string className) 259
Instance FindFirstChildWhichIsA (string className, bool recursive = false) 298
Instance FindFirstDescendant (string name) 477
Actor GetActor () 455 483
Variant GetAttribute (string attribute) 408
RBXScriptSignal GetAttributeChangedSignal (string attribute) 408
Dictionary GetAttributes () 408
Objects GetChildren ()
string GetDebugId (int scopeLength = 4) 152
Array GetDescendants () 303 349
string GetFullName ()
RBXScriptSignal GetPropertyChangedSignal (string property) 283 282 285 284 285
bool IsA (string className) 384
bool IsAncestorOf (Instance descendant)
bool IsDescendantOf (Instance ancestor)
void Remove () 49
void SetAttribute (string attribute, Variant value) 408
Instance WaitForChild (string childName, double timeOut) 90 251 251 250 250 251 251 349
Objects children ()
Instance clone ()
void destroy () 52
Instance findFirstChild (string name, bool recursive = false)
Objects getChildren () 48
bool isA (string className) 384
bool isDescendantOf (Instance ancestor) 50 49 50
void remove ()
AncestryChanged (Instance child, Instance parent)
AttributeChanged (string attribute) 408
Changed (string property)
ChildAdded (Instance child)
ChildRemoved (Instance child)
DescendantAdded (Instance descendant)
DescendantRemoving (Instance descendant)
Destroying () 500
childAdded (Instance child) 50 49 50

Details

Hierarchy

Objects are arranged in a tree structure. An object can have zero or more child objects, which are below it in the tree. Conversely, an object can have at most one parent object, which is above it in the tree. The root of a tree can have children, but has no parent. Objects that share the same parent are referred to as siblings.

An ancestor is any object that is reachable by repeatedly moving from child to parent. That is, an ancestor is the parent of an object, or the parent's parent, and so on, all the way to the root of the tree. A descendant is any object that is reachable by repeatedly moving from parent to child. That is, a descendant is a child of an object, or a child of the child, and so on.

References

Whenever Lua accesses an object for the first time, a userdata is created. This userdata acts as a "proxy" or "bridge" that enables the object to be accessed in Lua. The userdata will be reused while it exists, and recreated when it doesn't, which is a process that is meant to be completely opaque to Lua. For all intents and purposes, the userdata is the object. As such, almost no distinction will be made between the two in this reference.

In regards to garbage collection, Lua's garbage collector has no knowledge of the object, and does not affect the object in any way. The memory allocated to the object is managed by a separate, internal system. On the other hand, the userdata is known by the garbage collector, and may therefore be collected when it has no more strong references in Lua, just as any other Lua value.

It must be noted that an object makes no strong references to its userdata. A consequence of this is that, when there are only weak references to the userdata, the userdata can be garbage collected while the object is still accessible. For example, if the userdata's only reference is in a weak table, and the object is in the game tree, then userdata will be collected, removing it from the weak table. Despite this, the object still exists in the game tree, and can be accessed as usual.

Replication

For each connected peer, a particular object will usually have a copy of itself that exists on the peer. When an object is "replicated", each of these copies are being synchronized across the network. Several aspects of an object are replicated:

  • The presence or absence of the object.
  • The properties of the object.
  • The children of the object.

From the perspective of the hierarchy, replication behaves as though the object is being added, removed, or modified. Events will fire in response to such replicated changes.

When an object exists on the server, changes to the object on the server are replicated to each client.

When an object exists on the server, but its class has the NotReplicated tag, then no aspects of the object are replicated. This status is "inherited" by the object's parent. That is, if an object is tagged as NotReplicated, then its descendants will also not replicate.

Note that, while two non-replicating objects (one on each peer) may be similar, they are not considered the same object. For example, ServerStorage will exist on both the server and a client. This is because of how singleton services are initialized, and not because ServerStorage has somehow been replicated partially.

When an object exists on the server, and the object's class has the PlayerReplicated tag, then changes to the object are replicated only to a specific client.

When an object exists only on the client, changes are generally never replicated. In previous versions, changes on a client were allowed to replicate to the server (and then to each other client). Because of security concerns, it later became possible to disable this behavior with the FilteringEnabled property. Eventually, this toggle was removed entirely, and the behavior became generally disallowed.

Physics replication is a separate system with its own behaviors.

Special exceptions may exist. For example, ReplicatedFirst replicates from the server to a client exactly once, per client, after the client connects. Another example is player characters: certain aspects of a character can replicate from a client to the server (and then to each other client).

Constructors

Instance.new(className: string, parent: Instance?): Instance

Returns a new instance of a class. className is the name of the class. parent is an optional object to which the Parent property will be set before the object is returned. If unspecified, then the object's Parent will be nil.

Per class, each property of the instance is initialized with a default value. The default value of an inherited property depends on the current class (for example, the Name property of a Seat initializes as "Seat" rather than "Part" or "Instance"). Default values are considered a part of a class's API, and so will not change arbitrarily over time.

If an instance of the given class cannot be created, then the following error is thrown:

Unable to create an Instance of type "CLASS"

Where CLASS is the name of the given class. Existing classes that cannot be created include abstract classes, services, and classes tagged as NotCreatable.

Examples

Demonstration of an object's weak reference behavior. An object's userdata can be garbage collected while the object is in the game tree.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
-- Table with weak value references.
local weakTable = setmetatable({}, {__mode='v'})

-- Create an object, then add it to the game tree and the weak table.
local object = Instance.new("BoolValue")
object.Parent = workspace
weakTable[1] = object
object = nil -- Remove strong reference to the object.

print("Reference:", weakTable[1])
--> Reference: Value (userdata still exists)

-- Wait until the userdata is collected.
while #weakTable > 0 do
	wait()
end

print("Reference:", weakTable[1])
--> Reference: nil (userdata was collected)

print("Object:", workspace.Value)
--> Object: Value (object still exists)

History

Members

AncestryChanged On DevHub

Fired after the ancestry of the object changes.

Name Type Default
child Instance none
parent Instance none

AncestryChanged fires after the Parent of the object or any ancestor has changed. child is the object whose Parent has changed, and is never nil. parent is the new value of the Parent, which may be nil.

If changes only to the Parent of the object need to be detected, then GetPropertyChangedSignal should be used instead.

AncestryChanged is affected by parent locking. Modifying the Parent of child before it has resolved should be avoided.

Archivable On DevHub

Determines whether the object can be serialized.

When Archivable is false, the object will not be included when it is a part of a place or model that is saved to a file or published to Roblox. The object is also excluded from being copied with Clone.

Examples

Avoid cloning descendants by temporarily setting Archivable.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
function CopyObject(object)
	local children = object:GetChildren()
	local currentState = {}
	for i, child in pairs(children) do
		currentState[i] = child.Archivable
		child.Archivable = false
	end
	local copy = object:Clone()
	for i, child in pairs(children) do
		child.Archivable = currentState[i]
	end
	return copy
end

local part = Instance.new("Part")
part.Name = "Original"
part.Color = BrickColor.Red().Color
local smoke = Instance.new("Smoke", part)
smoke.Archivable = false
Instance.new("Fire", part)
part.Parent = workspace

local copy = CopyObject(part)
copy.Name = "Copy"
copy.Position = Vector3.new(8, 0, 0)
copy.Parent = workspace

AttributeChanged On DevHub

Name Type Default
attribute string none

History

Changed On DevHub

Fired after a property of the object changes.

Name Type Default
property string none

property is the name of the property that changed. This can be used to index the object to get the property's new value.

Changed is fired by changes to all properties of the object. If only one or a few properties need to be monitored, GetPropertyChangedSignal should be used instead.

For performance reasons, changes to a property made by the physics engine will not cause Changed to fire. For example, Changed will fire when the Position of a Part is modified by a script, but will not fire while the part is falling.

Bugs

Certain classes have hidden properties that cannot be indexed, but can still cause Changed to fire. When indexing such an object with property unguarded, using pcall is recommended.

Examples

Copy changes in appearance from one part to another.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
local appearance = {
	Color        = true,
	Material     = true,
	Reflectance  = true,
	Transparency = true,
}
local original = Instance.new("Part", workspace)
local copy = Instance.new("Part", workspace)
original.Changed:Connect(function(property)
	if not appearance[property] then
		return
	end
	copy[property] = original[property]
end)

original.Position = Vector3.new(8, 0, 0)
original.Color = BrickColor.Blue().Color

Safely copy all changes from one part to another.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
local original = Instance.new("Part", workspace)
local copy = Instance.new("Part", workspace)
original.Changed:Connect(function(property)
	local ok, value = pcall(function()
		return original[property]
	end)
	if not ok then
		return
	end
	copy[property] = value
end)

copy.Position = Vector3.new(8, 0, 0)
original.Color = BrickColor.Blue().Color

ChildAdded On DevHub

Fired after a child is added to the object.

Name Type Default
child Instance none

ChildRemoved On DevHub

Fired after a child is removed from the object.

Name Type Default
child Instance none

ClassName On DevHub

Returns the name of the object's class.

This property is read-only. Its value can be read, but it cannot be modified.
This item is not replicated. Its interface does not cross the network boundary.

Tags: [ReadOnly, NotReplicated]

ClearAllChildren On DevHub

Removes all of the children from the object.

Name Type Default
No parameters.

History

Clone On DevHub

Creates a deep copy of the object.

Name Type Default
No parameters.

DataCost On DevHub

Returns the cost of saving the object to data persistence, in data units.

This property is read-only. Its value can be read, but it cannot be modified.
This member is hidden. It is not meant to be used, and may have unresolved issues.
This item is deprecated. It exists for backwards-compatibility only, and should not be used for new work.
This item is not replicated. Its interface does not cross the network boundary.

History

  • 469 Change Tags of Instance.DataCost from [ReadOnly, NotReplicated, Deprecated] to [Hidden, ReadOnly, NotReplicated, Deprecated]
  • 390 Change Tags of Instance.DataCost from [ReadOnly, NotReplicated] to [ReadOnly, NotReplicated, Deprecated]
  • 311 Change ReadSecurity of Instance.DataCost from RobloxPlaceSecurity to LocalUserSecurity
  • 311 Change WriteSecurity of Instance.DataCost from RobloxPlaceSecurity to LocalUserSecurity

Tags: [Hidden, ReadOnly, NotReplicated, Deprecated]

DescendantAdded On DevHub

Fired after a descendant of the object is added.

Name Type Default
descendant Instance none

DescendantRemoving On DevHub

Fired before a descendant of the object is removed.

Name Type Default
descendant Instance none

Destroy On DevHub

Removes the object and marks it as destroyed, preventing reuse.

Name Type Default
No parameters.

History

Destroying On DevHub

Name Type Default
No parameters.

History

FindFirstAncestor On DevHub

Returns the first ancestor of the object whose Name matches the given name.

Name Type Default
name string none

History

FindFirstAncestorOfClass On DevHub

Returns the first ancestor of the object whose ClassName matches the given name.

Name Type Default
className string none

History

FindFirstAncestorWhichIsA On DevHub

Returns the first ancestor of the object whose class inherits a class of the given name.

Name Type Default
className string none

History

FindFirstChild On DevHub

Returns the first child of the object whose Name matches the given name.

Name Type Default
name string none
recursive bool false

FindFirstChildOfClass On DevHub

Returns the first child of the object whose ClassName matches the given name.

Name Type Default
className string none

History

FindFirstChildWhichIsA On DevHub

Returns the first child of the object whose class inherits a class of the given name.

Name Type Default
className string none
recursive bool false

History

FindFirstDescendant On DevHub

Name Type Default
name string none

History

GetActor On DevHub

Name Type Default
No parameters.

History

GetAttribute On DevHub

Name Type Default
attribute string none

History

GetAttributeChangedSignal On DevHub

Name Type Default
attribute string none

History

GetAttributes On DevHub

Name Type Default
No parameters.

History

GetChildren On DevHub

Returns a list of the object's children.

Name Type Default
No parameters.

GetDebugId On DevHub

Returns a value that uniquely identifies the object.

This item is not browsable. It is not visible in Studio's object browser.
Name Type Default
scopeLength int 4

History

Tags: [NotBrowsable]

GetDescendants On DevHub

Returns a list of all the descendants of the object.

Name Type Default
No parameters.

History

Tags: [CustomLuaState]

GetFullName On DevHub

Returns a name formatted according to the ascendants of the object.

Name Type Default
No parameters.

GetPropertyChangedSignal On DevHub

Returns a signal that fires after a property of the given name changes.

Name Type Default
property string none

History

IsA On DevHub

Returns whether the object's class inherits from a class of the given name.

Name Type Default
className string none

History

Tags: [CustomLuaState]

IsAncestorOf On DevHub

Returns whether the object is an ancestor of a given object.

Name Type Default
descendant Instance none

nil can be passed as an argument. Because nil is not a real object, and therefore can never be a child, passing nil always returns false.

IsDescendantOf On DevHub

Returns whether the object is a descendant of a given object.

Name Type Default
ancestor Instance none

nil can be passed as an argument. Because the root of a tree always has a nil parent, passing nil always returns true.

Name On DevHub

Specifies a string used to identify the object.

The value of Name is constrained to a maximum length of 100 bytes. On assignment, extra bytes are truncated.

While Name is generally used to differentiate between sibling objects, no attempts to enforce the uniqueness of the value are made.

Parent On DevHub

Specifies an object that the current object is a child of.

This item is not replicated. Its interface does not cross the network boundary.

An object cannot be its own parent. Attempting to set Parent to the object results in the following error:

Attempt to set OBJECT as its own parent

Where OBJECT is the full name of the object.

An object also cannot be a child of one of its descendants. Attempting to set Parent to a descendant results in the following error:

Attempt to set parent of OBJECT to VALUE would result in circular reference

Where OBJECT is the full name of the object, and VALUE is the full name of the descendant.

Locking

After its value is changed, the Parent property is locked, and cannot be changed. This is to prevent events from recursively firing themselves. Attempting to set Parent while it is locked fails without throwing an error, and the following warning is emitted:

Something unexpectedly tried to set the parent of OBJECT to NEWVALUE while trying to set the parent of OBJECT. Current parent is VALUE.

OBJECT is the Name of the object whose Parent is being modified. NEWVALUE is the Name of the object to which the Parent was attempted to be set. VALUE is the Name of the current parent. "NULL" is used if either value is nil.

Once all listeners from associated events have resolved, the Parent is unlocked. A listener is resolved when its thread is either dead or has yielded.

History

Tags: [NotReplicated]

Remove On DevHub

Removes the object from its parent.

This item is deprecated. It exists for backwards-compatibility only, and should not be used for new work.
Name Type Default
No parameters.

History

Tags: [Deprecated]

RobloxLocked On DevHub

Determines the restrictions of indexing the object.

This member is hidden. It is not meant to be used, and may have unresolved issues.

History

Tags: [Hidden]

SetAttribute On DevHub

Name Type Default
attribute string none
value Variant none

History

SourceAssetId On DevHub

This member is hidden. It is not meant to be used, and may have unresolved issues.
This item is not replicated. Its interface does not cross the network boundary.

History

Tags: [Hidden, NotReplicated]

WaitForChild On DevHub

Blocks until an object of the given name is a child of the object.

This function can yield. It may or may not block the calling thread until completion.
Name Type Default
childName string none
timeOut double none

History

Tags: [CustomLuaState, CanYield]

archivable On DevHub

Determines whether the object can be serialized.

This member is hidden. It is not meant to be used, and may have unresolved issues.
This item is deprecated. It exists for backwards-compatibility only, and should not be used for new work.
This item is not replicated. Its interface does not cross the network boundary.

History

Tags: [Hidden, NotReplicated, Deprecated]

childAdded On DevHub

Fired after a child is added to the object.

This item is deprecated. It exists for backwards-compatibility only, and should not be used for new work.
Name Type Default
child Instance none

History

Tags: [Deprecated]

children On DevHub

Returns a list of the object's children.

This item is deprecated. It exists for backwards-compatibility only, and should not be used for new work.
Name Type Default
No parameters.

Tags: [Deprecated]

className On DevHub

Returns the name of the object's class.

This property is read-only. Its value can be read, but it cannot be modified.
This item is deprecated. It exists for backwards-compatibility only, and should not be used for new work.
This item is not replicated. Its interface does not cross the network boundary.

History

  • 49 Change Tags of Instance.className from [Hidden, ReadOnly, NotReplicated] to [ReadOnly, NotReplicated, Deprecated]

Tags: [ReadOnly, NotReplicated, Deprecated]

clone On DevHub

Creates a deep copy of the object.

This item is deprecated. It exists for backwards-compatibility only, and should not be used for new work.
Name Type Default
No parameters.

Tags: [Deprecated]

destroy On DevHub

Removes the object and marks it as destroyed, preventing reuse.

This item is deprecated. It exists for backwards-compatibility only, and should not be used for new work.
Name Type Default
No parameters.

History

Tags: [Deprecated]

findFirstChild On DevHub

Returns the first child of the object whose Name matches the given name.

This item is deprecated. It exists for backwards-compatibility only, and should not be used for new work.
Name Type Default
name string none
recursive bool false

Tags: [Deprecated]

getChildren On DevHub

Returns a list of the object's children.

This item is deprecated. It exists for backwards-compatibility only, and should not be used for new work.
Name Type Default
No parameters.

History

Tags: [Deprecated]

isA On DevHub

Returns whether the object's class inherits from a class of the given name.

This item is deprecated. It exists for backwards-compatibility only, and should not be used for new work.
Name Type Default
className string none

History

  • 384 Change Tags of Instance.isA from [Deprecated] to [Deprecated, CustomLuaState]

Tags: [Deprecated, CustomLuaState]

isDescendantOf On DevHub

Returns whether the object is a descendant of a given object.

This item is deprecated. It exists for backwards-compatibility only, and should not be used for new work.
Name Type Default
ancestor Instance none

History

Tags: [Deprecated]

remove On DevHub

Removes the object from its parent.

This item is deprecated. It exists for backwards-compatibility only, and should not be used for new work.
Name Type Default
No parameters.

Tags: [Deprecated]

Relevant classes (2)

Relevant members (290)