Developer Preview

Your first resource

From an empty folder to a working command in ten minutes.

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.

In this guide you build a small resource called my_resource. It adds a /hello command: your Sim waves, everybody on the server gets a friendly notification, and the command shows up in chat suggestions. Along the way you'll meet every part a resource is made of.

1. Find the resources folder

Resources live in a folder called resources next to your server's server.json:

Where your server runsResources folder
Linux VPS/opt/neighborly/resources
Windows server kitC:\Neighborly Server\resources (next to start.bat)
Launcher (Host tab)Host → your server → ⋯ → Open server folder, then resources

Create a folder for your resource inside it. Folders in square brackets like [local] or [jobs] are only categories to keep things tidy – Neighborly looks inside them, but they are never resources themselves.

server.json
resources/
└── [local]/
    └── my_resource/
        ├── resource.toml
        ├── shared.lua
        ├── client.lua
        └── server.lua

Resource names may only use lowercase letters, numbers, _ and -. The folder name is the resource name, so keep it short and unique – prefixing with your initials or brand (rtx_cafe, nb_doorbell) avoids clashes.

2. Write the manifest

Every resource needs a resource.toml. It tells Neighborly who made the resource and which files to load where. Create it with this content:

resource.tomlTOML
name = "my_resource"
version = "1.0.0"
author = "Your Name"
description = "Says hello to the whole neighborhood"

shared_scripts = ["shared.lua"]
client_scripts = ["client.lua"]
server_scripts = ["server.lua"]

dependencies = ["neighborly", "chat"]

All keys are explained on the Resource manifest page.

3. Shared configuration

Shared scripts are loaded on both sides first, which makes them the perfect place for settings. Global variables you define here are visible to the client and server scripts of the same resource.

shared.luaLUA
Config = {
    Greeting = 'Hello, neighbors!',
    Cooldown = 10
}

4. The server script

RegisterCommand creates a chat and console command. On the server, source is the player who typed it – 0 when it came from the server console. We remember when each player last used the command so nobody can spam it, make their Sim wave and tell every client to show a notification.

server.luaLUA
local lastUsed = {}

RegisterCommand('hello', function(source, args, raw)
    if source == 0 then
        print('This command can only be used in game.')
        return
    end

    local now = os.time()
    if lastUsed[source] and now - lastUsed[source] < Config.Cooldown then
        TriggerClientEvent('neighborly:notify', source, {
            title = 'Slow down',
            text = 'You can say hello again in a few seconds.',
            type = 'warning'
        })
        return
    end
    lastUsed[source] = now

    local message = #args > 0 and table.concat(args, ' ') or Config.Greeting
    TriggerClientEvent('my_resource:greet', -1, GetPlayerName(source), message)
end, false)

AddEventHandler('playerDropped', function()
    lastUsed[source] = nil
end)

5. The client script

The client listens for the network event and shows a notification. RegisterNetEvent is needed because the event comes from the server – without it, Neighborly ignores network events for safety. We also add a chat suggestion so players discover the command while typing.

client.luaLUA
RegisterNetEvent('my_resource:greet', function(name, message)
    exports.neighborly:notify({
        title = name .. ' says',
        text = message,
        type = 'info',
        icon = 'wave'
    })
end)

TriggerEvent('chat:addSuggestion', '/hello', 'Wave and greet everyone on the server', {
    { name = 'message', help = 'Optional text instead of the default greeting' }
})

6. Start it

Add the resource to the resources list in server.json so it starts every time the server starts. Resources start in the order listed, after the built-in ones:

server.jsonJSON
{
  "name": "Sunny Bay RP",
  "license": "nbk_0123456789abcdef0123456789abcdef01234567",
  "resources": ["my_resource"]
}

You don't have to restart the whole server while developing. Open the server console (Host tab → Console, Manage server on the website, or console.cmd on Linux) and type:

> refresh
Found 1 new resource: my_resource
> ensure my_resource
Started resource my_resource (1.0.0 by Your Name)

Resource commands

CommandWhat it does
refreshScans the resources folder again and reads changed resource.toml files. Run it after adding a new resource.
ensure <name>Starts the resource, or restarts it if it is already running. The command you'll use most.
start <name>Starts a stopped resource (and its dependencies).
stop <name>Stops a resource. Resources that depend on it stop too.
restart <name>Stops and starts a running resource. Connected players get the new client files immediately.
resourcesLists all resources with their state and version.

7. Try it in game

Join your server, press F7 to open chat and type /hello or /hello Good morning!. Everyone on the server sees the notification.

Server print() output appears in the server console. Client print() output goes to the launcher log, and on servers with "developerMode": true in server.json it also shows up in the chat window – handy while you build.

Common problems

"Couldn't find resource my_resource"

Run refresh first. Check that the folder name matches the name you type and that resource.toml is directly inside the resource folder, not in a sub-folder.

The command does nothing

Look at the server console – a Lua error shows the file and line. A typo in a native name shows up as attempt to call a nil value.

The notification never shows

Check that the event name in TriggerClientEvent and RegisterNetEvent is exactly the same, including the my_resource: prefix.

My changes don't show up

Run ensure my_resource after every change. If you edited resource.toml, run refresh first.