esx_lib

esx_lib is the official ESX utility library. It exposes a global xLib table that lazily loads modules (callbacks, player cache, points, NUI helpers, streaming, validation, rate limiting and more) into any resource that includes @esx_lib/imports.lua. es_extended itself is built on top of it, so every ESX Legacy server needs esx_lib started first.

OverviewCopy Anchor Link

Parts of esx_lib are adapted from ox_lib by Linden (LGPL-3.0). Those files carry the original notice in the source.

Installation and load orderCopy Anchor Link

esx_lib ships in the [core] folder of esx_core. Start it before es_extended:

ensure oxmysql
ensure esx_lib
ensure es_extended

To use xLib in your own resource, add the import as a shared script and declare the dependency:

fx_version 'cerulean'
game 'gta5'
lua54 'yes'

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

client_scripts { 'client/*.lua' }
server_scripts { 'server/*.lua' }

dependencies {
    'es_extended',
    'esx_lib',
}

How lazy loading worksCopy Anchor Link

imports.lua creates the xLib table with an __index metamethod. The first time you read xLib.<name>, it loads imports/<name>/shared.lua plus imports/<name>/client.lua or imports/<name>/server.lua from esx_lib and runs them inside your resource. Modules you never touch are never loaded.

If no module folder exists for a name, xLib returns a proxy that calls exports.esx_lib:<name>(...). This is how functions that must live in one central place (callback validation, pub/sub registry, triggerClientEvent) are shared by every resource.

Module summaryCopy Anchor Link

The catalog folder is not a regular module. es_extended loads imports/catalog/bootstrap.lua directly (see SQL catalog).

CallbacksCopy Anchor Link

xLib.callback is the callback system ESX uses internally. ESX.TriggerServerCallback and ESX.RegisterServerCallback are compat wrappers around it (xLib.callback.registerCompat). For new code, use xLib directly or the ESX wrappers described in Callbacks.

xLib.callback.registerCopy Anchor Link

xLib.callback.register(name, cb)

Errors inside cb are printed with a stack trace and the caller receives false.

xLib.callback.awaitCopy Anchor Link

-- client
local ... = xLib.callback.await(name, delay, ...)
-- server
local ... = xLib.callback.await(name, playerId, ...)

Yields the current thread and returns the handler's return values. Rejects with callback '<name>' does not exist if nothing is registered, or with a timeout error.

xLib.callback (with function)Copy Anchor Link

xLib.callback(name, delayOrPlayerId, cb, ...)

Same as await, but calls cb(...) with the results instead of yielding. Omitting cb prints a warning and falls back to await.

xLib.callback.register('myshop:getBalance', function(source, account)
    local xPlayer = ESX.GetPlayerFromId(source)
    if not xPlayer then return false end

    return xPlayer.getAccount(account).money
end)

xLib.callback.registerCompatCopy Anchor Link

xLib.callback.registerCompat(name, cb, owner)

Registers a handler with the legacy ESX signature: server function(source, cb, ...), client function(cb, ...). owner is the resource whose stop removes the handler. es_extended uses this for ESX.RegisterServerCallback and ESX.RegisterClientCallback.

Callback limitsCopy Anchor Link

Server callbacks are protected by per-player budgets. When a player exceeds them, the request is answered with false. All values are server convars.

The server-side receiver also gives up after the configured timeout, or 30 seconds when none is set. Payloads are limited to 32 arguments, 2048 entries and 8 levels of nesting.

Client cacheCopy Anchor Link

local cache = xLib.cache

esx_lib polls every 100 ms and triggers a local event xLib:cache:<key> with (value, previous) when ped, vehicle, seat or weapon change. Other resources update their copy from that event.

AddEventHandler('xLib:cache:vehicle', function(vehicle, previous)
    if vehicle then
        print('Entered vehicle', vehicle, 'seat', xLib.cache.seat)
    else
        print('Left vehicle', previous)
    end
end)

Points and marker zonesCopy Anchor Link

xLib.points.createCopy Anchor Link

local handle = xLib.points.create(coords, distance, hidden, enter, leave, inside)

