# Introduction to ESX Legacy (/docs)

ESX Legacy is an open-source roleplay framework for [FiveM](https://fivem.net), 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](https://github.com/esx-framework/esx_core). When the official docs and the source disagree, this site follows the source.

<Callout type="info" title="Independent documentation">
esx-fivem.com is a community project and is **not affiliated with the ESX team**. The official documentation lives at [docs.esx-framework.org](https://docs.esx-framework.org/en) and the source code at [github.com/esx-framework](https://github.com/esx-framework). Report framework bugs on the official GitHub, not here.
</Callout>

## A short history [#a-short-history]

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](/docs/guides/convert-old-esx-scripts) for how to update it.

## Architecture [#architecture]

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

| Layer | Resources | Role |
| --- | --- | --- |
| Database driver | `oxmysql` | Connects FiveM to MariaDB or MySQL. Every ESX resource queries the database through it. |
| Library | `esx_lib` | Shared helpers used by `es_extended` (callbacks, schema helpers, OneSync helpers, validation). |
| Core | `es_extended` | The framework itself: player objects (`xPlayer`), accounts, jobs, items, commands, callbacks, paychecks. |
| Core resources | `esx_identity`, `esx_multicharacter`, `esx_skin`, `skinchanger`, `esx_notify`, `esx_textui`, `esx_progressbar`, `esx_context`, `esx_menu_*`, `esx_inventory`, `esx_whitelist`, `esx_loadingscreen`, `esx_chat_theme`, `cron` | UI, character creation and other systems that most servers need. They ship in the `[core]` folder. |
| Addons | `esx_policejob`, `esx_ambulancejob`, `esx_banking`, `esx_shops`, `esx_vehicleshop`, `esx_property` and more | Optional gameplay resources from the `[esx_addons]` folder in [ESX-Legacy-Addons](https://github.com/esx-framework/ESX-Legacy-Addons). |
| Your scripts | anything you write | Get the `ESX` object through `@es_extended/imports.lua` or `exports['es_extended']:getSharedObject()`. |

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`.

```lua title="server/main.lua"
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 glance [#requirements-at-a-glance]

- 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 for [#who-this-documentation-is-for]

- **Server owners** who want to install ESX, configure `server.cfg`, give admin rights and keep the server updated. Start with [Installation](/docs/getting-started/installation).
- **Script developers** who write resources on top of ESX. Start with [Your first ESX resource](/docs/getting-started/first-resource), then use the [es_extended reference](/docs/es_extended).
- **People coming from other frameworks** who want to compare. See [ESX vs QBCore](/docs/guides/esx-vs-qbcore).

## How this site is organized [#how-this-site-is-organized]

<Cards>
  <Card title="Getting Started" href="/docs/getting-started/installation">
    Install ESX with txAdmin or by hand, configure server.cfg, build your first resource and fix common errors.
  </Card>
  <Card title="es_extended" href="/docs/es_extended">
    Reference for the core: xPlayer, server and client functions, events, commands, config and shared helpers.
  </Card>
  <Card title="Core resources" href="/docs/core">
    Multicharacter, identity, skin, notifications, menus, text UI, progress bar, inventory and the other [core] resources.
  </Card>
  <Card title="Addons" href="/docs/addons">
    Jobs, shops, banking, housing, vehicles and the other official addons.
  </Card>
  <Card title="Guides" href="/docs/guides/create-a-job">
    Task-focused guides: create a job, add items, admin permissions, callbacks, oxmysql, ox_inventory and more.
  </Card>
  <Card title="FAQ" href="/docs/faq">
    Short answers to the questions people ask most often about ESX.
  </Card>
</Cards>

## Conventions used on this site [#conventions-used-on-this-site]

- 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.

## Related [#related]

- [Install ESX Legacy with txAdmin](/docs/getting-started/installation)
- [server.cfg for ESX](/docs/getting-started/server-cfg)
- [xPlayer reference](/docs/es_extended/server/xplayer)
- [FAQ](/docs/faq)