PlayerData

PlayerData is the information ESX keeps about the loaded character: identity, accounts, inventory, loadout, job, group and metadata. On the server it lives on the xPlayer object. On the client a copy is stored in ESX.PlayerData and kept up to date by ESX events. Read it on the client for UI and checks, but make every decision that matters (money, items, permissions) on the server.

OverviewCopy Anchor Link

Getting PlayerDataCopy Anchor Link

shared_script "@es_extended/imports.lua"

CreateThread(function()
    while not ESX.PlayerLoaded do
        Wait(250)
    end

    print("Job: " .. ESX.PlayerData.job.label)
end)

RegisterNetEvent("esx:setJob", function(job, lastJob)
    print(("Job changed from %s to %s"):format(lastJob.name, job.name))
end)

Field referenceCopy Anchor Link

"Client" means ESX.PlayerData.<field>, "Server" means the xPlayer object.

DetailsCopy Anchor Link

jobCopy Anchor Link

{
    name = "police",
    label = "LSPD",
    type = "leo",
    onDuty = true,
    grade = 2,
    grade_name = "sergeant",
    grade_label = "Sergeant",
    grade_salary = 900,
    skin_male = {},
    skin_female = {},
}

grade and grade_salary are numbers. onDuty comes from metadata.jobDuty. The field list is described in xPlayer.getJob.

accountsCopy Anchor Link

An array, not a map:

{
    { name = "bank", money = 50000, label = "Bank", round = true, index = 1 },
    { name = "money", money = 500, label = "Cash", round = true, index = 2 },
    { name = "black_money", money = 0, label = "Dirty Money", round = true, index = 3 },
}

The order follows Config.Accounts and is not guaranteed. Look accounts up by name:

local bank = ESX.GetAccount("bank")
print("Bank: $" .. (bank and bank.money or 0))

inventoryCopy Anchor Link

With the default inventory: an array of the items the player owns (count above 0), sorted by label.

{
    { name = "bread", label = "Bread", count = 3, weight = 1, usable = true, rare = false, canRemove = true },
    { name = "water", label = "Water", count = 1, weight = 1, usable = true, rare = false, canRemove = true },
}

local breadCount = ESX.SearchInventory("bread", true) -- 0 when the player has none

With ox_inventory, use ox_inventory's own exports to read items.

loadoutCopy Anchor Link

{
    { name = "WEAPON_PISTOL", label = "Pistol", ammo = 48, components = { "clip_default", "flashlight" }, tintIndex = 0 },
}

Empty with ox_inventory.

metadataCopy Anchor Link

A free-form table that is saved to the database. ESX itself uses health, armor, lastPlaytime and jobDuty. Write it on the server with xPlayer.setMeta; the client copy updates automatically.

-- client
local stress = ESX.PlayerData.metadata.stress or 0

Reacting to changes on the clientCopy Anchor Link

With @es_extended/imports.lua you can also define a global OnPlayerData function. It is called with key, value, lastValue whenever es_extended changes a field:

function OnPlayerData(key, value)
    if key == "job" then
        updateJobBlips(value.name)
    end
end

See client events for the full list.

Common issuesCopy Anchor Link

• attempt to index a nil value (field 'job'): you read ESX.PlayerData before esx:playerLoaded. Wait for ESX.PlayerLoaded.
• Stale data in a resource without imports: the exported ESX object is a snapshot. Use ESX.GetPlayerData() or switch to @es_extended/imports.lua.
• xPlayer.firstName is nil: on the server, identity fields are variables. Use xPlayer.get("firstName").
• Inventory indexed by name returns nil: inventory is an array. Use ESX.SearchInventory or xPlayer.getInventoryItem.

RelatedCopy Anchor Link

• xPlayer
• Client functions
• Client events
• Shared playerdata helpers

Frequently asked questions