Open Asterune
Instance

Instance

The base class for instances in a place.

Not creatable
Created by the engine or used as a base class.
Replication
Standard

Behavior

Instance defines the properties, hierarchy methods, and events shared by instances. It is abstract. Use Instance.new with a creatable class name.

Summary

Members47
Properties4
  • Archivable: booleanparallel read

    Whether the instance is included when cloning or saving the hierarchy.

  • ClassName: stringparallel readread only

    The concrete class name, such as "Part".

  • Name: stringparallel read

    The instance name.

  • Parent: Instance?parallel read

    The parent instance, or nil when unparented.

Methods35
Events8
  • AncestryChanged: RBXScriptSignalparallel readread only

    Fires when the instance or one of its ancestors is reparented.

  • AttributeChanged: RBXScriptSignalparallel readread only

    Fires when an attribute changes.

  • Changed: RBXScriptSignalparallel readread only

    Fires when a property changes.

  • ChildAdded: RBXScriptSignalparallel readread only

    Fires when an immediate child is added.

  • ChildRemoved: RBXScriptSignalparallel readread only

    Fires when an immediate child is removed, including by Destroy.

  • DescendantAdded: RBXScriptSignalparallel readread only

    Fires when an Instance becomes a descendant of this instance.

  • DescendantRemoving: RBXScriptSignalparallel readread only

    Fires before an Instance stops being a descendant of this instance.

  • Destroying: RBXScriptSignalparallel readread only

    Fires when the instance is being destroyed.

Properties

Archivable

Instance.Archivable: boolean

Whether the instance is included when cloning or saving the hierarchy.

ClassName

Instance.ClassName: string

The concrete class name, such as "Part". Use IsA to test whether an instance belongs to a class or one of its subclasses.

Name

Instance.Name: string

The instance name. Sibling names do not have to be unique. FindFirstChild returns the first matching child.

Parent

Instance.Parent: Instance?

The parent instance, or nil when unparented. Setting this property moves the instance in the hierarchy. An unparented instance remains accessible through existing script references.

Configure a new instance before parenting it so other scripts do not observe partially configured state.

Methods

AddComponent

Instance:AddComponent(component: Component | string, values: { [string]: any }?): ComponentHandle

Adds the named component and returns its ComponentHandle. Omitted fields use schema defaults. Initial values are validated before they are applied. Required components are added with it. Adding a component requires serial execution.

AddTag

Instance:AddTag(tag: string): ()

Adds the tag to this instance. Adding an existing tag does not create a duplicate.

ClearAllChildren

Instance:ClearAllChildren(): ()

Destroys all children and their descendants. This instance remains in the hierarchy.

ClearTags

Instance:ClearTags(): ()

Removes every tag from the instance.

Clone

Instance:Clone(): Instance

Returns an unparented copy of the instance and its archivable descendants. Returns nil if this instance has Archivable set to false.

Destroy

Instance:Destroy(): ()

Removes the instance and its descendants from the hierarchy and disconnects their event connections. Setting Parent to nil alone does not disconnect events.

FindFirstAncestor

Instance:FindFirstAncestor(name: string): Instance?

Returns the nearest ancestor with the specified name, or nil if none exists.

FindFirstAncestorOfClass

Instance:FindFirstAncestorOfClass(className: string): Instance?

Returns the nearest ancestor whose class exactly matches the specified class, or nil.

FindFirstAncestorWhichIsA

Instance:FindFirstAncestorWhichIsA(className: string): Instance?

Returns the nearest ancestor that matches the class or one of its subclasses, or nil.

FindFirstChild

Instance:FindFirstChild(name: string, recursive: boolean?): Instance?

Returns the first child with the specified name, or nil if no child matches. Pass true as the second argument to search descendants recursively. Check the result before indexing it.

FindFirstChildOfClass

Instance:FindFirstChildOfClass(className: string): Instance?

Returns the first direct child whose class exactly matches the specified class, or nil.

FindFirstChildWhichIsA

Instance:FindFirstChildWhichIsA(className: string, recursive: boolean?): Instance?

Returns the first child matching the class or one of its subclasses. Set recursive to search descendants. Returns nil if no match exists.

FindFirstDescendant

Instance:FindFirstDescendant(name: string): Instance?

Returns the first descendant with the specified name, or nil if none exists.

GetAttribute

Instance:GetAttribute(attribute: string): AttributeValue?

Returns the named attribute, or nil if it is unset.

GetAttributeChangedSignal

Instance:GetAttributeChangedSignal(string): AstScriptSignal

Returns a signal that fires when the named attribute changes.

GetAttributes

Instance:GetAttributes(): table

Returns a table containing this instance's attribute names and values.

GetChildren

Instance:GetChildren(): table

Returns an array of immediate children. The array is a snapshot and has no guaranteed order.

GetComponent

Instance:GetComponent(component: Component | string): ComponentHandle?

Returns a ComponentHandle when the instance has the component, or nil when it does not.

GetComponentChangedSignal

Instance:GetComponentChangedSignal(component: Component | string, field: string?): AstScriptSignal<string>

Returns the signal for changes to this instance's component. Supply a field name to observe that field. Without a field, the signal reports the changed field's name.

GetComponents

Instance:GetComponents(): table

Returns the component definitions attached to this instance.

GetDebugId

Instance:GetDebugId(number?): string

Returns a diagnostic identifier for the instance.

GetDescendants

Instance:GetDescendants(): table

Returns an array of all descendants. This traverses the subtree. Avoid repeatedly scanning large hierarchies when a cached result or hierarchy events can track changes.

GetFullName

Instance:GetFullName(): string

Returns the dot-separated hierarchy path, such as Workspace.Model.Part. Each call traverses the ancestors.

GetPropertyChangedSignal

Instance:GetPropertyChangedSignal(string): AstScriptSignal

Returns a signal that fires when the named property changes.

GetReferencing

Instance:GetReferencing(component: Component | string, field: string?): { Instance }

Returns Instances whose reference fields point to this instance. The component selects the schema; an optional field restricts the search to one reference field.

GetTags

Instance:GetTags(): table

Returns the tags assigned to this instance.

HasComponent

Instance:HasComponent(component: Component | string): boolean

Returns whether the instance has the specified component. Accepts a Component definition or a component name.

HasTag

Instance:HasTag(string): boolean

Returns whether this instance has the specified tag.

IsA

Instance:IsA(wanted: string): boolean

Returns whether the instance belongs to the specified class or a subclass. A Part returns true for both IsA("Part") and IsA("BasePart").

IsAncestorOf

Instance:IsAncestorOf(descendant: Instance): boolean

Returns whether the specified Instance is below this instance in the hierarchy.

IsDescendantOf

Instance:IsDescendantOf(ancestor: Instance): boolean

Returns whether this instance is a descendant of the specified instance.

RemoveComponent

Instance:RemoveComponent(component: Component | string): boolean

Removes the component and returns whether it was present. Fails if another attached component requires it. Removing a component requires serial execution.

RemoveTag

Instance:RemoveTag(tag: string): ()

Removes the tag from this instance.

SetAttribute

Instance:SetAttribute(attribute: string, value: AttributeValue?): ()

Sets the named attribute. Passing nil removes it.

WaitForChild

Instance:WaitForChild(childName: string, timeOut: number?): Instance

Yields until a child with the specified name exists. Use this when a client must wait for a replicated child. An optional timeout is measured in seconds. Without a timeout, a missing child can leave the thread waiting indefinitely.

Events

AncestryChanged

Instance.AncestryChanged: RBXScriptSignal

Fires when the instance or one of its ancestors is reparented.

AttributeChanged

Instance.AttributeChanged: RBXScriptSignal

Fires when an attribute changes. The argument is the attribute's name.

Changed

Instance.Changed: RBXScriptSignal

Fires when a property changes. The event arguments depend on the class; ValueBase classes report the stored value.

ChildAdded

Instance.ChildAdded: RBXScriptSignal

Fires when an immediate child is added. Passes the child instance. To track existing and future children, connect this event before calling GetChildren. Setup handlers should tolerate duplicate processing.

ChildRemoved

Instance.ChildRemoved: RBXScriptSignal

Fires when an immediate child is removed, including by Destroy. Passes the removed child.

DescendantAdded

Instance.DescendantAdded: RBXScriptSignal

Fires when an Instance becomes a descendant of this instance.

DescendantRemoving

Instance.DescendantRemoving: RBXScriptSignal

Fires before an Instance stops being a descendant of this instance.

Destroying

Instance.Destroying: RBXScriptSignal

Fires when the instance is being destroyed.

Example

Luau
local folder = Instance.new("Folder")
folder.Name = "Markers"
folder.Parent = workspace
print(folder:GetFullName())

Subclasses

Accoutrement · Animation · AnimationController · AnimationGraph · AnimationService · Animator · AssetService · Atmosphere · Attachment · Backpack · BackpackItem · BasePlayerGui · Beam · BindableEvent · BindableFunction · Camera · CharacterAppearance · CharacterController · Chat · ClickDetector · Clouds · Collider · ComponentService · Constraint · CoreGui · DataModel · DataModelMesh · Debris · DecalProjector · Dragger · ExecutionGroup · Explosion · FaceInstance · FogVolume · Folder · ForceField · GraphicsService · GravityField · GuiBase · GuiBase3d · GuiService · Health · HistoryService · HttpService · Humanoid · HumanoidDescription · InputService · Keyframe · KeyframeMarker · KeyframeSequence · Light · Lighting · LightProbeVolume · LocalizationService · LogService · LuaSourceContainer · MaterialService · MaterialVariant · Motor6D · Mouse · NetworkClient · NetworkServer · NetworkService · NetworkSettings · NoCollisionConstraint · PartAdornment · ParticleAttractor · ParticleEmitter · ParticleOperator · PathfindingLink · PathfindingModifier · PathfindingService · PhysicsService · PhysicsSettings · PlaceService · Player · Players · PlayerScripts · Pose · PostEffect · PrefabService · ProximityPrompt · ProximityPromptService · PVAdornment · PVInstance · ReflectionProbe · ReflectionService · RemoteEvent · RemoteFunction · ReplicatedFirst · ReplicatedStorage · ReplicationService · RetargetProfile · RigControl · RunService · ScriptContext · Selection · ServerScriptService · ServerStorage · ShaderEffect · Sky · Sound · SoundEffect · SoundGroup · SoundService · StarterGui · StarterPack · StarterPlayer · StarterPlayerScripts · Stats · StatsItem · StorageService · SurfaceAppearance · SurfaceShader · TagService · Team · Teams · TestService · TextService · Tool · Trail · TranslationTable · TweenService · UIBase · ValueBase · VRService · WeldConstraint

Related APIs

BasePart · Model · Folder · script