Open Asterune
Working with instances

Working with instances

Create, find, parent, clone, and destroy instances.

Instances form the place hierarchy. Instance defines shared properties and hierarchy operations.

Create and parent an instance

Pass a concrete class name to Instance.new. Services and abstract classes cannot be created this way. Configure the instance before setting Parent so scripts observing the hierarchy receive configured state.

Luau
local part = Instance.new("Part")
part.Name = "Marker"
part.Anchored = true
part.Position = Vector3.new(0, 5, 0)
part.Parent = workspace

Changing Parent moves the instance between containers. Setting it to nil removes it from the hierarchy without disconnecting its events.

Find a child

OperationBehavior when absent
parent.ChildNameRaises an error for a missing named child
parent:FindFirstChild("ChildName")Returns nil
parent:WaitForChild("ChildName", 5)Waits up to five seconds
parent:FindFirstChildOfClass("Part")Returns nil

Use FindFirstChild for an optional child. Pass true as its second argument to search descendants. Use WaitForChild when a required child may still be replicating. Always handle timeout results.

Luau
local marker = workspace:WaitForChild("Marker", 5)
if marker then
  print(marker.Position)
end

Sibling names need not be unique. A name lookup returns the first matching instance, so use distinct names when a lookup must identify one child.

Inspect the hierarchy

GetChildren returns immediate children. GetDescendants traverses the entire subtree. Both return snapshot arrays. Avoid repeated full scans of large trees; track additions and removals with hierarchy events when possible.

Use IsA to include subclasses in class checks.

Luau
for _, child in workspace:GetChildren() do
  if child:IsA("BasePart") then
    print(child.Name)
  end
end

Clone an instance

Clone returns an unparented copy and includes archivable descendants. It returns nil when the source is not archivable. Set properties on the copy before parenting it.

Destroy an instance

Destroy removes the instance and descendants and disconnects their events. ClearAllChildren destroys only the children and descendants.

References held by other scripts do not automatically become nil. Disconnect callbacks on other sources when they no longer need to retain the instance.

Related APIs