Events Guide

All you need to know about Events.

Classes Events

In nanos world, all actions performed by Players or Entities can be obtained through events.

The most basic event to bring an example is the Spawn. Every time an entity is spawned, the event Spawn will be triggered.

Subscribing for Class Events

Registering for events is very easy and straightforward using the method :Subscribe(), let's say we want to know when a Player has joined the server:

Server/Index.lua

Player.Subscribe("Spawn", function(player)
    Console.Log(player:GetName() .. " has joined!")
end)

info

Most events are triggered on both Client and Server sides, only a few exceptions which are indicated by the Availability icons in each event.

Preventing Actions

Some events are triggered before something happens, and allow you to cancel it by returning false. They usually start with Attempt, such as AttemptEnterVehicle:

Server/Index.lua

-- Only allows Characters from team 1 to drive vehicles
Character.Subscribe("AttemptEnterVehicle", function(character, vehicle, seat_index)
    if (seat_index == 0 and character:GetTeam() ~= 1) then
        return false
    end
end)

Unsubscribing of Class Events

Currently there are two ways of unsubscribing from events:

info

Note: Unsubscribing events will always only unregister from events which were registered in the Package you are.

Unsubscribing from all Events

-- This will unregister from all "Spawn" events of Player registered in this Package
Player.Unsubscribe("Spawn")

Unsubscribing from a specific Event Callback

-- Declares the Callback beforehand
function OnSpawnPlayer(player)
    Console.Log(player:GetName() .. " has joined!")
end

-- Subscribes the event, passing the Callback
Player.Subscribe("Spawn", OnSpawnPlayer)

-- Subscribes for the same event, twice
Player.Subscribe("Spawn", function(player)
    Console.Log(player:GetName() .. " has joined again!")
end)

-- Unsubscribes only from the first Callback
Player.Unsubscribe("Spawn", OnSpawnPlayer)

-- This will keep triggering "player has joined again" but will not trigger
-- "player has joined" anymore

tip

Subscribe returns the callback you passed, so you can also unsubscribe anonymous functions later:

local my_callback = Player.Subscribe("Spawn", function(player) end)
Player.Unsubscribe("Spawn", my_callback)

Entity Events

In nanos world it is possible to register for events on specific Entities as well, this way the callback will only be triggered if that specific entity is the event reason.

Subscribing for Entity Events

Server/Index.lua

-- Spawns a Character
local my_character = Character(Vector(0, 0, 100), Rotator(), "nanos-world::SK_Male")

my_character:Subscribe("EnterVehicle", function(self, vehicle)
    -- my_character entered vehicle
end)

tip

Note that once the entity is destroyed, all events registered for it will be unregistered automatically!

Unsubscribing of Entity Events

Currently there are two ways of unsubscribing from events:

info

Note: Unsubscribing events will always only unregister from events which were registered in the Package you are.

Unsubscribing from all Entity Events

-- This will unregister from all "EnterVehicle" events of this specific Character
-- registered in this Package
my_character:Unsubscribe("EnterVehicle")

Unsubscribing from a specific Entity Event Callback

-- Declares the Callback beforehand
function OnCharacterEnteredVehicle(character, vehicle)
    -- Entered vehicle!
end

-- Subscribes the event, passing the Callback
my_character:Subscribe("EnterVehicle", OnCharacterEnteredVehicle)

-- Subscribes for the same event, twice
my_character:Subscribe("EnterVehicle", function(character, vehicle)
    -- Entered vehicle again!
end)

-- Unsubscribes only from the first Callback
my_character:Unsubscribe("EnterVehicle", OnCharacterEnteredVehicle)

Custom Events

In nanos world, it is possible to define and call Custom Events. Please refer to Events Static Class for the technical documentation.

Custom events are user-created events which you can subscribe or call to all other Packages. There are two kinds of them:

Local Events

Local events stay on the same side (server or client) and reach every Package on that side. Use Events.Call() to trigger them and Events.Subscribe() to listen:

Server/Index.lua

-- In any Package
Events.Subscribe("RoundStarted", function(round_number)
    Console.Log("Round %d started!", round_number)
end)

-- In any other Package (or the same one)
Events.Call("RoundStarted", 1)

Remote Events

Remote events travel through the network, from the client to the server or from the server to clients. Listen to them with Events.SubscribeRemote():

Server/Index.lua

-- On the server, the first parameter is always the Player who sent it
Events.SubscribeRemote("BuyItem", function(player, item_name)
    Console.Log("%s wants to buy %s", player:GetName(), item_name)

    -- Answers only to that Player
    Events.CallRemote("ItemBought", player, Reliability.Reliable, item_name)
end)

Client/Index.lua

Events.SubscribeRemote("ItemBought", function(item_name)
    Console.Log("I bought %s!", item_name)
end)

-- Sends it to the server
Events.CallRemote("BuyItem", Reliability.Reliable, "medkit")

The server can also send events to a list of Players with CallRemotePlayers, to everyone with BroadcastRemote, or only to Players in a radius or dimension with BroadcastRemoteInRadius and BroadcastRemoteDimension.

A few important things to keep in mind:

• Reliability: Reliability.Reliable guarantees the event arrives, in order. Reliability.Unreliable is cheaper but can be lost, use it for events sent very often (e.g. every Tick) where only the latest one matters.
• Entities can be passed as parameters, they arrive as the same entity on the other side (as long as it exists there).
• Local and remote are separate: Events.Subscribe doesn't receive remote events and Events.SubscribeRemote doesn't receive local ones.
• Never trust the client: a player can send any remote event with any parameters, always validate them on the server. See the Never Trust the Client guide.

tip

Entities also have their own remote events, which are triggered on a specific entity. See :CallRemoteEvent() and :BroadcastRemoteEvent().