45 min read

Source: Roblox Creator Hub · CC BY 4.0 · View source · Code samples: MIT Imported 2026-10-03. Formatting adapted for this site.

Instance

Inherits from: Object

Instance is the base class for all classes in the Roblox class hierarchy which can be part of the DataModel tree.

It is not possible to directly create root Instance objects, but the special Instance.new() constructor creates objects via code, taking the name of the class as a parameter and returning the created object.

Inherits from: Object

Descendants: AccessoryDescription, Accoutrement, AdPortal, AdService, AdvancedDragger, AnalyticsService, Animation, AnimationClip, AnimationClipProvider, AnimationController, AnimationNodeDefinition, AnimationRigData, AnimationTrack, Animator, AssetDeliveryProxy, AssetPatchSettings, AssetService, Atmosphere, AudioAnalyzer, AudioChannelMixer, AudioChannelSplitter, AudioChorus, AudioCompressor, AudioDeviceInput, AudioDeviceOutput, AudioDistortion, AudioEcho, AudioEmitter, AudioEqualizer, AudioFader, AudioFilter, AudioFlanger, AudioGate, AudioLimiter, AudioListener, AudioPitchShifter, AudioPlayer, AudioRecorder, AudioReverb, AudioSearchParams, AudioSpeechToText, AudioTextToSpeech, AudioTremolo, AvatarCreationService, AvatarEditorService, Backpack, BadgeService, BaseCoreGuiConfiguration, BasePlayerGui, BaseRemoteEvent, BaseWrap, Beam, BindableEvent, BindableFunction, BodyPartDescription, BrowserService, CacheableContentProvider, CaptureService, ChangeHistoryService, CharacterAppearance, Chat, ClickDetector, Clouds, CollectionService, CommerceService, CompositeValueCurve, ConfigService, Configuration, ContentProvider, ContextActionService, Controller, ControllerService, CookiesService, CoreGuiConfiguration, CustomEvent, CustomEventReceiver, CustomLog, DataModelMesh, DataStoreGetOptions, DataStoreIncrementOptions, DataStoreInfo, DataStoreKey, DataStoreKeyInfo, DataStoreObjectVersionInfo, DataStoreOptions, DataStoreService, DataStoreSetOptions, Debris, DebugSettings, Dialog, DialogChoice, DigitsRigDescription, Dragger, EncodingService, EulerRotationCurve, ExperienceInviteOptions, ExperienceNotificationService, FaceControls, Fire, FlagStandService, FloatCurve, Folder, FriendService, FunctionalTest, GamePassService, GameSettings, GamepadService, GenerationService, Geometry, GeometryService, GlobalDataStore, GroupService, GuiBase, GuiService, GuidRegistryService, HapticEffect, HapticService, HeapProfilerService, HeightmapImporterService, HiddenSurfaceRemovalAsset, Highlight, Hopper, HttpService, Humanoid, HumanoidDescription, HumanoidRigDescription, IKControl, ILegacyStudioBridge, IncrementalPatchBuilder, InputObject, InsertService, KeyboardService, Keyframe, KeyframeMarker, KeyframeSequenceProvider, Light, Lighting, LocalizationService, LocalizationTable, LogService, LoginService, LuaSettings, LuaSourceContainer, LuaWebService, MLService, MakeupDescription, MarkerCurve, MarketplaceService, MatchmakingService, MaterialService, MaterialVariant, MemStorageConnection, MemoryStoreHashMap, MemoryStoreQueue, MemoryStoreService, MemoryStoreSortedMap, Message, MessagingService, ModerationService, Mouse, MouseService, NetworkSettings, OpenCloudApiV1, OpenCloudService, PackageLink, PackageService, Pages, ParticleEmitter, Path, PathfindingLink, PathfindingModifier, PathfindingService, Player, PlayerScripts, PlayerViewService, Players, Plugin, PluginAction, PluginCapabilities, PluginDebugService, PluginDragEvent, PluginGuiService, PluginManager, PluginManagerInterface, PluginMenu, PluginToolbar, PluginToolbarButton, PointsService, PolicyService, PoseBase, PostEffect, ProximityPrompt, ProximityPromptService, PublishService, ReflectionService, RemoteDebuggerServer, RemoteFunction, ReplicatedFirst, ReplicatedStorage, RotationCurve, RunService, SceneAnalysisService, ScreenshotHud, ScriptContext, ScriptDebuggerService, ScriptProfilerService, ScriptService, Selection, SerializationService, ServerScriptService, ServerStorage, ServiceProvider, SharedTableRegistry, Sky, Smoke, SocialService, Sound, SoundEffect, SoundGroup, SoundService, Sparkles, SpawnerService, StandalonePluginScripts, StarterGear, StarterPack, StarterPlayer, StarterPlayerScripts, Stats, StatsItem, StyleQuery, SurfaceAppearance, TaskScheduler, Team, Teams, TeleportAsyncResult, TeleportOptions, TeleportService, TerrainDetail, TerrainRegion, TestService, TextBoxService, TextChannel, TextChatCommand, TextChatConfigurations, TextChatMessage, TextChatMessageProperties, TextChatService, TextFilterResult, TextFilterTranslatedResult, TextGenerator, TextService, TextSource, TimerService, TouchInputService, TouchTransmitter, Trail, Translator, TweenBase, TweenService, UIBase, UserGameSettings, UserInputService, UserService, VRService, ValueBase, ValueCurve, Vector3Curve, VideoCaptureService, VideoPlayer, VideoService, VirtualUser, VisibilityCheckDispatcher, Visit, VoiceChatService, Wire, WrapTextureTransfer, RenderSettings, StopWatchReporter, VirtualInputManager, CreatorStoreService, InputAction, InputBinding, InputContext, ClusterPacketCache, ConfigureServerService, NetworkMarker, NetworkPeer, NetworkReplicator, PVInstance, Attachment, Constraint, ControllerBase, ControllerManager, NoCollisionConstraint, WeldConstraint, BodyMover, Explosion, FaceInstance, Feature, ForceField, JointInstance, JointsService, PartOperationAsset, PhysicsService, PhysicsSettings, ProcessInstancePhysicsService, SensorBase, RecommendationService, DraftsService, DraggerService, File, InstanceFileSyncService, PluginConnectionService, PluginManagementService, ReflectionMetadata, ReflectionMetadataCallbacks, ReflectionMetadataClasses, ReflectionMetadataEnums, ReflectionMetadataEvents, ReflectionMetadataFunctions, ReflectionMetadataItem, ReflectionMetadataProperties, ReflectionMetadataYieldFunctions, ScriptDocument, ScriptEditorService, SelectionHighlightManager, Studio, StudioCaptureService, StudioDeviceSimulatorService, StudioScreenshotCapture, StudioTestService, StudioTheme, StudioService, StyleBase, StyleDerive, StyleLink, RemoteCommandService, UniqueIdLookupService, GetTextBoundsParams

