InstanceHandle

The InstanceHandle data type is a weak reference to an Instance that might not be available locally. Use it to point at an instance that hasn't arrived yet, could stream out, or exists only on another machine, and to pick that instance up once it's there.

A handle always refers to the same target. To reach that target, call InstanceHandle:Wait(), which yields until the instance is available:

local Workspace = game:GetService("Workspace")

local part = Instance.new("Part")
local target = Instance.new("Part")
target.Name = "TargetPart"
part.Parent = Workspace
target.Parent = Workspace

part:SetAttribute("Target", target)

local handle = part:GetAttribute("Target")
local instance = handle:Wait(10)
if instance then
	print("Target is", instance.Name) --> Target is TargetPart
end

Prefer InstanceHandle:Wait() with a timeout so your code runs as soon as the instance shows up. Use InstanceHandle:Get() when you want an immediate answer and can handle nil, such as in code that runs every frame.

Examples#

Attributes#

Attributes use InstanceHandle instead of an ordinary instance reference. Since the handle itself is never nil, you can tell apart an attribute that is missing from one where the instance is not currently present:

local part = Instance.new("Part")

print(part:GetAttribute("Target")) --> nil

part:SetAttribute("Target", InstanceHandle.new(nil))
local handle = part:GetAttribute("Target")
print(handle:Get()) --> nil

InstanceHandle attributes also appear in Instance:GetAttributes(), which can't hold nil values.

Instance:GetAttributeChangedSignal() fires when the attribute is set to a new target or removed. It does not fire when the target streams in or out, or when the target is destroyed. To react to availability, combine the signal with InstanceHandle:Wait():

local part = Instance.new("Part")

part:GetAttributeChangedSignal("Target"):Connect(function()
	local handle = part:GetAttribute("Target")
	if not handle then
		return
	end

	local instance = handle:Wait(10)
	if instance then
		print("New target:", instance.Name)
	end
end)

Remote events#

Pass a handle through a RemoteEvent to give the receiver a reference to an instance it doesn't have yet. The receiver waits for the instance instead of getting nothing.

In a server script, call this function with your remote event, the receiving player, and the model to send:

local function sendHandle(remoteEvent: RemoteEvent, player: Player, spawnedModel: Model)
	local handle = InstanceHandle.new(spawnedModel)
	remoteEvent:FireClient(player, handle)
end

In a client script, call this function with the same remote event to start listening before the server sends the handle:

local function receiveHandles(remoteEvent: RemoteEvent)
	remoteEvent.OnClientEvent:Connect(function(handle)
		local model = handle:Wait(10)
		if model then
			print("Received", model.Name)
		end
	end)
end

Ownership#

A handle acts as a weak reference. It never keeps its target alive. The lifetime of the target is controlled by the rest of your experience: its parent and any ordinary references your scripts hold that prevent it from being garbage collected.

InstanceHandle:Get() and InstanceHandle:Wait() return an ordinary instance reference, which does keep the instance alive for as long as you hold it.

A handle is otherwise lightweight and needs no cleanup.

Equality#

Two handles are equal when they refer to the same target, even if you created them separately and even after the target is gone. All empty handles are equal to each other. Each handle is still a distinct value.

local instance1 = Instance.new("Part")
local instance2 = Instance.new("Part")

local a = InstanceHandle.new(instance1)
local b = InstanceHandle.new(instance1)
local c = InstanceHandle.new(instance2)

print(a == b) --> true
print(a == c) --> false

Equality depends on target identity, so it still works when the target isn't currently available.