Version: bleeding-edge 🩸

🚩 Events

Subscribe for user-defined Events.

🗿Static Class

This is a Static Class. Access it's methods directly with .. It's not possible to spawn new instances.

💂Authority

This static class can be accessed on both 🟧 Client and 🟦 Server side.

🧑‍💻API Source

This page is auto-generated! The Functions, Properties and Events described here are defined in our GitHub's API Repository! Feel free to commit suggestions and changes to the source .json API files!

🎒 Examples

info

Remote means the other side, e.g.: if I'm the Client, the remote is the Server. If I'm the Server, the remote is the Client.

Basic Usage

Client/Index.lua
-- register for a local Event (local = client only)
Events.Subscribe("MyLocalEvent", function(my_text)
    Console.Log("Event received locally! " .. my_text)
    -- outputs "Event received locally! hello nanos world!"
end)

-- calls a local Event in all Local Packages
Events.Call("MyLocalEvent", "hello nanos world!")

-- register for a server Event (remote = server)
Events.SubscribeRemote("MyClientEvent", function(my_text)
    Console.Log("Event received from server! " .. my_text)
    -- outputs "Event received from server! hello nanos world!"
end)

-- calls a remote Event in all Server Packages
Events.CallRemote("MyServerEvent", Reliability.Reliable, "hello nanos world!")

info

On Server, registering for remote events has an addition parameter: Player, which is the client who sent the event.

Server/Index.lua
-- register for a local Event (local = server only)
Events.Subscribe("MyLocalEvent", function(my_text)
    Console.Log("Event received locally! " .. my_text)
    -- outputs "Event received locally! hello nanos world!"
end)

-- calls a local Event in all Local Packages
Events.Call("MyLocalEvent", "hello nanos world!")

-- register for a client Event (remote = client)
Events.SubscribeRemote("MyServerEvent", function(player, my_text)
    Console.Log(player:GetName() .. " sent an event from client! " .. my_text)
    -- outputs "Syed sent an event from client! hello nanos world!"

    -- sends an "answer" to the player which sent this event
    Events.CallRemote("MyClientEvent", player, Reliability.Reliable, "hello nanos world! message only for you!")
end)

-- sends a remote Event to all Players in all Client Packages
Events.BroadcastRemote("MyClientEvent", Reliability.Reliable, "hello nanos world!")

Passing entities through Events

-- register for an Event (remote or local)
Events.Subscribe("MyAnotherEvent", function(my_text, my_vector, my_character, my_number)
    Console.Log("Event received! " .. my_text .. " " .. my_vector.X .. " " .. my_character:GetViewMode() .. " " .. my_number)
    -- outputs "Event received! hello nanos world! 123 1 456"
end)

-- passing Characters through events
local my_temp_character = Character()

-- calls a local Event in all Local Packages
Events.Call("MyEvent", "hello nanos world!", Vector(123, 123, 123), my_temp_character, 456)

-- calls a remote Event in all Server Packages
Events.CallRemote("MyEvent", Reliability.Reliable, "hello nanos world!", Vector(123, 123, 123), my_temp_character, 456)

tip

You can find more examples and a comprehensive guide at the Events Guide page.

Events Guidecore-concepts/scripting/events-guide

🗿 Static Functions

Returns	Name	Description
	`BroadcastRemote`	Broadcasts a remote custom Event from the Server to ALL currently connected Players (Server ➔ Clients)
	`BroadcastRemoteDimension`	Broadcasts a remote custom Event from the Server to all Players currently residing in the specified Dimension (Server ➔ Clients)
	`BroadcastRemoteInRadius`	Broadcasts a remote custom Event from the Server to all Players within a specific location radius (Server ➔ Clients)
	`BroadcastRemoteInRadiusDimension`	Broadcasts a remote custom Event from the Server to all Players within a specific location radius AND residing in a specific Dimension (Server ➔ Clients)
	`Call`	Triggers a local custom Event across all Packages on the same side (Client ➔ Client OR Server ➔ Server)
	`CallRemote`	Triggers a remote custom Event from the Client to the Server (Client ➔ Server)
	`CallRemote`	Triggers a remote custom Event from the Server to the Client (Server ➔ Client)
	`CallRemotePlayers`	Triggers a remote custom Event from the Server to an array of specific Players (Server ➔ Clients)
