|
|
| (95 intermediate revisions by 13 users not shown) |
| Line 1: |
Line 1: |
| {{CatUp|Class reference}}
| | #redirect [[RBXScriptSignal]] |
| | |
| __NOTOC__
| |
| | |
| 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.
| |
| | |
| ==Functions==
| |
| Events have these functions:
| |
| | |
| *[[#connect|connect]]( [[Function]] callback )
| |
| *[[#wait|wait]]()
| |
| *<strike>disconnect( [[Function]] callback )</strike>
| |
| | |
| === 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|connection]] object.
| |
| {{example|<pre>
| |
| Workspace.Part.Touched:connect( myTouchedFunction )
| |
| </pre>
| |
| This causes myTouchedFunction to be called whenever that [[Part]] is touched by another Part.
| |
| }}
| |
| | |
| === 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.
| |
| The return value is arguments of the event.
| |
| {{example|<pre>
| |
| local otherPart = Workspace.Part.Touched:wait()
| |
| </pre>
| |
| This causes the script to stop and wait for that [[Part]] to be touched by another Part.
| |
| }}
| |
| | |
| == Usage ==
| |
| Take the example of the [[Touched (Event)|Touched]] event of Part:
| |
| {{:Touched (Event)}}
| |
| 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}:
| |
| <pre>
| |
| function onTouched()
| |
| </pre>
| |
| 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:
| |
| <pre>
| |
| function onTouched( otherPart )
| |
| </pre>
| |
| | |
| Finally, we can used the last piece of information to make a connection to that function:
| |
| <pre>
| |
| part.Touched:connect( onTouched )
| |
| </pre>
| |
| | |
| {{example|<pre>local part = Workspace.Part -- your part here
| |
| function onTouched( otherPart )
| |
| otherPart.Transparency = 1 -- make part that touched invisible
| |
| part.BrickColor = BrickColor.Random() -- give this part a new random color
| |
| end
| |
| | |
| part.Touched:connect( onTouched ) -- call onTouched each time something touches
| |
| </pre>}}
| |
| | |
| == Limitations ==
| |
| Connections are also automatically removed if:
| |
| * The called function 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:
| |
| <pre>
| |
| Fri Apr 23 21:50:48 2010 - attempt to call a nil value
| |
| Fri Apr 23 21:50:48 2010 -
| |
| </pre>
| |
| 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 ==
| |
| Using anonymous functions in connect is common:
| |
| <pre>
| |
| part.Touched:connect(
| |
| function( otherPart )
| |
| otherPart.Transparency = 1
| |
| part.BrickColor = BrickColor.Random()
| |
| end -- end for function
| |
| ) -- close paranthesis for connect
| |
| </pre>
| |
| | |
| You can also use anonymous functions to change the arguments:
| |
| <pre>
| |
| player.Chatted:connect(
| |
| function( message, recipient )
| |
| onChatted( player, message ) -- new arguments need to match onChatted function call
| |
| end
| |
| )
| |
| </pre>
| |
| | |
| You can create connections at any time even inside of event functions:
| |
| <pre>
| |
| 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 )
| |
| </pre>
| |
| | |
| = connection =
| |
| The connection object is a special object returned by the connect() method of an Event.
| |
| | |
| == Functions ==
| |
| It has 1 method:
| |
| *[[#disconnect|disconnect]]()
| |
| | |
| === disconnect ===
| |
| The connection object disconnect method, removes the association created by connect. The defined function will no longer be called when the Event occurs.
| |
| | |
| {{example|<pre>
| |
| -- turn on connection
| |
| local conn = part.Touched:connect( onTouched )
| |
| | |
| -- later to turn off connection
| |
| conn:disconnect()
| |
| </pre>}}
| |