Memory category: Instances

Tags: NotCreatable, NotBrowsable

Properties

Inherited from Object

Instance.Archivable

This property determines whether the instance should be included when the experience is published or saved, or when Clone() is called on one of the instance's ancestors. Calling Clone() directly on an instance will return nil if that instance is not Archivable.

Copying an object in Studio using the Duplicate or Copy/Paste options will ignore its own Archivable property and set Archivable to true for the copy.

Code samples: View on Creator Hub (Instance-Archivable).

Instance.archivable

Deprecated. This deprecated property is a variant of Instance.Archivable which should be used instead.

Instance.Capabilities

The set of capabilities allowed to be used for scripts inside this instance. For the capabilities to take effect, Instance.Sandboxed property must be enabled.

This property is used by an experimental feature. See script capabilities for further details.

Instance.IsInSandbox

This read-only property returns true if the instance is contained within a sandboxed container — that is, if the instance itself or any of its ancestors has Instance.Sandboxed enabled. Otherwise it returns false.

This property is not scriptable and is only visible in Studio's Properties window. See script capabilities for further details.

Instance.Name

A non-unique identifier of the Instance. Names are used to keep the object hierarchy organized, along with allowing scripts to access specific objects. The name of an instance cannot exceed 100 characters in size.

The name of an object is often used to access the object through the data model hierarchy using the following methods:

local Workspace = game:GetService("Workspace")

local baseplate = Workspace.Baseplate
local baseplate = Workspace["Baseplate"]
local baseplate = Workspace:FindFirstChild("BasePlate")

In order to make an object accessible using the dot operator (.), its name must start with an underscore or letter, and the rest of the name can only contain letters, numbers, or underscores (no other special characters). If an object's name does not follow this syntax, it will not be accessible using the dot operator and Luau will not interpret its name as an identifier.

If more than one object with the same name are siblings, any attempt to index an object by that name will return only one of the objects, similar to Instance:FindFirstChild(), but not always the desired object. If a specific object needs to be accessed through code, it's recommended to give it a unique name or guarantee that none of its siblings share the same name.

See also Instance:GetFullName() to obtain a full name including the object's hierarchy.

Instance.Parent

The Parent property determines the hierarchical parent of the Instance. The following terminology is commonly used when talking about how this property is set:

• An object is a child of, or is parented to, another object when its Parent is set to that object.

• The descendants of an Instance are the children of that object, plus the descendants of the children as well.

• The ancestors of an Instance are all the objects that the instance is a descendant of.

It is from the Parent property that many other API members get their name, such as GetChildren() and FindFirstChild(). This property is also used to manage whether an object exists in the experience or needs to be removed. As long as an object's parent is in the DataModel, is stored in a variable, or is referenced by another object's property, the object remains in the experience; otherwise, the object will automatically be removed.

Calling Destroy() will set the Parent of an Instance and all of its descendants to nil, and also lock the Parent property. An error is raised when setting the Parent of a destroyed object.

Newly created objects using Instance.new() will not have a parent, and usually will not be visible or function until one is set.

Object Replication

An object created by the server will not replicate to clients until it is parented to some object that is replicated. When creating an object and setting many properties, it's recommended to set the Parent property last. This ensures the object replicates once, instead of replicating many property changes.

local Workspace = game:GetService("Workspace")

-- Set new instance's parent last (recommended)
local part = Instance.new("Part")
part.Position = Vector3.new(0, 10, 0)
part.Parent = Workspace

