FiveM KVP хранилище: SetResourceKvp и GetResourceKvpString руководство

Вы хотите скрипт помнить настройку между сеансами: громкость радио, позицию HUD, последнюю вкладку которую игрок использовал в меню. Таблица базы данных на настройку это слишком много, и файл невозможен на клиенте. FiveM имеет встроенное хранилище ключ-значение ровно для этого, называется KVP.

Эта статья охватывает функции, как сохранять таблицы, где данные живут, и что вы не должны там помещать.

#Функции

KVP хранит значение под ключом. Строки, целые и плавающие точки имеют свои собственные функции:

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

Отметьте разницу в "не найдено": читатель строк даёт nil, в то время как читатели чисел дают 0. Если 0 это валидное значение для вашей настройки, сохраняйте это как строку, или держите второй ключ который говорит значение было установлено.

#Всегда предоставляйте по умолчанию

Новый игрок ничего не сохранил ещё, поэтому читайте с fallback:

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

#Сохранение таблиц с json.encode

KVP знает только строки и числа. Для таблицы, сериализуйте её:

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 доступен в каждом FiveM Lua ресурсе, без импорта. Всегда обрабатывайте случай где ключ не существует, и держите сохранённую таблицу маленькой: это не место для больших списков.

Совет: поместите версию в таблицу, такую как version = 1. Когда вы измените макет в позднейшем обновлении, вы можете прочитать старую форму и конвертировать её вместо краша на отсутствующем поле.

#Где оно хранится

Клиент KVP живёт на компьютере игрока, в папке данных FiveM, не на вашем сервере. Это держится на ресурс и на сервер: одинаковый ключ в одинаковом ресурсе на другом сервере это другое значение, и два ресурса могут оба использовать ключ volume без трогания друг друга.

Это имеет три последствия:

• Переустановка FiveM или стирание его папки данных может удалить его. Если игроку сказано очистить кеш, попросите их держать данные KVP когда они могут.
• Игрок который играет с двух ПК имеет два отдельных набора настроек.
• Вы не можете читать KVP игрока с сервера. Это клиент функция.

Внимание: данные это обычный локальный файл под контролем игрока. Игрок может редактировать его, удалить его или копировать его другу. Никогда не держите что-либо сервер должен верить там: деньги, предметы, разрешения, cooldowns, флаги банов или прогресс с наградой.

#Сервер KVP

Одинаковые функции существуют на сервере. Там данные сохраняются на диск сервера в папке данных сервера, на ресурс, и переживают перезагрузки:

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

Это удобно для маленьких глобальных значений которые не заслуживают таблицу SQL: счётчик, флаг функции переключённый с команды, дата последнего события. Для чего-либо с много рядами, или что вы хотите запросить, редактировать вручную или резервировать с остальными вашими данными, используйте базу данных (oxmysql руководство запросов). Сервер KVP не видим в вашем SQL инструменте, и резервирование сервера нужна папка данных также.

#Запись много ключей

Каждый SetResourceKvp записывает на диск. Если вы сохраняете много ключей сразу, например когда игрок закрывает меню настроек, FiveM предлагает вариант который не пишет сразу и вызов который очищает пакет:

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

Для горсти ключей сохранённых сейчас и потом, нормальные функции в порядке. Не пишите на каждый кадр, например пока ползунок перетаскивается: сохраняйте когда игрок отпускает.

#Перечисление ключей

Чтобы найти все ключи которые начинаются с префикса, используйте функции поиска:

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

Префиксируйте ваши ключи с коротким именем что они есть (hud:x, hud:y) так что это остаётся легким.

#Когда использовать что-то другое

#Контрольный список