Almacenamiento KVP en FiveM: guía de SetResourceKvp y GetResourceKvpString

Quieres que un script recuerde una configuración entre sesiones: el volumen de una radio, una posición de HUD, la última pestaña que un jugador usó en un menú. Una tabla de base de datos por configuración es demasiado, y un archivo no es posible en el cliente. FiveM tiene un almacén clave-valor integrado para exactamente esto, llamado KVP.

Este artículo cubre las funciones, cómo almacenar tablas, dónde viven los datos, y qué no debes poner en él.

#Las funciones

KVP almacena un valor bajo una clave. Las cadenas, enteros y flotantes tienen sus propias funciones:

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

Ten en cuenta la diferencia en "no encontrado": el lector de cadena da nil, mientras que los lectores de números dan 0. Si 0 es un valor válido para tu configuración, guárdalo como cadena, o mantén una segunda clave que diga que el valor fue establecido.

#Siempre proporciona un valor por defecto

Un jugador nuevo no tiene nada guardado aún, así que lee con un respaldo:

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

#Almacenar tablas con json.encode

KVP solo conoce cadenas y números. Para una tabla, serialízala:

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á disponible en cada recurso Lua de FiveM, sin importación. Siempre maneja el caso donde la clave no existe, y mantén la tabla almacenada pequeña: este no es un lugar para listas grandes.

Consejo: pon una versión en la tabla, como version = 1. Cuando cambies el diseño en una actualización posterior, puedes leer la forma antigua y convertirla en lugar de bloquearte en un campo faltante.

#Dónde se almacena

El KVP del cliente vive en la computadora del jugador, en la carpeta de datos de FiveM, no en tu servidor. Se mantiene por recurso y por servidor: la misma clave en el mismo recurso en otro servidor es un valor diferente, y dos recursos pueden ambos usar la clave volume sin tocarse.

Eso tiene tres consecuencias:

• Reinstalar FiveM o limpiar su carpeta de datos puede borrarlo. Si a un jugador se le dice que limpia el caché, pídele que mantenga los datos de KVP cuando pueda.
• Un jugador que juega desde dos PCs tiene dos conjuntos separados de configuración.
• No puedes leer el KVP de un jugador desde el servidor. Es una característica del cliente.

Cuidado: los datos son un archivo local simple bajo el control del jugador. Un jugador puede editarlo, borrarlo o copiarlo a un amigo. Nunca mantengas nada que el servidor deba confiar ahí: dinero, objetos, permisos, cooldowns, banderas de ban o progreso con recompensa.

#KVP del servidor

Las mismas funciones existen en el servidor. Ahí los datos se guardan en el disco del servidor en la carpeta de datos del servidor, por recurso, y sobreviven reinicios:

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

Es práctico para pequeños valores globales que no merecen una tabla SQL: un contador, una bandera de característica toggled con un comando, la fecha del último evento. Para cualquier cosa con muchas filas, o que quieras consultar, editar a mano o respaldar con el resto de tus datos, usa la base de datos (guía de consultas oxmysql). El KVP del servidor no es visible en tu herramienta SQL, y respaldar el servidor necesita la carpeta de datos también.

#Escribiendo muchas claves

Cada SetResourceKvp escribe al disco. Si guardas muchas claves a la vez, por ejemplo cuando un jugador cierra un menú de configuración, FiveM ofrece una variante que no escribe inmediatamente y una llamada que vacía el lote:

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

Para un puñado de claves guardadas de vez en cuando, las funciones normales están bien. No escribas en cada fotograma, por ejemplo mientras se arrastra un deslizador: guarda cuando el jugador suelta.

#Listando claves

Para encontrar todas las claves que comienzan con un prefijo, usa las funciones de búsqueda:

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

Prefija tus claves con un nombre corto de lo que son (hud:x, hud:y) así esto permanece fácil.

#Cuándo usar algo más

#Checklist