RBXScriptSignal

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

{{{1}}}

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 valid function. If you misspell the name or otherwise give an invalid function you'll get an error when the event next triggers:

Fri Apr 23 21:50:48 2010 - attempt to call a nil value
Fri Apr 23 21:50:48 2010 - 

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.