Archiviazione FiveM KVP: guida a SetResourceKvp e GetResourceKvpString

Vuoi che uno script ricordi un'impostazione tra le sessioni: il volume di una radio, una posizione dell'HUD, l'ultima scheda che un giocatore ha utilizzato in un menu. Una tabella di database per impostazione è troppo, e un file non è possibile sul client. FiveM ha un archivio di coppie chiave-valore integrato esattamente per questo, chiamato KVP.

Questo articolo copre le funzioni, come memorizzare tabelle, dove vivono i dati e cosa non devi mettere in esso.

#Le funzioni

KVP memorizza un valore sotto una chiave. Stringhe, interi e float hanno le loro funzioni:

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

Nota la differenza in "non trovato": il lettore di stringhe dà nil, mentre i lettori di numeri danno 0. Se 0 è un valore valido per la tua impostazione, memorizzalo come stringa, o mantieni una seconda chiave che dice che il valore è stato impostato.

#Fornisci sempre un valore predefinito

Un nuovo giocatore non ha nulla salvato ancora, quindi leggi con un fallback:

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

#Memorizzazione di tabelle con json.encode

KVP conosce solo stringhe e numeri. Per una tabella, serializzala:

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 è disponibile in ogni risorsa Lua FiveM, senza importazione. Gestisci sempre il caso in cui la chiave non esiste, e mantieni la tabella memorizzata piccola: questo non è un posto per grandi elenchi.

Suggerimento: metti una versione nella tabella, come version = 1. Quando cambi il layout in un aggiornamento successivo, puoi leggere la forma vecchia e convertirla invece di bloccarti su un campo mancante.

#Dove è memorizzato

Il KVP del client vive sul computer del giocatore, nella cartella dati FiveM, non sul tuo server. Viene mantenuto per risorsa e per server: la stessa chiave nella stessa risorsa su un altro server è un valore diverso, e due risorse possono entrambe usare la chiave volume senza toccarsi.

Questo ha tre conseguenze:

• Reinstallare FiveM o cancellare la sua cartella dati può cancellarlo. Se a un giocatore viene detto di pulire la cache, faigli mantenere i dati KVP quando può.
• Un giocatore che gioca da due PC ha due set di impostazioni separati.
• Non puoi leggere il KVP di un giocatore dal server. È una funzione client.

Attenzione: i dati sono un file locale semplice sotto il controllo del giocatore. Un giocatore può modificarlo, cancellarlo o copiarlo a un amico. Non mantenere mai nulla di cui il server deve fidarsi lì: denaro, oggetti, autorizzazioni, cooldown, flag di ban o progresso con una ricompensa.

#Server KVP

Le stesse funzioni esistono sul server. Lì i dati vengono salvati sul disco del server nella cartella dei dati del server, per risorsa, e sopravvivono ai riavvii:

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

È utile per piccoli valori globali che non meritano una tabella SQL: un contatore, un flag di funzione attivato con un comando, la data dell'ultimo evento. Per qualsiasi cosa con molte righe, o che vuoi interrogare, modificare a mano o eseguire il backup con il resto dei tuoi dati, usa il database (guida alle query oxmysql). Il server KVP non è visibile nel tuo strumento SQL, e il backup del server ha bisogno della cartella dei dati pure.

#Scrivere molte chiavi

Ogni SetResourceKvp scrive su disco. Se salvi molte chiavi contemporaneamente, ad esempio quando un giocatore chiude un menu di impostazioni, FiveM offre una variante che non scrive immediatamente e una chiamata che scarica il batch:

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

Per una manciata di chiavi salvate di tanto in tanto, le funzioni normali vanno bene. Non scrivere su ogni frame, ad esempio mentre un cursore viene trascinato: salva quando il giocatore lascia andare.

#Elenco delle chiavi

Per trovare tutte le chiavi che iniziano con un prefisso, usa le funzioni di ricerca:

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

Prefissa le tue chiavi con un nome breve per quello che sono (hud:x, hud:y) in modo che questo rimanga facile.

#Quando usare qualcosa d'altro

#Elenco di controllo