Stockage KVP FiveM : guide SetResourceKvp et GetResourceKvpString

Vous voulez qu'un script mémorise un paramètre entre les sessions : le volume d'une radio, une position HUD, le dernier onglet qu'un joueur a utilisé dans un menu. Une table de base de données par paramètre est trop, et un fichier n'est pas possible sur le client. FiveM a un magasin de paires clé-valeur intégré pour exactement cela, appelé KVP.

Cet article couvre les fonctions, comment stocker les tables, où vivent les données, et ce que vous ne devez pas y mettre.

#Les fonctions

KVP stocke une valeur sous une clé. Les chaînes, les entiers et les flottants ont leurs propres fonctions :

SetResourceKvp('volume', '0.6')
local volume = GetResourceKvpString('volume')   -- '0.6', or nil if it was never saved

SetResourceKvpInt('hud:x', 40)
local x = GetResourceKvpInt('hud:x')            -- 40, or 0 if it was never saved

DeleteResourceKvp('volume')

Remarquez la différence dans « non trouvé » : le lecteur de chaîne donne nil, tandis que les lecteurs de nombres donnent 0. Si 0 est une valeur valide pour votre paramètre, stockez-le en tant que chaîne, ou gardez une deuxième clé qui dit que la valeur a été définie.

#Toujours fournir une valeur par défaut

Un nouveau joueur n'a rien enregistré pour le moment, donc lisez avec une solution de secours :

local function getVolume()
    local saved = GetResourceKvpString('volume')
    return saved and tonumber(saved) or 0.5
end

#Stocker des tables avec json.encode

KVP ne connaît que les chaînes et les nombres. Pour une table, sérializez-la :

local settings = { volume = 0.6, hud = { x = 40, y = 12 }, tabs = { 'home', 'bank' } }
SetResourceKvp('settings', json.encode(settings))

local raw = GetResourceKvpString('settings')
local settings = raw and json.decode(raw) or { volume = 0.5, hud = { x = 0, y = 0 }, tabs = {} }

json est disponible dans chaque ressource Lua FiveM, sans importation. Gérez toujours le cas où la clé n'existe pas, et gardez la table stockée petite : ce n'est pas une place pour de grandes listes.

Conseil : mettez une version dans la table, comme version = 1. Quand vous changez la disposition dans une mise à jour ultérieure, vous pouvez lire l'ancienne forme et la convertir au lieu de planter sur un champ manquant.

#Où c'est stocké

KVP client vit sur l'ordinateur du joueur, dans le dossier de données FiveM, pas sur votre serveur. Il est gardé par ressource et par serveur : la même clé dans la même ressource sur un autre serveur est une valeur différente, et deux ressources peuvent toutes deux utiliser la clé volume sans se toucher.

Cela a trois conséquences :

• Réinstaller FiveM ou effacer son dossier de données peut l'effacer. Si un joueur est invité à effacer le cache, demandez-lui de conserver les données KVP quand il le peut.
• Un joueur qui joue à partir de deux PC a deux séries distinctes de paramètres.
• Vous ne pouvez pas lire le KVP d'un joueur à partir du serveur. C'est une fonction client.

Attention : les données sont un fichier local simple sous le contrôle du joueur. Un joueur peut l'éditer, l'effacer ou le copier à un ami. Ne gardez jamais rien que le serveur doit faire confiance là : argent, articles, autorisations, cooldowns, drapeaux d'interdiction ou progrès avec une récompense.

#KVP serveur

Les mêmes fonctions existent sur le serveur. Là, les données sont sauvegardées sur le disque du serveur dans le dossier de données du serveur, par ressource, et survivent aux redémarrages :

-- server
SetResourceKvp('last_restart', tostring(os.time()))
local last = GetResourceKvpString('last_restart')

C'est pratique pour les petites valeurs globales qui ne méritent pas une table SQL : un compteur, un drapeau de fonctionnalité basculé avec une commande, la date du dernier événement. Pour quoi que ce soit avec de nombreuses lignes, ou que vous voulez interroger, éditer à la main ou sauvegarder avec le reste de vos données, utilisez la base de données (guide des requêtes oxmysql). KVP serveur n'est pas visible dans votre outil SQL, et sauvegarder le serveur a besoin du dossier de données aussi.

#Écrire beaucoup de clés

Chaque SetResourceKvp écrit sur le disque. Si vous enregistrez de nombreuses clés à la fois, par exemple quand un joueur ferme un menu de paramètres, FiveM offre une variante qui n'écrit pas immédiatement et un appel qui vide le lot :

SetResourceKvpNoSync('a', '1')
SetResourceKvpNoSync('b', '2')
SetResourceKvpNoSync('c', '3')
FlushResourceKvp()

Pour une poignée de clés enregistrées de temps en temps, les fonctions normales conviennent. N'écrivez pas à chaque image, par exemple tandis qu'un curseur est entraîné : enregistrez quand le joueur le lâche.

#Énumération des clés

Pour trouver toutes les clés qui commencent par un préfixe, utilisez les fonctions de recherche :

local handle = StartFindKvp('hud:')
if handle ~= -1 then
    local key
    repeat
        key = FindKvp(handle)
        if key then print(key, GetResourceKvpString(key)) end
    until not key
    EndFindKvp(handle)
end

Préfixez vos clés avec un court nom pour ce qu'elles sont (hud:x, hud:y) pour que cela reste facile.

#Quand utiliser quelque chose d'autre

#Liste de contrôle