State bags FiveM : Entity(entity).state, GlobalState et handlers

Vous voulez partager une petite donnée entre le serveur et chaque client, par exemple qu'un véhicule est verrouillé, qu'un joueur est menotté, ou la météo actuelle, et vous continuer à écrire des événements qui se déclenchent à chaque changement et se désynchronisent pour les joueurs qui rejoignent plus tard. Les state bags sont la réponse intégrée.

Cet article couvre les types de state bags, comment les écrire et les lire, comment réagir aux changements, et quand un événement reste le meilleur choix.

#Qu'est-ce qu'un state bag

Un state bag est un magasin ressemblant à une table de clés et de valeurs attaché à quelque chose. Le runtime le synchronise pour vous, y compris pour les joueurs qui se connectent après que la valeur ait été définie. FiveM vous en propose trois types :

Dans tous les cas, vous lisez une valeur comme un champ normal :

local locked = Entity(vehicle).state.locked

#Écrire depuis le serveur

Sur le serveur, définir une valeur la réplique aux clients qui peuvent voir ce bag :

-- server
local veh = CreateVehicle(`adder`, 215.0, -810.0, 30.7, 90.0, true, true)
Entity(veh).state.locked = true

Player(source).state.cuffed = true

GlobalState.weather = 'RAIN'

Vous pouvez utiliser le style de champ ou l'appel explicite, ce qui vous permet également de choisir si la valeur est répliquée :

Entity(veh).state:set('locked', true, true)

:set(key, value, replicated) prend la clé, la valeur et un booléen. Avec true, la valeur est envoyée de l'autre côté, avec false, elle reste du côté qui l'a écrite.

Conseil : Les valeurs peuvent être des nombres, des chaînes, des booléens et des tables. Une table est copiée quand vous la définissez, donc modifier un champ dans la table que vous relisez ne fait rien. Définissez la table entière à nouveau pour la mettre à jour.

#Écrire depuis le client

Un client peut écrire sur son propre joueur et sur les entités qu'il contrôle, mais une affectation simple reste locale :

-- client
LocalPlayer.state:set('inService', true, true)  -- replicated to the server
LocalPlayer.state.hasMask = true                -- local only

Le serveur peut alors lire Player(source).state.inService. Considérez-le comme non approuvé : un client modifié peut écrire n'importe quelle valeur. Utilisez l'état écrit par le client pour la commodité, comme les drapeaux d'interface utilisateur, et conservez tout ce qui a un avantage attaché (argent, emploi, permissions) sur le serveur.

GlobalState est l'opposé : le serveur l'écrit, chaque client le lit, et les clients ne peuvent pas le changer pour les autres.

-- client
local weather = GlobalState.weather

#Réagir aux changements

Au lieu d'interroger une valeur dans une boucle, enregistrez un handler qui s'exécute quand une clé change. C'est la raison principale d'utiliser les state bags côté client :

-- AddStateBagChangeHandler(keyFilter, bagFilter, handler)
AddStateBagChangeHandler('locked', nil, function(bagName, key, value, reserved, replicated)
    local entity = GetEntityFromStateBagName(bagName)
    if entity == 0 then return end

    SetVehicleDoorsLocked(entity, value and 2 or 1)
end)

• keyFilter est la clé qui vous intéresse, ou nil pour toutes les clés.
• bagFilter limite le bag, par exemple un bag de joueur spécifique, ou nil pour tous.
• bagName ressemble à entity:1234, player:5 ou global. GetEntityFromStateBagName transforme un bag d'entité en un handle, et GetPlayerFromStateBagName fait de même pour un bag de joueur.

Sur le client, l'entité peut ne pas exister encore quand le handler s'exécute, par exemple pour un véhicule qui est encore en train de charger. GetEntityFromStateBagName peut retourner 0 dans ce cas, donc vérifiez-le. Relire l'état quand l'entité charge est la bonne habitude.

La même fonction existe sur le serveur, où elle est pratique pour réagir à un client écrivant une valeur répliquée.

#State bags ou événements

Une bonne règle : les événements sont pour les actions, les state bags sont pour l'état. Si un joueur qui rejoint à mi-chemin aurait besoin d'être informé de la même chose à nouveau, c'est de l'état. Voir événements client et serveur pour l'autre côté.

#Erreurs courantes

• L'utiliser pour des données volumineuses ou qui changent rapidement. Chaque changement est envoyé sur le réseau. N'écrivez pas une position dans un state bag à chaque frame.
• Faire confiance aux écritures du client. Validez tout ce qu'un client définit avant d'agir dessus sur le serveur.
• S'attendre à ce que le handler s'exécute avant que l'entité existe. Vérifiez le handle et relisez l'état quand l'entité apparaît.
• Muter une table en place. Lire state.items, y ajouter et ne pas la définir à nouveau ne change rien.
• Oublier la réinitialisation. L'état sur une entité disparaît avec l'entité, mais l'état sur un joueur ou GlobalState persiste jusqu'à ce que vous le effiez, donc définissez-le à nil quand vous avez terminé.

Player(source).state.cuffed = nil

#Liste de contrôle