Events Guide

Tudo o que você precisa saber sobre os eventos.

Eventos de aulas

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.

Inscrevendo-se para Eventos de Classe

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)

Cancelando assinatura de Eventos de Classe

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.

Cancelando assinatura de todos os eventos

-- Isto irá cancelar o registro de todos os eventos "Spawn" do jogador registrado neste pacote
Player.Unsubscribe("Spawn")

Cancelando a assinatura de um Callback de Evento específico

-- 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)

Eventos de Entidade

No mundo do nanos é possível registrar eventos em entidades específicas também Desta forma, o retorno de chamada só será acionado se a entidade específica for o motivo do evento.

Inscrevendo-se para Eventos de Entidade

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 que uma vez que a entidade é destruída, todos os eventos registrados serão cancelados automaticamente!

Cancelando assinatura de Eventos de Entidade

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.

Cancelando assinatura de todos os eventos da entidade

-- Isso irá cancelar o registro de todos os eventos "EnterVehicle" deste Personagem específico
-- registrado nesse Pacote
meu_character:Unsubscribe("EnterVehicle")

Desinscrevendo-se de um Callback de evento de entidade específica

-- 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)

Eventos Personalizados

No mundo do nano, é possível definir e chamar eventos personalizados. 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().