xPlayer

xPlayer is the server-side object that represents one loaded ESX character. You get it with ESX.GetPlayerFromId(source) and use its methods to change money, items, job, group, weapons and metadata. Every change goes through these methods so that es_extended can sync the client, fire events and save the data to the database.

OverviewCopy Anchor Link

Getting an xPlayerCopy Anchor Link

local xPlayer = ESX.GetPlayerFromId(source)

if not xPlayer then
    return -- player is not loaded (still connecting, in character selection, or gone)
end

print(xPlayer.getName(), xPlayer.getJob().name)

Other ways to get a player object:

Static players (ESX.Player)Copy Anchor Link

ESX.Player(src) and ESX.ExtendedPlayers() exist only in resources that load @es_extended/imports.lua. They return a lightweight proxy instead of the real object. Every key you index on the proxy becomes a function that calls the method through the RunStaticPlayerMethod export:

local player = ESX.Player(source)

if player then
    player.addAccountMoney("bank", 500, "Quest reward")
    local job = player.getJob() -- returns a copy, not a live reference
end

PropertiesCopy Anchor Link

The object also exposes raw fields. Read them if you like, but change state only through methods, otherwise the client is not updated and nothing is saved.

Character identity data (firstName, lastName, dateofbirth, sex, height) is not a field on the server object. It is stored as variables, so read it with xPlayer.get("firstName"). See PlayerData.

Identity and sessionCopy Anchor Link

getIdentifierCopy Anchor Link

xPlayer.getIdentifier()

Returns the database identifier of the character (the identifier column in users).

Returns: string

local identifier = xPlayer.getIdentifier()
MySQL.update("UPDATE users SET phone_number = ? WHERE identifier = ?", { number, identifier })

getSSNCopy Anchor Link

xPlayer.getSSN()

Returns the character's social security number, for example "482-17-3390". ESX generates a unique SSN when the character is created.

Returns: string

getSourceCopy Anchor Link

xPlayer.getSource()

Returns the player's server ID. xPlayer.getPlayerId() is an alias.

Returns: number

getPlayerIdCopy Anchor Link

xPlayer.getPlayerId()

Alias of getSource.

Returns: number

getNameCopy Anchor Link

xPlayer.getName()

Returns the character name. With esx_identity or multicharacter this is "Firstname Lastname", otherwise the FiveM player name.

Returns: string

setNameCopy Anchor Link

xPlayer.setName(newName)

Changes the name on the object and in the name state bag. It does not update firstname / lastname in the database, so the change is lost on reconnect.

xPlayer.setName("John Doe")

getPlayTimeCopy Anchor Link

xPlayer.getPlayTime()

Returns the total playtime of the character in seconds: the saved playtime plus the time online in this session. The value is persisted in metadata.lastPlaytime.

Returns: number

local hours = math.floor(xPlayer.getPlayTime() / 3600)
xPlayer.showNotification(("You have played %d hours"):format(hours))

isCurrentCopy Anchor Link

xPlayer.isCurrent()

Returns true while this object is still the active entry in ESX.Players. Use it after a Wait or an awaited database query to make sure the player has not dropped or switched characters in the meantime.

Returns: boolean

local result = MySQL.single.await("SELECT * FROM my_table WHERE owner = ?", { xPlayer.identifier })

if not xPlayer.isCurrent() then
    return -- player left while we were waiting
end

isAdminCopy Anchor Link

xPlayer.isAdmin()

Returns true if the player is allowed the ACE command, if sv_lan is "true", or if the player's group is listed in Config.AdminGroups.

Returns: boolean

kickCopy Anchor Link

xPlayer.kick(reason)

Drops the player from the server. ESX saves the character in the playerDropped handler.

xPlayer.kick("You have been kicked for exploiting.")

triggerEventCopy Anchor Link

xPlayer.triggerEvent(eventName, ...)

Shortcut for TriggerClientEvent(eventName, xPlayer.source, ...).

xPlayer.triggerEvent("myjob:client:startShift", { route = 3 })

executeCommandCopy Anchor Link

xPlayer.executeCommand(command)

