# Client Functions (/docs/es_extended/client/functions)

These are the general-purpose functions that `es_extended` adds to the `ESX` object on the client. Use them to check whether the character is loaded, read and update the cached player data, search the built-in inventory, register secure net events and key bindings.

## Overview [#overview]

| | |
|---|---|
| Resource | `es_extended` |
| Side | Client |
| Source | `client/modules/player/*.lua`, `client/modules/core/events.lua`, `client/compat.lua`, `client/modules/game/*.lua` |
| Access | `ESX = exports['es_extended']:getSharedObject()` or `shared_script '@es_extended/imports.lua'` |

UI helpers (notifications, menus, context, progress bar) are on [Client UI](/docs/es_extended/client/ui). Entity helpers are on [ESX.Game](/docs/es_extended/client/modules/game).

## Client fields [#client-fields]

These values are set when `es_extended` starts on the client.

| Field | Type | Description |
|---|---|---|
| `ESX.PlayerData` | `table` | Cached data of the local character. See [Client PlayerData](/docs/es_extended/shared/playerdata). |
| `ESX.PlayerLoaded` | `boolean` | `true` after `esx:playerLoaded` has been handled, `false` after logout. |
| `ESX.playerId` | `number` | Local player index (`PlayerId()`). |
| `ESX.serverId` | `number` | Server id of the local player (`GetPlayerServerId(PlayerId())`). |

## Player data [#player-data]

### ESX.IsPlayerLoaded [#esxisplayerloaded]

```lua
ESX.IsPlayerLoaded()
```

Returns whether the local character is fully loaded. Check this before you read `ESX.PlayerData`.

**Returns:** `boolean`

```lua title="client/main.lua"
CreateThread(function()
    while not ESX.IsPlayerLoaded() do
        Wait(250)
    end

    print(('Loaded as %s'):format(ESX.PlayerData.job.label))
end)
```

### ESX.GetPlayerData [#esxgetplayerdata]

```lua
ESX.GetPlayerData()
```

Returns the `ESX.PlayerData` table. It is the same table reference, so reading `ESX.PlayerData` directly is equivalent.

**Returns:** `table`

```lua
local data = ESX.GetPlayerData()
print(data.identifier, data.job.name, data.job.grade_label)
```

### ESX.SetPlayerData [#esxsetplayerdata]

```lua
ESX.SetPlayerData(key, val)
```

Writes a value into the local `ESX.PlayerData` and fires the local `esx:setPlayerData` event so other scripts (and `OnPlayerData` from the imports file) can react. The event is not fired for the `loadout` key, or when a non-table value did not change.

| Name | Type | Description |
|---|---|---|
| `key` | `string` | Key in `ESX.PlayerData` to set. |
| `val` | `any` | New value. |

**Returns:** nothing

<Callout type="warn">
This only changes the client cache. It does not save anything on the server and the server will overwrite the key the next time it sends an update. Change real data (job, money, items) on the server through the [xPlayer](/docs/es_extended/server/xplayer) object.
</Callout>

```lua
ESX.SetPlayerData('isCuffed', true)
```

### ESX.GetAccount [#esxgetaccount]

```lua
ESX.GetAccount(account)
```

Returns one entry from `ESX.PlayerData.accounts`.

| Name | Type | Description |
|---|---|---|
| `account` | `string` | Account name, for example `money`, `bank` or `black_money`. |

**Returns:** `table|nil` with `name`, `money`, `label`, `round` and `index`, or `nil` if the account does not exist.

```lua
local bank = ESX.GetAccount('bank')

if bank then
    print(('Bank balance: $%s'):format(ESX.Math.GroupDigits(bank.money)))
end
```

### ESX.SearchInventory [#esxsearchinventory]

```lua
ESX.SearchInventory(items, count)
```

Searches `ESX.PlayerData.inventory` (built-in ESX inventory only).

| Name | Type | Description |
|---|---|---|
| `items` | `string \| string[]` | One item name, or an array of item names. |
| `count` | `boolean?` | When `true`, return counts instead of item tables. Missing items return `0`. |

**Returns:**

- with a single item name: the item table (`name`, `count`, `label`, `weight`, `usable`, `rare`, `canRemove`), its count, or `nil`.
- with an array: a table keyed by item name.

```lua
local counts = ESX.SearchInventory({ 'bread', 'water' }, true)
print(('bread: %d, water: %d'):format(counts.bread, counts.water))

local bread = ESX.SearchInventory('bread')
if bread then
    print(bread.label, bread.count)
end
```

### ESX.ShowInventory [#esxshowinventory]

```lua
ESX.ShowInventory()
```

Opens the default inventory UI through `exports.esx_inventory:ShowInventory()`. Does nothing unless `Config.EnableDefaultInventory` is enabled.

**Returns:** nothing

## Events and spawning [#events-and-spawning]

### ESX.SecureNetEvent [#esxsecurenetevent]

```lua
ESX.SecureNetEvent(name, func)
```

Registers a client net event that only runs when the **server** triggered it. Calls from a local `TriggerEvent` (where `source` is an empty string) are ignored. Handlers are removed automatically when the registering resource stops. Errors inside the handler are re-thrown with the original message.

| Name | Type | Description |
|---|---|---|
| `name` | `string` | Event name. |
| `func` | `function` | Handler, receives the event arguments. |

**Returns:** nothing

