FiveM KVP Speicher: SetResourceKvp und GetResourceKvpString Anleitung

Du möchtest, dass ein Skript eine Einstellung zwischen Sessions merkt: die Lautstärke eines Radios, eine HUD-Position, der letzte Tab, den ein Spieler in einem Menü verwendet hat. Eine Datenbank-Tabelle pro Einstellung ist zu viel, und eine Datei ist auf dem Client nicht möglich. FiveM hat einen eingebauten Key-Value-Speicher für genau dies, genannt KVP.

Dieser Artikel behandelt die Funktionen, wie man Tabellen speichert, wo die Daten leben und was man nicht darin speichern darf.

#Die Funktionen

KVP speichert einen Wert unter einem Schlüssel. Strings, Integrale und Gleitkommazahlen haben ihre eigenen Funktionen:

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

Beachte den Unterschied bei "nicht gefunden": der String-Leser gibt nil, während die Zahlen-Leser 0 geben. Wenn 0 ein gültiger Wert für deine Einstellung ist, speichere es als String, oder behalte einen zweiten Schlüssel, der sagt, dass der Wert gesetzt wurde.

#Gib immer einen Standard an

Ein neuer Spieler hat noch nichts gespeichert, daher lies mit einem Fallback:

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

#Speichere Tabellen mit json.encode

KVP kennt nur Strings und Zahlen. Für eine Tabelle, serialisiere sie:

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 ist in jeder FiveM Lua-Resource verfügbar, ohne Import. Behandle immer den Fall, wo der Schlüssel nicht existiert, und behalte die gespeicherte Tabelle klein: dies ist kein Platz für große Listen.

Tipp: Lege eine Version in die Tabelle, wie version = 1. Wenn du die Layout in einer späteren Aktualisierung änderst, kannst du die alte Form lesen und konvertieren, statt auf einem fehlenden Feld zu zeigen.

#Wo es gespeichert wird

Client KVP lebt auf dem Computer des Spielers, im FiveM-Datenordner, nicht auf deinem Server. Es wird pro Resource und pro Server behalten: der gleiche Schlüssel in der gleichen Resource auf einem anderen Server ist ein anderer Wert, und zwei Resources können beide den Schlüssel volume nutzen, ohne sich gegenseitig zu berühren.

Das hat drei Konsequenzen:

• Die Neuinstallation von FiveM oder das Löschen seines Datenordners kann es löschen. Wenn ein Spieler aufgefordert wird, den Cache zu leeren, lass ihn die KVP-Daten behalten, wenn er kann.
• Ein Spieler, der von zwei PCs spielt, hat zwei separate Einstellungs-Sets.
• Du kannst die KVP eines Spielers nicht vom Server lesen. Es ist eine Client-Funktion.

Achtung: die Daten sind eine einfache lokale Datei unter der Kontrolle des Spielers. Ein Spieler kann sie bearbeiten, löschen oder zu einem Freund kopieren. Halte niemals etwas, das der Server vertrauen muss: Geld, Gegenstände, Berechtigungen, Cooldowns, Ban-Flaggen oder Fortschritt mit einer Belohnung.

#Server KVP

Die gleichen Funktionen existieren auf dem Server. Dort werden die Daten auf der Festplatte des Servers im Server-Datenordner gespeichert, pro Resource, und überstehen Neustarts:

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

Es ist praktisch für kleine globale Werte, die keine SQL-Tabelle verdienen: einen Zähler, eine Funktionsflagge, die mit einem Befehl umgeschaltet wird, das Datum des letzten Ereignisses. Für alles mit vielen Zeilen, oder das du abfragen, manuell bearbeiten oder mit dem Rest deiner Daten sichern möchtest, nutze die Datenbank (oxmysql Queries Guide). Server KVP ist nicht in deinem SQL-Tool sichtbar, und eine Sicherung des Servers braucht auch den Datenordner.

#Schreibe viele Schlüssel

Jeder SetResourceKvp schreibt auf die Festplatte. Wenn du viele Schlüssel auf einmal speicherst, zum Beispiel wenn ein Spieler ein Einstellungsmenü schließt, bietet FiveM eine Variante, die nicht sofort schreibt und einen Aufruf, der den Batch spült:

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

Für eine Handvoll Schlüssel, die jetzt und dann gespeichert werden, sind die normalen Funktionen in Ordnung. Schreibe nicht auf jedem Frame, zum Beispiel während ein Schieber gezogen wird: speichere, wenn der Spieler ihn loslässt.

#Auflistungs-Schlüssel

Um alle Schlüssel zu finden, die mit einem Präfix beginnen, nutze die Suchfunktionen:

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äfix deine Schlüssel mit einem kurzen Namen für das, was sie sind (hud:x, hud:y), damit dies leicht bleibt.

#Wann man etwas anderes nutzt

#Checkliste