The root class of all classes in the API.

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

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)