Developer Preview

Developer docs

Build your own resources for Neighborly servers with Lua.

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.

Neighborly servers can run resources – small packages of Lua scripts, web UI and data that add new things to your neighborhood. A resource can be as small as a /dice command or as big as a full roleplay economy with jobs, phones, banks and businesses. If you have written resources for FiveM before, you will feel right at home: the same ideas – events, commands, exports, state bags and NUI – with natives built for The Sims 4.

Resources live on the server. When a player joins, the launcher downloads the client part of every running resource automatically, so players never install anything by hand.

Client, server and shared scripts

Every resource is split into up to three kinds of scripts. Deciding where a piece of code belongs is the most important design decision you will make.

KindRuns onUse it for
ClientEvery player's PC, in the Neighborly launcher right next to their gameUI, menus, notifications, the camera, key bindings, reading what the local player sees. Each player runs their own copy, and client natives reach into the game through the Neighborly mod.
ServerOnce, inside the Neighborly serverAnything that changes the shared world: money, ownership, Sims' needs and skills, objects, saving data. The server is the single source of truth.
SharedBoth – loaded before client and server scriptsConfiguration tables, constants, small helper functions used on both sides.

Both sides run Lua 5.4 with the standard library, plus json, vector3, promise and the Neighborly natives. Every native in the reference is marked Client Server or Shared so you always know where it can be called.

How everything stays in sync

In a multiplayer neighborhood everyone must see the same thing. Neighborly takes care of Sims, objects, lots and time for you – as long as world changes happen on the server. A typical action flows like this:

  1. The player does somethingThey type a command, press a key or click a button in your UI. Your client script notices it.
  2. The client asks the serverThe client script sends a network event with TriggerServerEvent. It never changes money or the world itself.
  3. The server checks and decidesYour server script validates the request – is the player really on that lot, can they afford it, are they spamming? – and then calls server natives like TakeMoney or SetSimNeed.
  4. Neighborly syncs the worldSim natives run in the game of the player who owns that Sim, and Neighborly's world sync shows the result to everyone on the lot.
  5. Clients update their UIFor anything that isn't part of the game world – a notification, a menu, a custom HUD – the server uses TriggerClientEvent, answers a server callback or sets a state bag. Client ↔ server data explains which one to pick.

Here is that whole round trip in a few lines. The client adds a /snack command (and a key for it) that works next to a fridge; the server rate-limits it and fills the Sim's hunger:

client.luaLUA
local function nearFridge()
    local object = GetClosestObject(GetSimPosition(GetActiveSim()), nil, 3.0)
    return object ~= nil and GetObjectDefinition(object):lower():find('fridge') ~= nil
end

RegisterCommand('snack', function()
    if not nearFridge() then
        return exports.neighborly:notify({ text = 'Walk up to a fridge first.' })
    end
    TriggerServerEvent('snacks:grab')
end, false)

RegisterKeyMapping('snack', 'Grab a midnight snack', 'keyboard', 'F10')
server.luaLUA
local lastSnack = {}

RegisterNetEvent('snacks:grab', function()
    local src = source
    local sim = GetPlayerCharacter(src)
    if not sim or (lastSnack[src] or -60000) > GetGameTimer() - 60000 then
        return
    end
    lastSnack[src] = GetGameTimer()
    SetSimNeed(sim, 'hunger', math.min(GetSimNeed(sim, 'hunger') + 25, 100))
end)

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

Notice that the server decides on its own how often a snack is allowed, no matter what the client says. Clients can be modified by cheaters, so the server must never trust what it receives – read more in Best practices.

Built-in resources

Every server ships with two resources that are always running. You can use them from your own code straight away:

ResourceWhat it gives you
neighborlyThe core: menus, context menus, notifications, progress bars, dialogs, the database and the neighborly:notify event.
chatThe F7 chat window, chat:addSuggestion and the chatMessage event.

What's ready

PartWhat's includedStatus
Lua runtimeClient, server and shared scripts, resource.toml and fxmanifest.lua, events, commands, ACE permissions, exports, threads, KVP, the resource database, state bags and the natives referenceLive
NUIHTML/CSS/JS pages in the Neighborly overlay, NUI callbacks, the Neighborly UI kit, menus and dialogsLive
Tebex & escrowSell resources on Tebex, encrypted resources tied to the buyer's account and server keysPlanned
Developer toolsresmon in the server console today; an in-game developer console and NUI DevTools laterPartly

Where to go next

Want to see complete, real resources first? Example resources has nine of them to download as ZIPs – from a welcome message to a savings bank with server callbacks.