function	`Subscribe`	Listens for a local custom Event triggered by `Events.Call()` on the same side
function	`SubscribeRemote`	Listens for a network custom Event
	`Unsubscribe`	Removes a local event listener previously registered with `Events.Subscribe()`
	`UnsubscribeRemote`	Removes a network event listener previously registered with `Events.SubscribeRemote()`

`BroadcastRemote`

Broadcasts a remote custom Event from the Server to ALL currently connected Players (Server ➔ Clients)
Must be caught using Events.SubscribeRemote() on the Clients

Events.BroadcastRemote(event_name, reliability?, args...?)

Type	Parameter	Default	Description
string	`event_name`	Required parameter	The Event Name to trigger the event
Reliability	`reliability?`	`Reliability.Reliable`	The network reliability rule
any	`args...?`	`nil`	Arguments to pass to the event

See also SubscribeRemote.

`BroadcastRemoteDimension`

Broadcasts a remote custom Event from the Server to all Players currently residing in the specified Dimension (Server ➔ Clients)
Must be caught using Events.SubscribeRemote() on the Clients

Events.BroadcastRemoteDimension(event_name, dimension, reliability?, args...?)

Type	Parameter	Default	Description
string	`event_name`	Required parameter	The Event Name to trigger the event
integer	`dimension`	Required parameter	The Dimension to send this event
Reliability	`reliability?`	`Reliability.Reliable`	The network reliability rule
any	`args...?`	`nil`	Arguments to pass to the event

See also SubscribeRemote.

`BroadcastRemoteInRadius`

Broadcasts a remote custom Event from the Server to all Players within a specific location radius (Server ➔ Clients)
Must be caught using Events.SubscribeRemote() on the Clients

Events.BroadcastRemoteInRadius(event_name, location, radius, reliability?, args...?)

Type	Parameter	Default	Description
string	`event_name`	Required parameter	The Event Name to trigger the event
Vector	`location`	Required parameter	The location used to calculate the event radius
number	`radius`	Required parameter	The radius to send this event
Reliability	`reliability?`	`Reliability.Reliable`	The network reliability rule
any	`args...?`	`nil`	Arguments to pass to the event

See also SubscribeRemote.

`BroadcastRemoteInRadiusDimension`

Broadcasts a remote custom Event from the Server to all Players within a specific location radius AND residing in a specific Dimension (Server ➔ Clients)
Must be caught using Events.SubscribeRemote() on the Clients

Events.BroadcastRemoteInRadiusDimension(event_name, location, radius, dimension, reliability?, args...?)

Type	Parameter	Default	Description
string	`event_name`	Required parameter	The Event Name to trigger the event
Vector	`location`	Required parameter	The location used to calculate the event radius
number	`radius`	Required parameter	The radius to send this event
integer	`dimension`	Required parameter	The Dimension to send this event
Reliability	`reliability?`	`Reliability.Reliable`	The network reliability rule
any	`args...?`	`nil`	Arguments to pass to the event

See also SubscribeRemote.

`Call`

Triggers a local custom Event across all Packages on the same side (Client ➔ Client OR Server ➔ Server)
Must be caught using Events.Subscribe()

Events.Call(event_name, args...?)

Type	Parameter	Default	Description
string	`event_name`	Required parameter	The Event Name to trigger the event
any	`args...?`	`nil`	Arguments to pass to the event

`CallRemote`

Triggers a remote custom Event from the Client to the Server (Client ➔ Server)
The receiving Server will implicitly receive the sender 'Player' as the very first argument before your custom args
Must be caught using Events.SubscribeRemote()

