Introduction to ESX Legacy

ESX Legacy is an open-source roleplay framework for FiveM, the GTA V multiplayer platform. It gives your server a persistent player object with money accounts, jobs, an inventory and permission groups, plus a set of ready-made resources (character creation, menus, jobs, shops, banking) that you can use as they are or replace with your own.

This site documents ESX Legacy 1.16.4 (current release as of October 2026). Everything here is checked against the Lua source in esx-framework/esx_core. When the official docs and the source disagree, this site follows the source.

A short historyCopy Anchor Link

ESX started in 2017 as a framework that added jobs, money accounts and an inventory to FiveM servers. It quickly became one of the most common bases for FiveM roleplay servers, and a large ecosystem of free and paid scripts grew around it.

The original ESX releases were written for a much older FiveM: no OneSync, Lua 5.3, mysql-async and many client-trusted events. ESX Legacy is the continued, actively maintained line of the framework. It keeps the familiar API (ESX.GetPlayerFromId, xPlayer.addMoney, esx:playerLoaded and so on) so that most older scripts still work, but it modernizes the internals:

• oxmysql instead of mysql-async / ghmattimysql
• Lua 5.4 (lua54 'yes') in every core resource
• OneSync Infinity is required, which allows server-side entity and player lookups
• a shared library resource, esx_lib, that provides callbacks, validation, rate limiting and other helpers to the core
• automatic database migrations when you update the core
• many security fixes, for example events that only accept calls from es_extended itself

If you find a tutorial that uses TriggerEvent('esx:getSharedObject', ...) or mysql-async, it was written for old ESX. See Convert old ESX scripts for how to update it.

ArchitectureCopy Anchor Link

An ESX Legacy server is a normal FiveM server with a few layers of resources. They start in this order:

The most important idea is the player object. When a player has loaded, the server holds an xPlayer for them. You get it with ESX.GetPlayerFromId(source) and call methods on it, for example xPlayer.addAccountMoney('bank', 500, 'Salary'). ESX keeps that state in memory and saves it to the users table. On the client, the same data is mirrored in ESX.PlayerData.

local ESX = exports['es_extended']:getSharedObject()

RegisterNetEvent('myscript:hello', function()
    local xPlayer = ESX.GetPlayerFromId(source)
    if not xPlayer then return end

    xPlayer.showNotification(('Hello %s, you work as %s'):format(xPlayer.getName(), xPlayer.job.label))
end)

Requirements at a glanceCopy Anchor Link

• A current FiveM server build (ESX refuses connections on artifacts older than 10188)
• OneSync set to on (Infinity). off and legacy are rejected when a player connects.
• MariaDB (recommended) or MySQL
• oxmysql and esx_lib started before es_extended

Who this documentation is forCopy Anchor Link

• Server owners who want to install ESX, configure server.cfg, give admin rights and keep the server updated. Start with Installation.
• Script developers who write resources on top of ESX. Start with Your first ESX resource, then use the es_extended reference.
• People coming from other frameworks who want to compare. See ESX vs QBCore.

How this site is organizedCopy Anchor Link

Conventions used on this siteCopy Anchor Link

• Code examples use Lua 5.4 and the modern way of getting ESX (@es_extended/imports.lua or the getSharedObject export).
• Every function has its side marked: server, client or shared. Calling a server function on the client (or the other way round) is the most common cause of attempt to call a nil value errors.
• source always means the server ID of the player who triggered an event or command.
• Each page lists its upstream source file, so you can check the code yourself.

RelatedCopy Anchor Link

• Install ESX Legacy with txAdmin
• server.cfg for ESX
• xPlayer reference
• FAQ

Frequently asked questions