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
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
| Parameter | Type | Description |
|---|---|---|
key | string | The key. |
value | any | A 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
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
| Parameter | Type | Description |
|---|---|---|
key | string | The 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
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
| Parameter | Type | Description |
|---|---|---|
key | string | The 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
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
| Parameter | Type | Description |
|---|---|---|
prefix | string | Only 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
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
| Parameter | Type | Description |
|---|---|---|
key | string | The key. |
value | int | Whole number. |
Returns
Nothing (void).
Example
SetResourceKvpInt('visits', GetResourceKvpInt('visits') + 1)GetResourceKvpInt
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
| Parameter | Type | Description |
|---|---|---|
key | string | The key. |
Returns
int The number, or 0.
Example
print('This server started me', GetResourceKvpInt('boots'), 'times')SetResourceKvpFloat
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
| Parameter | Type | Description |
|---|---|---|
key | string | The key. |
value | number | Number. |
Returns
Nothing (void).
Example
SetResourceKvpFloat('volume', 0.65)GetResourceKvpFloat
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
| Parameter | Type | Description |
|---|---|---|
key | string | The key. |
Returns
number The number, or 0.0.
Example
local volume = GetResourceKvpFloat('volume')GetResourceKvpString
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
| Parameter | Type | Description |
|---|---|---|
key | string | The key. |
Returns
string? The value as text.
Example
local theme = GetResourceKvpString('theme') or 'light'SetResourceKvpNoSync
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
| Parameter | Type | Description |
|---|---|---|
key | string | The key. |
value | any | Value. |
Returns
Nothing (void).
Example
SetResourceKvpNoSync('lastSeen', os.time())DeleteResourceKvpNoSync
void DeleteResourceKvpNoSync(string key)Same as DeleteResourceKvp.
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
| Parameter | Type | Description |
|---|---|---|
key | string | The key. |
Returns
Nothing (void).
Example
DeleteResourceKvpNoSync('lastSeen')FlushResourceKvp
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
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
| Parameter | Type | Description |
|---|---|---|
prefix | string | Key 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
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
| Parameter | Type | Description |
|---|---|---|
handle | int | Handle 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
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
| Parameter | Type | Description |
|---|---|---|
handle | int | Handle from StartFindKvp. |
Returns
Nothing (void).
Example
EndFindKvp(handle)