In addition to properties and functions, every object also has events which can be used to set up cause-and-effect systems. Events send out signals when specific things happen in a game, such as a player touching an object or a player connecting to the game. To fire an event is to have it send out such a signal.
Waiting for an Event to Occur
Wait() function will cause the script to pause until the event occurs once. When it does, the function returns the data associated with the event’s firing.
local myPart = game.Workspace.Part -- Wait until another part collides with "myPart" local otherPart = myPart.Touched:Wait() print("myPart was touched by: ", otherPart.Name)
Connecting a Function to an Event
Connect() function can be used when a given function should run every time an event fires. This function immediately returns a connection object. In the example below, we connect a function,
onTouched(), to a
Part in the
Workspace. If another part collides with
myPart, the script prints the name of the other part involved in the collision.
local myPart = game.Workspace.Part local function onTouched(otherPart) print("myPart collided with: ", otherPart.Name) end myPart.Touched:Connect(onTouched)
Disconnecting a Function From an Event
Eventually, you may no longer need a connected function to run when an event fires. To disconnect it, use the
Disconnect() method of the connection object returned by
Remember to Call Disconnect()
Disconnect() when a connection is no longer needed. Forgetting to do so can cause your game to use more resources than necessary. Note, however, that this may not always be necessary; when an object is destroyed, all connections to that object’s events are disconnected automatically.
Almost every event in Roblox will send data relevant to the event’s occurrence. For example, when a
Player joins the game, the
Players/PlayerAdded event fires with a reference to the new player.
local Players = game:GetService("Players") local function onPlayerAdded(player) print("A new player joined: ", player.Name) end Players.PlayerAdded:Connect(onPlayerAdded)
Sometimes you will need to connect a function to an event on an object provided by another event. To do so, define a second local function within the function connected to the first event.
A common example is detecting when a player’s character is spawned into the game. For this, we need to access the
Player/CharacterAdded|CharacterAdded event of the
Player involved in the
local Players = game:GetService("Players") local function onPlayerAdded(player) local function onCharacterAdded(character) print(player.Name .. " spawned in: " .. character:GetFullName()) end player.CharacterAdded:Connect(onCharacterAdded) end Players.PlayerAdded:Connect(onPlayerAdded)
Playerobject is destroyed. This causes the connection to
onPlayerAdded()to be disconnected, so we don't need to call
Disconnect()in this example. In other circumstances where the object in question is not necessarily destroyed, you may need to use a table to keep track of connections to be disconnected later via another function.
Custom Game Events Using BindableEvent
Often times, you will need to define your own events for gameplay, such as when a team scores a goal. You might have one script give that team a point and another script launch some fireworks. For this, you’ll need to use a
BindableEvent which features a single user-fireable event named
You can either use a
BindableEvent that already exists in the game hierarchy or create one using
Instance.new(). Then, call
BindableEvent/Fire|Fire with any relevant data to trigger the
BindableEvent/Event|Event. For example:
-- Step 1: Create or get reference to a BindableEvent -- You don't have to set Parent for the object to work local beGoal = Instance.new("BindableEvent") -- Step 2: Connect a function to the custom event local function onGoalScored(team) team.Score = team.Score + 1 end beGoal.Event:Connect(onGoalScored) -- Somewhere else in your code, fire the event: local Teams = game:GetService("Teams") local redTeam = Teams["Red Team"] beGoal:Fire(redTeam)
Simple data like strings, numbers, booleans, simple tables, and Roblox object references can be sent as event data through
BindableEvent, but more complicated data such as functions or tables with metatables will require a more complicated custom solution. See the documentation for
BindableEvent/Fire|BindableEvent:Fire() for details on the kinds of data that can be sent when firing bindable events.
Roblox runs on a client-server model. As such, some events that fire on the server will replicate and also fire on the client. This depends on the event, but when a game needs to define a custom event to be replicated from server-to-client or vice-versa, a
RemoteEvent can be used. This works similarly to
BindableEvent but is network-ready. For more information, see the
articles/Roblox Client Server Model|Roblox Client-Server Model article.