Event: Difference between revisions
>NXTBoy |
>NXTBoy No edit summary |
||
Line 5: | Line 5: | ||
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. | 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 | Events have these methods: | ||
*[[#connect|connect]]([[Function]] callback) | *[[#connect|connect]]([[Function]] callback) | ||
Line 18: | Line 18: | ||
The function is called with the arguments for that event. | The function is called with the arguments for that event. | ||
The connect method returns another special object called a [[#connection|connection]] object. | The connect method returns another special object called a [[#connection|connection]] object. | ||
{{example| | {{example| | ||
game.Workspace.Part.Touched:connect(myTouchedFunction) | game.Workspace.Part.Touched:connect(myTouchedFunction) | ||
This causes myTouchedFunction to be called whenever that [[Part]] is touched by another Part. | This causes myTouchedFunction to be called whenever that [[Part]] is touched by another Part. | ||
}} | }} | ||
=== connectFirst === | === connectFirst === | ||
The connectFirst method acts like the connect method, except that the function provided gets called | The connectFirst method acts like the connect method, except that the function provided gets called ''before'' any other function connected to that event. | ||
=== connectLast === | === connectLast === | ||
The connectLast method acts like the connect method, except that the function provided gets called | The connectLast method acts like the connect method, except that the function provided gets called ''after'' every other function connected to that event. | ||
=== wait === | === wait === | ||
Works like the global [[Function_Dump/Roblox_Specific_Functions|wait]] function except that instead of waiting for a fixed period of time, it waits for the next occurance of the Event. | Works like the global [[Function_Dump/Roblox_Specific_Functions|wait]] function except that instead of waiting for a fixed period of time, it waits for the next occurance of the Event. | ||
The return | The return values are the event arguments. | ||
{{example| | {{example| | ||
local otherPart = Workspace.Part.Touched:wait() | local otherPart = Workspace.Part.Touched:wait() | ||
</pre> | </pre> | ||
This causes the script to stop and wait for that [[Part]] to be touched by another Part. | This causes the script to stop and wait for that [[Part]] to be touched by another Part. | ||
}} | }} | ||
=== deprecated | === disconnect (deprecated) === | ||
The old method of using Event:disconnect method is superceded by [[#disconnect|Connection:disconnect]]. | The old method of using Event:disconnect method is superceded by [[#disconnect|Connection:disconnect]]. | ||
Line 50: | Line 50: | ||
Traditionally, such functions are called "handlers" and are named on{Event Name}: | Traditionally, such functions are called "handlers" and are named on{Event Name}: | ||
function onTouched() | function onTouched() | ||
The arguments that will be passed by the event are given by "Instance otherPart". This means that "otherPart" will be passed and the type will be Instance (which all Parts are). | The arguments that will be passed by the event are given by "Instance otherPart". This means that "otherPart" will be passed and the type will be Instance (which all Parts are). | ||
To allow our function to use that, we defined it as: | To allow our function to use that, we defined it as: | ||
Finally, we can used the last piece of information to | function onTouched(otherPart) | ||
part.Touched:connect(onTouched) | Finally, we can used the last piece of information to bind our function to that event: | ||
part.Touched:connect(onTouched) | |||
{{ | {{Example| | ||
function onTouched(otherPart) | local part = game.Workspace.Part -- your part here | ||
function onTouched(otherPart) | |||
otherPart.Transparency = 1 -- make part that was touched invisible | |||
end | part.BrickColor = BrickColor.Random() -- give this part a new random color | ||
end | |||
part.Touched:connect(onTouched) -- call onTouched each time something touches | part.Touched:connect(onTouched) -- call onTouched each time something touches | ||
Here we are giving "otherPart" to the | Here we are giving "otherPart" as an argument to the event handler, onTouched. | ||
}} | |||
== Limitations == | == Limitations == | ||
Connections are also automatically removed if: | Connections are also automatically removed if: | ||
* The | * The event handler generates an error before the first wait() call. | ||
* The script itself is removed or reparented. | * The script itself is removed or reparented. | ||
Line 101: | Line 100: | ||
otherPart.Transparency = 1 | otherPart.Transparency = 1 | ||
part.BrickColor = BrickColor.Random() | part.BrickColor = BrickColor.Random() | ||
end) -- end anonymous function and connect | end) -- end anonymous function, and `connect` method call | ||
You can also use anonymous functions to change the arguments: | You can also use anonymous functions to change the arguments: |
Revision as of 14:39, 16 July 2011
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:
- connect(Function callback)
- connectFirst(Function callback)
- connectLast(Function callback)
- wait()
disconnect(Function callback)
connect
The connect method establishes a function to be called whenever the event occurs. The function is called with the arguments for that event. The connect method returns another special object called a connection object.
game.Workspace.Part.Touched:connect(myTouchedFunction)
This causes myTouchedFunction to be called whenever that Part is touched by another Part.
connectFirst
The connectFirst method acts like the connect method, except that the function provided gets called before any other function connected to that event.
connectLast
The connectLast method acts like the connect method, except that the function provided gets called after every other function connected to that event.
wait
Works like the global wait function except that instead of waiting for a fixed period of time, it waits for the next occurance of the Event. The return values are the event arguments.
disconnect (deprecated)
The old method of using Event:disconnect method is superceded by Connection:disconnect.
Usage
Take the example of the Touched event of Part:
Touched ( BasePart otherPart ) | |
Description | Fired when another object comes in contact with this object. |
---|---|
Member of: | BasePart |
The first section tells you there's an event named "Touched" which has arguments "Instance otherPart". The middle section explains when the event will occur and why. The last section lists types of objects that have this event.
We use this information to create a function and a "connection" line in our script.
Traditionally, such functions are called "handlers" and are named on{Event Name}:
function onTouched()
The arguments that will be passed by the event are given by "Instance otherPart". This means that "otherPart" will be passed and the type will be Instance (which all Parts are).
To allow our function to use that, we defined it as:
function onTouched(otherPart)
Finally, we can used the last piece of information to bind our function to that event:
part.Touched:connect(onTouched)
Limitations
Connections are also automatically removed if:
- The event handler generates an error before the first wait() call.
- The script itself is removed or reparented.
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.
Advanced Usage
Any function name is valid:
function blah() print("In event") end part.Changed:connect(blah)
Using anonymous functions in connect is common:
part.Touched:connect(function(otherPart) otherPart.Transparency = 1 part.BrickColor = BrickColor.Random() end) -- end anonymous function, and `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)
You can create connections 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)
connection
The connection object is a special object returned by the connect() method of an Event.
Functions
It has 1 method:
Properties
It has 1 property: