DEV Community: xFiveM Shop

Validate Your FiveM Script's config.lua at Startup (and Fail Loudly)

xFiveM Shop — Wed, 07 Oct 2026 23:55:07 +0000

Most FiveM job scripts ship with a config.lua that server owners are expected to edit. That is a good thing: it means you can change payouts, locations and job names without touching the logic. It also means the config is the part of the resource most likely to break. A missing comma, a job name with a capital letter, a vector3 with only two numbers, or a minimum payout bigger than the maximum, and the script either throws an error deep inside a thread or, worse, keeps running with nonsense values.

This post shows a small pattern for checking the config when the resource starts, printing clear messages, and refusing to run the job logic until the config is fixed. It needs no extra libraries, so you can drop it into any resource.

An example config

Here is a typical config for a simple delivery job:

-- shared/config.lua
Config = {}

Config.Job = 'delivery'          -- must match a job name in your framework
Config.RequiredItem = 'package'  -- item the player must carry
Config.Payout = { min = 150, max = 300 }
Config.Cooldown = 600            -- seconds between runs

Config.Depots = {
    { label = 'Docks',   coords = vector3(1205.4, -3110.2, 5.5), heading = 90.0 },
    { label = 'Airport', coords = vector3(-1037.8, -2737.6, 20.2), heading = 330.0 },
}

Everything here can go wrong after a server owner edits it. The goal is to catch those mistakes on the first start rather than when the first player clocks in.

The idea

The pattern has three parts:

A few tiny helper functions that record errors instead of throwing them.
A validateConfig function that checks each field and collects every problem it finds.
A flag, ConfigOk, that the rest of the server code checks before doing anything.

Collecting all errors at once matters: if the validator stops at the first problem, the owner fixes one line, restarts, and hits the next one.

The helpers

-- server/validate.lua
local errors = {}