Makes the player's client run ExecuteCommand(command). The command runs with the player's own permissions. Throws an error if command is not a string.

xPlayer.executeCommand("e sit")

PositionCopy Anchor Link

getCoordsCopy Anchor Link

xPlayer.getCoords(vector, heading)

Reads the live ped position when the ped exists, otherwise the last cached position. Falls back to a random Config.DefaultSpawns entry if nothing valid is known.

Returns: vector3, vector4 or { x, y, z, heading? }

local coords = xPlayer.getCoords(true)

if #(coords - vector3(441.8, -982.0, 30.7)) < 10.0 then
    print("Player is at Mission Row PD")
end

setCoordsCopy Anchor Link

xPlayer.setCoords(coordinates)

Teleports the ped on the server side. Returns false if the coordinates are invalid (non-finite or beyond Config.PlayerCoordinateLimit) or the ped does not exist. Returns nothing on success.

xPlayer.setCoords(vector4(-269.4, -955.3, 31.2, 205.0))

Permission groupCopy Anchor Link

getGroupCopy Anchor Link

xPlayer.getGroup()

Returns the player's permission group, for example "user", "admin" or "owner".

Returns: string

if xPlayer.getGroup() ~= "user" then
    print(xPlayer.getName() .. " is staff")
end

setGroupCopy Anchor Link

xPlayer.setGroup(newGroup)

Replaces the ACE principal identifier.<license> → group.<old> with group.<new>, updates the group state bag and fires esx:setGroup on the server (source, group, lastGroup) and on the client (group, lastGroup). The group is saved to the users table.

xPlayer.setGroup("admin")

VariablesCopy Anchor Link

Variables are temporary key/value pairs on the player. They are not saved to the database. ESX itself uses them for identity data (firstName, lastName, dateofbirth, sex, height).

setCopy Anchor Link

xPlayer.set(key, value, replicate)

xPlayer.set("lastRobbery", os.time(), false) -- server-only flag

getCopy Anchor Link

xPlayer.get(key)

Returns: any (the stored value or nil)

local first, last = xPlayer.get("firstName"), xPlayer.get("lastName")

updatePlayerDataCopy Anchor Link

Money and accountsCopy Anchor Link

Every character has the accounts defined in Config.Accounts. By default these are money (cash), bank and black_money. Account names are case-insensitive in getAccount. See the money and accounts guide.

getAccountsCopy Anchor Link

xPlayer.getAccounts(minimal)

Returns: table[] of { name, money, label, round, index }, or a name → money map.

local balances = xPlayer.getAccounts(true)
print(balances.bank, balances.money, balances.black_money)

getAccountCopy Anchor Link

xPlayer.getAccount(account)

Returns: { name, money, label, round, index } or nil if the account does not exist.

local bank = xPlayer.getAccount("bank")

if bank and bank.money >= 2500 then
    -- player can afford it
end

getMoneyCopy Anchor Link

xPlayer.getMoney()

Returns the balance of the money (cash) account, or 0.

Returns: number

setMoneyCopy Anchor Link

xPlayer.setMoney(money)

Shortcut for setAccountMoney("money", money).

Returns: true on success.

addMoneyCopy Anchor Link

xPlayer.addMoney(money, reason)

Shortcut for addAccountMoney("money", money, reason).

Returns: true on success, false on overflow.

xPlayer.addMoney(150, "Sold fish")

removeMoneyCopy Anchor Link

xPlayer.removeMoney(money, reason)

Shortcut for removeAccountMoney("money", money, reason).

Returns: true on success, false if the player does not have enough cash.

setAccountMoneyCopy Anchor Link

xPlayer.setAccountMoney(accountName, money, reason)

Sets the balance to an exact value. Fires esx:setAccountMoney on the server (source, accountName, money, reason) and on the client (the updated account table).

Returns: true on success. Throws for negative or invalid amounts and unknown accounts.

xPlayer.setAccountMoney("black_money", 0, "Money laundered")

addAccountMoneyCopy Anchor Link

xPlayer.addAccountMoney(accountName, money, reason)

Fires esx:addAccountMoney on the server (source, accountName, money, reason) and syncs the account to the client.

