Developer Preview

Best practices

Secure, fast and friendly resources that keep everyone in sync.

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.

A great resource is secure, light and plays nicely with others. These are the rules we follow ourselves – and the ones server owners will thank you for.

Security: never trust the client

Everything a client sends can be faked. A cheater can trigger any network event you registered with any arguments, as often as they want. Treat every RegisterNetEvent handler on the server like a public API.

This handler pays whatever the client asks for. Anyone can call it with 99999:

server.luaLUA
RegisterNetEvent('rtx_cafe:finishShift', function(earned)
    GiveMoney(source, earned, 'Café shift')
end)

The fixed version lets the server decide the amount from what it tracked itself:

server.luaLUA
RegisterNetEvent('rtx_cafe:finishShift', function()
    local src = source
    local state = Player(src).state
    if not state.onDuty then
        return
    end
    local served = state.servedThisShift or 0
    local earned = math.min(served * Config.PayPerDrink, Config.MaxShiftPay)
    state:set('onDuty', false, true)
    state:set('servedThisShift', 0, true)
    if earned > 0 then
        GiveMoney(src, earned, 'Café shift')
    end
end)

Checklist for every server event

  • Check types and ranges. type(x) == 'number' for amounts and player ids, type(x) == 'string' for Sim, lot and object ids, whole numbers with math.floor, sensible minimum and maximum.
  • Check the player may do it. Are they on duty, on the right lot, near the object, the owner of the house, allowed by ACE?
  • Check the target exists. DoesSimExist for Sims, GetPlayerName(target) or DoesPlayerExist for player ids, GetLotName for lots.
  • Compute rewards on the server. Never accept prices, amounts or results from the client.
  • Rate-limit. Ignore events that arrive faster than a human could cause them.
  • Never run code from the client. No load() on received strings, no "call any function by name" events.
  • Keep secrets on the server. Webhooks and API keys never belong in shared or client scripts.

A reusable rate limiter

server/security.luaLUA
local buckets = {}

function RateLimit(player, action, perSeconds)
    local now = GetGameTimer()
    buckets[player] = buckets[player] or {}
    local last = buckets[player][action]
    if last and now - last < perSeconds * 1000 then
        return false
    end
    buckets[player][action] = now
    return true
end

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

RegisterNetEvent('rtx_cafe:tip', function(target, amount)
    local src = source
    if not RateLimit(src, 'tip', 5) then
        return
    end
    if type(target) ~= 'number' or type(amount) ~= 'number' or not GetPlayerName(target) then
        return
    end
    amount = math.floor(amount)
    if amount < 1 or amount > 500 or GetPlayerLot(target) ~= GetPlayerLot(src) then
        return
    end
    TransferMoney(src, target, amount, 'Tip')
end)

Sync: everyone sees the same thing

The magic of a shared neighborhood is that every player sees the same world. Keep it that way:

  • Change the world from the server. Needs, buffs, skills, interactions and money – always with server natives, which run in the owner's game and are synced from there.
  • Broadcast state, not just events. An event reaches only the players online at that moment. Players who join later miss it. Put lasting facts in a state bag (GlobalState.cafeOpen) and use events for one-off moments (a notification, a sound).
  • Keep client-only effects cosmetic. UI, local sounds and objects made with CreateObject exist only for one player – anything that affects gameplay must not depend on them.
  • Respect packs. Only use objects, interactions and worlds from packs in game_packs or checked with GetRequiredPacks, so no player ever sees a missing object.
  • Save on change, not on a timer. Write to the database when something important happens, so a crash never loses a purchase.

Performance

  • Keep idle client loops at a second or more, and stop threads you don't need – check thread counts with resmon.
  • React to events instead of polling.
  • Use fast loops only while they matter, and sleep for longer otherwise. See Threads & timing.
  • Send small event payloads – ids instead of whole tables – and batch updates.
  • Clean up objects, UI focus and handlers in onResourceStop.

Naming

ThingConventionExample
ResourceLowercase, short brand prefixrtx_cafe
Eventsresource:actionrtx_cafe:serve
ExportscamelCase verbsgetBalance, addSavings
CommandsShort, lowercase, unique/cafe, /dice
State keysPrefixed unless meant to be shared by many resourcesrtx_cafe:tips, job
Database keystype:idaccount:4821
GlobalsOne table per resourceConfig, Cafe

Declare everything local unless it really has to be global. Globals are shared by all scripts of a resource and easy to overwrite by accident.

Versioning

  • Use semantic versions in resource.toml: bump patch for fixes, minor for new features, major when you break exports, events or config.
  • Keep a changelog – server owners need to know what changed before they update.
  • Store a schema number with your saved data and migrate old data when your resource starts.
  • Never rename config options silently. Read the old name, warn in the console, and remove it a major version later.
server/migrate.luaLUA
local db = exports.neighborly:db()
local SCHEMA = 2

AddEventHandler('onResourceStart', function(name)
    if name ~= GetCurrentResourceName() then
        return
    end
    if (db:get('schema') or 1) < 2 then
        for _, row in ipairs(db:find('account:', function() return true end)) do
            row.value.earned = row.value.earned or row.value.money or 0
            row.value.money = nil
            db:set(row.key, row.value)
        end
        db:set('schema', SCHEMA)
        print('rtx_cafe: migrated saved data to schema 2')
    end
end)

Configuration

  • Put every option in one config.lua shared script and list it in escrow_ignore.
  • Give options safe defaults so the resource works straight after ensure.
  • Validate config on start and print a friendly message for wrong values instead of crashing later.
  • Translations go into locales/ – one table per language.

Before you release, run through this list on a server with two players: both see the same thing, nothing breaks when one of them leaves mid-action, and restarting your resource doesn't leave anything behind.