However, if parenting parts to a Model whose parent hasn't been set yet, parenting each part to that model is acceptable since the model would not have replicated.

Instance.PredictionMode

This property reflects the PredictionMode currently applied to the instance, which determines whether the instance's state is predicted on the client ahead of the authoritative server state under server-authoritative physics. It defaults to Automatic.

This property is read-only and cannot be assigned directly from a script; the prediction mode is set through RunService:SetPredictionMode(). The property is shown in Studio's Properties window only when the experience uses server-authoritative physics.

• Automatic (default) — the engine automatically decides whether to predict the instance. Currently, only BaseParts near the local player character's Humanoid are predicted, within a dynamic radius that grows and shrinks based on the device's capacity to handle the simulation load.
• On — the instance is always predicted. If it is a BasePart, its physics properties are predicted ahead of the replicated authoritative server state, and mismatches in the instance's attributes between the client and server cause a rollback and resimulation.
• Off — the instance is not predicted, and regular network ownership semantics apply.

Instance.RobloxLocked

Deprecated. This property is deprecated and does not do anything.

This property used to protect objects in the CoreGui service from being altered by users in an unauthorized manner. It has been deprecated and does not do anything.

Instance.Sandboxed

Turns the instance to be a sandboxed container, an experimental feature which limits the actions that scripts inside a particular container can perform. See script capabilities for further details.

Instance.UniqueId

A unique identifier for the instance, distinct from Instance.Name which is not necessarily unique. This property is visible in the Properties window in Studio but is not readable or writable from scripts.

Methods

Inherited from Object

Instance:AddTag

This method applies a tag to the instance, with no effect if the tag is already applied. Successfully adding a tag will fire a signal created by CollectionService:GetInstanceAddedSignal() with the given tag.

Warnings

• An instance's tags that were added client-side will be dropped if the server later adds or removes a tag on that instance because the server replicates all tags together and overwrites previous tags.

• When tagging an instance, it is common that some resources are used to give the tag its functionality, for example event connections or tables. To prevent memory leaks, it's a good idea to clean these up (disconnect, set to nil, etc.) when no longer needed for a tag. Do this when calling Instance:RemoveTag(), calling Instance:Destroy(), or in a function connected to a signal returned by CollectionService:GetInstanceRemovedSignal().

Parameters

Returns

Instance:children

Deprecated. This item has been superseded by Instance:GetChildren() which should be used in all new work.

The children function returns an array of the object's children.

Returns

Instance:ClearAllChildren

This method destroys all of an instance's children and descendants.

local part = Instance.new("Part")

-- Add some sparkles
for i = 1, 3 do
	local sparkles = Instance.new("Sparkles")
	sparkles.Parent = part

  local sc = Instance.new("Sparkles")
  sc.Parent = sparkles
end

