Signal

Getting it

local Signal = Engine:GetPackage("Signal")

Overview

A Signal is a lightweight replacement for a BindableEvent. It never crosses the client/server boundary and it passes tables by reference, so there is no copying cost. Engine uses Signals for every event it exposes, such as TimeService.TimeScaleChanged or JunkService.LeakDetected, so once you know Signal you know how to listen to all of them.

local Signal = Engine:GetPackage("Signal")

local scored = Signal.new()

local connection = scored:Connect(function(player, points)
	print(player.Name, "scored", points)
end)

scored:Fire(somePlayer, 10)

connection:Disconnect()

Handlers run in their own thread (Engine reuses one thread while handlers don't yield), so a handler that yields or errors never blocks the code that called :Fire() or the other handlers. Handlers connected later run first.

Constructor

new

Signal.new<T...>(): Signal<T...>

Creates an empty Signal. Annotate it to get typed handlers: Signal.new() :: Signal.Signal<Player, number>.

Methods

Connect

signal:Connect(fn: (T...) -> ()): Connection

Calls fn every time the signal fires. Returns a Connection. Connecting to a destroyed signal returns a connection that is already disconnected.

Once

signal:Once(fn: (T...) -> ()): Connection

Like :Connect(), but disconnects itself before the first call.

Fire

signal:Fire(...: T...)

Calls every connected handler with the given arguments.

Wait

signal:Wait(timeout: number?): T...

Yields the current thread until the signal fires and returns the fired values. With a timeout in seconds, it returns nothing once the timeout passes without a fire.

local player, points = scored:Wait(5)
if player == nil then
	print("nobody scored within 5 seconds")
end

GetConnections

signal:GetConnections(): { Connection }

Returns every connection the signal currently holds.

DisconnectAll

signal:DisconnectAll()

Disconnects every handler. The signal stays usable.

Destroy

signal:Destroy()

Disconnects every handler and marks the signal destroyed. Later :Connect() calls return dead connections.

IsDestroyed

signal:IsDestroyed(): boolean

Connection

The object returned by :Connect() and :Once().

Types

export type Signal<T...>
export type Connection

Reading or writing a member that does not exist on a Signal or Connection raises an error instead of returning nil, so typos fail loudly.