|
|
| (37 intermediate revisions by 5 users not shown) |
| Line 1: |
Line 1: |
| 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.
| | #redirect [[RBXScriptSignal]] |
| | |
| ==Methods==
| |
| Events have these methods:
| |
| | |
| {|class="wikitable" style="width: 100%"
| |
| ! 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.||'''Deprecated'''
| |
| |-
| |
| | connectLast([[function]] handler)||Same as connect except handler functions gets called ''after'' all the other handlers.||'''Deprecated'''
| |
| |-
| |
| | 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)|Touched]] event of the Part instance:
| |
| {{:Touched (Event)}}
| |
| {{clear floats}}
| |
| The Top of the event box tells you that it is an event named "Touched" which has arguments "BasePart hit". 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|1=
| |
| <code lua>
| |
| function onTouched()
| |
| --code
| |
| end
| |
| </code>
| |
| }}
| |
| | |
| 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:
| |
| <code lua>
| |
| function onTouched(otherPart)
| |
| --code
| |
| end
| |
| </code>
| |
| | |
| Finally, we can use the connection method of events to bind our function to the event.
| |
| <code lua>
| |
| part.Touched:connect(onTouched)
| |
| </code>
| |
| | |
| Here's an example using the Touched event of a Part object.
| |
| {{Example|
| |
| <code lua>
| |
| 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
| |
| </code>
| |
| Here we are giving "otherPart" as an argument to the event handler, onTouched. When the ''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:
| |
| {{example|
| |
| <code lua>
| |
| function blah()
| |
| print("In event")
| |
| end
| |
| part.Changed:connect(blah)
| |
| </code>
| |
| }}
| |
| | |
| 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|
| |
| <code lua>
| |
| part.Touched:connect(function(otherPart)
| |
| otherPart.Transparency = 1
| |
| part.BrickColor = BrickColor.Random()
| |
| end) -- ends the anonymous function and the ''connect'' method call.
| |
| </code>
| |
| }}
| |
| | |
| You can also use anonymous functions to change the arguments:
| |
| {{example|
| |
| <code lua>
| |
| player.Chatted:connect(function(message, recipient)
| |
| onChatted(player, message) -- new arguments need to match onChatted function call
| |
| end)
| |
| </code>
| |
| }}
| |
| | |
| Connections can be created at any time, even inside of event functions:
| |
| {{example|
| |
| <code lua>
| |
| 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)
| |
| </code>
| |
| }}
| |
| | |
| == 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)|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:
| |
| <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.
| |
| | |
| =Connections=
| |
| The connection object is a special object returned by the connect methods of an Event.
| |
| | |
| == Methods ==
| |
| Connections have one method:
| |
| {|class="wikitable"
| |
| ! Method !! Description
| |
| |-
| |
| | disconnect()||Disconnects the connection from the event.
| |
| |}
| |
| | |
| == Properties ==
| |
| Connections have one property:
| |
| {|class="wikitable"
| |
| ! Property !! Description
| |
| |-
| |
| | [[Bool]] connected||True if the connection is connected to an event. Otherwise false.
| |
| |}
| |
