# Shared Functions (/docs/es_extended/shared)

These functions are defined in `es_extended/shared` and exist on both the client and the server `ESX` object. They cover config access, weapon data from `Config.Weapons`, input validation and a few utilities. Math, table and timeout helpers have their own pages.

## Overview [#overview]

| | |
|---|---|
| Resource | `es_extended` |
| Side | Shared (client and server) |
| Source | `shared/main.lua`, `shared/modules/*.lua`, `shared/compat.lua` |

Related shared pages: [Math](/docs/es_extended/shared/math), [Table](/docs/es_extended/shared/table), [Timeout](/docs/es_extended/shared/timeout), [Client PlayerData](/docs/es_extended/shared/playerdata).

## Getting the ESX object [#getting-the-esx-object]

```lua
ESX = exports['es_extended']:getSharedObject()
```

The `getSharedObject` export returns the `ESX` table. The `@es_extended/imports.lua` shared script does this for you and also keeps `ESX.PlayerData` in sync on the client.

<Callout type="warn" title="Deprecated">
The event `esx:getSharedObject` still answers for old scripts, but new code should use the export or the imports file. See [Convert old ESX scripts](/docs/guides/convert-old-esx-scripts).
</Callout>

## Config [#config]

### ESX.GetConfig [#esxgetconfig]

```lua
ESX.GetConfig(key)
```

| Name | Type | Description |
|---|---|---|
| `key` | `string?` | Config key. Without it the whole `Config` table is returned. |

**Returns:** the value of `Config[key]`, or the full config table.

```lua
if ESX.GetConfig('Multichar') then
    print('Multicharacter is enabled')
end

local inventory = ESX.GetConfig('CustomInventory') -- false or 'ox'
```

See [Configuration](/docs/es_extended/config) for all keys.

## Weapons [#weapons]

Weapon data comes from `Config.Weapons` ([weapon config](/docs/es_extended/config/weapons)). Each entry has `name`, `label`, `ammo` (`label`, `hash`), `tints` and `components` (`name`, `label`, `hash`).

### ESX.GetWeapon [#esxgetweapon]

```lua
ESX.GetWeapon(weaponName)
```

| Name | Type | Description |
|---|---|---|
| `weaponName` | `string` | Weapon name, case-insensitive (`weapon_pistol` works). |

**Returns:** `index` in `Config.Weapons` and the weapon `table`. Raises `Invalid weapon name!` for unknown weapons.

```lua
local _, weapon = ESX.GetWeapon('WEAPON_PISTOL')
print(weapon.label, weapon.ammo.label)
```

### ESX.GetWeaponFromHash [#esxgetweaponfromhash]

```lua
ESX.GetWeaponFromHash(weaponHash)
```

| Name | Type | Description |
|---|---|---|
| `weaponHash` | `number \| string` | Weapon hash, or a name that is hashed with `joaat`. |

**Returns:** weapon `table` or `nil`. Does not raise errors.

```lua
local weapon = ESX.GetWeaponFromHash(GetSelectedPedWeapon(PlayerPedId()))

if weapon then
    print('Holding', weapon.label)
end
```

### ESX.GetWeaponList [#esxgetweaponlist]

```lua
ESX.GetWeaponList(byHash)
```

| Name | Type | Description |
|---|---|---|
| `byHash` | `boolean?` | When `true`, return a table keyed by weapon hash. |

**Returns:** `Config.Weapons` (array) or the hash-keyed table.

### ESX.GetWeaponLabel [#esxgetweaponlabel]

```lua
ESX.GetWeaponLabel(weaponName)
```

**Returns:** `string` label (empty string if the entry has no label). Raises `Invalid weapon name!` for unknown weapons.

```lua
print(ESX.GetWeaponLabel('weapon_carbinerifle')) -- Carbine Rifle
```

### ESX.GetWeaponComponent [#esxgetweaponcomponent]

```lua
ESX.GetWeaponComponent(weaponName, weaponComponent)
```

| Name | Type | Description |
|---|---|---|
| `weaponName` | `string` | Weapon name. |
| `weaponComponent` | `string` | Component name from the config, for example `suppressor`. |

**Returns:** component table (`name`, `label`, `hash`) or `nil`. Raises for unknown weapons.

```lua
local suppressor = ESX.GetWeaponComponent('WEAPON_PISTOL', 'suppressor')
if suppressor then
    GiveWeaponComponentToPed(PlayerPedId(), `WEAPON_PISTOL`, suppressor.hash)
end
```

## Validation [#validation]

### ESX.ValidateType [#esxvalidatetype]