Also available: xLib.points.remove(handle) and xLib.points.hide(handle, hidden). Proximity is scanned every 500 ms; the loop only runs every frame while at least one point with inside is active. Points are removed automatically when the creating resource stops.

xLib.point is the class form: xLib.point:new({ coords, distance, hidden, enter, leave, inside }) with methods :delete() and :toggle(hidden?). Its callbacks receive self.

xLib.markerZone.createCopy Anchor Link

local zone = xLib.markerZone.create(data)

Returns { handle, remove(), hide(hidden?), show() }, or nil when coords is invalid.

local zone = xLib.markerZone.create({
    coords = vector3(25.7, -1347.3, 29.5),
    interactDistance = 1.5,
    onEnter = function()
        ESX.TextUI('[E] Open shop')
    end,
    onExit = function()
        ESX.HideUI()
    end,
})

Interactions and keybindsCopy Anchor Link

xLib.addKeybindCopy Anchor Link

local keybind = xLib.addKeybind(data)

The returned object has currentKey, isPressed, getCurrentKey(), isControlPressed(), disable(toggle) and remove().

xLib.interactionsCopy Anchor Link

esx_lib registers one keybind named esx_interact (default E) and triggers the local event xLib:interact when it is pressed. xLib.interactions lets many resources share that key:

xLib.interactions.register(name, onPress, condition)
xLib.interactions.remove(name)
local key = xLib.interactions.getInteractKey() -- e.g. "E"

Every registered interaction whose condition() returns true runs onPress(). Interactions are removed when their resource stops.

NUI helpersCopy Anchor Link

handler(data, reply) can return a value (sent as response, nil becomes ok()), or call reply(response) later. Handlers that declare two parameters and return nil are treated as deferred; they time out after xLib:nuiDeferTimeout ms (default 10000) and reply fail('timeout', 'timeout').

StreamingCopy Anchor Link

All functions accept an optional cb. Without it they yield and return the loaded asset; with it they call cb(asset). Requests time out after xLib:streamingTimeout ms (default 10000).

Game and entity helpers (client)Copy Anchor Link

The ESX.Game.* client functions in es_extended are direct aliases of these (ESX.Game.SpawnVehicle = xLib.game.spawnVehicle and so on). See ESX.Game.

Server player and OneSync helpersCopy Anchor Link

source may be a number or numeric string. Functions return nil (or false) for invalid or disconnected players instead of erroring.

xLib.server.* (getPlayerCoords, distanceToCoords, isPlayerNearCoords, distanceToPlayer, isPlayerNearPlayer, isPlayerNearAnyCoords) and xLib.validation.playerNearCoords / playerNearPlayer are aliases of the same checks. Use them to validate client requests, for example that a player is actually standing at a shop before you charge them:

local SHOP <const> = vector3(25.7, -1347.3, 29.5)

xLib.callback.register('myshop:buy', function(source, item)
    if not xLib.player.isNearCoords(source, SHOP, 5.0) then
        return false
    end

    -- process purchase
    return true
end)

Validation and type checksCopy Anchor Link

xLib.validation (shared)Copy Anchor Link

RegisterNetEvent('myshop:deposit', function(amount)
    local value = xLib.validation.money(amount, 1, 1000000)
    if not value then return end

    local xPlayer = ESX.GetPlayerFromId(source)
    if xPlayer and xPlayer.getMoney() >= value then
        xPlayer.removeMoney(value, 'Shop deposit')
        xPlayer.addAccountMoney('bank', value, 'Shop deposit')
    end
end)

xLib.verifyCopy Anchor Link

local ok = xLib.verify(value, types, throwError)

Checks value against one type or an array of types and returns a boolean, or raises an error when throwError is true. Supported types: Lua types plus array, int, uint, float, char, vector3, vector4, ped, vehicle, prop, playerId, class and model. On the server, model asks a random connected client to validate the model through the xLib:validateModel callback. xLib.verify.debug(...) only runs when the xLib:debug convar is true.

Rate limiter and tokens (server)Copy Anchor Link

xLib.rateLimiterCopy Anchor Link

local limiter = xLib.rateLimiter(options)

