Armazenamento KVP em FiveM: guia de SetResourceKvp e GetResourceKvpString

Você quer que um script lembre de uma configuração entre sessões: o volume de um rádio, uma posição HUD, a última aba que um jogador usou em um menu. Uma tabela de banco de dados por configuração é muito, e um arquivo não é possível no cliente. FiveM tem um armazenamento chave-valor integrado exatamente para isso, chamado KVP.

Este artigo cobre as funções, como armazenar tabelas, onde os dados vivem, e o que você não deve colocar nele.

#As funções

KVP armazena um valor sob uma chave. Strings, inteiros e floats têm suas próprias funções:

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

Observe a diferença em "não encontrado": o leitor de string dá nil, enquanto os leitores de número dão 0. Se 0 é um valor válido para sua configuração, armazene como string, ou mantenha uma segunda chave que diz que o valor foi definido.

#Sempre forneça um padrão

Um novo jogador não tem nada salvo ainda, então leia com um fallback:

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

#Armazenando tabelas com json.encode

KVP só conhece strings e números. Para uma tabela, serialize-a:

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á disponível em todo recurso Lua de FiveM, sem importação. Sempre lide com o caso onde a chave não existe, e mantenha a tabela armazenada pequena: este não é um lugar para grandes listas.

Dica: coloque uma versão na tabela, como version = 1. Quando você muda o layout em uma atualização posterior, você pode ler a forma antiga e convertê-la em vez de falhar em um campo faltante.

#Onde está armazenado

KVP do cliente vive no computador do jogador, na pasta de dados FiveM, não em seu servidor. É mantido por recurso e por servidor: a mesma chave no mesmo recurso em outro servidor é um valor diferente, e dois recursos podem ambos usar a chave volume sem se tocar.

Isso tem três consequências:

• Reinstalar FiveM ou limpar sua pasta de dados pode apagá-lo. Se um jogador for instruído a clear the cache, faça-os manter os dados KVP quando puderem.
• Um jogador que joga de dois PCs tem dois conjuntos separados de configurações.
• Você não pode ler KVP de um jogador do servidor. É um recurso do cliente.

Atenção: os dados são um arquivo local simples sob o controle do jogador. Um jogador pode editá-lo, deletá-lo ou copiá-lo para um amigo. Nunca mantenha nada que o servidor deve confiar lá: dinheiro, itens, permissões, cooldowns, flags de ban ou progresso com recompensa.

#KVP do servidor

As mesmas funções existem no servidor. Lá os dados são salvos no disco do servidor na pasta de dados do servidor, por recurso, e sobrevivem a reinicializações:

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

É útil para pequenos valores globais que não merecem uma tabela SQL: um contador, uma flag de recurso alternada com um comando, a data do último evento. Para qualquer coisa com muitas linhas, ou que você queira consultar, editar manualmente ou fazer backup com o resto de seus dados, use o banco de dados (oxmysql queries guide). KVP do servidor não é visível em sua ferramenta SQL, e backing up the server precisa da pasta de dados também.

#Escrevendo muitas chaves

Cada SetResourceKvp escreve em disco. Se você salvar muitas chaves de uma vez, por exemplo quando um jogador fecha um menu de configurações, FiveM oferece uma variante que não escreve imediatamente e uma chamada que libera o lote:

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

Para um punhado de chaves salvas de vez em quando, as funções normais são boas. Não escreva a cada frame, por exemplo enquanto um slider é arrastado: salve quando o jogador soltá-lo.

#Listando chaves

Para encontrar todas as chaves que começam com um prefixo, use as funções de busca:

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

Prefixe suas chaves com um nome curto do que elas são (hud:x, hud:y) para que isso permaneça fácil.

#Quando usar algo diferente

#Lista de verificação