print("Children:", #part:GetChildren())  --> Children: 3

part:ClearAllChildren()

print("Children:", #part:GetChildren())  --> Children: 0

If you do not wish to destroy all children and descendants, use either Instance:GetChildren() or Instance:GetDescendants() to loop through those children/descendants and select what to destroy. For example, the following code sample will destroy all BaseParts descending from a Model:

local Workspace = game:GetService("Workspace")

local model = Workspace:FindFirstChild("TestModel")

for _, descendant in model:GetDescendants() do
	if descendant:IsA("BasePart") then
		descendant:Destroy()
	end
end

Returns

Instance:Clone

Clone() creates a copy of an instance and all of its descendants, ignoring all instances that are not Archivable. The copy of the root instance is returned by this method and its Parent is set to nil. Note that if the instance itself has Archivable set to false, this method will return nil.

If a reference property such as ObjectValue.Value is set in a cloned instance, the value of the copy's property depends on the original's value:

• If a reference property refers to an instance that was also cloned, the copy will refer to the copy.
• If a reference property refers to an instance that was not cloned, the same value is maintained in the copy.

Returns

Code samples: View on Creator Hub (Clone-Example).

Instance:clone

Deprecated. This deprecated function is a variant of Instance:Clone() which should be used instead.

Returns

Instance:Destroy

Sets the Instance.Parent property to nil, locks the Instance.Parent property, disconnects all connections, and calls Destroy() on all children. This method is the correct way to dispose of objects that are no longer required.

Disposing of unneeded objects is important, since unnecessary objects and connections in a place use up memory which can lead to serious performance issues over time.

As a best practice after calling Destroy() on an object, set any variables referencing the object (or its descendants) to nil. This prevents your code from accessing anything to do with the object.

local part = Instance.new("Part")
part.Name = "Hello, world"
part:Destroy()
-- Don't do this:
print(part.Name)  --> "Hello, world"
-- Do this to prevent the above line from working:
part = nil

Once an Instance has been destroyed by this method, it cannot be reused because the Instance.Parent property is locked. To temporarily remove an object instead of destroying it, set Parent to nil. For example:

local Workspace = game:GetService("Workspace")

object.Parent = nil
task.wait(2)
object.Parent = Workspace

To destroy an object after a set amount of time, use Debris:AddItem().

Returns

Code samples: View on Creator Hub (Instance-Destroy1).

Instance:destroy

Deprecated. This deprecated function is a variant of Instance:Destroy() which should be used instead.

Returns

Instance:FindFirstAncestor

Returns the first ancestor of the Instance whose Instance.Name is equal to the given name.

This method works upwards, meaning it starts at the instance's immediate Instance.Parent and works up towards the DataModel. If no matching ancestor is found, it returns nil.

The following code snippet would find the first ancestor of the object named Car.

local car = object:FindFirstAncestor("Car")

For variants of this method that find ancestors of a specific class, please see Instance:FindFirstAncestorOfClass() and Instance:FindFirstAncestorWhichIsA().

Parameters

Returns

Instance:FindFirstAncestorOfClass

Returns the first ancestor of the Instance whose Object.ClassName is equal to the given className.

This method works upwards, meaning it starts at the instance's immediate Instance.Parent and works up towards the DataModel. If no matching ancestor is found, it returns nil.

A common use of this method is finding the Model a BasePart belongs to. For example:

local model = part:FindFirstAncestorOfClass("Model")

This method is a variant of Instance:FindFirstAncestor() which checks the Object.ClassName property rather than Instance.Name. Instance:FindFirstAncestorWhichIsA() also exists, using the Object:IsA() method instead to respect class inheritance.

Parameters

Returns

Instance:FindFirstAncestorWhichIsA

Returns the first ancestor of the Instance for whom Object:IsA() returns true for the given className.

This method works upwards, meaning it starts at the instance's immediate Instance.Parent and works up towards the DataModel. If no matching ancestor is found, it returns nil.

Unlike Instance:FindFirstAncestorOfClass(), this method uses Object:IsA() which respects class inheritance. For example:

print(part:IsA("Part"))  --> true
print(part:IsA("BasePart"))  --> true
print(part:IsA("Instance"))  --> true

Therefore, the following code sample will return the first BasePart ancestor, regardless of if it is a WedgePart, MeshPart or Part.

local part = object:FindFirstAncestorWhichIsA("BasePart")

See also Instance:FindFirstAncestor().

Parameters

Returns

Instance:FindFirstChild

Returns the first child of the Instance with the given name, or nil if no such child exists. If the optional recursive argument is true, this method searches all descendants rather than only the immediate children of the Instance.

Checking the Existence of an Object

FindFirstChild() is necessary if you need to verify an object exists before continuing. Attempting to index a child by name using the dot operator throws an error if the child doesn't exist.

local Workspace = game:GetService("Workspace")

-- The following line errors if the part doesn't exist in the workspace
Workspace.Part.Transparency = 0.5

A better approach is to use FindFirstChild() to first check for Part, then use an if statement to run code that needs it.

local Workspace = game:GetService("Workspace")

local part = Workspace:FindFirstChild("Part")
if part then
	part.Transparency = 0.5
end

Finding a Child Whose Name Matches a Property

Sometimes the Name of an object is the same as that of a property of its Parent. When using the dot operator, properties take precedence over children if they share a name.

In the following example, a Folder called Color is added to a Part, which also has the Part.Color property. Notice that part.Color refers to the Color3 property value, not the child Folder instance. A benefit of using FindFirstChild() is that the introduction of new properties does not impose a risk on your code.

local part = Instance.new("Part")
local folder = Instance.new("Folder")
folder.Name = "Color"
folder.Parent = part
local c1 = part.Color  -- The property
local c2 = part:FindFirstChild("Color")  -- The child folder

Performance Notes

FindFirstChild() takes about 20% longer than using the dot operator and almost 8 times longer than simply storing a reference to an object. Therefore, you should avoid calling it in performance-dependent code such as in tight loops or functions connected to RunService.Heartbeat and RunService.PreRender. Instead, store the result in a variable, or consider using ChildAdded or WaitForChild() to detect when a child of a given name becomes available.

Parameters

Returns

Code samples: View on Creator Hub (Instance-FindFirstChild1).

Instance:findFirstChild

Deprecated. This deprecated function is a variant of Instance:FindFirstChild() which should be used instead.

Parameters

Returns

Instance:FindFirstChildOfClass

Returns the first child of the Instance whose ClassName is equal to the given className. Unlike Instance:FindFirstChildWhichIsA(), this method only returns objects whose class matches className, ignoring class inheritance. If no matching child is found, this method returns nil.

Parameters

Returns

Code samples: View on Creator Hub (Instance-FindFirstChildOfClass1).

Instance:FindFirstChildWhichIsA

Returns the first child of the Instance for whom Object:IsA() returns true for the given className.

If no matching child is found, this method returns nil. If the optional recursive argument is true, this method searches all descendants rather than only the immediate children of the Instance.

Unlike Instance:FindFirstChildOfClass(), this method uses Object:IsA() which respects class inheritance. For example:

print(part:IsA("Part")) --> true
print(part:IsA("BasePart")) --> true
print(part:IsA("Instance")) --> true

Therefore, the following code sample will return the first BasePart child, regardless of if it is a WedgePart, MeshPart or Part.

local part = object:FindFirstChildWhichIsA("BasePart")

Developers looking for a child by name, should use Instance:FindFirstChild() instead.

Parameters

Returns

Instance:FindFirstDescendant

Returns the first descendant found with the given Instance.Name.

This method is disabled and cannot be used. To find the first descendant of an instance, consider using the recursive parameter on Instance:FindFirstChild() instead.

Parameters

Returns

Instance:GetActor

If the Instance is an Actor, the Actor itself is returned. Otherwise, its closest ancestor Actor is returned. If no ancestor is an Actor, the result is nil.

Returns

Instance:GetAttribute

This method returns the value which has been assigned to the given attribute name. If no attribute has been assigned, nil is returned.

For example, the following code snippet sets and then gets the value of the instance's InitialPosition attribute:

local Workspace = game:GetService("Workspace")

local part = Workspace.Part
part:SetAttribute("InitialPosition", part.Position)

local initialPosition = instance:GetAttribute("InitialPosition")
print(initialPosition)

See Also

• Instance:SetAttribute() which sets the attribute with the given name to the given value.
• Instance:GetAttributes() which returns a dictionary of key‑value pairs for each of the instance's attributes.

Parameters

Returns

Instance:GetAttributeChangedSignal

This method returns an event that behaves exactly like the Changed event, except that it only fires when the specific given attribute changes; effectively it is similar to GetPropertyChangedSignal() but for attributes.

It's generally a good idea to use this method instead of a connection to Changed with a function that checks the attribute name. Subsequent calls to this method on the same object with the same attribute name return the same event.

The following code example returns a signal that fires the function attributeChanged() when the part's InitialPosition attribute changes:

local Workspace = game:GetService("Workspace")

local part = Workspace.Part
part:SetAttribute("InitialPosition", part.Position)

local function attributeChanged()
	print("Attribute changed")
end

part:GetAttributeChangedSignal("InitialPosition"):Connect(attributeChanged)

See also Instance.AttributeChanged which fires whenever any attribute is changed on the instance.

Parameters

Returns

Instance:GetAttributes

This method returns a dictionary of key‑value pairs for each attribute where the key is the attribute's name and the value is a non‑nil value.

For example, the following code snippet outputs an instance's attributes and values:

local Workspace = game:GetService("Workspace")

local part = Workspace.Part
part:SetAttribute("InitialPosition", part.Position)
part:SetAttribute("CanUse", true)

for name, value in part:GetAttributes() do
	print(name .. " = " .. value)
end

See also Instance:GetAttribute() which returns the value that has been assigned to the given attribute name.

Returns

Instance:GetChildren

Returns an array (a numerically indexed table) containing all of the instance's direct children, or every Instance whose Parent is equal to the object. The array can be iterated upon using either a numeric or generic for loop:

local Workspace = game:GetService("Workspace")

-- Numeric loop example
local children = Workspace:GetChildren()
for i = 1, #children do
	local child = children[i]
	print(child.Name .. " is child number " .. i)
end

local Workspace = game:GetService("Workspace")

-- Generic loop example
local children = Workspace:GetChildren()
for i, child in children do
	print(child.Name .. " is child number " .. i)
end

Note that the returned array is not sorted in any particular order, so manual sorting (for example using table.sort()) is advised for sorting the children returned by this method.

See also the GetDescendants() method.

Returns

Code samples: View on Creator Hub (Instance-GetChildren1).

Instance:getChildren

Deprecated. This deprecated function is a variant of Instance:GetChildren() which should be used instead.

Returns

Instance:GetDebugId

Returns a coded string of the debug ID used internally by Roblox. Note that:

• This item is protected. Attempting to use it in a Script or LocalScript will cause an error.
• A debug ID is an ID used in debugging processes. It allows a debugger to read each instruction before an application processes it. All objects in Roblox act like processes and each run instructions (or 'code') that can be debugged if needed.
• This can be helpful for plugins which need to distinguish similar objects from one-another (such as objects that share the same name).

Parameters

Returns

Code samples: View on Creator Hub (Instance-GetDebugId1).

Instance:GetDescendants

This object method returns an array that contains all of the descendants of that object. Unlike Instance:GetChildren(), which only returns the immediate children of an object, this method finds every child of the object, every child of those children, and so on.

Note that the returned array is not sorted in any particular order, so manual sorting (for example using table.sort()) is advised for sorting the descendants returned by this method. Also consdier the QueryDescendants() method to query descendants by a combination of selectors and combinators.

Returns

Code samples: View on Creator Hub (Instance-GetDescendants1).

Instance:GetFullName

Returns a string describing the instance's ancestry. The string is a concatenation of the Name of the object and its ancestors, separated by periods. The DataModel (game) is not considered. For example, a Part in the Workspace may return Workspace.Part.

When called on an Instance that is not a descendant of the DataModel, this method considers all ancestors up to and including the topmost one without a Parent.

This method is useful for logging and debugging. You shouldn't attempt to parse the returned string for any useful operation; this method does not escape periods (or any other symbol) in object names. In other words, although its output often appears to be a valid Luau identifier, it is not guaranteed.

Returns

Code samples: View on Creator Hub (Instance-GetFullName1, instance-getfullname-lua-implementation).

Instance:GetStyled

This method returns the styled or explicitly modified value of the specified property, or else the default property value if it hasn't been styled/modified. This differs slightly from accessing the property value directly, such as [GuiObject].Rotation, which returns the default or modified value of the property.

Parameters

Returns

Code samples: View on Creator Hub (Instance-GetStyled).

Instance:GetStyledPropertyChangedSignal

This method returns an event that behaves exactly like the StyledPropertiesChanged event, except that it only fires when the given style property changes. It's generally a good idea to use this method instead of a connection to StyledPropertiesChanged with a function that checks the property name. Subsequent calls to this method on the same object with the same property name return the same event.

Note that this event will not pass any arguments to a connected function, so the value of the changed property must be read directly within a script.

Parameters

Returns

Code samples: View on Creator Hub (Instance-GetStyledPropertyChangedSignal).

Instance:GetTags

This method returns an array of the tags applied to the given instance, as strings. You can add tags either in Studio in the Properties window or at runtime with AddTag().

This method is useful when you want to do something with multiple tags on an instance at once. However, it is inefficient to use this method to check for the existence of a single tag; instead, use HasTag() to check for a specific tag.

Returns

Instance:HasTag

This method returns true if the provided tag has been added to the object. You can add tags either in Studio in the Properties window or at runtime with AddTag().

Parameters

Returns

Instance:IsAncestorOf

Returns true if an Instance is an ancestor of the given descendant.

An Instance is considered the ancestor of an object if the object's Instance.Parent or one of it's parent's Instance.Parent is set to the Instance.

See also, Instance:IsDescendantOf().

Parameters

Returns

Code samples: View on Creator Hub (Instance-IsAncestorOf1).

Instance:IsDescendantOf

Returns true if an Instance is a descendant of the given ancestor.

Note that IsDescendantOf() cannot be used with a parameter of nil to check if an object has been removed.

See also Instance:IsAncestorOf().

Parameters

Returns

Code samples: View on Creator Hub (Instance-IsDescendantOf1).

Instance:isDescendantOf

Deprecated. This deprecated function is a variant of Instance:IsDescendantOf() which should be used instead.

Parameters

Returns

Instance:IsPropertyModified

This method indicates whether a specific property has been modified from the code‑instantiated default. If called on an instance newly created via code (Instance.new()), this method will return false. If called on an object newly created by Studio workflows such as Explorer window insertion, the result may differ.

For example, querying the BackgroundColor3 property of a TextLabel inserted via the Explorer will return true, but querying the same property of a TextLabel created through Instance.new() will return false, assuming no other changes were made to its BackgroundColor3.

Note that this method only returns useful results for services and user‑creatable instances. Return values for system‑populated properties of instances like PackageLink is undefined behavior.

Also note that if this method returns true, styling will not affect the property because explicitly modifying a property takes precedence over styling it. To reset a property to its code‑instantiated default and allow styling on it, use ResetPropertyToDefault().

Parameters

Returns

Instance:QueryDescendants

This object method returns an array that contains all descendants of the object that match the provided selector string. selector can include multiple selectors and combinators to match characteristics such as the class name, instance name, and hierarchy relationships, as well as specific values of instance properties and attributes. The selector grammar is similar to the one used in StyleRule, with only a few differences regarding which parts of the grammar are supported or not.

Selectors

• ClassName — Matches instances of the specified class in a Object:IsA() relationship.
• .Tag — Matches instances tagged with a CollectionService tag.
• #Name — Matches instances of a specific Instance.Name.
• [property = value] — Matches instances which have the specified property and that property has the specified value. Boolean, number, and string values are supported. Letters, numbers, _, and - can be used without putting the value in quotation marks.
• [$attribute] — Matches instances which have the specified attribute set.
• [$attribute = value] — Matches instances which have the specified attribute and that attribute has the specified value. Same limitations apply as for property selectors. If you want to check for the absence of an attribute, do not query it as nil; instead use the :not pseudo‑class as in :not([$attribute]).

Selectors can also be combined. For example, Model.Apple[$Variety = Fuji][$Flavor = 4] will match instances which are a Model tagged as Apple and which have a Variety attribute equal to Fuji as well as a Flavor attribute equal to 4.

local Workspace = game:GetService("Workspace")

-- Get all MeshPart descendants
print(Workspace:QueryDescendants("MeshPart"))

-- Get all descendants tagged as "Fruit"
print(Workspace:QueryDescendants(".Fruit"))

-- Get all descendants with the name "RedTree"
print(Workspace:QueryDescendants("#RedTree"))

-- Get all descendants with CanCollide property set to false
print(Workspace:QueryDescendants("[CanCollide = false]"))

-- Get all descendants with a "FuelCapacity" attribute assigned
print(Workspace:QueryDescendants("[$FuelCapacity]"))
-- Get all descendants with a "FuelCapacity" attribute set to 75
print(Workspace:QueryDescendants("[$FuelCapacity = 75]"))

Combinators

Combinators let you mix basic selectors to match deeper hierarchy relationships.

• > — Matches instances that are direct children of the previous filter matches.

• >> — Matches instances that are descendants of the previous filter matches. This is the default first filter, meaning that SpotLight.Red is the same as >> SpotLight.Red.

• , — Specifies a list of multiple independent selectors for the descendant query. Only elements matching the filter are placed in the returned array; nil will not be included for non‑matches in a query list.

local Workspace = game:GetService("Workspace")

-- Get direct children of any Model that are tagged as "SwordPart"
print(Workspace:QueryDescendants("Model > .SwordPart"))

-- Get direct children which are a Part and are tagged as "Apple"
print(Workspace:QueryDescendants("> Part.Apple"))

-- Get descendants of any Model with an attribute "OnFire" set to true
print(Workspace:QueryDescendants("Model >> [$OnFire = true]"))

-- Get MeshPart descendants tagged as "SwordPart" OR with an attribute "OnFire" set to true
print(Workspace:QueryDescendants("MeshPart.SwordPart, MeshPart[$OnFire = true]"))

Pseudo-class selectors

• :not(complex-selector-list) — Allows selecting instances which do not match any of the selectors inside, effectively performing a negation of the selectors. Since the expression inside is a list of complex selectors, it's possible to filter based on multiple conditions.

• :has(relative-selector-list) — Allows selecting instances based on which instances they contain inside. The selector list is evaluated relative to each instance.

local Workspace = game:GetService("Workspace")

-- Get all descendants which are NOT of class SpotLight
print(Workspace:QueryDescendants(":not(SpotLight)"))
-- Get all descendants which are NOT of class SpotLight OR PointLight
print(Workspace:QueryDescendants(":not(SpotLight, PointLight)"))
-- Get all descendants which do NOT have an attribute "OnFire"
print(Workspace:QueryDescendants(":not([$OnFire])"))
-- Get all descendants EXCEPT children of a Model tagged as "SwordPart"
print(Workspace:QueryDescendants(":not(Model > .SwordPart)"))

-- Get descendants which contain a Tool instance as their own descendant
print(Workspace:QueryDescendants(":has(Tool)"))
-- Get MeshPart descendants which contain a direct child tagged as "SwordPart"
print(Workspace:QueryDescendants("MeshPart:has(> .SwordPart)"))

-- Get MeshPart descendants with direct children NOT of SurfaceAppearance or Texture class
print(Workspace:QueryDescendants("MeshPart:has(> :not(SurfaceAppearance, Texture))"))

Parameters

Returns

Instance:Remove

Deprecated. This item is deprecated in favor of Instance:Destroy() and Instance:ClearAllChildren(). If you must remove an object from the game, and wish to use the object later, set its Parent property to nil instead of using this method.

This method sets the object's Instance.Parent to nil, and does the same for all its descendants.

If the object is referenced before being removed, it is possible to retrieve the object at a later point.

Returns

Code samples: View on Creator Hub (Instance-Remove1).

Instance:remove

Deprecated. This deprecated function is a variant of Instance:Remove() which has also been deprecated. Neither function should be used in new work.

Returns

Instance:RemoveTag

This method removes a tag from an instance. It will not throw an error if the object does not have the tag. Successfully removing a tag will fire a signal created by CollectionService:GetInstanceRemovedSignal() with the given tag.

Note that when tagging an instance, it's common that some resources are used to give the tag its functionality, for example event connections or tables. To prevent memory leaks, it's a good idea to clean these up (disconnect, set to nil, etc.) when no longer needed for a tag.

Parameters

Returns

Instance:ResetPropertyToDefault

Resets a property to its default value. For example, calling ResetPropertyToDefault("Rotation") on a TextLabel is equivalent to setting its Rotation to 0 (the property's default value). This method can be used to ensure styling will override this property's default value.

Parameters

Returns

Instance:SetAttribute

This method sets the attribute with the given name to the given value. If the value given is nil, the attribute will be removed, since nil is returned by default.

For example, the following code snippet sets the instance's InitialPosition attribute to Vector3.new(0, 10, 0):

local Workspace = game:GetService("Workspace")

local part = Workspace.Part
part:SetAttribute("InitialPosition", Vector3.new(0, 10, 0))

Limitations

Naming requirements and restrictions:

• Names must only use alphanumeric characters.
  • You may also include periods, hyphens, slashes, and underscores.
• No spaces or unique symbols (such as @, ~, !) are allowed.
• Strings must be 100 characters or less.
• Names are not allowed to start with RBX unless the caller is a Roblox core script (reserved for Roblox).

When attempting to set an attribute to an unsupported type, an error will be thrown.

See Also

• Instance:GetAttribute() which returns the value that has been assigned to the given attribute name.
• Instance:GetAttributes() which returns a dictionary of key‑value pairs for each of the instance's attributes.

Parameters

Returns

Instance:WaitForChild

Returns the child of the Instance with the given name. If the child does not exist, it will yield the current thread until it does. If the timeOut parameter is specified, this method will time out after the specified number of seconds and return nil.

Primary Usage

WaitForChild() is extremely important when working on code run by the client in a LocalScript. The Roblox engine does not guarantee the time or order in which objects are replicated from the server to the client. Additionally, if an experience has Workspace.StreamingEnabled set to true, BaseParts that are far away from the player's character may not be streamed to the client, potentially causing scripts to break when indexing objects that do not yet exist on the client.

Notes

• This method does not yield if a child with the given name exists when the call is made.
• Instance:FindFirstChild() is a more efficient alternative to WaitForChild() for objects that are assumed to exist.
• If a call to this method exceeds 5 seconds without returning, and no timeOut parameter has been specified, a warning will be printed to the output that the thread may yield indefinitely.

Parameters

Returns

Code samples: View on Creator Hub (Instance-WaitForChild1).

Events

Inherited from Object

Instance.AncestryChanged

Fires when this instance is reparented or when any of its ancestors is reparented.

You can use this event to track the deletion of an instance in Studio, such as manual deletion in the Explorer or through a plugin. If you need to detect when an instance is destroyed using Instance:Destroy(), use the Instance.Destroying event instead.

Parameters

Code samples: View on Creator Hub (Instance-AncestryChanged1).

Instance.AttributeChanged

This event fires whenever any attribute is changed on the instance, including when an attribute is set to nil. The name of the changed attribute is passed to the connected function.

For example, the following code snippet connects the attributeChanged() function to fire whenever one of the part's attributes changes:

local Workspace = game:GetService("Workspace")

local part = Workspace.Part

local function attributeChanged(attributeName)
	print(attributeName, "changed")
end

part.AttributeChanged:Connect(attributeChanged)

See also Instance:GetAttributeChangedSignal() which returns an event that fires when a specific given attribute changes.

Parameters

Instance.ChildAdded

Fires after an object is parented to this Instance.

Note, when using this method on a client to detect objects created by the server it is necessary to use Instance:WaitForChild() when indexing these object's descendants. This is because the object and its descendants are not guaranteed to replicate from the server to the client simultaneously. For example:

local Workspace = game:GetService("Workspace")

Workspace.ChildAdded:Connect(function(child)
	-- Use WaitForChild() since descendants may not have replicated yet
	local head = child:WaitForChild("Head")
end)

Note, this event only operates for immediate children of the Instance. For an event that captures all descendants, use Instance.DescendantAdded.

See also Instance.ChildRemoved.

Parameters

Code samples: View on Creator Hub (Instance-ChildAdded1).

Instance.childAdded

Deprecated. This deprecated event is a variant of Instance.ChildAdded which should be used instead.

Parameters

Instance.ChildRemoved

Fires after a child is removed from this Instance.

Removed refers to when an object's parent is changed from this Instance to something other than this Instance. Note, this event will also fire when a child is destroyed (using Instance:Destroy()) as the destroy function sets an object's parent to nil.

This event only operates for immediate children of the Instance. For an event that captures all descendants, use Instance.DescendantRemoving.

See also Instance.ChildAdded.

Parameters

Code samples: View on Creator Hub (Instance-ChildRemoved1).

Instance.DescendantAdded

This event fires after a descendant is added to the Instance.

As it fires for every descendant, parenting an object to the Instance will fire the event for this object and all of its descendants individually.

If you're only concerned with the direct children of the Instance, use Instance.ChildAdded instead.

See also Instance.DescendantRemoving.

Parameters

Code samples: View on Creator Hub (Instance-DescendantAdded1).

Instance.DescendantRemoving

This event fires immediately before the parent Instance changes such that a descendant instance will no longer be a descendant. Destroy() changes an instance's Parent to nil, so calling that method on a descendant of the parent will cause this event to fire.

Since this event fires before the descendant's removal, the parent of the descendant will be unchanged at the time of this event firing. If the descendant is also a direct child of the parent, this event will fire before Instance.ChildRemoved.

If a descendant has children, this event fires with the descendant first, followed by its descendants.

Warning

This event fires with the descendant object that is being removed. Attempting to set the Parent of the descendant to something else will fail. Below is an example that demonstrates this:

local Workspace = game:GetService("Workspace")

Workspace.DescendantRemoving:Connect(function(descendant)
	-- Do not manipulate the parent of the descendant in this function!
	-- This event fires BECAUSE the parent was manipulated, and the change hasn't happened yet
	-- Therefore, it is problematic to change the parent like this:
	descendant.Parent = game
end)

local part = Instance.new("Part")
part.Parent = Workspace
part.Parent = nil

See also DescendantAdded.

Parameters

Code samples: View on Creator Hub (Instance-DescendantRemoving1).

Instance.Destroying

The Instance will never be deleted from memory while a connected function is still using it. However, if the function yields at any point, the Instance and its descendants will be parented to nil.

If the Workspace.SignalBehavior property is set to SignalBehavior.Immediate, this event fires immediately before the Instance or one of its ancestors is destroyed with Instance:Destroy().

If the Workspace.SignalBehavior property is set to SignalBehavior.Deferred, this event fires at the next resumption point, which will be after the Instance or one of its ancestors is destroyed with Instance:Destroy().

With Deferred behavior, connecting a script to its own Instance.Destroying event is problematic, as the script will be destroyed before the callback can be called (meaning it will not execute).

When deleting an Instance in Studio, such as manually deleting through the Explorer or through a plugin, the Instance isn't destroyed. Instead, the parent is set to nil which you can track with Instance.AncestryChanged.

Code samples: View on Creator Hub (Instance-Destroying-Immediate, Instance-Destroying-Deferred).

Instance.StyledPropertiesChanged

This event fires whenever any style property is changed on the instance, including when a property is set to nil.

Code samples: View on Creator Hub (Instance-StyledPropertiesChanged).