Returns: true on success, false if the new balance would overflow. Throws for amounts of 0 or below.

local reward = 1200

if reward > 0 then
    xPlayer.addAccountMoney("bank", reward, "Delivery job")
end

removeAccountMoneyCopy Anchor Link

xPlayer.removeAccountMoney(accountName, money, reason)

Balances never go negative. Fires esx:removeAccountMoney on the server.

Returns: true on success, false if the balance is too low or rounding turned the amount into 0. Throws for amounts of 0 or below.

local price = 500

if xPlayer.removeAccountMoney("bank", price, "Bought a phone") then
    xPlayer.addInventoryItem("phone", 1)
else
    xPlayer.showNotification("Not enough money in your bank account", "error")
end

PaycheckCopy Anchor Link

togglePaycheckCopy Anchor Link

xPlayer.togglePaycheck(toggle)

Not saved. Every new session starts with paychecks enabled.

xPlayer.togglePaycheck(false) -- e.g. while the player is in jail

isPaycheckEnabledCopy Anchor Link

xPlayer.isPaycheckEnabled()

Returns: boolean

JobCopy Anchor Link

getJobCopy Anchor Link

xPlayer.getJob()

Returns the live job table.

local job = xPlayer.getJob()

if job.name == "police" and job.onDuty then
    -- allow cuffing
end

setJobCopy Anchor Link

xPlayer.setJob(newJob, grade, onDuty)

If the job or grade does not exist, ESX prints a warning and does nothing. On success it stores the duty state in metadata.jobDuty, updates the job state bag and fires esx:setJob on the server (source, job, lastJob) and the client (job, lastJob).

if ESX.DoesJobExist("mechanic", 0) then
    xPlayer.setJob("mechanic", 0)
end

-- Toggle duty without changing the job
local job = xPlayer.getJob()
xPlayer.setJob(job.name, job.grade, not job.onDuty)

refreshJobCopy Anchor Link

xPlayer.refreshJob()

Reloads label, grade name, salary and outfits from ESX.Jobs while keeping the grade and duty state. Fires esx:jobDataRefreshed. ESX.RefreshJob(jobName) calls this for every player in that job, so you rarely need it directly.

Returns: true, or false if the grade no longer exists. In that case the player is set to unemployed grade 0.

InventoryCopy Anchor Link

These methods describe the default es_extended inventory. Items must exist in the items table (or be added with ESX.AddItems). See adding items.

getInventoryCopy Anchor Link

xPlayer.getInventory(minimal)

Returns: an array of items the player owns (count above 0), sorted by label. Each item is { name, count, label, weight, usable, rare, canRemove }.

for _, item in ipairs(xPlayer.getInventory()) do
    print(item.label, item.count)
end

getInventoryItemCopy Anchor Link

xPlayer.getInventoryItem(itemName)

Returns: the item table. For known items the player does not own, a new entry with count = 0. nil for items that do not exist.

local bread = xPlayer.getInventoryItem("bread")

if bread and bread.count >= 2 then
    -- player has at least 2 bread
end

hasItemCopy Anchor Link

xPlayer.hasItem(itemName)

Returns: item, count if the player has at least one, otherwise false.

local item, count = xPlayer.hasItem("lockpick")

if item then
    print(("Player has %d lockpicks"):format(count))
end

With ox_inventory the signature is hasItem(name, metadata).

addInventoryItemCopy Anchor Link

xPlayer.addInventoryItem(itemName, count)

Fires esx:onAddInventoryItem on the server (source, itemName, newCount) and esx:addInventoryItem on the client.

Returns: true on success, false for invalid counts or unknown items.

if xPlayer.canCarryItem("water", 3) then
    xPlayer.addInventoryItem("water", 3)
else
    xPlayer.showNotification("You cannot carry that much", "error")
end

With ox_inventory the signature is addInventoryItem(name, count, metadata, slot); count defaults to 1.

removeInventoryItemCopy Anchor Link

xPlayer.removeInventoryItem(itemName, count)

Fires esx:onRemoveInventoryItem on the server (source, itemName, newCount).

