Przechowywanie FiveM KVP: przewodnik SetResourceKvp i GetResourceKvpString

Chcesz, aby skrypt pamiętał ustawienie między sesjami: głośność radia, pozycję HUD, ostatnią kartę, którą gracz używał w menu. Tabela bazy danych dla każdego ustawienia to za dużo, a plik nie jest możliwy na kliencie. FiveM ma wbudowany magazyn kluczy wartości dokładnie w tym celu, zwany KVP.

Ten artykuł obejmuje funkcje, jak przechowywać tabele, gdzie żyją dane i co nie możesz tam wkładać.

#Funkcje

KVP przechowuje wartość pod kluczem. Stringi, liczby całkowite i zmiennoprzecinkowe mają swoje własne funkcje:

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

Zwróć uwagę na różnicę w "not found": czytnik stringów daje nil, podczas gdy czytniki liczb dają 0. Jeśli 0 to ważna wartość dla Twojego ustawienia, przechowuj ją jako string, lub trzymaj drugi klucz, który mówi, że wartość została ustawiona.

#Zawsze dostarczaj domyślny

Nowy gracz nic nie ma zapisane, więc przeczytaj z rezerwą:

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

#Przechowywanie tabel za pomocą json.encode

KVP zna tylko stringi i liczby. Dla tabeli, serializuj ją:

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 jest dostępny w każdym zasobie Lua FiveM, bez importu. Zawsze obsługuj przypadek, gdzie klucz nie istnieje, i trzymaj przechowywana tabelę małą: to nie jest miejsce dla dużych list.

Wskazówka: umieść wersję w tabeli, taką jak version = 1. Gdy zmienisz układ w późniejszej aktualizacji, możesz przeczytać stary kształt i go przekonwertować zamiast rozbić się na brakującym polu.

#Gdzie to jest przechowywane

Client KVP żyje na komputerze gracza, w folderze danych FiveM, nie na Twoim serwerze. Jest utrzymywany na zasób i na serwer: ten sam klucz w tym samym zasobie na innym serwerze to inny wróżba, i dwa zasoby mogą zarówno użyć klucza volume bez dotykania siebie nawzajem.

To ma trzy konsekwencje:

• Ponowna instalacja FiveM lub wyczyszczenie jego folderu danych może go wymazać. Jeśli gracz jest proszony o clear the cache, niech przechowuje dane KVP, gdy może.
• Gracz, który gra z dwóch PC, ma dwa oddzielne zestawy ustawień.
• Nie możesz przeczytać KVP gracza z serwera. To funkcja klienta.

Ostrzeżenie: dane to zwykły plik lokalny pod kontrolą gracza. Gracz może go edytować, usunąć lub skopiować do przyjaciela. Nigdy nie przechowuj nic, co serwer musi ufać tam: pieniądze, przedmioty, uprawnienia, cooldowny, flagi banu lub postęp z nagrodą.

#Server KVP

Te same funkcje istnieją na serwerze. Tam dane są zapisywane na dysku serwera w folderze danych serwera, na zasób i przetrwają restarty:

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

To jest przydatne do małych globalnych wartości, które nie zasługują na tabelę SQL: licznik, flaga funkcji przełączona z polecenia, data ostatniego zdarzenia. Dla czegokolwiek z wieloma wierszami, lub co chcesz zapytać, edytować ręcznie lub wykonać kopię zapasową z resztą Twoich danych, użyj bazy danych (oxmysql queries guide). Server KVP nie jest widoczny w Twoim narzędziu SQL i backing up the server również potrzebuje folderu danych.

#Pisanie wielu kluczy

Każdy SetResourceKvp pisze na dysk. Jeśli zapiszesz wiele kluczy naraz, na przykład gdy gracz zamyka menu ustawień, FiveM oferuje wariant, który nie pisze od razu i wywołanie, które opróżnia paczkę:

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

Dla garści kluczy zapisywanych teraz i potem, normalne funkcje są w porządku. Nie pisz na każdej klatce, na przykład podczas gdy suwak jest przeciągany: zapisz gdy gracz puści.

#Wyświetlanie kluczy

Aby znaleźć wszystkie klucze, które zaczynają się od prefiksu, użyj funkcji wyszukiwania:

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

Przedrostuj swoje klucze krótką nazwą do czego są (hud:x, hud:y) aby to pozostało łatwe.

#Gdy użyć czegoś innego

#Checklist