ESX Framework — базовая настройка для FiveM RP-сервера

MAATRIX GAMES

Голый FiveM-сервер уже поднят, порт открыт, в браузере серверов он виден — но это просто пустой движок без инвентаря, работ и экономики. Если ты выбрал ESX как основу для RP-проекта, дальше начинается отдельный квест: клонировать ядро, подружить его с базой данных, не перепутать порядок ресурсов в конфиге и не словить красную простыню ошибок при первом запуске. Разберём весь путь от чистого репозитория до заспавненного персонажа на карте.

Что нужно подготовить перед установкой

ESX не ставится на голое место — сначала должен быть рабочий FiveM-сервер с актуальным FXServer-рантаймом и структурой server-data. Если этого шага ещё нет, сначала пройди установку базового FiveM-сервера — без рабочего server.cfg, лицензии Cfx.re и понятной структуры resources ядро фреймворка просто не найдёт, куда встраиваться.

Дальше понадобится:

• MySQL или MariaDB-сервер — локально на той же машине или отдельным инстансом, с доступом по логину/паролю и созданной под ESX базой (её создадим ниже).
• Git на сервере, чтобы клонировать репозитории напрямую, а не таскать zip-архивы вручную.
• Понимание, что ESX сейчас живёт как активно поддерживаемый форк — оригинальный ESX-Org/es_extended давно не обновляется, актуальная ветка на конец августа 2026 года — ESX Legacy в организации esx-framework. Перед клонированием загляни на GitHub и проверь, какой репозиторий сейчас числится официальным продолжением — форки RP-фреймворков имеют привычку переезжать раз в год-два.
• Базовое знание, что такое ресурс FiveM (папка с fxmanifest.lua) — если пока не разбирался, глянь установку кастомных скриптов на FiveM, там разобран сам механизм подключения ресурсов через ensure.

Оперативки для голого ESX без тяжёлых community-скриптов хватит той же нормы, что и для базового RP-сервера — от 8 ГБ, дальше добавляется по мере роста набора ресурсов и онлайна.

Клонируем es_extended в resources

Заходим в папку с ресурсами сервера и клонируем ядро в отдельную подпапку — по конвенции ESX её принято класть в [esx], чтобы визуально отделить core-ресурсы фреймворка от остальных модов:

cd ~/fxserver/server-data/resources
mkdir -p '[esx]'
cd '[esx]'
git clone https://github.com/esx-framework/esx-legacy.git es_extended

После клонирования внутри es_extended будет папка client, server, locales, html и корневой fxmanifest.lua. Ядро само по себе ничего не делает без базы данных и без набора зависимостей — идти сразу к ensure в конфиге рано, сначала ставим то, на чём ESX держится.

Отдельный момент: если планируешь не с нуля, а брать готовый ESX-рецепт из репозитория с уже собранными базовыми ресурсами (спавн, инвентарь, гаражи) — учти, что версии зависимостей в таких сборках жёстко зафиксированы под конкретный релиз ядра. Смешивать «свежий» es_extended с ресурсами под старую версию — частая причина непонятных ошибок в консоли уже на старте.

Зависимости: oxmysql и ox_lib

Современный ESX Legacy не работает через устаревшие синхронные MySQL-обёртки — стандартом де-факто стал oxmysql, асинхронный коннектор к базе, и ox_lib — общая библиотека UI/утилит, которую сейчас использует большинство актуальных ESX- и QBCore-ресурсов. Оба ставятся так же, как и ядро — отдельными ресурсами:

cd ~/fxserver/server-data/resources
git clone https://github.com/overextended/oxmysql.git
git clone https://github.com/overextended/ox_lib.git

У oxmysql есть свой fxmanifest.lua с зависимостями на msgpack/node под капотом FXServer — отдельно ничего доустанавливать не нужно, рантайм FiveM уже несёт нужное окружение. А вот подключение к базе задаётся не в конфиге ресурса, а строкой окружения в server.cfg — этим займёмся в следующем разделе, вместе с настройкой самой базы.

Важно про порядок: oxmysql и ox_lib должны стартовать раньше es_extended — ядро ESX при загрузке сразу лезет в базу через oxmysql и ждёт готовые экспорты ox_lib. Если порядок в server.cfg перепутан, увидишь в консоли ошибку про отсутствующий экспорт ещё до того, как дело дойдёт до собственно проблем с базой.

База данных MySQL под ESX

Заходим в MySQL-консоль (или используем phpMyAdmin/Adminer, если хостинг даёт панель) и создаём отдельную базу с явной кодировкой — старые дампы под ESX иногда несут utf8, но для новых проектов лучше сразу ставить utf8mb4, чтобы не ловить проблемы с эмодзи в никах и текстовых полях:

