Events Guide

Tout ce que vous devez savoir sur les Évènements.

Évènements de classe

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.

S'abonner à des Évènements 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)

Se désabonner des Évènements 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.

Se désabonner de tous les évènements de classe

-- Ceci affectera tous les évènements "Spawn" de joueur dans le package actuel
Player.Unsubscribe("Spawn")

Se désabonner d'un évènement de classe spécifique

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

Évènements d'entité

Dans nanos world, il est possible de s'abonner à des évènements pour des Entités spécifiques également, par conséquent la méthode de callback sera appelée si cette entité spécifique a déclenché l'évènement.

S'abonner à des Évènements d'entité

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

À savoir qu'une fois l'entité détruite, tous les évènements enregistrés pour celle-ci seront automatiquement retirés !

Se désabonner des Évènements d'entité

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.

Se désabonner de tous les Évènements d'entité

-- Cela va retirer tous les évènements "EnterVehicle" de ce personnage spécifique
-- enregistrés dans ce Package
my_character:Unsubscribe("EnterVehicle")

Se désabonner d'un évènement d'entité spécifique

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

Événements personnalisés

Dans nanos world, il est possible de définir et d'appeler des Évènements personnalisés. 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().