Guide des événements

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

Évènements de classe

Dans nanos world, toutes les actions des joueurs ou des entités peuvent être captées grâce aux événements.

L'exemple le plus simple est l'événement Spawn. Chaque fois qu'une entité apparaît, l'événement Spawn est déclenché.

S'abonner à des Évènements de classe

S'abonner à un événement est très simple avec la méthode :Subscribe(). Imaginons qu'on veuille savoir quand un joueur rejoint le serveur :

Server/Index.lua

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

info

La plupart des événements sont déclenchés côté client et côté serveur, à quelques exceptions près, signalées par les icônes de disponibilité sur chaque événement.

Empêcher des actions

Certains événements sont déclenchés avant qu'une action ait lieu, et permettent de l'annuler en renvoyant false. Leur nom commence généralement par Attempt, comme 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

Il existe actuellement deux façons de se désabonner d'un événement :

info

Remarque : se désabonner ne retire toujours que les abonnements faits dans le Package où vous vous trouvez.

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 renvoie le callback que vous avez passé, vous pouvez donc aussi désabonner plus tard des fonctions anonymes :

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é

Il existe actuellement deux façons de se désabonner d'un événement :

info

Remarque : se désabonner ne retire toujours que les abonnements faits dans le Package où vous vous trouvez.

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. Consultez la classe statique Events pour la documentation technique.

Les événements personnalisés sont des événements créés par vous, que tous les autres Packages peuvent appeler ou écouter. Il en existe deux sortes :

Événements locaux

Les événements locaux restent du même côté (serveur ou client) et atteignent tous les Packages de ce côté. Utilisez Events.Call() pour les déclencher et Events.Subscribe() pour les écouter :

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)

Événements distants

Les événements distants passent par le réseau, du client vers le serveur ou du serveur vers les clients. Écoutez-les avec 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")

Le serveur peut aussi envoyer des événements à une liste de joueurs avec CallRemotePlayers, à tout le monde avec BroadcastRemote, ou seulement aux joueurs dans un rayon ou une dimension avec BroadcastRemoteInRadius et BroadcastRemoteDimension.

Quelques points importants à garder en tête :

• Fiabilité : Reliability.Reliable garantit que l'événement arrive, et dans l'ordre. Reliability.Unreliable coûte moins cher mais peut se perdre : utilisez-le pour les événements envoyés très souvent (par ex. à chaque Tick), quand seul le dernier compte.
• Les entités peuvent être passées en paramètre : elles arrivent comme la même entité de l'autre côté (tant qu'elle y existe).
• Local et distant sont séparés : Events.Subscribe ne reçoit pas les événements distants, et Events.SubscribeRemote ne reçoit pas les événements locaux.
• Ne faites jamais confiance au client : un joueur peut envoyer n'importe quel événement distant avec n'importe quels paramètres, validez-les toujours sur le serveur. Voir le guide Ne jamais faire confiance au client.

tip

Les entités ont aussi leurs propres événements distants, déclenchés sur une entité précise. Voir :CallRemoteEvent() et :BroadcastRemoteEvent().