Developer Preview

Resource natives

Information about resources and their files.

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.

Information about resources and their files.

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

Natives marked Restricted only work in resources the server owner trusts: add_ace resource.my_resource neighborly.restricted allow.

GetCurrentResourceName

Shared
string GetCurrentResourceName()

Returns the resource the code runs in.

Use it instead of hard-coding your resource name, so the resource keeps working when a server owner renames the folder.

Parameters

This native takes no parameters.

Returns

string Name of this resource.

Example

AddEventHandler('onResourceStart', function(name)
    if name == GetCurrentResourceName() then
        print('Started!')
    end
end)

GetInvokingResource

Shared
string? GetInvokingResource()

Inside an export or event handler: which resource called it.

Returns nil when your own resource called the function. Use it to log or restrict who may use your exports.

Parameters

This native takes no parameters.

Returns

string? Calling resource.

Example

exports('reset', function()
    print('reset called by', GetInvokingResource())
end)

GetResourceState

Shared
string GetResourceState(string resource)

Returns a resource's state.

Check it before calling exports of optional integrations, so your resource keeps working when the other one isn't installed.

Parameters

ParameterTypeDescription
resourcestringResource name.

Returns

string 'started', 'starting', 'stopped', 'stopping', 'uninitialized' or 'missing'.

Example

if GetResourceState('rtx_bank') == 'started' then
    exports.rtx_bank:addSavings(source, 10, 'Bonus')
end

GetNumResources

Shared
int GetNumResources()

Returns how many resources exist.

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

int Number of known resources.

Example

RegisterCommand('started', function()
    local started = 0
    for i = 0, GetNumResources() - 1 do
        if GetResourceState(GetResourceByFindIndex(i)) == 'started' then
            started = started + 1
        end
    end
    print(('%d of %d resources are running'):format(started, GetNumResources()))
end, true)

GetResourceByFindIndex

Shared
string GetResourceByFindIndex(int index)

Iterates over all resources.

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
indexint0 to GetNumResources() - 1.

Returns

string Resource name.

Example

for i = 0, GetNumResources() - 1 do
    local name = GetResourceByFindIndex(i)
    print(name, GetResourceState(name))
end

GetResourceMetadata

Shared
string? GetResourceMetadata(string resource, string key, int index)

Reads a value from a resource's resource.toml.

Custom keys in resource.toml are allowed and ignored by Neighborly, so you can store things like a support link and read them here.

Parameters

ParameterTypeDescription
resourcestringResource name.
keystringManifest key.
indexintIndex for list keys, 0 for single values.

Returns

string? The value.

Example

AddEventHandler('onResourceStart', function(name)
    if name ~= GetCurrentResourceName() then
        return
    end
    local version = GetResourceMetadata(name, 'version', 0)
    local author = GetResourceMetadata(name, 'author', 0) or 'unknown'
    print(('%s %s by %s started'):format(name, version, author))
end)

LoadResourceFile

Shared
string? LoadResourceFile(string resource, string path)

Reads a file from a resource. On the client the file must be listed in files.

On a client, only files listed in files in the manifest are available. Server-only data belongs in files that aren't listed, so players never download them.

Parameters

ParameterTypeDescription
resourcestringResource name.
pathstringFile path inside the resource.

Returns

string? File contents.

Example

local recipes = {}

AddEventHandler('onResourceStart', function(name)
    if name ~= GetCurrentResourceName() then
        return
    end
    local raw = LoadResourceFile(name, 'data/recipes.json')
    recipes = raw and json.decode(raw) or {}
    print(('Loaded %d recipes'):format(#recipes))
end)

SaveResourceFile

Server
boolean SaveResourceFile(string resource, string path, string data)

Writes a file into a resource folder.

Writes inside the resource folder. Don't use it for player data – the database is backed up, resource folders usually aren't, and updates may overwrite them.

Parameters

ParameterTypeDescription
resourcestringResource name.
pathstringFile path.
datastringContents.

Returns

boolean true on success.

Example

RegisterCommand('exportsales', function()
    local db = exports.neighborly:db()
    local report = db:find('sale:', function()
        return true
    end)
    if SaveResourceFile(GetCurrentResourceName(), 'data/sales.json', json.encode(report)) then
        print(('Saved %d sales to data/sales.json'):format(#report))
    end
end, true)

GetResourcePath

Server
string GetResourcePath(string resource)

Returns where a resource lives on disk.

Server only. To show the result in a client UI, return it from a server callback or publish it in a state bag.

Parameters

ParameterTypeDescription
resourcestringResource name.

Returns

string Absolute folder path.

Example

RegisterCommand('wherecafe', function()
    print('rtx_cafe lives in ' .. GetResourcePath('rtx_cafe'))
end, true)

StartResource

Server Restricted
boolean StartResource(string resource)

Starts a resource.

Starting resources can change a server completely, so only trusted resources should do it. The resource must exist in the resources folder – run refresh after adding new ones.

Restricted: the resource needs add_ace resource.<name> neighborly.restricted allow in the server permissions.

Parameters

ParameterTypeDescription
resourcestringResource name.

Returns

boolean true if it started.

Example

AddEventHandler('seasonChanged', function(season)
    if season == 'fall' and GetResourceState('rtx_halloween') == 'stopped' then
        StartResource('rtx_halloween')
    end
end)

StopResource

Server Restricted
boolean StopResource(string resource)

Stops a resource.

Server only: the change happens on the server and Neighborly syncs it to every player who can see it. Validate anything that came from a client before you call it.

Restricted: the resource needs add_ace resource.<name> neighborly.restricted allow in the server permissions.

Parameters

ParameterTypeDescription
resourcestringResource name.

Returns

boolean true if it stopped.

Example

AddEventHandler('seasonChanged', function(season, previous)
    if previous == 'fall' and GetResourceState('rtx_halloween') == 'started' then
        StopResource('rtx_halloween')
    end
end)

GetNumResourceMetadata

Shared
int GetNumResourceMetadata(string resource, string key)

Counts the values of a manifest key, for example how many client_scripts a resource has.

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
resourcestringResource name.
keystringManifest key.

Returns

int How many values the key has.

Example

for i = 0, GetNumResourceMetadata(GetCurrentResourceName(), 'author') - 1 do
    print('Author:', GetResourceMetadata(GetCurrentResourceName(), 'author', i))
end