```lua title="client/main.lua"
ESX.SecureNetEvent('myjob:setDuty', function(onDuty)
    ESX.ShowNotification(onDuty and 'You are on duty' or 'You are off duty')
end)
```

```lua title="server/main.lua"
TriggerClientEvent('myjob:setDuty', source, true)
```

Use it for every client event that changes state or grants something. A plain `RegisterNetEvent` handler can also be fired locally by any client script.

### ESX.DisableSpawnManager [#esxdisablespawnmanager]

```lua
ESX.DisableSpawnManager()
```

Turns off auto-spawn of the default `spawnmanager` resource if it is started. ESX calls this itself before it spawns the player.

**Returns:** nothing

### ESX.SpawnPlayer [#esxspawnplayer]

```lua
ESX.SpawnPlayer(skin, coords, cb)
```

Loads a skin through `skinchanger:loadSkin`, freezes the player, moves the ped to `coords`, waits up to 5 seconds for collision, resurrects the ped and fires the `playerSpawned` event. Used by ESX on first spawn and by multicharacter resources.

| Name | Type | Description |
|---|---|---|
| `skin` | `table` | Skin table for skinchanger. |
| `coords` | `table` | Table with `x`, `y`, `z` and `heading` (not `w`). |
| `cb` | `function` | Called when the spawn is done. |

**Returns:** nothing

<Callout type="warn">
`ESX.SpawnPlayer` leaves the player frozen. ESX unfreezes it in its own `esx:playerLoaded` handler. If you call it yourself later, unfreeze the ped in `cb` (for example with `FreezeEntityPosition(PlayerPedId(), false)`).
</Callout>

## Input and keys [#input-and-keys]

### ESX.RegisterInput [#esxregisterinput]

```lua
ESX.RegisterInput(command_name, label, input_group, key, on_press, on_release)
```

Registers a remappable key binding. It wraps `xLib.addKeybind`, which creates the commands `+command_name` and `-command_name` and a key mapping the player can change in the GTA settings. The callbacks do not fire while the pause menu is open.

| Name | Type | Description |
|---|---|---|
| `command_name` | `string` | Unique name. ESX prefixes it with `+` / `-`. |
| `label` | `string` | Text shown in the key bindings settings. |
| `input_group` | `string` | Input mapper, usually `keyboard`. See [input mapper ids](https://docs.fivem.net/docs/game-references/input-mapper-parameter-ids/). |
| `key` | `string` | Default key, for example `f6`. |
| `on_press` | `function?` | Called on key down. |
| `on_release` | `function?` | Called on key up. |

**Returns:** a keybind object with `currentKey`, `isPressed`, `disable(self, toggle)`, `remove(self)` and `getCurrentKey(self)`.

```lua title="client/main.lua"
local menuKey = ESX.RegisterInput('myjob_menu', 'Open job menu', 'keyboard', 'f6', function()
    if ESX.PlayerData.job.name == 'police' then
        OpenPoliceMenu()
    end
end)

print('Menu key is', menuKey.currentKey)
```

### ESX.HashString [#esxhashstring]

```lua
ESX.HashString(str)
```

Despite the name, this builds a `~INPUT_...~` text token for a command mapping, so GTA can render the bound key inside help text.

| Name | Type | Description |
|---|---|---|
| `str` | `string` | The mapped command name. For keys made with `ESX.RegisterInput`, the mapped command is `+` plus your name. |

**Returns:** `string`

```lua
ESX.ShowHelpNotification(('Press %s to open the menu'):format(ESX.HashString('+myjob_menu')))
```

If the token does not render for your binding, use the `currentKey` field of the object returned by `ESX.RegisterInput` instead.

## Vehicles [#vehicles]

### ESX.GetVehicleTypeClient [#esxgetvehicletypeclient]

```lua
ESX.GetVehicleTypeClient(model)
```

Returns the vehicle type string FiveM expects for `CreateVehicleServerSetter`, based on the vehicle class plus a list of known exceptions. `ESX.GetVehicleType` is an alias on the client.

| Name | Type | Description |
|---|---|---|
| `model` | `string \| number` | Model name or hash. |

**Returns:** `string|false`: one of `automobile`, `bike`, `boat`, `heli`, `plane`, `submarine`, `trailer`, `train`, or `false` when the model does not exist or is not a vehicle.

```lua
print(ESX.GetVehicleTypeClient('policeb')) -- bike
print(ESX.GetVehicleTypeClient('kosatka')) -- submarine
```

The server version is documented in [Server functions](/docs/es_extended/server/functions).

## Common issues [#common-issues]

- **`ESX.PlayerData.job` is nil.** You read it before the player loaded. Wait for `ESX.IsPlayerLoaded()` or the `esx:playerLoaded` event.
- **Changes from `ESX.SetPlayerData` disappear.** The server owns the real data and pushes it again on the next update.
- **Inventory helpers return nothing.** `ESX.SearchInventory` and `ESX.ShowInventory` only work with the built-in inventory, not with `Config.CustomInventory`.

## Related [#related]

- [Client UI functions](/docs/es_extended/client/ui)
- [Callbacks](/docs/es_extended/client/modules/callback)
- [Client events](/docs/es_extended/events/client)
- [Client PlayerData](/docs/es_extended/shared/playerdata)
- [Server functions](/docs/es_extended/server/functions)