Methods: limiter:consume(key, cost?) returns allowed, retryAfterMs; limiter:retryAfter(key, cost?), limiter:reset(key), limiter:clear(), limiter:size(). Buckets keyed by a player id are reset on playerDropped.

local limiter = xLib.rateLimiter({ capacity = 5, refill = 1, interval = 2000 })

RegisterNetEvent('myjob:search', function()
    local allowed, retryAfter = limiter:consume(source)
    if not allowed then
        return TriggerClientEvent('esx:showNotification', source, ('Wait %d s'):format(math.ceil(retryAfter / 1000)), 'error')
    end
    -- handle search
end)

xLib.tokenCopy Anchor Link

Tokens of a player are removed on playerDropped.

Pub/subCopy Anchor Link

The server subscribes players to topics and publishes data only to them. Clients can only listen. Topic names must match ^[%w_:%.%-]+$ (max 200 chars); prefix them with your resource name.

Players are removed from all topics on disconnect, and topics are cleared when the resource that created them stops.

local TOPIC <const> = 'myshop:247:stock'

RegisterNetEvent('myshop:openShop', function()
    xLib.pubsub.subscribe(source, TOPIC)
end)

local function updateStock(stock)
    xLib.pubsub.publish(TOPIC, stock)
end

Shared utilitiesCopy Anchor Link

Table, string and mathCopy Anchor Link

xLib.table: isArray, searchForKey, filter, deepcopy, merge, dump, sizeOf, set, indexOf, lastIndexOf, find, findIndex, map, reverse, clone, concat, join, contains, sort (sorted pairs iterator), toArray, wipe. The ESX.Table.* functions are direct aliases, see ESX.Table.

xLib.string: normalize, capitalize, toSnake, toCamel, toPascal, escapePattern, matchSafe, before, after, contains, replace, randomHex(length), uuid().

xLib.math: clamp, toNumber, tryNumber, toInteger, toScalars, toVector, normalToRotation, toRGBA, hexToRGBA, toHex, groupDigits, round, interpolate, lerp, inverseLerp, remap, plus the ESX-style Round, GroupDigits, Trim, Random, GetHeadingFromCoords used by ESX.Math.

Timeout and waitForCopy Anchor Link

local id = xLib.timeout.setTimeout(msec, cb)
xLib.timeout.clearTimeout(id)

local value = xLib.waitFor(cb, errMessage, timeout, interval)

waitFor calls cb until it returns a non-nil value. It errors after timeout ms (default 5000; pass false to wait forever) and polls every interval ms (default 0). ESX.SetTimeout, ESX.ClearTimeout and ESX.Await are aliases. See Timeout.

local vehicle = xLib.waitFor(function()
    local veh = GetVehiclePedIsIn(PlayerPedId(), false)
    if veh ~= 0 then return veh end
end, 'Player never entered a vehicle', 10000)

Vehicle platesCopy Anchor Link

Other shared modulesCopy Anchor Link

• xLib.class(copy?) creates a class; instances are made with Class:new(...), which calls constructor.
• xLib.overload(name, validTypes, cb, obj?) registers a typed overload, dispatched by argument types.
• xLib.isEnhanced() returns true on the GTA V Enhanced build (server: gamename convar gta5enhanced or gta5_enhanced).
• xLib.colors exposes brand, darkest, dark, mid, light, lightest and getESXTheme(defaults?). See convars.

require, load and loadJsonCopy Anchor Link

local config = require 'config.shops'        -- loads config/shops.lua from your resource
local other  = require '@other_resource.data' -- loads data.lua from another resource
local result = xLib.load('scripts/once')     -- runs a file without caching
local data   = xLib.loadJson('data/items')   -- decodes data/items.json

Dots become slashes. Search paths are ./?.lua and ./?/init.lua. The file must be listed in the target resource's files or scripts so LoadResourceFile can read it on the client. Circular requires raise an error.

Other client modulesCopy Anchor Link

