Developer Preview

Storage natives

Resource KVP – a small key/value store saved on disk, separately for every resource.

Developer Preview. Scripting is live on Neighborly servers – everything on these pages works today. The API is young, so tell us what you need next on Discord.

Resource KVP – a small key/value store saved on disk, separately for every resource. For real server data use the database from the State & storage guide.

Open in the natives browser Search all 199 natives at once.

SetResourceKvp

Shared
void SetResourceKvp(string key, any value)

Saves a value in this resource's KVP store – on the player's PC in client scripts (per server), in the server's data folder in server scripts.

Writes are saved to disk right away. KVP is perfect for small settings; for data that must survive a reinstall or be shared between servers, use the server database.

Parameters

ParameterTypeDescription
keystringThe key.
valueanyA string, number, boolean or table. Tables are stored as JSON.

Returns

Nothing (void).

Example

RegisterNUICallback('setTheme', function(data, cb)
    local theme = data.theme == 'dark' and 'dark' or 'light'
    SetResourceKvp('theme', theme)
    cb({ ok = true, theme = theme })
end)

GetResourceKvp

Shared
any GetResourceKvp(string key)

Reads a value from this resource's KVP store.

Returns values with their original type – numbers stay numbers and tables come back as tables.

Parameters

ParameterTypeDescription
keystringThe key.

Returns

any The saved value, or nil.

Example

AddEventHandler('onClientResourceStart', function(name)
    if name == GetCurrentResourceName() then
        SendNUIMessage({ action = 'theme', theme = GetResourceKvp('theme') or 'light' })
    end
end)

DeleteResourceKvp

Shared
void DeleteResourceKvp(string key)

Removes a key from this resource's KVP store.

Deleting a key that doesn't exist is fine and does nothing.

Parameters

ParameterTypeDescription
keystringThe key.

Returns

Nothing (void).

Example

RegisterCommand('resetphone', function()
    for _, key in ipairs(GetResourceKvpKeys('phone:')) do
        DeleteResourceKvp(key)
    end
    exports.neighborly:notify({ text = 'Phone settings reset.' })
end, false)

GetResourceKvpKeys

Shared
table GetResourceKvpKeys(string prefix)

Lists the keys in this resource's KVP store.

Use prefixes like 'lot:' or 'player:' in your keys so you can list one kind of entry at a time.

Parameters

ParameterTypeDescription
prefixstringOnly keys starting with this text. '' for all.

Returns

table List of keys.

Example

AddEventHandler('onResourceStart', function(name)
    if name ~= GetCurrentResourceName() then
        return
    end
    for _, key in ipairs(GetResourceKvpKeys('sign:')) do
        local zoneId = key:sub(6)
        Lot(zoneId).state:set('sign', GetResourceKvp(key), true)
    end
end)

SetResourceKvpInt

Shared
void SetResourceKvpInt(string key, int value)

Saves a whole number.

Available in client and server scripts. On a client it reads the synced copy of the world, which can trail the server by a moment – make gameplay decisions on the server.

Parameters

ParameterTypeDescription
keystringThe key.
valueintWhole number.

Returns

Nothing (void).

Example

SetResourceKvpInt('visits', GetResourceKvpInt('visits') + 1)

GetResourceKvpInt

Shared
int GetResourceKvpInt(string key)

Reads a whole number saved with SetResourceKvpInt.

Available in client and server scripts. On a client it reads the synced copy of the world, which can trail the server by a moment – make gameplay decisions on the server.

Parameters

ParameterTypeDescription
keystringThe key.

Returns

int The number, or 0.

Example

print('This server started me', GetResourceKvpInt('boots'), 'times')

SetResourceKvpFloat

Shared
void SetResourceKvpFloat(string key, number value)

Saves a number with decimals.

Available in client and server scripts. On a client it reads the synced copy of the world, which can trail the server by a moment – make gameplay decisions on the server.

Parameters

ParameterTypeDescription
keystringThe key.
valuenumberNumber.

Returns

Nothing (void).

Example

SetResourceKvpFloat('volume', 0.65)

GetResourceKvpFloat

Shared
number GetResourceKvpFloat(string key)

Reads a number saved with SetResourceKvpFloat.

Available in client and server scripts. On a client it reads the synced copy of the world, which can trail the server by a moment – make gameplay decisions on the server.

Parameters

ParameterTypeDescription
keystringThe key.

Returns

number The number, or 0.0.

Example

local volume = GetResourceKvpFloat('volume')

GetResourceKvpString

Shared
string? GetResourceKvpString(string key)

Reads a value as a string. Tables come back as JSON text.

Available in client and server scripts. On a client it reads the synced copy of the world, which can trail the server by a moment – make gameplay decisions on the server.

Parameters

ParameterTypeDescription
keystringThe key.

Returns

string? The value as text.

Example

local theme = GetResourceKvpString('theme') or 'light'

SetResourceKvpNoSync

Shared
void SetResourceKvpNoSync(string key, any value)

Same as SetResourceKvp. Writes are always batched, so it exists for FiveM compatibility.

Available in client and server scripts. On a client it reads the synced copy of the world, which can trail the server by a moment – make gameplay decisions on the server.

Parameters

ParameterTypeDescription
keystringThe key.
valueanyValue.

Returns

Nothing (void).

Example

SetResourceKvpNoSync('lastSeen', os.time())

FlushResourceKvp

Shared
void FlushResourceKvp()

Writes pending KVP changes to disk now. Neighborly flushes on its own within half a second and when the resource stops.

Available in client and server scripts. On a client it reads the synced copy of the world, which can trail the server by a moment – make gameplay decisions on the server.

Parameters

This native takes no parameters.

Returns

Nothing (void).

Example

AddEventHandler('onResourceStop', function(name)
    if name == GetCurrentResourceName() then
        FlushResourceKvp()
    end
end)

StartFindKvp

Shared
int StartFindKvp(string prefix)

Starts going through every key that begins with a prefix. Use FindKvp to step and EndFindKvp when done.

Available in client and server scripts. On a client it reads the synced copy of the world, which can trail the server by a moment – make gameplay decisions on the server.

Parameters

ParameterTypeDescription
prefixstringKey prefix.

Returns

int A search handle.

Example

local handle = StartFindKvp('score:')
local key = FindKvp(handle)
while key do
    print(key, GetResourceKvpInt(key))
    key = FindKvp(handle)
end
EndFindKvp(handle)

FindKvp

Shared
string? FindKvp(int handle)

Returns the next key of a search.

Available in client and server scripts. On a client it reads the synced copy of the world, which can trail the server by a moment – make gameplay decisions on the server.

Parameters

ParameterTypeDescription
handleintHandle from StartFindKvp.

Returns

string? The next key, or nil at the end.

Example

local handle = StartFindKvp('note:')
local count = 0
while FindKvp(handle) do
    count = count + 1
end
EndFindKvp(handle)

EndFindKvp

Shared
void EndFindKvp(int handle)

Ends a search and frees its handle.

Available in client and server scripts. On a client it reads the synced copy of the world, which can trail the server by a moment – make gameplay decisions on the server.

Parameters

ParameterTypeDescription
handleintHandle from StartFindKvp.

Returns

Nothing (void).

Example

EndFindKvp(handle)