Instance

The base class of every object in a game: parts, models, scripts, UI, services and the game itself.

• Subclasses: Animation, BasePart, Behavior, BindableEvent, BoolValue, Camera, Character, Constraint, DataModel, Folder, GuiObject, Model, ModuleScript, NumberValue, ObjectValue, Player, PlayerGui, PointLight, RemoteEvent, RemoteFunction, ScreenGui, Script, Service, Sound, StarterPlayerScripts, StringValue, Terrain
• Creatable: No: create one of its subclasses, such as new Part().
• Replication: Replicated: clients get a copy, and changes the server makes reach them.

Everything in a game is an instance in one tree. The root is game; under it are the fixed services (workspace, Players, ReplicatedStorage, …); under those are your objects. An instance is part of the game once its parent is set to something in the game, and leaves it when you set parent to null or call destroy().

Set an instance’s properties before you parent it: it then arrives on players’ devices with those values in one go.

Every instance can also hold attributes: your own named values (strings, numbers, booleans, Vector3, Vector2 and Color3), replicated like properties. Use them for small pieces of state such as “this door is locked” or “this coin is worth 5”.

Properties

name

Type: string · Default: the class name · Access: read/write · Replicates: yes

Used by findFirstChild, waitForChild and tree paths. Names don’t have to be unique: lookups return the first match. Rally Studio doesn’t allow / in names (scripts use it in paths) or names longer than 100 characters.

archivable

Type: boolean · Default: true · Access: read/write · Replicates: yes

When false, clone() leaves this instance out when it copies one of its ancestors, and the instance isn’t saved or published with the world.

id

Type: string | null · Access: read-only

Stable across the network: the same object has the same id on the server and on every player’s device. null until the instance first joins a game.

className

Type: string · Access: read-only

The class name, such as 'Part'. To include subclasses, use isA.

parent

Type: Instance | null · Access: read/write

The instance this one is inside, or null. Setting it moves the instance and everything inside it: into the game, out of it (null), or somewhere else in the tree. Throws if the new parent is the instance itself or one of its descendants, if either one was destroyed, or for services, which can’t move.

destroyed

Type: boolean · Access: read-only

True once destroy() has been called. A destroyed instance can’t be parented again.

Methods

Instance.new

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

Creates an instance by class name, e.g. Instance.new('Part', workspace).

Throws for an unknown class name, and for classes scripts can’t create (services, players, scripts). The result is typed as Instance: new Part() gives you a typed Part.

getPropertyChangedSignal

getPropertyChangedSignal(property: string): Signal<[]>

Fires (with no arguments) when one property changes.

Only the class’s registered properties (the ones in Properties with a default) have one: getPropertyChangedSignal('parent') throws. Use ancestryChanged for parent changes.

setAttribute

setAttribute(key: string, value: AttributeValue | undefined): void

Custom data on any instance, replicated like properties.

Names are 1–100 characters of letters, digits and _, and don’t start with a digit. Values are strings, numbers, booleans, Vector3, Vector2 or Color3; undefined or null removes the attribute. Anything else throws a TypeError.

getAttribute

getAttribute(key: string): AttributeValue | undefined

The attribute’s value, or undefined if it isn’t set.

getAttributes

getAttributes(): Record<string, AttributeValue>

Every attribute, as a plain object.

getAttributeChangedSignal

getAttributeChangedSignal(key: string): Signal<[]>

A signal that fires, with no arguments, when the attribute key changes or is removed.

getChildren

getChildren(): Instance[]

The children, in the order they were added. It’s a copy, so changing the tree while you loop over it is safe.

getDescendants

getDescendants(): Instance[]

Every instance inside this one, at any depth: each child, followed by its own descendants.

findFirstChild

findFirstChild(name: string, recursive = false): Instance | undefined

The first child named name, or undefined. With recursive set to true, it checks the children first and then searches inside each child, in order.

findFirstChildOfClass

findFirstChildOfClass<T extends Instance = Instance>(className: string): T | undefined

First child whose class is exactly className.

findFirstChildWhichIsA

findFirstChildWhichIsA<T extends Instance = Instance>(className: string): T | undefined

First child that isA(className) (subclasses count).

findFirstAncestor

findFirstAncestor(name: string): Instance | undefined

The nearest ancestor named name, or undefined.

findFirstAncestorWhichIsA

findFirstAncestorWhichIsA<T extends Instance = Instance>(className: string): T | undefined

The nearest ancestor that isA(className), or undefined.

waitForChild

waitForChild(name: string, timeoutSeconds?: number): Promise<Instance>

Resolves with the child once it exists (useful on clients, where replicated objects arrive over time). Rejects after timeoutSeconds if given.

The timeout counts game time while the instance is in a game. The waitForChild helper does the same and also checks the child’s class, which gives you a typed result.

isA

isA(className: string): boolean

True if this is a className or inherits from it.

isDescendantOf

isDescendantOf(other: Instance): boolean

True if this instance is inside other, at any depth.

isAncestorOf

isAncestorOf(other: Instance): boolean

True if other is inside this instance, at any depth.

getFullName

getFullName(): string

The names from the service down to this instance, joined with dots: Workspace.Map.Door.

clearAllChildren

clearAllChildren(): void

Removes every child (each one is destroyed).

destroy

destroy(): void

Removes this instance and its descendants for good: disconnects their events, locks their parent to nothing. On the server this also removes it from every client.

destroying fires first. Services can’t be destroyed.

clone

clone(): this

A deep copy with no parent. References inside the copied subtree (such as a model’s primaryPart) point at the copies.

Children whose archivable is false are left out. Attributes are copied; event connections aren’t. Scripts can clone any instance, including classes they can’t create with new.

toString

toString(): string

The instance’s name.

Events

changed

Arguments: property: string

Fires with the property name whenever a property changes.

Only for registered properties: changing parent doesn’t fire it.

childAdded

Arguments: child: Instance

Fires when an instance is parented to this one.

childRemoved

Arguments: child: Instance

Fires when a child is removed, destroyed or moved elsewhere.

descendantAdded

Arguments: descendant: Instance

Fires for every instance added anywhere inside this one, including each instance inside an added subtree.

descendantRemoving

Arguments: descendant: Instance

Fires for every instance about to leave this one’s subtree, before it leaves.

ancestryChanged

Arguments: child: Instance, parent: Instance | null

Fires when this instance or one of its ancestors changes parent.

destroying

Arguments: none

Fires just before destroy() removes this instance.

attributeChanged

Arguments: attribute: string

Fires with the attribute’s name when an attribute changes or is removed.

Examples

Build, find and remove

import { Folder, Part, Vector3, task, workspace } from '@rally/sdk';

const crates = new Folder();
crates.name = 'Crates';
crates.parent = workspace;

for (let i = 0; i < 3; i++) {
  const crate = new Part();
  crate.name = `Crate${i}`;
  crate.size = new Vector3(3, 3, 3);
  crate.position = new Vector3(i * 4, 10, 0);
  crate.anchored = false;
  crate.parent = crates; // parent last: the crate arrives with its properties set
}

const first = crates.findFirstChild('Crate0');
if (first?.isA('BasePart')) first.setAttribute('special', true);

// Ten seconds later, remove the folder and every crate in it.
task.delay(10, () => crates.destroy());

Attributes

import { Part, getChild, print, workspace } from '@rally/sdk';

const door = getChild(workspace, 'Door', Part);
door.getAttributeChangedSignal('locked').connect(() => {
  print('locked:', door.getAttribute('locked'));
});
door.setAttribute('locked', true);