Returns: true on success, false if the player does not have the item or not enough of it. Throws for counts of 0 or below.

if xPlayer.removeInventoryItem("lockpick", 1) then
    TriggerClientEvent("myscript:client:pickLock", xPlayer.source)
end

With ox_inventory the signature is removeInventoryItem(name, count, metadata, slot).

setInventoryItemCopy Anchor Link

xPlayer.setInventoryItem(itemName, count)

Adds or removes the difference using the methods above.

Returns: the result of addInventoryItem / removeInventoryItem, nil if the count is already correct, false for unknown items or negative counts.

xPlayer.setInventoryItem("bandage", 0) -- remove all bandages

With ox_inventory the signature is setInventoryItem(name, count, metadata).

canCarryItemCopy Anchor Link

xPlayer.canCarryItem(itemName, count)

Returns: true if weight + itemWeight * count stays within maxWeight. false for unknown items.

With ox_inventory the signature is canCarryItem(name, count, metadata).

canSwapItemCopy Anchor Link

xPlayer.canSwapItem(firstItem, firstItemCount, testItem, testItemCount)

Returns: true if the player owns enough of firstItem and the weight after the swap fits.

if xPlayer.canSwapItem("fish", 10, "packaged_fish", 5) then
    xPlayer.removeInventoryItem("fish", 10)
    xPlayer.addInventoryItem("packaged_fish", 5)
end

getWeightCopy Anchor Link

xPlayer.getWeight()

Returns: number, the current inventory weight.

getMaxWeightCopy Anchor Link

xPlayer.getMaxWeight()

Returns: number, the weight limit (starts at Config.MaxWeight).

setMaxWeightCopy Anchor Link

xPlayer.setMaxWeight(newWeight)

Not saved; resets to Config.MaxWeight on the next load. Returns false for invalid values. With ox_inventory, the value is also forwarded to SetMaxWeight.

-- backpack equipped
xPlayer.setMaxWeight(xPlayer.getMaxWeight() + 20)

syncInventoryCopy Anchor Link

xPlayer.syncInventory(weight, maxWeight, items, money)

Only exists with ox_inventory. ox_inventory calls it to copy its weight, items and account balances into the xPlayer. Do not call it yourself.

WeaponsCopy Anchor Link

Weapon methods only work with the default inventory. With ox_inventory, weapons are items: these methods do nothing, getLoadout() returns {}, and hasWeapon / hasWeaponComponent return false.

Weapon names are the upper-case names from Config.Weapons, for example "WEAPON_PISTOL". Component names are the short ESX names from that config, for example "clip_extended" or "suppressor".

getLoadoutCopy Anchor Link

xPlayer.getLoadout(minimal)

Returns: array of { name, label, ammo, components, tintIndex } or the minimal map.

for _, weapon in ipairs(xPlayer.getLoadout()) do
    print(weapon.label, weapon.ammo)
end

getWeaponCopy Anchor Link

xPlayer.getWeapon(weaponName)

Returns: loadoutIndex, weapon (the live loadout entry) or nil, nil.

local _, weapon = xPlayer.getWeapon("WEAPON_PISTOL")

if weapon then
    print("Pistol ammo: " .. weapon.ammo)
end

hasWeaponCopy Anchor Link

xPlayer.hasWeapon(weaponName)

Returns: boolean

addWeaponCopy Anchor Link

xPlayer.addWeapon(weaponName, ammo)

Gives the weapon to the ped and shows an inventory notification.

Returns: true, or false if the player already has the weapon.

if not xPlayer.hasWeapon("WEAPON_STUNGUN") then
    xPlayer.addWeapon("WEAPON_STUNGUN", 0)
end

removeWeaponCopy Anchor Link

xPlayer.removeWeapon(weaponName)

Removes the weapon, its components and its ammo from the ped.

Returns: true, or false if the player did not have it.

addWeaponAmmoCopy Anchor Link

xPlayer.addWeaponAmmo(weaponName, ammoCount)

Returns: true, or false if the player does not have the weapon.

removeWeaponAmmoCopy Anchor Link

xPlayer.removeWeaponAmmo(weaponName, ammoCount)