CREATE DATABASE esx_server CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'esx_user'@'localhost' IDENTIFIED BY 'надёжный_пароль';
GRANT ALL PRIVILEGES ON esx_server.* TO 'esx_user'@'localhost';
FLUSH PRIVILEGES;

Если MySQL и FXServer стоят на разных машинах — вместо localhost в имени пользователя указывай реальный хост/подсеть, с которой будет идти подключение, и открывай порт 3306 только для нужного адреса, а не всему интернету.

Дальше нужна сама схема: в репозитории es_extended в актуальных версиях SQL-дамп лежит в корне или в папке docs/sql (проверь README конкретного релиза — расположение файла между версиями плавает). Импортируем его в свежую базу:

mysql -u esx_user -p esx_server < es_extended.sql

После импорта в базе должны появиться таблицы users, jobs, job_grades, items, vehicles и ещё десяток служебных — это и есть каркас, вокруг которого держится вся экономика и инвентарь ESX. Если параллельно ставишь готовые community-ресурсы (гаражи, банды, фракции) — почти каждый из них несёт свой отдельный .sql с дополнительными таблицами, их импортируют тем же способом уже после базовой схемы.

Строка подключения задаётся одной переменной в server.cfg в формате, который понимает oxmysql:

set mysql_connection_string "mysql://esx_user:надёжный_пароль@localhost/esx_server?charset=utf8mb4"

Если после первого запуска в консоли всплывают ошибки вроде Access denied или ECONNREFUSED — это почти всегда либо неверные данные в этой строке, либо права пользователя не долетели до нужной базы. Разбор частых причин и решений — в отдельном гайде про проблему подключения FiveM к MySQL, не буду здесь повторять его целиком.

Добавляем ресурсы в server.cfg и первый запуск

Открываем server-data/server.cfg и прописываем строку подключения и порядок загрузки — именно в такой последовательности, зависимости раньше ядра:

set mysql_connection_string "mysql://esx_user:надёжный_пароль@localhost/esx_server?charset=utf8mb4"

ensure oxmysql
ensure ox_lib
ensure es_extended

Если планируешь сразу добавлять сторонние ESX-ресурсы (спавн-меню, магазины, работы) — они дописываются ensure-строками ниже es_extended, так как сами зависят от загруженного ядра.

Запускаем сервер и следим за консолью:

cd ~/fxserver/server-data
../run.sh +exec server.cfg

При чистом запуске должна пройти цепочка: oxmysql подключился к базе и вывел строку про успешное соединение, ox_lib стартовал без ошибок, es_extended подгрузил конфиг, синхронизировал таблицы (могут появиться служебные ALTER-запросы, если версия ядра новее схемы в базе) и объявил готовность. Если где-то в этой цепочке консоль красная — почти всегда причина в предыдущем шаге, а не в самом es_extended: сначала чини базу и зависимости, потом смотри на ошибки ядра.

Создание персонажа и первая проверка

Заходишь на сервер через клиент FiveM по адресу connect ip:port (или через избранное в браузере серверов) — при первом подключении ESX создаёт запись в таблице users по идентификатору Steam/FiveM-аккаунта и должен показать экран создания персонажа, если в сборке ядра он включён (в чистом es_extended без дополнительных ресурсов спавна экран может быть минимальным — это нормально, полноценный мультихарактерный интерфейс обычно добавляют отдельным community-ресурсом).

Что стоит проверить сразу после первого спавна:

• Деньги видны в HUD (если стоит ресурс интерфейса) или командой в чате /setmoney для админа — новый персонаж получает стартовый баланс из конфига ядра.
• Работа по умолчанию присвоена — в таблице users у свежесозданного персонажа должна стоять job = 'unemployed' или другая дефолтная работа из jobs.
• В консоли сервера нет повторяющихся ошибок при каждом действии игрока (открытие инвентаря, смена оружия) — если да, обычно не хватает зависимого ресурса, который забыли добавить в ensure.

Для проверки прав администратора у себя добавь в server.cfg строку add_ace group.admin command allow и назначь себе группу через add_principal identifier.fivem:12345 group.admin, подставив свой FiveM-идентификатор (его видно в консоли при подключении).

Чем ESX отличается от QBCore

Если ты выбирал между двумя основными RP-фреймворками для FiveM и остановился на ESX — коротко, почему это может быть верным решением: у ESX кардинально больше готовых community-ресурсов и туториалов под любую типовую задачу, экономика строится вокруг классической связки money/bank/black_money, а сообщество вокруг фреймворка одно из самых крупных в RP-нише FiveM. Обратная сторона — часть старых ресурсов ещё несёт легаси-код под устаревшие практики.

Если сомневаешься, что выбор окончательный, — прочитай подробное сравнение ESX и QBCore с разбором архитектуры, экономики и таблицей по критериям: менять фреймворк на живом сервере с наполненной базой игроков — задача на порядок болезненнее, чем определиться на старте.

Частые вопросы