FiveM Docs
es_extendedShared

Client PlayerData

What ESX.PlayerData contains on the client in ESX Legacy, how it stays in sync with the server, and how to react to changes with OnPlayerData and esx:setPlayerData.

ESX.PlayerData is the client-side copy of the local character: identifier, job, accounts, inventory, loadout, metadata and a few live values like the ped. The server sends it on esx:playerLoaded and pushes updates through secure events. This page explains the fields and how to keep your copy in sync.

Overview

Resourcees_extended
SideClient (server code uses the xPlayer object)
Kept in sync by@es_extended/imports.lua

For the server-side player model and database columns see Player data.

Getting PlayerData in your resource

Load the imports file in your manifest. It fetches the ESX object, fills ESX.PlayerData on esx:playerLoaded, applies every esx:setPlayerData update coming from es_extended, and clears the data on logout.

fxmanifest.lua
shared_scripts {
    '@esx_lib/imports.lua',
    '@es_extended/imports.lua',
}

Since the ESX object comes from an export, your resource gets a copy of the table. If you only call exports['es_extended']:getSharedObject() once, ESX.PlayerData is a snapshot and does not update. Use the imports file, or ESX.GetPlayerData(), which always returns the current data from es_extended.

Fields

Values after esx:playerLoaded. Some keys are added later by ESX on the client.

KeyTypeDescription
identifierstringCharacter identifier, for example char1:abc... with multicharacter.
ssnstringSocial security number of the character.
namestringCharacter name (firstName lastName when esx_identity data exists, else the FiveM name).
firstName, lastNamestringCharacter names.
dateofbirth, sex, heightstring, string, numberIdentity data when available.
groupstringPermission group, for example user or admin.
jobtableid, name, label, type, grade, grade_name, grade_label, grade_salary, skin_male, skin_female.
accountstable[]Each { name, money, label, round, index }. Use ESX.GetAccount.
moneynumberCash at load time. Use ESX.GetAccount('money') for the current value.
inventorytable[]Built-in inventory items (name, count, label, weight, usable, rare, canRemove).
weight, maxWeightnumberCurrent and maximum inventory weight.
loadouttable[]Weapons: name, label, ammo, components, tintIndex. Built-in inventory only.
metadatatableCharacter metadata (health, armor, jobDuty and custom keys).
variablestableValues set with xPlayer.set (replicated).
coordsvector3Live position of the ped, computed on read.
pednumberCurrent player ped. Updated when the ped changes.
deadbooleantrue after death, false after spawn.
weaponnumberHash of the selected weapon.
vehiclenumber | falseVehicle the player is entering or sitting in.
seatnumber | falseSeat index in that vehicle.

With Config.CustomInventory (ox_inventory), inventory, weight and loadout are not maintained by ESX. Use the inventory's own exports.

client/main.lua
RegisterNetEvent('esx:playerLoaded', function(xPlayer)
    print(('Hello %s, you work as %s (%s)'):format(
        xPlayer.firstName,
        xPlayer.job.label,
        xPlayer.job.grade_label
    ))
end)

Reacting to changes

OnPlayerData

The imports file defines a global function OnPlayerData(key, val, last) that does nothing by default. Override it in your resource to react to every PlayerData update from es_extended.

NameTypeDescription
keystringChanged key, for example job, accounts, dead, ped.
valanyNew value.
lastanyPrevious value.
client/main.lua
function OnPlayerData(key, val, last)
    if key == 'job' and val.name ~= (last and last.name) then
        RefreshJobBlips(val.name)
    elseif key == 'dead' and val then
        CloseAllMyMenus()
    end
end

esx:setPlayerData

ESX.SetPlayerData fires the local event esx:setPlayerData with (key, val, last). Listen to it if you do not use the imports file. The imports file only accepts this event when it comes from es_extended, so other resources cannot fake updates into your copy.

AddEventHandler('esx:setPlayerData', function(key, val)
    if key == 'accounts' then
        UpdateHudMoney(val)
    end
end)

Specific events

For single values you can also listen to the secure net events that change them: esx:setJob, esx:setAccountMoney, esx:setGroup, esx:setInventory, esx:setMaxWeight and esx:updatePlayerData. See Client events.

Common issues

  • ESX.PlayerData.job is nil in a thread at resource start. Wait for ESX.IsPlayerLoaded() first.
  • Changing ESX.PlayerData does nothing on the server. It is a client cache. Change data on the server through xPlayer.
  • Money in PlayerData.money is outdated. Read the money account instead.

Frequently asked questions

Independent documentation

esx-fivem.com is a community project and is not affiliated with the ESX Framework team. Facts on this page were checked against the upstream source. Official resources: docs.esx-framework.org and github.com/esx-framework.
Edit on GitHub

Last updated on

Timeout

ESX.SetTimeout and ESX.ClearTimeout run code after a delay in ESX Legacy and let you cancel it, on both client and server. Includes examples and pitfalls.

Server Events

Every esx server event in ESX Legacy 1.16 with parameters, who triggers it and example handlers, plus which client-sent events are untrusted and must be validated.

On this page

OverviewGetting PlayerData in your resourceFieldsReacting to changesOnPlayerDataesx:setPlayerDataSpecific eventsCommon issuesRelated