Server Functions

These are the functions on the shared ESX object that only exist on the server. Get the object with ESX = exports['es_extended']:getSharedObject() or @es_extended/imports.lua, then call them from any server script. Functions that work on both sides (ESX.GetConfig, ESX.GetWeapon, ESX.Math, ESX.Table, ...) are on the shared functions page.

OverviewCopy Anchor Link

Global tablesCopy Anchor Link

PlayersCopy Anchor Link

GetPlayerFromIdCopy Anchor Link

ESX.GetPlayerFromId(source)

Returns: xPlayer or nil if the player has no loaded character.

RegisterNetEvent("myshop:buy", function(itemName)
    local xPlayer = ESX.GetPlayerFromId(source)
    if not xPlayer then return end

    -- validate itemName and price here
end)

GetPlayerFromIdentifierCopy Anchor Link

ESX.GetPlayerFromIdentifier(identifier)

Returns: xPlayer or nil if that character is not online.

local xTarget = ESX.GetPlayerFromIdentifier(row.owner)

if xTarget then
    xTarget.showNotification("Your vehicle was impounded")
end

GetPlayerIdFromIdentifierCopy Anchor Link

ESX.GetPlayerIdFromIdentifier(identifier)

Returns: number (server ID) or nil.

IsPlayerLoadedCopy Anchor Link

ESX.IsPlayerLoaded(source)

Returns: boolean, true if an xPlayer exists for this ID.

GetExtendedPlayersCopy Anchor Link

ESX.GetExtendedPlayers(key, value, minimal)

Returns:

• No key: array of all xPlayers (or IDs).
• Single value: array of matching xPlayers (or IDs).
• List of values: { [value] = { xPlayer, ... } }.

-- All police officers
for _, xPlayer in ipairs(ESX.GetExtendedPlayers("job", "police")) do
    xPlayer.showNotification("Robbery in progress at the Fleeca bank")
end

