Shared Functions

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.

OverviewCopy Anchor Link

Related shared pages: Math, Table, Timeout, Client PlayerData.

Getting the ESX objectCopy Anchor Link

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.

ConfigCopy Anchor Link

ESX.GetConfigCopy Anchor Link

ESX.GetConfig(key)

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

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

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

See Configuration for all keys.

WeaponsCopy Anchor Link

Weapon data comes from Config.Weapons (weapon config). Each entry has name, label, ammo (label, hash), tints and components (name, label, hash).

ESX.GetWeaponCopy Anchor Link

ESX.GetWeapon(weaponName)

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

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

ESX.GetWeaponFromHashCopy Anchor Link

ESX.GetWeaponFromHash(weaponHash)

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

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

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

ESX.GetWeaponListCopy Anchor Link

ESX.GetWeaponList(byHash)

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

ESX.GetWeaponLabelCopy Anchor Link

ESX.GetWeaponLabel(weaponName)

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

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

ESX.GetWeaponComponentCopy Anchor Link

ESX.GetWeaponComponent(weaponName, weaponComponent)

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

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

ValidationCopy Anchor Link

ESX.ValidateTypeCopy Anchor Link

ESX.ValidateType(value, ...)

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

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.AssertTypeCopy Anchor Link

ESX.AssertType(value, ...)

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

ESX.IsFunctionReferenceCopy Anchor Link

ESX.IsFunctionReference(val)

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

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

ESX.IsValidLocaleStringCopy Anchor Link

ESX.IsValidLocaleString(str, allowDigits)

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

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.

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

UtilitiesCopy Anchor Link

ESX.GetRandomStringCopy Anchor Link

ESX.GetRandomString(length)

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

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

ESX.AwaitCopy Anchor Link

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

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

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

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

ESX.DumpTableCopy Anchor Link

ESX.DumpTable(table, nb)

Turns a table into a readable string for debugging.

Returns: string

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

ESX.RoundCopy Anchor Link

ESX.Round(value, numDecimalPlaces)

Shortcut for ESX.Math.Round.

RelatedCopy Anchor Link

• Math functions
• Table functions
• Timeout functions
• Server functions
• Client functions

Frequently asked questions