```lua
ESX.ValidateType(value, ...)
```

| Name | Type | Description |
|---|---|---|
| `value` | `any` | Value to check. |
| `...` | `string` | Allowed Lua type names, for example `'string', 'number'`. |

**Returns:** `true`, or `false` and an error message such as `bad value (string expected, got number)`. With no types given it returns `true`.

```lua title="server/main.lua"
RegisterNetEvent('shop:buy', function(item, amount)
    local ok, err = ESX.ValidateType(amount, 'number')
    if not ok then
        return print(('[shop] %s from %s'):format(err, source))
    end
end)
```

### ESX.AssertType [#esxasserttype]

```lua
ESX.AssertType(value, ...)
```

Same as `ValidateType`, but raises an error instead of returning `false`. **Returns:** `true`.

### ESX.IsFunctionReference [#esxisfunctionreference]

```lua
ESX.IsFunctionReference(val)
```

**Returns:** `true` for functions and for tables with a callable `__call` metamethod (function references received from other resources).

```lua
local function runCallback(cb, ...)
    if ESX.IsFunctionReference(cb) then
        return cb(...)
    end
end
```

### ESX.IsValidLocaleString [#esxisvalidlocalestring]

```lua
ESX.IsValidLocaleString(str, allowDigits)
```

Checks that a string only contains characters allowed for names, for example in character creation.

| Name | Type | Description |
|---|---|---|
| `str` | `string` | Text to check. Must be valid UTF-8. |
| `allowDigits` | `boolean?` | Also allow `0-9`. |

**Returns:** `boolean`

Always allowed: `A-Z`, `a-z`, space, `-` and Latin extended letters (accents). Extra ranges are added for `Config.Locale` values `el` (Greek), `sr` (Cyrillic), `he` (Hebrew), `ar` (Arabic) and `zh-cn` (Chinese), and for every charset enabled in `Config.ValidCharacterSets`.

```lua
print(ESX.IsValidLocaleString('Jean-Luc')) -- true
print(ESX.IsValidLocaleString('John_Doe')) -- false
print(ESX.IsValidLocaleString('Agent 47', true)) -- true
```

## Utilities [#utilities]

### ESX.GetRandomString [#esxgetrandomstring]

```lua
ESX.GetRandomString(length)
```

| Name | Type | Description |
|---|---|---|
| `length` | `number` | Number of characters. Fractions are rounded up, `0` or less returns `''`. |

**Returns:** `string` of random `0-9`, `A-Z` and `a-z` characters. It uses `math.random`, so do not use it for secrets.

```lua
local reference = ESX.GetRandomString(8) -- e.g. "aZ3k9QpL"
```

### ESX.Await [#esxawait]

```lua
ESX.Await(cb, errMessage, timeout, interval)
```

Calls `cb` until it returns a non-`nil` value. Must run in a thread.

| Name | Type | Description |
|---|---|---|
| `cb` | `function` | Condition. Return any non-`nil` value to stop waiting. `false` counts as a result. |
| `errMessage` | `string?` | Error text on timeout. Default `failed to resolve callback`. |
| `timeout` | `number \| false?` | Max wait in ms. Default `5000`. `false` waits forever. |
| `interval` | `integer?` | Wait between checks in ms. Default `0`. |

**Returns:** the first non-`nil` value of `cb`. Raises an error on timeout.

```lua
local ped = ESX.Await(function()
    local p = PlayerPedId()
    return DoesEntityExist(p) and p or nil
end, 'Player ped did not load', 10000, 100)
```

<Callout type="info">
Return `nil`, not `false`, while you are still waiting. `ESX.Await` stops on `false` because it only checks for `nil`.
</Callout>

### ESX.DumpTable [#esxdumptable]

```lua
ESX.DumpTable(table, nb)
```

Turns a table into a readable string for debugging.

| Name | Type | Description |
|---|---|---|
| `table` | `any` | Value to dump. Non-tables are returned with `tostring`. |
| `nb` | `number?` | Starting indentation level. Default `0`. |

**Returns:** `string`

```lua
print(ESX.DumpTable(ESX.GetConfig('Accounts')))
```

### ESX.Round [#esxround]

```lua
ESX.Round(value, numDecimalPlaces)
```

Shortcut for [ESX.Math.Round](/docs/es_extended/shared/math).

## Related [#related]

- [Math functions](/docs/es_extended/shared/math)
- [Table functions](/docs/es_extended/shared/table)
- [Timeout functions](/docs/es_extended/shared/timeout)
- [Server functions](/docs/es_extended/server/functions)
- [Client functions](/docs/es_extended/client/functions)