local function fail(path, msg)
    errors[#errors + 1] = ('%s: %s'):format(path, msg)
end

local function expectType(path, value, expected)
    local actual = type(value)
    if actual ~= expected then
        fail(path, ('expected %s, got %s'):format(expected, actual))
        return false
    end
    return true
end

local function expectNumberRange(path, value, min, max)
    if not expectType(path, value, 'number') then return false end
    if (min and value < min) or (max and value > max) then
        fail(path, ('%s is outside the allowed range %s to %s')
            :format(value, tostring(min), tostring(max)))
        return false
    end
    return true
end

One detail worth knowing: in FiveM's Lua runtime, vectors are their own type. type(vector3(1.0, 2.0, 3.0)) returns 'vector3', not 'table' or 'userdata'. That makes it easy to check that coordinates really are vectors, which catches the common mistake of writing a plain table like {1205.4, -3110.2, 5.5} or using vector2 by accident.

The validator

local function validateConfig()
    if not expectType('Config', Config, 'table') then return end

    if expectType('Config.Job', Config.Job, 'string') and Config.Job == '' then
        fail('Config.Job', 'must not be empty')
    end

    expectType('Config.RequiredItem', Config.RequiredItem, 'string')

    if expectType('Config.Payout', Config.Payout, 'table') then
        local okMin = expectNumberRange('Config.Payout.min', Config.Payout.min, 0)
        local okMax = expectNumberRange('Config.Payout.max', Config.Payout.max, 0)
        if okMin and okMax and Config.Payout.min > Config.Payout.max then
            fail('Config.Payout', 'min is larger than max')
        end
    end

    expectNumberRange('Config.Cooldown', Config.Cooldown, 0, 86400)

    if expectType('Config.Depots', Config.Depots, 'table') then
        if #Config.Depots == 0 then
            fail('Config.Depots', 'needs at least one depot')
        end
        local seen = {}
        for i, depot in ipairs(Config.Depots) do
            local p = ('Config.Depots[%d]'):format(i)
            if expectType(p, depot, 'table') then
                if expectType(p .. '.label', depot.label, 'string') then
                    if seen[depot.label] then
                        fail(p .. '.label', ('duplicate label "%s"'):format(depot.label))
                    end
                    seen[depot.label] = true
                end
                expectType(p .. '.coords', depot.coords, 'vector3')
                expectNumberRange(p .. '.heading', depot.heading, 0, 360)
            end
        end
    end
end

Each check uses a readable path such as Config.Depots[2].coords, so the message points the owner straight at the line to fix.

Running it on start

ConfigOk = false

CreateThread(function()
    validateConfig()

    local resource = GetCurrentResourceName()
    if #errors > 0 then
        print(('^1[%s] %d config problem(s) found:^7'):format(resource, #errors))
        for _, e in ipairs(errors) do
            print(('^1[%s]^7   %s'):format(resource, e))
        end
        print(('^1[%s] job is disabled until config.lua is fixed.^7'):format(resource))
        return
    end

    ConfigOk = true
    print(('^2[%s] config OK^7'):format(resource))
end)

The ^1, ^2 and ^7 codes colour the console output red, green and back to white, which makes problems hard to miss in a busy server log.

Then guard your event handlers and callbacks:

RegisterNetEvent('delivery:startRun', function(depotIndex)
    if not ConfigOk then return end
    local src = source
    local depot = Config.Depots[tonumber(depotIndex) or 0]
    if not depot then return end
    -- normal job logic continues here
end)

The resource stays started, so nothing else on the server breaks, but the job simply refuses to run until the config is valid. That is far better than paying out nil or spawning a vehicle at the bottom of the ocean.

Checking against the framework

Type checks catch syntax-level mistakes. The most common real-world problem, though, is a job or item name that does not exist on this particular server. You can add an optional second pass that asks the framework.

For ESX Legacy, the server object exposes the loaded jobs and item labels:

local function validateAgainstESX(ESX)
    local jobs = ESX.GetJobs()
    if jobs and not jobs[Config.Job] then
        fail('Config.Job', ('job "%s" is not registered in ESX'):format(Config.Job))
    end
    if not ESX.GetItemLabel(Config.RequiredItem) then
        fail('Config.RequiredItem', ('item "%s" does not exist'):format(Config.RequiredItem))
    end
end

For QBCore, the shared tables serve the same purpose: QBCore.Shared.Jobs[Config.Job] and QBCore.Shared.Items[Config.RequiredItem]. If your server uses a separate inventory resource, check items through that inventory's own API instead, because the framework's item list may be empty.

Two cautions. First, run this pass a moment after start, once the framework has finished loading its jobs and items; checking too early can report false errors. Second, exact function names can differ between framework versions, so confirm them against the version you run. Wrapping the framework pass in pcall keeps a version mismatch from crashing your validator.

Small habits that make configs safer

Comment every field with its unit and an example, as in the config above. "Seconds" versus "minutes" causes more bugs than bad code.
Keep secrets out of shared files. Anything in a shared_script is sent to every client, so webhook URLs and API keys belong in a server-only file.
Ship defaults. Fill missing optional values with sensible defaults instead of failing, and reserve hard errors for values the job cannot run without.

The open source advantage

When you can read and edit a resource's code, you can add a validator like this yourself in a few minutes, even if the original author did not. That is one of the practical benefits of open source releases such as the ESX job scripts on xFiveM Shop: you are not stuck guessing why a locked file fails silently. If you are setting up a new resource and want the general install steps first, see xfivem.shop/help/installation.

Summary

A config validator is around a hundred lines of plain Lua. It turns vague runtime errors into a clear list of problems on the first start and protects your economy from broken values. Add it once, then reuse it across resources.

State Bags vs Events in FiveM: Syncing Vehicle and Player State the Simple Way

xFiveM Shop — Wed, 07 Oct 2026 22:45:40 +0000

When you write a FiveM script that needs every player to agree on something (a car is locked, a player is on duty, the weather is rainy), there are two common tools: network events and state bags. Both work, but they solve different problems. Picking the wrong one is why some scripts show a car locked for one player and unlocked for another. This post compares the two with small Lua examples.

The quick difference

Events are messages. The server says "this just happened" and every client that receives it reacts. If a client wasn't connected, or the entity wasn't loaded on their side, they never hear about it.

State bags are stored values attached to something: an entity, a player or the whole server. Clients that come into range later still see the current value, because they read the state rather than waiting for a message.

A useful rule: if you are describing something that happened, use an event. If you are describing how something currently is, use a state bag.

The three kinds of state bag

Entity(entity).state: attached to a networked entity such as a vehicle, ped or object. Entity state bags rely on OneSync, which most roleplay servers run.
Player(source).state on the server, LocalPlayer.state on the client: attached to a player.
GlobalState: server-wide values that the server writes and every client can read.

Values should be simple data (strings, numbers, booleans and small tables). Functions can't be stored, and large tables that change often are a bad fit.

Example: vehicle locks with an event (the fragile way)

-- server
RegisterNetEvent('locks:toggle', function(netId)
    TriggerClientEvent('locks:apply', -1, netId, true)
end)

-- client
RegisterNetEvent('locks:apply', function(netId, locked)
    local veh = NetToVeh(netId)
    if veh ~= 0 then
        SetVehicleDoorsLocked(veh, locked and 2 or 1)
    end
end)

This works until a player drives into the area after the event fired, or joins later. Their client never got the message, so the doors are open for them. Patching that with "request current state" callbacks means rebuilding state bags by hand.

Example: the same lock with a state bag

-- server
RegisterNetEvent('locks:toggle', function(netId)
    local src = source
    local veh = NetworkGetEntityFromNetworkId(netId)
    if veh == 0 or not DoesEntityExist(veh) then return end

    -- add your own distance and key/ownership check here
    local locked = not Entity(veh).state.locked
    Entity(veh).state:set('locked', locked, true)
end)

The third argument to set is replicated. With true, the value is sent to clients.

On the client, listen for changes with AddStateBagChangeHandler:

-- client
AddStateBagChangeHandler('locked', nil, function(bagName, key, value)
    local veh = GetEntityFromStateBagName(bagName)
    if veh == 0 then return end
    SetVehicleDoorsLocked(veh, value and 2 or 1)
end)

Two details matter here:

Use the value argument, not Entity(veh).state.locked. The handler runs before the new value is stored on the bag, so reading the bag inside the handler can give you the old value.
GetEntityFromStateBagName returns 0 if the entity isn't loaded on this client yet. That's fine: when it does stream in, the state is already on it, and your script can read Entity(veh).state.locked when the player tries to enter.

Example: player duty status

Duty status is a classic "how things currently are" value. Set it on the server when the job script clocks someone in:

-- server
local function setDuty(src, onDuty)
    Player(src).state:set('onDuty', onDuty, true)
end

Any server script can now check it without asking the job resource:

-- server, in another resource
if not Player(src).state.onDuty then
    return -- not clocked in, ignore the request
end

And the player's own client can read LocalPlayer.state.onDuty to show or hide job menus.

Example: server-wide values

Weather, time or "is the bank vault open" are good fits for GlobalState:

-- server
GlobalState:set('vaultOpen', false, true)

-- client
if GlobalState.vaultOpen then
    -- show the vault interaction
end

When events are still the right choice

State bags don't replace events. Use events for:

One-off actions: play a sound, show a notification, start an animation.
Requests from a client to the server ("I want to lock this car"), which the server then validates.
Anything that should not be repeated when a player streams in later, such as an explosion effect.

A good pattern combines both: the client sends an event as a request, the server validates it, and the server writes the result to a state bag.

Security: don't trust state you didn't write

Server-side checks should rely on values the server set itself. Depending on how your server is configured, clients may be able to write replicated values to their own player bag or to entities they control. If your server code reads a state bag value that a client could have written, treat it like any other client input and validate it.

Other good habits:

Prefix keys with your resource name (mylocks:locked) if you're worried about collisions with other scripts.
Don't write to a state bag every frame. Update it when the value actually changes.
Keep values small. A boolean or a number is ideal; a full inventory table is not.

Where this shows up in real scripts

Vehicle scripts (locks, fuel, keys) and job scripts (duty, grade-based menus) are where state bags save the most bugs, so they're worth looking for when you review code. If you want readable examples, xFiveM Shop ships its resources with no escrow, so you can open its open source QBCore scripts and see how each one syncs data. If you're building lock or fuel features, its vehicle collection gives you test models to try them on.

Summary

Events describe things that happen, while state bags describe how things are. Use state bags for locks, duty status and server-wide flags so late joiners see the right values. Keep events for one-off actions and client requests, and always validate on the server before you write state.

How do you sync state in your resources? Share your approach in the comments.

Securing Server Events in FiveM Scripts: A Short Checklist

xFiveM Shop — Wed, 07 Oct 2026 21:20:30 +0000

Most money and item exploits on FiveM servers come from the same mistake: a script trusts the client. A modder can trigger any network event with any arguments, so every server event has to assume the request might be fake. Here is a short checklist I run through on every script before it goes live.

1. Never accept amounts from the client

If a client event says "pay me 500", a modder will send "pay me 5000000". The server should decide the amount based on its own config.

-- bad
RegisterNetEvent('job:pay', function(amount)
    Bridge.AddMoney(source, amount)
end)

-- better (Bridge.AddMoney is a small wrapper around your QBCore or ESX money function)
RegisterNetEvent('job:pay', function()
    local src = source
    Bridge.AddMoney(src, Config.Payout)
end)

2. Check job, distance and state

Before rewarding anything, check on the server that the player has the right job, is near the right location (#(GetEntityCoords(GetPlayerPed(src)) - Config.Location) < 5.0) and has actually started the task.

3. Add cooldowns

Store a timestamp per player and reject events that come in faster than a human could do the task. That stops looped triggers even if every other check passes.

4. Log suspicious calls

When a check fails, log the player identifier and event name. A few failed checks can be lag; hundreds per minute is someone injecting events.

5. Prefer scripts you can read

All of this is only possible to verify if you can open the code. With escrowed resources you have to trust the author got it right. Open source FiveM scripts let you check every event yourself before installing. xFiveM Shop publishes its QBCore, ESX and RedM resources unescrowed, and the setup steps are at xfivem.shop/help/installation.

Summary

Decide amounts on the server, validate job, distance and state, add cooldowns, log failures, and only run code you can read.

Writing One FiveM Script That Works on Both QBCore and ESX (A Simple Bridge Pattern)

xFiveM Shop — Wed, 07 Oct 2026 20:35:13 +0000

A lot of FiveM servers run either QBCore or ESX, and a lot of script authors end up maintaining two copies of the same resource. That gets painful fast: every bug fix has to be done twice and the two versions drift apart. A small "bridge" file solves most of this. Here is the pattern I use.

The idea

Your script logic should never call QBCore.Functions... or ESX.GetPlayerFromId... directly. Instead it calls your own small API (Bridge.GetPlayer, Bridge.AddMoney, Bridge.GetJob), and one file decides which framework is underneath.

my_script/
├── fxmanifest.lua
├── bridge/
│   └── server.lua
└── server/
    └── main.lua

fx_version 'cerulean'
game 'gta5'
lua54 'yes'

server_scripts {
    'bridge/server.lua',
    'server/main.lua',
}

The bridge loads first, so main.lua can use it straight away.

Detecting the framework

-- bridge/server.lua
Bridge = {}

local framework

if GetResourceState('qb-core') == 'started' then
    framework = 'qb'
    Bridge.Core = exports['qb-core']:GetCoreObject()
elseif GetResourceState('es_extended') == 'started' then
    framework = 'esx'
    Bridge.Core = exports['es_extended']:getSharedObject()
else
    print('^1[my_script] No supported framework found (qb-core or es_extended)^0')
end

Bridge.Framework = framework

GetResourceState is a native, so this works without any extra dependency. Remember to start your framework before this resource in server.cfg so the check sees it as started.

Wrapping the common calls

function Bridge.GetPlayer(src)
    if framework == 'qb' then
        return Bridge.Core.Functions.GetPlayer(src)
    elseif framework == 'esx' then
        return Bridge.Core.GetPlayerFromId(src)
    end
end

function Bridge.AddMoney(src, amount)
    local player = Bridge.GetPlayer(src)
    if not player then return false end

    if framework == 'qb' then
        player.Functions.AddMoney('cash', amount)
    else
        player.addMoney(amount)
    end
    return true
end

function Bridge.GetJob(src)
    local player = Bridge.GetPlayer(src)
    if not player then return nil end

    if framework == 'qb' then
        return player.PlayerData.job.name
    else
        return player.job.name
    end
end

Using it in your actual script

-- server/main.lua
RegisterNetEvent('my_script:payout', function()
    local src = source

    if Bridge.GetJob(src) ~= 'mechanic' then
        return
    end

    Bridge.AddMoney(src, 250)
end)

That file has no idea which framework is running, and that is the whole point. When a new framework version renames something, you fix it in one place.

Things to watch out for

Validate on the server. The example above checks the job server-side before paying out. Never trust a client event to tell you how much money to give.
Account names differ. QBCore uses cash and bank; ESX uses money and bank accounts. Keep that mapping inside the bridge.
Inventory is its own problem. Many servers use ox_inventory or qb-inventory regardless of framework, so treat inventory as a second bridge rather than tying it to QBCore or ESX.
Client side too. If your script needs player data on the client, write a small bridge/client.lua with the same approach.

Why this matters for open source scripts

When the source is open, server owners can read the bridge, see exactly how it maps to their framework, and patch it themselves if they run a fork. That is much easier than debugging an escrowed resource you cannot open. If you want to see more examples of this style, xFiveM Shop publishes open source FiveM scripts with QBCore and ESX support, and the setup steps are in the xfivem.shop installation guide.

Wrapping up

A bridge file is maybe 60 lines, and it saves you from maintaining two versions of every script. Start with player, money and job, then add inventory and notifications as you need them.

How do you handle multi-framework support in your resources? Let me know in the comments.