Subtracts ammo. There is no lower bound, so check the current ammo first if it matters.

Returns: true, or false if the player does not have the weapon.

updateWeaponAmmoCopy Anchor Link

xPlayer.updateWeaponAmmo(weaponName, ammoCount)

Sets the stored ammo to an exact value without touching the ped (ESX uses it to sync ammo reported by the client). Throwable weapons (throwable = true in the config) are removed when the ammo reaches 0.

Returns: true, or false if the player does not have the weapon.

addWeaponComponentCopy Anchor Link

xPlayer.addWeaponComponent(weaponName, weaponComponent)

Returns: true, or false if the player lacks the weapon, the component does not exist for it, or it is already attached.

xPlayer.addWeaponComponent("WEAPON_PISTOL", "flashlight")

removeWeaponComponentCopy Anchor Link

xPlayer.removeWeaponComponent(weaponName, weaponComponent)

Returns: true, or false if nothing was removed.

hasWeaponComponentCopy Anchor Link

xPlayer.hasWeaponComponent(weaponName, weaponComponent)

Returns: boolean

setWeaponTintCopy Anchor Link

xPlayer.setWeaponTint(weaponName, weaponTintIndex)

Returns: true, or false if the player lacks the weapon or the tint is invalid.

xPlayer.setWeaponTint("WEAPON_PISTOL", 2) -- gold

getWeaponTintCopy Anchor Link

xPlayer.getWeaponTint(weaponName)

Returns: number, the tint index, or 0 if the player does not have the weapon.

MetadataCopy Anchor Link

Metadata is a persistent table saved in the metadata column of users. Changes are synced to ESX.PlayerData.metadata on the client.

getMetaCopy Anchor Link

xPlayer.getMeta(index, subIndex)

Returns: the value, a { [key] = value } table when subIndex is a list, or nil if the key does not exist (an error when Config.EnableDebug is on).

local stress = xPlayer.getMeta("stress") or 0
local licenses = xPlayer.getMeta("licenses", { "driver", "weapon" })

setMetaCopy Anchor Link

xPlayer.setMeta(index, value, subValue)

xPlayer.setMeta("stress", 35)
xPlayer.setMeta("licenses", "driver", true) -- metadata.licenses.driver = true

clearMetaCopy Anchor Link

xPlayer.clearMeta(index, subValues)

xPlayer.clearMeta("stress")
xPlayer.clearMeta("licenses", { "weapon", "pilot" })

NotificationsCopy Anchor Link

These methods trigger client events, so the notification shows on the player's screen.

showNotificationCopy Anchor Link

xPlayer.showNotification(msg, notifyType, length, title, position)

xPlayer.showNotification("Vehicle stored", "success", 3000)

showAdvancedNotificationCopy Anchor Link

xPlayer.showAdvancedNotification(sender, subject, msg, textureDict, iconType, flash, saveToBrief, hudColorIndex)

xPlayer.showAdvancedNotification("Maze Bank", "Transfer", "You received $500", "CHAR_BANK_MAZE", 9, false)

showHelpNotificationCopy Anchor Link

xPlayer.showHelpNotification(msg, thisFrame, beep, duration)

Internal methodsCopy Anchor Link

beginAccountOperation, endAccountOperation, beginAccountShutdown and getPendingAccountOperations exist on every xPlayer. es_extended uses them to finish pending money operations before the final save when a player drops. They are not meant for resource code.

Common issuesCopy Anchor Link

• attempt to index a nil value (local 'xPlayer'): the player is not loaded yet or has left. Always check the result of ESX.GetPlayerFromId.
• Money "disappears" after a restart: you changed xPlayer.accounts[i].money directly. Use the account methods.
• Items over the weight limit: addInventoryItem does not check weight with the default inventory. Use canCarryItem.
• Weapon methods do nothing: you run ox_inventory. Give weapons as items with exports.ox_inventory:AddItem.
• Trusting client input: never pass amounts from a client event straight into addAccountMoney. Validate type, range and the player's distance on the server.

RelatedCopy Anchor Link

• Server functions
• PlayerData
• Server events
• Money and accounts guide
• Create a job

Frequently asked questions