• xLib.blips.create(data), xLib.blips.createMany(items, defaults?), xLib.blips.remove(blip). data can be a vector3 or a table with coords or entity or radius, plus sprite, display, scale, color, alpha, shortRange, label, route, routeColor and more.
• xLib.dui:new({ url, width, height, debug? }) with remove(), setUrl(url), sendMessage(message), sendMouseMove(x, y), sendMouseDown(button), sendMouseUp(button), sendMouseWheel(deltaX, deltaY). DUIs are destroyed when the resource stops.
• xLib.scaleform.showFreemodeMessage(title, msg, sec), showBreakingNews(title, msg, bottom, sec), showPopupWarning(title, msg, bottom, sec), showTrafficMovie(sec), plus xLib.scaleform.utils.requestScaleformMovie(movie) and runMethod(scaleform, methodName, returnValue?, ...).
• xLib.Raycast.FromScreen(depth, ...), xLib.Raycast.Start(depth, ...), xLib.Raycast:Stop(), xLib.Raycast:IsActive(), xLib.Raycast.GetShapeTestResult(shape).
• xLib.medal.triggerClip(publicKey?, eventName?, clipOptions?) and xLib.medal.getConfig().

Server-only modulesCopy Anchor Link

• xLib.schema (needs oxmysql): column(tableName, columnName), identifier(value), ensureColumn(tableName, columnName, definition), widenVarchar(tableName, columnName, length, column?), ensureProperty(), ensureMileage(). es_extended migrations and esx_multicharacter use it to adjust tables safely.
• xLib.triggerClientEvent(eventName, targets, ...): targets is one server id or an array. For arrays, the payload is packed once and sent to each client, which is cheaper than calling TriggerClientEvent in a loop.

SQL catalogCopy Anchor Link

imports/catalog/bootstrap.lua is loaded as a server script by es_extended, esx_identity, esx_multicharacter and esx_skin. On start it reads imports/catalog/data.json (catalog version 1.16.0) and creates missing tables, columns and seed rows (jobs, items, licenses, vehicles and more) for ESX core and official addons, using the locale from Config.SqlCatalogLocale, Config.Locale or the esx:locale convar. Other resources call the es_extended export EnsureSqlCatalog(name, locale), which only lets a resource prepare its own catalog. When done, it triggers the server event esx:sqlCatalogReady with the list of touched catalogs. If it fails, resource initialization is blocked and the console prints SQL catalog FAILED.

ExportsCopy Anchor Link

Functions defined in esx_lib's own resource/ scripts are exported automatically. You normally reach them through xLib, but they are callable as exports.esx_lib:<name>(...):

EventsCopy Anchor Link

ConfigurationCopy Anchor Link

config.lua only configures the Medal.tv integration. esx_lib's NUI page posts clip requests to the Medal desktop client at http://localhost:12665, so nothing happens for players who do not run Medal.

ConvarsCopy Anchor Link

Callback convars are listed in Callback limits.

setr esx:ui:primaryColor "#3B82F6"
set xLib:callbackTimeout 60000

Version reportingCopy Anchor Link

On the server, esx_lib publishes the version and legacyversion metadata of every ESX resource (names starting with esx_ or es_, or that depend on es_extended or esx_lib) as server info convars named <resource>-version. This is what server lists and support tools read to see which ESX version you run. It runs 2 seconds after start and again for each ESX resource that starts later.

Common issuesCopy Anchor Link

• attempt to index a nil value (global 'xLib'): @esx_lib/imports.lua is missing from shared_scripts, or esx_lib is not started.
• Renamed folder: the loader reads files from a resource literally named esx_lib. Keep the name.
• callback '<name>' does not exist: the name is not registered on the receiving side, or its resource stopped. On the server this is reported after the validation grace period (up to 15 s).
• callback '<name>' is already owned by resource '<x>': two resources registered the same callback name. Prefix names with your resource.
• Callback returns false under load: the player hit a callback budget. Check the callback limits and avoid calling server callbacks every frame; use the client delay argument.
• require cannot find a file on the client: the file is not in the resource's files list, so LoadResourceFile cannot read it.
• SQL catalog FAILED: oxmysql is not connected or the database user cannot create or alter tables.

RelatedCopy Anchor Link

• ESX Legacy core resources
• Callbacks guide
• ESX shared functions
• Client callback module
• OneSync server functions

Frequently asked questions