Como instalar a base ESX em um servidor FiveM do zero

ESX é o framework de roleplay dominante no FiveM brasileiro. Apesar de existirem alternativas (QBCore, Ox Core, vRP), a maioria dos scripts comerciais e gratuitos do mercado pressupõe ESX instalado — então saber montar a base limpa, sem dívida técnica acumulada de tutoriais antigos, é o ponto de partida pra qualquer servidor que pretende crescer.

Este guia cobre a instalação do es_extended 1.10+ com oxmysql como driver de banco, ox_lib como biblioteca base e ox_inventory como inventário. É a stack moderna mantida ativamente em 2026 — diferente dos tutoriais de 2020-2022 que ainda recomendam mysql-async e esx_inventoryhud.

Tempo estimado de execução: 30 a 45 minutos pra quem já tem o servidor FiveM rodando. Se você ainda precisa instalar o txAdmin e subir o artifact do FXServer, reserve uma hora extra.

Pré-requisitos

Antes de baixar qualquer coisa, confirme que o servidor base sobe limpo — sem ESX ainda, só o FXServer puro. Conecte via FiveM client no IP do servidor e verifique se entra no mapa default sem erro de conexão. Se já tem problema nesse ponto, resolva primeiro: ESX vai amplificar qualquer instabilidade da camada de baixo.

Tenha em mãos os dados de conexão do banco:

Preparar o banco de dados

ESX usa MySQL pra persistir jogadores, inventário, veículos, empregos e tudo que precisa sobreviver a um restart. A primeira ação é criar o banco com charset correto — utf8mb4 não é negociável, scripts modernos esperam suporte completo a 4 bytes (emoji, caracteres asiáticos, símbolos especiais usados em RP).

mysql -u root -p

CREATE DATABASE esx_server CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'esx_user'@'localhost' IDENTIFIED BY 'SenhaForteAqui123!';
GRANT ALL PRIVILEGES ON esx_server.* TO 'esx_user'@'localhost';
FLUSH PRIVILEGES;
EXIT;

cd server-data/resources/
git clone https://github.com/overextended/oxmysql.git [standalone]/oxmysql

set mysql_connection_string "mysql://esx_user:SenhaForteAqui123!@localhost/esx_server?charset=utf8mb4"
ensure oxmysql

Instalar ox_lib e es_extended

Com banco respondendo, vem a base do framework. O ox_lib é uma biblioteca de utilitários (UI, callbacks, locale, cache) que o ESX moderno e a maioria dos scripts atuais exigem como dependência declarada no manifesto.

cd server-data/resources/[standalone]/
git clone https://github.com/overextended/ox_lib.git

mkdir -p server-data/resources/\[esx\]
cd server-data/resources/\[esx\]
git clone https://github.com/esx-framework/esx_core.git

mysql -u esx_user -p esx_server < server-data/resources/\[esx\]/esx_core/\[core\]/es_extended/install.sql

Configurar o server.cfg

A ordem de ensure define o que sobe primeiro. ESX é sensível a isso — recursos que chamam ESX.GetPlayerFromId() antes do framework terminar de inicializar retornam nil silenciosamente e o jogador vira fantasma. A regra é simples: drivers de baixo nível antes, biblioteca depois, framework em seguida, recursos consumidores por último.

# Banco (já configurado anteriormente)
set mysql_connection_string "mysql://esx_user:SenhaForteAqui123!@localhost/esx_server?charset=utf8mb4"
ensure oxmysql

# Biblioteca base
ensure ox_lib

# Framework ESX (ordem importa)
ensure es_extended
ensure esx_menu_default
ensure esx_menu_dialog
ensure esx_menu_list
ensure esx_notify
ensure esx_textui
ensure esx_progressbars

# Inventário (depois do framework)
ensure ox_inventory

cd server-data/resources/[standalone]/
git clone https://github.com/overextended/ox_inventory.git

Verificar a instalação

Subir sem erro no console é metade do trabalho — o outro lado é confirmar que o framework realmente funciona em runtime, com um jogador conectado.

[oxmysql] Database server connection established!
Started resource ox_lib
Started resource es_extended
[es_extended] ESX has started successfully!
Started resource ox_inventory

/setjob mecanico boss

Resolução de problemas comuns

Erro attempt to index a nil value (global 'ESX')

Significa que um script tentou usar ESX = exports['es_extended']:getSharedObject() antes do framework terminar de carregar. Acontece em client scripts mal escritos. Solução: envolva a inicialização do client em um loop de espera:

ESX = nil
CreateThread(function()
    while ESX == nil do
        ESX = exports['es_extended']:getSharedObject()
        Wait(0)
    end
end)

Esse padrão é o oficial recomendado pelo time do ESX desde a versão 1.10.

Jogador entra mas inventário fica vazio

Verifique se a tabela users tem registro pro identificador Steam/license do jogador. Se não tiver, o ox_inventory não consegue carregar slots. Solução: certifique que o ensure es_extended está antes do ensure ox_inventory e que o banco está respondendo (sem erro de conexão no console).

Console mostra oxmysql was unable to establish a connection

A string de conexão está errada. Causas comuns: senha com caractere especial sem escape (use senha alfanumérica simples ou escape com %XX), MySQL escutando só em socket Unix e não em TCP 127.0.0.1 (edite bind-address no my.cnf), firewall bloqueando 3306 localmente (raro mas acontece em servidor com UFW configurado agressivo).

Próximos passos

Com a base ESX rodando, o servidor está pronto pra receber a camada de gameplay. Sugestões pra continuar:

• Empregos e gangues: adicione esx_jobs, esx_society, esx_billing pra completar a economia base. Edite o seeder jobs no banco pra criar empregos custom do seu RP.
• MDT e sistema policial: integre mdt-fivem ou similar — depende de oxmysql e es_extended já rodando, então a base que você acabou de montar é pré-requisito.
• Loadouts e armas: configure o Config.EnablePVP no es_extended/config.lua e use ox_inventory pra controlar permissões de arma por job.
• Persistência de veículos: instale esx_vehicleshop pra concessionária e ative o spawn de garagem com esx_garage ou qb-garages-esx-bridge.
• Performance: use o profiler do FXServer (profiler record 1000, depois profiler view) pra medir tick de cada recurso. Acima de 1ms por resource em loop, refatore ou troque.

Se você está colocando o servidor em produção com mais de 32 slots, uma máquina dedicada ao FiveM vale o investimento — o tick rate cai sensivelmente quando o servidor compete com web, banco e outras cargas no mesmo host. Os planos de hospedagem de jogos da Hostini já vêm com CPU isolada e NVMe local, que é exatamente o perfil que ESX gosta sob carga real.