Event

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.

Methods

Events have these methods:

Method	Description	Notes
connect(function handler)	Establishes a function to be called whenever the event occurs.
connectFirst(function handler)	Same as connect except handler functions gets called before any other handler.	Protected
connectLast(function handler)	Same as connect except handler functions gets called after all the other handlers.	Protected
wait()	Pauses the script until the event is fired and returns any arguments the event returns.
disconnect(function handler)	Disconnects the specified handler function. Use Connection:disconnect() instead.	Deprecated

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 "Instance 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.

Traditionally, such functions are called "handlers" and are named on{Event Name}:

Example

function onTouched() --code end

The arguments that will be passed by the event are given by the name of the event. In this case it is "Instance otherPart". This means that "otherPart" will be passed and the type of otherPart will be an instance (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:

Example

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.

Example

{{{1}}}

You can also use anonymous functions to change the arguments:

Example

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:

Example

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)

Limitations

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
diconnect()	Disconnects the connection from the event.

Properties

Connections have one property:

Property	Description
Bool connected	True if the connection is connected to an event. Otherwise false.