Instance

Not to be confused with Instance, the base class which shares the same name.

Explorer 2023 02 15 — The hierarchy viewed through the Explorer.

In the Roblox engine, an instance is an object created through the instantiation of a class, similar to a class-based model. Instances make up the engine's data model and are exposed in Roblox Studio represented by a hierarchy, viewed through the Explorer window. Instances are also exposed through the engine's Lua API with the "Instance" data type. An array of instances is exposed through the engine's API with the Instances data type.

All instances inherit indirectly from the Object class, which is the top-level class of the class hierarchy. Each instance is derived from the class that was instantiated, which can be determined by the Object.ClassName property.

Each instance has a Parent property that points to the instance that contains it. Each instance is also given an identifier (similar to a universally unique identifier) known as a referent, which may be linked by other instances such as ObjectValues and WeldConstraints.

Place and model file formats contain instance data, in the form of either binary or XML. Both share the same data structure but are different in that a place is loaded into the engine first before models can be inserted. On Roblox, places and models are also asset types, where places are grouped under experiences which then can be visited by users and models have their category in the Creator Marketplace. Many other asset types that also contain instance data share the format with the model asset type, such as accessories and decals.

Instantiation[]

There are many ways instances of any class are created within the engine:

Loading a place file that will load all of its instances.
Through the Instance.new function.
Through Roblox Studio:
- Insert Basic Objects window
- Explorer window (through the plus icon button)
- Right-click context menu

Constructor[]

Instances are a data type and holds a constructor accessed by Instance:

Instance.new(className: string, parent: Instance): Returns an instance of the specified class. If the class cannot be instantiated, this function will error.

The parent parameter is optional but there is a performance concern using the parameter. If the instance's parent is set before setting its properties, the properties will be listened to by the engine unnecessarily more than once.^[1]

Terminology[]

Because instances within the Roblox engine are derived from class-based programming, the terms related to instances are shared with the ones used in class-based programming.

class: A type of instance that can be instantiated, in contrast to an abstract class, which cannot be instantiated in any way and only serves to be a base class for other classes. Both classes can inherit members from another class if it is a subclass of that class. The Instance class serves as the base class that keeps all other classes known as subclasses.
service: A class that is a top-level singleton (cannot be instantiated more than once). The instance of a service is always parented to DataModel and can only be retrieved through GetService (game:GetService(className)). Some services are instantiated by default when loading the data model, such as Workspace, Lighting, and Players.
member: A property, method, event or callback that belongs to a class, which is inherited by subclasses. In Lua, members of an instance can be accessed by indexing the member through the instance just as one would do to a table. If the member being indexed does not exist, it will look up a child instance with the same name. If the child instance also does not exist, it will result in an error.
property: A member that accepts values of a data type that is associated. Enum properties can only accept EnumItems of an Enum that is associated. In Roblox Studio, most properties of one or more selected instances can be viewed and edited through the Properties window.
method: A member that is a function.
event: A member that is a RBXScriptSignal.
callback: A member that a function can be assigned to. Unlike others, this type of member cannot be retrieved; calling it will result in an error.

Hierarchy[]

Instances make up the data structure of the Roblox engine's data model which is based on the tree model, referred to as the hierarchy. The DataModel object serves as the root of the hierarchy, accessed by a game in Lua. The DataModel houses services, each of which represents an internal service. Services cannot be instantiated through Instance.new.

Certain objects, such as EditableImage, can exist outside of the data model structure. These objects inherit from the Object class, but not from the Instance class (the latter of which requires the object to be located within the data model).