RBXScriptSignal

"Event" redirects here. For the Event event of the BindableEvent object, see Event (Event).

A RBXScriptSignal, more commonly called an event, is a special kind of Roblox Object. It provides a way for user-defined functions to be called when something happens in the game. A RBXScriptSignal is similar to a property, but instead of holding a variable, events fire when a certain event happens. When a RBXScriptSignal fires, functions that are called "handlers", which are connected, or bound, to the event are ran.

Methods

Events have these methods:

Method	Description	Notes
connect(function handler)	Establishes a function to be called whenever the event occurs. Returns a RBXScriptConnection object.
connectFirst(function handler)	Same as connect except handler functions gets called before any other handler.	Protected and Deprecated
connectLast(function handler)	Same as connect except handler functions gets called after all the other handlers.	Protected and Deprecated
wait()	Pauses the script until the event is fired and returns any arguments the event returns.
disconnect()	Can not be used anymore; prints an error message. Use RBXScriptConnection:disconnect() instead.	Obsolete

Usage

Take the example of the Touched event of the Part instance:

Touched ( BasePart otherPart )
Description	Fired when another object comes in contact with this object.
Member of:	BasePart

The top of the event box tells you that it is an event named "Touched" which has arguments "BasePart otherPart". The middle section explains when the event will fire and why. The last section lists the objects that have this event.

We use this information on the event to create a connection to an event line in our script.

Functions that are called when an event fire are called handlers.

The arguments that will be passed by the event are given by the name of the event. In this case it is "BasePart otherPart". This means that otherPart will be passed and the type of otherPart will be a BasePart (which all Parts are).

To allow our function to use that, we defined it as:

function onTouched(otherPart)
--code
end

Finally, we can use the connection method of events to bind our function to the event.

part.Touched:connect(onTouched)

Here's an example using the Touched event of a Part object.

Example

local part = game.Workspace.Part -- your part here
function onTouched(otherPart)
    otherPart.Transparency = 1            -- make part that was touched invisible
    part.BrickColor = BrickColor.Random() -- give this part a new random color
end

 part.Touched:connect(onTouched) -- call onTouched each time something touches

Here we are giving otherPart as an argument to the event handler, onTouched. When part is touched, the part that touches part will turn invisible and part will become a different color.

Advanced Usage

Any function name is valid:

function blah()
   print("In event")
end
part.Changed:connect(blah)

Using anonymous functions in connect is common and results in slightly shorter code. This can be useful if you only need to connect a function to an event once.

part.Touched:connect(function(otherPart)
    otherPart.Transparency = 1
    part.BrickColor = BrickColor.Random()
end) -- ends the anonymous function and the ''connect'' method call.

You can also use anonymous functions to change the arguments:

player.Chatted:connect(function(message, recipient)
    onChatted(player, message) -- new arguments need to match onChatted function call
end)

Connections can be created at any time, even inside of event functions:

function onChatted(player, message)
    print(player .. " said " .. message)
end

function onPlayerAdded(player)
    player.Chatted:connect(function(message, recipient) 
        onChatted(player, message) 
    end)
end

game.Players.PlayerAdded:connect(onPlayerAdded)

Notes

Connections are automatically disconnected if:

• The event handler generates an error before the first wait() call.
• The script itself is removed or reparented.
• The object the event relates to is destroyed with the Destroy method.

Note: The connect method does not check that the argument is a function/is callable. If you give a value that is not callable (usually, a non-function), you will see an error when the event triggers.

Notice that the error has no script reference or line number. This is because it comes from Roblox itself inside the event generation code.

Connections

The connection object is a special object returned by the connect methods of an Event.

Methods

Connections have one method:

Method	Description
disconnect()	Disconnects the connection from the event.

Properties

Connections have one property:

Property	Description
bool connected	If the connection is connected to an event, true. Otherwise, false.