RBXScriptSignal

(Redirected from Events)
"Event" redirects here. For the Event event of the BindableEvent object, see API:Class/BindableEvent/Event.

RBXScriptSignal, more commonly known as an Event, is a special kind of Roblox object. It provides a way for user-defined functions, called listeners, to be called when something happens in the game. When a certain event happens, the Event is fired, calling any listeners that are connected to the Event. An Event may also pass arguments to each listener, to provide extra information about the event that occurred.

Quick Reference[edit]

Functions
SyntaxDescription
RBXScriptConnection RBXScriptSignal:connect(function<void>(Tuple<Variant>) func)Establishes a function to be called whenever the event occurs.

Returns an RBXScriptConnection object associated with the connection.

Tuple<Variant> RBXScriptSignal:wait()Yields the current thread until this signal is fired. Returns what was fired to the signal.
RBXScriptConnection RBXScriptSignal:Connect(function<void>(Tuple<Variant>) func)Establishes a function to be called whenever the event occurs.

Returns an RBXScriptConnection object associated with the connection.

Tuple<Variant> RBXScriptSignal:Wait()Yields the current thread until this signal is fired. Returns what was fired to the signal.

Methods[edit]

Connect[edit]

RBXScriptConnection RBXScriptSignal:Connect(function<void>(Tuple<Variant>) func)

Description:
Establishes a function to be called whenever the event occurs. Returns an RBXScriptConnection object associated with the connection.

connect[edit]

RBXScriptConnection RBXScriptSignal:connect(function<void>(Tuple<Variant>) func)

Description:
Establishes a function to be called whenever the event occurs. Returns an RBXScriptConnection object associated with the connection.

Wait[edit]

Tuple<Variant> RBXScriptSignal:Wait()

Description:
Yields the current thread until this signal is fired. Returns what was fired to the signal.

wait[edit]

Tuple<Variant> RBXScriptSignal:wait()

Description:
Yields the current thread until this signal is fired. Returns what was fired to the signal.


Usage[edit]

Take the example of the Touched event of the Part instance. The procedure for connecting a function to an Event is to pass the function as an argument in a call to the Connect method of the Event:

local part = Instance.new("Part")
part.Parent = game.Workspace
 
function onTouched()
	print("I've run into something!")
end
 
part.Touched:Connect(onTouched)


A common convention is to give the function a name that indicates it will be called when the Event fires, such as "OnEventName" ("when EventName occurs"), though it is important to note that this is not required.

When the Touched event is fired, it passes a value to each connected listener (in this case, our OnTouched function). As referenced above, this value is a BasePart, so we can expect the value to always be a BasePart (which can be a Part, WedgePart, etc).

local part = Instance.new("Part")
 
function onTouched(hitPart)
	print("I've run into a " .. hitPart.Name .. " brick!")
end
 
part.Touched:Connect(onTouched)


Passing an anonymous function to Connect can be convenient and often results in slightly shorter code. This can be useful if you only need to connect a listener to an Event once.

local part = Instance.new("Part")
 
part.Touched:Connect(function(hitPart)
	print("I've run into a " .. hitPart.Name .. " brick!")
end)


You can also use this to "change" the arguments. In the following example, we use an anonymous function to pass the touched Part as well as the touching Part to a generic OnTouched function:

local function onTouched(touchingPart, touchedPart)
	print(touchingPart .. " has touched " .. touchedPart.Name)
end
 
local part = Instance.new("Part")
part.Touched:Connect(function(hitPart)
	onTouched(part, hitPart)
end)

You may want to disconnect the listener from the Event, so that it will no longer be called when the Event fires. This can be accomplished using the Connection object returned by the Connect method. See below for how to use it.

Notes[edit]

A connection is automatically disconnected if:

  • The event listener generates an error before the thread yields.
  • The script itself is removed or reparented.
  • The object the Event relates to is destroyed with the Destroy method.

When an event is fired,

  1. Threads that are waiting on a call to wait are resumed
  2. Each connected function is called in separate threads, in the reverse order they were connected (last connected, first called)

There is only one known (and very obscure) case when remote events sent to the server may be discarded:

  1. You do *not* subscribe to the remote event on the server side
  2. You send events to the server; they are being queued on the server side and await the subscriber
  3. Once the queue gets bigger than 256 items and you still have not connected to the event the rest will drop
  4. Connecting a subscriber will process the entire queue and start processing new items