Events

User defined events can be specified using the Events namespace. The Events namespace uses the following class functions:

Class Functions

Additional Info

The maximum size a networked event can send is 128 bytes and all networked events are subjected to a rate limit of 10 events per second.

If strings are used to broadcast byte encoded data over the network (via Events.BroadcastToPlayer, Events.BroadcastToAllPlayers or Events.BroadcastToServer) then their characters must have ASCII values within the range 1-127. Strings used locally and not sent over the network (i. e. Events.Broadcast) can use the full 0-255 range.

Examples

Example using:

BroadcastToAllPlayers

This event connection allows the server to send a message to all players. In this example, two scripts communicate over the network. The first one is on the server as child of a Trigger and the second one is in a Client Context. The server is authoritative over the state of the flag being captured and listens for overlaps on the Trigger. When a new team captures the flag a message is sent to all clients with information about who captured and what team they belong to.

Server script:

local teamHasFlag = 0

function OnBeginOverlap(trigger, other)
    if other and other:IsA("Player") and other.team ~= teamHasFlag then
        teamHasFlag = other.team

        local resultCode, errorMsg = Events.BroadcastToAllPlayers("FlagCaptured", other.name, other.team)
        print("Server sent FlagCaptured event. Result Code = " .. resultCode .. ", error message = " .. errorMsg)
    end
end

script.parent.beginOverlapEvent:Connect(OnBeginOverlap)

--[[#description
    Client script:
]]
function OnFlagCaptured(playerName, playerTeam)
    local message = playerName .. " captured the flag for team " .. playerTeam

    UI.PrintToScreen(message, Color.MAGENTA)
    print(message)
end

Events.Connect("FlagCaptured", OnFlagCaptured)

See also: other.IsA | Player.team | CoreLua.print | CoreObject.parent | Trigger.beginOverlapEvent | UI.PrintToScreen | Events.Connect | Event.Connect

Example using:

BroadcastToPlayer

If your script runs on a server, you can broadcast game-changing information to your players. In this example, the OnExecute function was connected to an ability object's executeEvent. This bandage healing ability depends on a few conditions, such as bandages being available in the inventory and the player having actually lost any hit points. If one of the conditions is not true, the broadcast function is used for delivering a user interface message that only that player will see.

local ABILITY

function OnExecute(ability)
    if ability.owner:GetResource("Bandages") <= 0 then
        Events.BroadcastToPlayer(ability.owner, "BannerSubMessage", "No Bandages to Apply")
        return
    end

    if ability.owner.hitPoints < ability.owner.maxHitPoints then
        ability.owner:ApplyDamage(Damage.New(-30))
        ability.owner:RemoveResource("Bandages", 1)
    else
        Events.BroadcastToPlayer(ability.owner, "BannerSubMessage", "Full Health")
    end
end

ABILITY.executeEvent:Connect(OnExecute)

See also: Ability.owner | Player.GetResource | Damage.New | Event.Connect

Example using:

Connect

Broadcast

The Events namespace allows two separate scripts to communicate without the need to reference each other directly. In this example, two scripts communicate through a custom "GameStateChanged" event. The first one has the beginnings of a state machine and broadcasts the event each time the state changes. The second script listens for that specific event. This is a non-networked message.

Primary script that drives the state machine:

local currentState = ""

function SetState(newState)
    currentState = newState
    Events.Broadcast("GameStateChanged", newState)
end

function Tick(deltaTime)
    SetState("Lobby")
    Task.Wait(1)
    SetState("Playing")
    Task.Wait(3)
end

--[[#description
    A separate script that listens to event changes:
]]
function OnStateChanged(newState)
    print("New State = " .. newState)
end

Events.Connect("GameStateChanged", OnStateChanged)

See also: Task.Wait | CoreLua.Tick

Example using:

ConnectForPlayer

BroadcastToServer

This event connection allows the server to listen for broadcasts that originate from clients. In this example, two scripts communicate over the network. The first one is in a Server Context and the second one is in a Client Context. The client can send input data to the server, in this case their cursor's position.

Server script:

function OnPlayerInputData(player, data)
    print("Player " .. player.name .. " sent  data = " .. tostring(data))
end

Events.ConnectForPlayer("CursorPosition", OnPlayerInputData)

--[[#description
    Client script:
]]
UI.SetCursorVisible(true)

function Tick(deltaTime)
    local cursorPos = Input.GetCursorPosition()
    Events.BroadcastToServer("CursorPosition", cursorPos)
    Task.Wait(0.25)
end

See also: Player.name | UI.SetCursorVisible | Input.GetCursorPosition | CoreLua.Tick | Task.Wait