-- Grouped by job, only IDs
local byJob = ESX.GetExtendedPlayers("job", { "police", "ambulance" }, true)
print(#byJob.police, #byJob.ambulance)

GetNumPlayersCopy Anchor Link

ESX.GetNumPlayers(key, value)

Returns: number, or { [value] = count } when value is a list. Without arguments it returns #GetPlayers(), which also counts players who are still loading.

if ESX.GetNumPlayers("job", "police") < 2 then
    return xPlayer.showNotification("Not enough police online", "error")
end

GetPlayersCopy Anchor Link

ESX.GetPlayers()

Alias of the FiveM native GetPlayers(). Returns all connected server IDs as strings, including players without a loaded character.

Returns: string[]

PlayerCopy Anchor Link

ESX.Player(src)

Only available in resources that load @es_extended/imports.lua. Returns a static proxy: every key you index is a function that calls the matching xPlayer method through the RunStaticPlayerMethod export. Fields like .job are not available, use getters.

Returns: static player or nil if not loaded.

local player = ESX.Player(source)

if player then
    player.addAccountMoney("bank", 250, "Daily bonus")
end

ExtendedPlayersCopy Anchor Link

ESX.ExtendedPlayers(key, value)

Static-player version of GetExtendedPlayers. Same filters, returns static proxies. Only available through @es_extended/imports.lua.

for _, medic in ipairs(ESX.ExtendedPlayers("job", "ambulance")) do
    medic.showNotification("New dispatch call")
end

GetIdentifierCopy Anchor Link

ESX.GetIdentifier(playerId)

Returns the player's identifier of the type set in Config.Identifier (convar esx:identifier, default license) without the license: prefix. In FXDK mode it returns "ESX-DEBUG-LICENCE". Asserts if the player has no identifier of that type.

Returns: string

AddEventHandler("playerConnecting", function(_, _, deferrals)
    local identifier = ESX.GetIdentifier(source)
    print("Connecting: " .. identifier)
end)

CallbacksCopy Anchor Link

Server callbacks are handled by esx_lib. See the callbacks guide for the full flow with the client side.

RegisterServerCallbackCopy Anchor Link

ESX.RegisterServerCallback(name, handler)

The resource that registers a name first owns it. Registering the same name from another resource throws an error; registering again from the same resource replaces the handler.

ESX.RegisterServerCallback("myshop:getBalance", function(source, cb)
    local xPlayer = ESX.GetPlayerFromId(source)
    cb(xPlayer and xPlayer.getAccount("bank").money or 0)
end)

The client calls it with ESX.TriggerServerCallback("myshop:getBalance", function(balance) end), see client functions.

DoesServerCallbackExistCopy Anchor Link

ESX.DoesServerCallbackExist(name)

Returns: boolean, whether a callback with this name is registered.

TriggerClientCallbackCopy Anchor Link

ESX.TriggerClientCallback(player, name, cb, ...)

ESX.TriggerClientCallback(source, "myscript:getStreetName", function(street)
    print("Player is on " .. street)
end)

AwaitClientCallbackCopy Anchor Link

ESX.AwaitClientCallback(player, name, ...)

Same as TriggerClientCallback but yields the current thread and returns the client's values directly.

Returns: ... (whatever the client returned)

local street = ESX.AwaitClientCallback(source, "myscript:getStreetName")

EventsCopy Anchor Link

TriggerClientEventCopy Anchor Link

ESX.TriggerClientEvent(eventName, playerIds, ...)

For an array, the arguments are serialized once and sent to every player, which is cheaper than calling TriggerClientEvent in a loop.

local officers = ESX.GetExtendedPlayers("job", "police", true)
ESX.TriggerClientEvent("dispatch:client:alert", officers, { code = "10-31", coords = coords })

CommandsCopy Anchor Link

RegisterCommandCopy Anchor Link

ESX.RegisterCommand(name, group, cb, allowConsole, suggestion)

Each entry in suggestion.arguments is { name, help, type, Validator? }:

Set validate = true to require the exact number of arguments. Validator = { validate = function(value) return true end, err = "message" } adds a custom check per argument. showError(msg) shows a notification to the player, or prints to the console.

Registering an existing name again overrides the previous handler and prints a warning.

ESX.RegisterCommand("givecash", "admin", function(xPlayer, args, showError)
    args.target.addMoney(args.amount, "Admin gift")
    showError(("Gave $%d to %s"):format(args.amount, args.target.getName()))
end, true, {
    help = "Give cash to a player",
    validate = true,
    arguments = {
        { name = "target", help = "Player ID", type = "player" },
        { name = "amount", help = "Amount", type = "number", Validator = {
            validate = function(value) return value > 0 end,
            err = "Amount must be positive",
        } },
    },
})

The list of built-in commands is on the commands page.

JobsCopy Anchor Link

GetJobsCopy Anchor Link

ESX.GetJobs(jobType)

Waits until jobs are loaded, then returns { [jobName] = job }. Each job contains the columns of its jobs row (name, label, type, ...) plus grades, keyed by grade as string.

for name, job in pairs(ESX.GetJobs()) do
    print(name, job.label)
end

DoesJobExistCopy Anchor Link

ESX.DoesJobExist(job, grade)

Waits until jobs are loaded.

Returns: boolean

if ESX.DoesJobExist("police", 4) then
    xPlayer.setJob("police", 4)
end

RefreshJobsCopy Anchor Link

ESX.RefreshJobs()

Reloads every job and grade from the jobs and job_grades tables. Jobs without grades are skipped. If unemployed (or its grade 0) is missing, a fallback is created. Fires esx:jobsRefreshed.

RefreshJobCopy Anchor Link

ESX.RefreshJob(jobName)

Reloads one job and calls xPlayer.refreshJob() for every online member. Fires esx:jobRefreshed (jobName, job). If the job or its grades are gone, it is removed, its members become unemployed and esx:jobRemoved fires.

Returns: boolean, true if the job was refreshed.

MySQL.update.await("UPDATE job_grades SET salary = ? WHERE job_name = ? AND grade = ?", { 900, "police", 2 })
ESX.RefreshJob("police")

CreateJobCopy Anchor Link

ESX.CreateJob(name, label, grades, jobType)

Inserts the job and any missing grades into the database in one transaction and adds them to ESX.Jobs. If the job exists, only new grades are added and the existing label and type are kept. Fires esx:jobCreated.

Returns: boolean, false if arguments are missing, nothing new was inserted, or the transaction failed.

ESX.CreateJob("baker", "Baker", {
    { grade = 0, name = "trainee", label = "Trainee", salary = 150 },
    { grade = 1, name = "baker", label = "Baker", salary = 300 },
    { grade = 2, name = "boss", label = "Owner", salary = 500 },
})

See create a job.

ItemsCopy Anchor Link

GetItemsCopy Anchor Link

ESX.GetItems()

Returns: { [itemName] = { label, weight, rare, canRemove } }

GetItemLabelCopy Anchor Link

ESX.GetItemLabel(item)

Returns: string or nil (prints a warning for unknown items). With ox_inventory the label comes from exports.ox_inventory:Items(item).

xPlayer.showNotification(("You received %s"):format(ESX.GetItemLabel("bread")))

AddItemsCopy Anchor Link

ESX.AddItems(items)

Inserts new items into the items table (INSERT IGNORE), registers them in ESX.Items and refreshes online inventories. Items that already exist or have invalid fields are skipped. Not available with ox_inventory.

ESX.AddItems({
    { name = "coffee", label = "Coffee", weight = 0.3 },
    { name = "donut", label = "Donut", weight = 0.2 },
})

RefreshItemsCopy Anchor Link

ESX.RefreshItems()

Reloads all items from the items table and removes unknown items from online players. Not available with ox_inventory.

Returns: number, the number of items loaded.

RegisterUsableItemCopy Anchor Link

ESX.RegisterUsableItem(item, cb)

ESX does not remove the item for you. Remove it inside the callback.

ESX.RegisterUsableItem("bandage", function(source)
    local xPlayer = ESX.GetPlayerFromId(source)
    if not xPlayer or not xPlayer.removeInventoryItem("bandage", 1) then return end

    TriggerClientEvent("myhealth:client:heal", source, 25)
end)

UseItemCopy Anchor Link

ESX.UseItem(source, item, ...)

Runs the registered usable callback for item as if the player used it. Does not check whether the player owns the item. Errors inside the callback are caught and printed.

GetUsableItemsCopy Anchor Link

ESX.GetUsableItems()

Returns: { [itemName] = true } for every registered usable item.

CreatePickupCopy Anchor Link

ESX.CreatePickup(itemType, name, count, label, playerId, components, tintIndex, coords, bucket)

Pickups expire after 30 minutes. ESX limits them to 50 per player, 250 per 100 m grid cell and 5000 in total. Not available with ox_inventory.

Returns: pickup ID (number) or nil when a limit is reached or no position is known.

ESX.CreatePickup("item_standard", "bread", 3, "Bread x3", nil, nil, nil, vector3(215.0, -810.0, 30.7))

VehiclesCopy Anchor Link

GetVehicleTypeCopy Anchor Link

ESX.GetVehicleType(model, player, cb)

Returns the server vehicle type for CreateVehicleServerSetter: "automobile", "bike", "boat", "heli", "plane", "submarine", "trailer" or "train". Unknown models without a player return nil. The server console command clearvehicletypes clears the cache.

local vehicleType = ESX.GetVehicleType("t20", source)

CreateExtendedVehicleCopy Anchor Link

ESX.CreateExtendedVehicle(owner, plate, coords)

Spawns an owned vehicle from owned_vehicles with its saved properties, marks it as not stored and tracks it. Returns the existing object if that plate is already out. Fires esx:createdExtendedVehicle.

Returns: extended vehicle object or nil.

local vehicle = ESX.CreateExtendedVehicle(xPlayer.identifier, "ESX 123", vector4(215.8, -810.1, 30.7, 160.0))

if vehicle then
    print("Spawned with net ID " .. vehicle:getNetId())
end

GetExtendedVehicleFromPlateCopy Anchor Link

ESX.GetExtendedVehicleFromPlate(plate)

Returns: the extended vehicle object for a spawned plate, or nil.

local vehicle = ESX.GetExtendedVehicleFromPlate("ESX 123")

if vehicle then
    vehicle:delete("legion_garage")
end

Player function overridesCopy Anchor Link

RegisterPlayerFunctionOverridesCopy Anchor Link

ESX.RegisterPlayerFunctionOverrides(index, overrides)

Each entry is a factory that receives the xPlayer and returns the new method. All registered sets are applied to every xPlayer created afterwards. ESX uses this for its ox_inventory bridge.

ESX.RegisterPlayerFunctionOverrides("myOverrides", {
    getName = function(self)
        return function()
            return ("[%s] %s"):format(self.job.label, self.name)
        end
    end,
})

SetPlayerFunctionOverrideCopy Anchor Link

ESX.SetPlayerFunctionOverride(index)

Logging and debugCopy Anchor Link

DiscordLogCopy Anchor Link

ESX.DiscordLog(name, title, color, message)

ESX.DiscordLog("UserActions", "Bank robbery", "red", ("%s started a robbery"):format(xPlayer.getName()))

See the logs config.

DiscordLogFieldsCopy Anchor Link

ESX.DiscordLogFields(name, title, color, fields)

Other parameters are the same as DiscordLog.

ESX.DiscordLogFields("UserActions", "Item sold", "green", {
    { name = "Player", value = xPlayer.getName(), inline = true },
    { name = "Item", value = "gold_bar", inline = true },
    { name = "Price", value = 2500, inline = true },
})

TraceCopy Anchor Link

ESX.Trace(msg)

Prints [TRACE] msg to the server console only when Config.EnableDebug is true.

Common issuesCopy Anchor Link

• ESX.Player is nil: you did not add @es_extended/imports.lua to shared_scripts.
• Empty ESX.Jobs in your resource: read jobs with ESX.GetJobs(), which also waits until they are loaded.
• AddItems, RefreshItems or CreatePickup is nil: ox_inventory is running, so the default inventory functions are not defined.

RelatedCopy Anchor Link

• xPlayer
• OneSync functions
• Shared functions
• Server events
• Callbacks guide

Frequently asked questions