Events.CallRemote(event_name, reliability?, args...?)

Type	Parameter	Default	Description
string	`event_name`	Required parameter	The Event Name to trigger the event
Reliability	`reliability?`	`Reliability.Reliable`	The network reliability rule
any	`args...?`	`nil`	Arguments to pass to the event

See also SubscribeRemote.

`CallRemote`

Triggers a remote custom Event from the Server to the Client (Server ➔ Client)
Must be caught using Events.SubscribeRemote()

Events.CallRemote(event_name, player, reliability?, args...?)

Type	Parameter	Default	Description
string	`event_name`	Required parameter	The Event Name to trigger the event
Player	`player`	Required parameter	The remote player to send this event
Reliability	`reliability?`	`Reliability.Reliable`	The network reliability rule
any	`args...?`	`nil`	Arguments to pass to the event

See also SubscribeRemote.

`CallRemotePlayers`

Triggers a remote custom Event from the Server to an array of specific Players (Server ➔ Clients)
More network-efficient than looping CallRemote
Must be caught using Events.SubscribeRemote() on the Clients

Events.CallRemotePlayers(event_name, players, reliability?, args...?)

Type	Parameter	Default	Description
string	`event_name`	Required parameter	The Event Name to trigger the event
table of Player	`players`	Required parameter	The remote players to send this event
Reliability	`reliability?`	`Reliability.Reliable`	The network reliability rule
any	`args...?`	`nil`	Arguments to pass to the event

See also SubscribeRemote.

`Subscribe`

Listens for a local custom Event triggered by Events.Call() on the same side

— Returns function (the subscribed callback itself).

local ret = Events.Subscribe(event_name, callback)

Type	Parameter	Default	Description
string	`event_name`	Required parameter	The Event Name to subscribe
function	`callback`	Required parameter	The callback function to execute

`SubscribeRemote`

Listens for a network custom Event
If on the Server, it catches Events.CallRemote() from Clients (receiving the sender 'Player' as the first argument)
If on the Client, it catches Server broadcasts and remote calls

— Returns function (the subscribed callback itself).

local ret = Events.SubscribeRemote(event_name, callback)

Type	Parameter	Default	Description
string	`event_name`	Required parameter	The Event Name to subscribe
function	`callback`	Required parameter	The callback function to execute

`Unsubscribe`

Removes a local event listener previously registered with Events.Subscribe(). If no specific callback function is passed, it removes ALL local listeners for that event name in the current Package

Events.Unsubscribe(event_name, callback?)

Type	Parameter	Default	Description
string	`event_name`	Required parameter	The Event Name to unsubscribe
function	`callback?`	`nil`	The callback function to unsubscribe

`UnsubscribeRemote`

Removes a network event listener previously registered with Events.SubscribeRemote(). If no specific callback function is passed, it removes ALL remote listeners for that event name in the current Package

Events.UnsubscribeRemote(event_name, callback?)

Type	Parameter	Default	Description
string	`event_name`	Required parameter	The Event Name to unsubscribe
function	`callback?`	`nil`	The callback function to unsubscribe

🎒 Examples​

Basic Usage​

Passing entities through Events​

🗿 Static Functions​

BroadcastRemote

BroadcastRemoteDimension

BroadcastRemoteInRadius

BroadcastRemoteInRadiusDimension

Call

CallRemote

CallRemote

CallRemotePlayers

Subscribe

SubscribeRemote

Unsubscribe

UnsubscribeRemote

🎒 Examples

Basic Usage

Passing entities through Events

🗿 Static Functions

`BroadcastRemote`

`BroadcastRemoteDimension`

`BroadcastRemoteInRadius`

`BroadcastRemoteInRadiusDimension`

`Call`

`CallRemote`

`CallRemote`

`CallRemotePlayers`

`Subscribe`

`SubscribeRemote`

`Unsubscribe`

`UnsubscribeRemote`