The root class of all classes in the API.
Memory Category | Instances |
---|
Type | Member | History | |
---|---|---|---|
PropertyStatus | PropertyStatusStudio | 522 525 |
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.
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.
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:
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).
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.
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) |
Parameters | 1 |
---|
Name | Type | Default |
---|---|---|
tag | string | none |
Return Type | null |
---|
Fired after the ancestry of the object changes.
Parameters | 2 |
---|
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.
Determines whether the object can be serialized.
Value Type | bool |
---|---|
Category | Behavior |
Can Load | false |
Can Save | false |
PropertyOrder | 990 |
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.
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 |
Parameters | 1 |
---|
Name | Type | Default |
---|---|---|
attribute | string | none |
Fired after a property of the object changes.
Parameters | 1 |
---|
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.
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.
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 |
Fired after a child is added to the object.
Parameters | 1 |
---|
Name | Type | Default |
---|---|---|
child | Instance | none |
Fired after a child is removed from the object.
Parameters | 1 |
---|
Name | Type | Default |
---|---|---|
child | Instance | none |
Returns the name of the object's class.
Value Type | string |
---|---|
Category | Data |
Can Load | false |
Can Save | false |
Removes all of the children from the object.
Parameters | 0 |
---|
Name | Type | Default |
---|---|---|
No parameters. |
Return Type | null |
---|
Creates a deep copy of the object.
Parameters | 0 |
---|
Name | Type | Default |
---|---|---|
No parameters. |
Return Type | Instance |
---|
Returns the cost of saving the object to data persistence, in data units.
Value Type | int |
---|---|
Security | LocalUserSecurity |
Category | Data |
Can Load | false |
Can Save | false |
Fired after a descendant of the object is added.
Parameters | 1 |
---|
Name | Type | Default |
---|---|---|
descendant | Instance | none |
Fired before a descendant of the object is removed.
Parameters | 1 |
---|
Name | Type | Default |
---|---|---|
descendant | Instance | none |
Removes the object and marks it as destroyed, preventing reuse.
Parameters | 0 |
---|
Name | Type | Default |
---|---|---|
No parameters. |
Return Type | null |
---|
Parameters | 0 |
---|
Name | Type | Default |
---|---|---|
No parameters. |
Returns the first ancestor of the object whose Name matches the given name.
Parameters | 1 |
---|
Name | Type | Default |
---|---|---|
name | string | none |
Return Type | Instance |
---|
Returns the first ancestor of the object whose ClassName matches the given name.
Parameters | 1 |
---|
Name | Type | Default |
---|---|---|
className | string | none |
Return Type | Instance |
---|---|
Constraint | Instance:isScriptCreatable:0 |
Returns the first ancestor of the object whose class inherits a class of the given name.
Parameters | 1 |
---|
Name | Type | Default |
---|---|---|
className | string | none |
Return Type | Instance |
---|---|
Constraint | Instance:Any:0 |
Returns the first child of the object whose Name matches the given name.
Parameters | 2 |
---|
Name | Type | Default |
---|---|---|
name | string | none |
recursive | bool | false |
Return Type | Instance |
---|
Returns the first child of the object whose ClassName matches the given name.
Parameters | 1 |
---|
Name | Type | Default |
---|---|---|
className | string | none |
Return Type | Instance |
---|---|
Constraint | Instance:isScriptCreatable:0 |
Returns the first child of the object whose class inherits a class of the given name.
Parameters | 2 |
---|
Name | Type | Default |
---|---|---|
className | string | none |
recursive | bool | false |
Return Type | Instance |
---|---|
Constraint | Instance:Any:0 |
Parameters | 1 |
---|
Name | Type | Default |
---|---|---|
name | string | none |
Return Type | Instance |
---|
Parameters | 0 |
---|
Name | Type | Default |
---|---|---|
No parameters. |
Return Type | Actor |
---|
Parameters | 1 |
---|
Name | Type | Default |
---|---|---|
attribute | string | none |
Return Type | Variant |
---|
Parameters | 1 |
---|
Name | Type | Default |
---|---|---|
attribute | string | none |
Return Type | RBXScriptSignal |
---|
Parameters | 0 |
---|
Name | Type | Default |
---|---|---|
No parameters. |
Return Type | Dictionary |
---|
Returns a list of the object's children.
Parameters | 0 |
---|
Name | Type | Default |
---|---|---|
No parameters. |
Return Type | Objects |
---|
Returns a value that uniquely identifies the object.
Parameters | 1 |
---|
Name | Type | Default |
---|---|---|
scopeLength | int | 4 |
Return Type | string |
---|---|
Security | PluginSecurity |
Returns a list of all the descendants of the object.
Parameters | 0 |
---|
Name | Type | Default |
---|---|---|
No parameters. |
Return Type | Array |
---|
Returns a name formatted according to the ascendants of the object.
Parameters | 0 |
---|
Name | Type | Default |
---|---|---|
No parameters. |
Return Type | string |
---|
Returns a signal that fires after a property of the given name changes.
Parameters | 1 |
---|
Name | Type | Default |
---|---|---|
property | string | none |
Return Type | RBXScriptSignal |
---|
Parameters | 0 |
---|
Name | Type | Default |
---|---|---|
No parameters. |
Return Type | Array |
---|
Parameters | 1 |
---|
Name | Type | Default |
---|---|---|
tag | string | none |
Return Type | bool |
---|
Returns whether the object's class inherits from a class of the given name.
Parameters | 1 |
---|
Name | Type | Default |
---|---|---|
className | string | none |
Return Type | bool |
---|---|
Constraint | Instance:Any:0 |
Returns whether the object is an ancestor of a given object.
Parameters | 1 |
---|
Name | Type | Default |
---|---|---|
descendant | Instance | none |
Return Type | bool |
---|
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.
Returns whether the object is a descendant of a given object.
Parameters | 1 |
---|
Name | Type | Default |
---|---|---|
ancestor | Instance | none |
Return Type | bool |
---|
nil
can be passed as an argument. Because the root of a tree always has a nil
parent, passing nil
always returns true.
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.
Value Type | string |
---|---|
Category | Data |
Can Load | true |
Can Save | true |
While Name is generally used to differentiate between sibling objects, no attempts to enforce the uniqueness of the value are made.
Specifies an object that the current object is a child of.
Value Type | Instance |
---|---|
Category | Data |
Can Load | true |
Can Save | false |
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.
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.
Removes the object from its parent.
Parameters | 0 |
---|
Name | Type | Default |
---|---|---|
No parameters. |
Return Type | null |
---|
Parameters | 1 |
---|
Name | Type | Default |
---|---|---|
tag | string | none |
Return Type | null |
---|
Determines the restrictions of indexing the object.
Value Type | bool |
---|---|
Security | PluginSecurity |
Category | Data |
Can Load | false |
Can Save | false |
Parameters | 2 |
---|
Name | Type | Default |
---|---|---|
attribute | string | none |
value | Variant | none |
Return Type | null |
---|
Value Type | int64 |
---|---|
Security | RobloxScriptSecurity |
Category | Data |
Can Load | true |
Can Save | true |
Blocks until an object of the given name is a child of the object.
Parameters | 2 |
---|
Name | Type | Default |
---|---|---|
childName | string | none |
timeOut | double | none |
Return Type | Instance |
---|
Determines whether the object can be serialized.
Value Type | bool |
---|---|
Category | Behavior |
Can Load | true |
Can Save | false |
Fired after a child is added to the object.
Parameters | 1 |
---|
Name | Type | Default |
---|---|---|
child | Instance | none |
Returns a list of the object's children.
Parameters | 0 |
---|
Name | Type | Default |
---|---|---|
No parameters. |
Return Type | Objects |
---|
Returns the name of the object's class.
Value Type | string |
---|---|
Category | Data |
Can Load | false |
Can Save | false |
Creates a deep copy of the object.
Parameters | 0 |
---|
Name | Type | Default |
---|---|---|
No parameters. |
Return Type | Instance |
---|
Removes the object and marks it as destroyed, preventing reuse.
Parameters | 0 |
---|
Name | Type | Default |
---|---|---|
No parameters. |
Return Type | null |
---|
Returns the first child of the object whose Name matches the given name.
Parameters | 2 |
---|
Name | Type | Default |
---|---|---|
name | string | none |
recursive | bool | false |
Return Type | Instance |
---|
Returns a list of the object's children.
Parameters | 0 |
---|
Name | Type | Default |
---|---|---|
No parameters. |
Return Type | Objects |
---|
Returns whether the object's class inherits from a class of the given name.
Parameters | 1 |
---|
Name | Type | Default |
---|---|---|
className | string | none |
Return Type | bool |
---|
Returns whether the object is a descendant of a given object.
Parameters | 1 |
---|
Name | Type | Default |
---|---|---|
ancestor | Instance | none |
Return Type | bool |
---|
Removes the object from its parent.
Parameters | 0 |
---|
Name | Type | Default |
---|---|---|
No parameters. |
Return Type | null |
---|
Value Type | PropertyStatus |
---|---|
Security | RobloxSecurity |
Category | Data |
Can Load | false |
Can Save | true |