Event
Event provides a messaging system for sending data between server and clients, or broadcasting game state changes. Think of events as a way to say "something happened" and notify interested listeners with optional data.
Common uses:
- Client tells server about player action (button clicked, item collected)
- Server tells client(s) about game updates (score changed, round started)
- Broadcasting announcements to all players
- Triggering UI updates or gameplay effects
How it works:
- Create an event with a unique name: local myEvent = Event.new("EventName")
- Connect listeners to respond: myEvent:Connect(function(data) ... end)
- Fire the event to send data: myEvent:FireServer(data) or myEvent:FireAllClients(data)
Parameters you can pass:
- Types: string, number, boolean, table, Vector3, Player objects
- Avoid large tables (under 1KB recommended) - use Storage or Inventory for big data
IMPORTANT: Event names must be unique within each script
- Different scripts can have events with the same name (they're separate)
- Within one script, each event name can only be used once
- In ClientAndServer scripts, matching event names on client/server sides automatically connect
Performance tips:
- FireAllClients sends to everyone - use sparingly for important updates only
- For frequent per-player updates, use FireClient instead
- Events are fast but not instant - expect small network delay (~50-200ms)
- If client disconnects mid-event, it's safely ignored (no error)
Properties
The unique name identifier for this event.
print("Event name: " .. myEvent.name)
Methods
Connects a callback function to this event. The callback is invoked whenever the event is fired.
IMPORTANT Parameter Handling:
- When receiving from FireServer: First parameter is ALWAYS the player object, followed by your custom parameters
- When receiving from FireClient/FireAllClients: Only your custom parameters (no automatic player object)
Returns an EventConnection that can be used to disconnect later.
--!Type(ClientAndServer)
local event = Event.new("CustomEvent")
-- CLIENT: Connect to receive from server (no player object)
function self:ClientStart()
event:Connect(function(message, score)
print("Received from server: " .. message .. " | Score: " .. score)
end)
end
-- SERVER: Connect to receive from client (player object is first parameter)
function self:ServerStart()
event:Connect(function(player, action, data)
print(player.name .. " sent action: " .. action)
print("Data: " .. tostring(data))
end)
end
--!Type(ClientAndServer)
local event = Event.new("PlayerScore")
-- SERVER: Fire to client (send data)
function self:ServerStart()
event:FireClient(player, "You scored!", 100)
end
-- CLIENT: Receive from server (no player object)
function self:ClientStart()
event:Connect(function(message, points)
print(message) -- "You scored!"
print("Points: " .. points) -- 100
end)
end
--!Type(ClientAndServer)
local event = Event.new("PlayerAction")
-- CLIENT: Fire to server (don't send player)
function self:ClientStart()
event:FireServer("jump", Vector3.new(0, 5, 0))
end
-- SERVER: Receive from client (player is first parameter automatically)
function self:ServerStart()
event:Connect(function(player, action, position)
print(player.name .. " performed: " .. action)
print("Position: " .. tostring(position))
end)
end
Returns
An EventConnection instance that can be used to disconnect the callback.
Fires the event locally in the same context where Fire is called.
- In server scripts: fires on server only
- In client scripts: fires on that specific client only
- Does NOT send across network - for local callbacks only Use this for triggering local code without network communication.
local event = Event.new("LocalEvent")
event:Connect(function(message)
print(message)
end)
event:Fire("Hello!")
Parameters
__ELLIPSIS__
Returns
Fires the event to ALL connected clients (called from SERVER side only). Use this to broadcast important updates that everyone needs to know. Performance note: Sends to every player, so use sparingly for critical updates only (round start, game over, etc.) For frequent or player-specific updates, use FireClient or FireClients instead.
-- Server side
local event = Event.new("GlobalAnnouncement")
event:FireAllClients("Game starting in 10 seconds!")
Parameters
__ELLIPSIS__
Returns
Fires the event to all clients except the specified player. Useful for broadcasting actions to other players.
-- Server side
local event = Event.new("PlayerAction")
event:FireAllOtherClients(player, player.name .. " scored a goal!")
Parameters
player
__ELLIPSIS__
Returns
Fires the event to all clients in a specific scene except the specified player. Combines scene filtering with player exclusion.
-- Server side
local event = Event.new("ScenePlayerAction")
event:FireAllOtherSceneClients(scene, player, player.name .. " joined the scene!")
Fires the event to a specific client (called from SERVER side only). Use this to send data or notifications to one specific player. More efficient than FireAllClients when only one player needs to know.
-- Server side
local event = Event.new("PlayerNotification")
event:FireClient(player, "You earned 100 points!")
Parameters
player
__ELLIPSIS__
Returns
Fires the event to multiple specific clients. Called from server to send data to selected players.
-- Server side
local event = Event.new("TeamMessage")
local teamPlayers = { player1, player2, player3 }
event:FireClients(teamPlayers, "Your team won!")
Parameters
players
__ELLIPSIS__
Returns
Fires the event to all clients in a specific scene. Useful for scene-specific events in multi-scene worlds.
-- Server side
local event = Event.new("SceneEvent")
event:FireSceneClients(scene, "Event started in this scene!")
Parameters
scene
__ELLIPSIS__
Returns
Fires the event to the server (called from CLIENT side only). Use this when the client needs to tell the server about a player action or request. The server's Connect callback will automatically receive the player object as the FIRST parameter, followed by your custom parameters. Security note: Always validate client data on server - clients can send anything, including fake/invalid data.
-- Client side
local event = Event.new("PlayerAction")
event:FireServer("jump", player.Position)
Parameters
__ELLIPSIS__
Returns
Updated 13 days ago
