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
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("Part was touched by: " .. otherPart.Name)
Connecting a Function
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("Part was touched by: " .. otherPart.Name) end myPart.Touched:Connect(onTouched)
Disconnecting a Function
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
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(player.Name .. " joined the game") 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, you’ll 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 you don't need to call
Disconnect()in this case. 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 award 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:
-- Create or get reference to a BindableEvent local beGoal = Instance.new("BindableEvent") -- 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)
BindableEvent, but more complicated data such as functions or tables with metatables will require a more 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.