ESX Basics for Beginners: Your First FiveM Roleplay Script

ESX (es_extended) is one of the oldest and most widely deployed roleplay frameworks for FiveM. It gives you a ready-made player object, an economy with cash and bank accounts, a job system, and a network of community addons, so you can build a roleplay server without writing the player-data layer yourself. If you have ever wanted to add a custom shop, a paycheck system, or a job-locked vehicle to a GTA roleplay server, ESX is usually where you start.

This guide walks you through the core ESX concepts a beginner needs: how to get the shared object, how to read and modify a player with xPlayer, the most common money and job functions, and how to wire up a tiny server-and-client script that actually runs. You do not need to be a strong programmer to follow along, but knowing a little Lua helps. At PlayDeck we teach this exact workflow with AI assistance: you describe the feature you want, the AI writes the Lua, and you steer it and learn the framework as you go.

What ESX gives you (and what es_extended is)

ESX is a collection of resources that sit on top of FiveM. The core resource is es_extended (often shown in code as the ESX object), and it depends on oxmysql for the database and a MySQL server for persistence. When es_extended starts, it loads every player into a server-side player object, syncs basic data to the client, and exposes functions and events that your own resources can call.

The most important concept is the player object. On the server, ESX calls this xPlayer, and it represents one connected character: their identifiers, their job, their money accounts (cash, bank, and black money), their inventory, and helper functions to change all of it. Almost every ESX script you will ever read starts by getting an xPlayer from a source (the player's server ID) and then calling functions on it.

• es_extended: the core that manages players, money, and jobs
• oxmysql: the database layer ESX uses to save data
• xPlayer: the server-side object representing one player
• Addons: community resources (shops, jobs, garages) that call ESX functions

Getting the shared object the modern way

Older ESX tutorials show an event-based pattern using a TriggerEvent call to esx:getSharedObject. On current ESX Legacy you should use the export instead, because the old event has been deprecated and is a frequent source of nil errors. In both your client and server files, grab ESX once at the top:

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

If you copy an old script and see it crash with an attempt-to-index-a-nil-value error on ESX, the getSharedObject line is almost always the culprit. Replace the deprecated event call with the export above and the script will usually start working. This single line is the most common beginner stumbling block in the entire ESX ecosystem.

Working with xPlayer: money and jobs

Once you have an xPlayer on the server, you can read and change that character's state. To get the player, call ESX.GetPlayerFromId(source) inside a server-side event, where source is the player's server ID. Always check that the result is not nil before using it, because a player can disconnect mid-event.

The money functions are the ones you will reach for constantly. xPlayer.addMoney(amount) and xPlayer.removeMoney(amount) change cash; xPlayer.addAccountMoney('bank', amount) and xPlayer.getAccount('bank').money handle the bank and black-money accounts. For jobs, xPlayer.setJob('police', 2) assigns the police job at grade 2, and xPlayer.getJob().name reads the current job name, which is how job-locked features check permission.

• xPlayer.addMoney(500): add cash
• xPlayer.removeMoney(500): take cash (check they can afford it first)
• xPlayer.getAccount('bank').money: read bank balance
• xPlayer.setJob('mechanic', 0): set job and grade
• xPlayer.getJob().name: read current job for permission checks

A minimal ESX command: paying a player

Here is the shape of a real, working feature. On the server, register a command that gives the calling player cash. RegisterCommand('givecash', function(source) local xPlayer = ESX.GetPlayerFromId(source) if xPlayer then xPlayer.addMoney(1000) end end) that is genuinely all it takes to credit a player 1000 cash when they type /givecash.

Notice what is NOT here: there is no SQL, no syncing, no UI. ESX handles persistence and the client HUD update for you. The lesson for beginners is to lean on the framework instead of reinventing it. Your job is to call the right xPlayer function at the right moment, validate input, and never trust the client with money decisions. We cover server-side trust in depth on the server-side vs client-side page linked below.

Key ESX events to know

ESX communicates through events as well as functions. esx:playerLoaded fires on the client when a character is fully loaded and gives you the player data table, which is the right moment to build your HUD or request data. esx:setJob fires when a player's job changes, so a job-restricted blip or menu can react instantly without polling.

Understanding which events run where is essential. Client events run on each player's machine and handle visuals; server events run once on the server and handle authoritative data like money. Mixing these up is the second most common beginner mistake after getSharedObject, and it is exactly the kind of thing AI can flag for you while you learn.