Установка кастомных скриптов на FiveM

MAATRIX GAMES

Сервер поднят, txAdmin отвечает, порт открыт — а дальше начинается самое интересное: наполнение сервера логикой. Магазины, гаражи, экономика, кастомный HUD, банда-система — всё это ресурсы, которые нужно правильно положить в нужную папку и подключить в конфиге в правильном порядке. Разберём весь путь от скачанного архива со скриптом до рабочего ресурса на живом сервере — и что делать, если после ensure в консоли вместо приветствия сыпется красный текст ошибок.

Структура ресурса: из чего состоит скрипт для FiveM

Ресурс в терминологии FiveM — это не один файл, а папка со строго определённой структурой. Минимальный набор внутри:

my-resource/
├── fxmanifest.lua       — обязательный файл-манифест
├── client.lua           — код, исполняемый на клиенте у каждого игрока
├── server.lua           — код, исполняемый на сервере
└── shared/
    └── config.lua       — общие настройки, доступные и клиенту, и серверу

Конкретная раскладка файлов внутри — на усмотрение автора скрипта, единственное жёсткое правило — рядом с кодом обязан лежать fxmanifest.lua, без него движок вообще не увидит папку как ресурс. Скрипты пишутся на Lua (основной язык FiveM), но встречаются и на JavaScript/TypeScript или C# — тип языка не влияет на структуру папки, только на то, что указывается внутри манифеста.

Важный нюанс для организации: если положить ресурсы во вложенные папки с именем, начинающимся на подчёркивание (например resources/[esx]/_es_extended), FXServer всё равно найдёт и загрузит вложенные ресурсы — подчёркивание и квадратные скобки в именах категорий игнорируются загрузчиком и служат только для порядка в файловой системе. Это удобно, когда ресурсов на сервере становится полсотни и больше, и держать их плоским списком в одной папке уже неудобно.

fxmanifest.lua: что туда пишут и зачем

Это сердце ресурса — файл, который объясняет серверу, что за скрипт перед ним, какие файлы к нему относятся и от чего он зависит. Базовый пример:

fx_version 'cerulean'
game 'gta5'

author 'Автор скрипта'
description 'Краткое описание, что делает ресурс'
version '1.0.0'

shared_scripts {
    'shared/config.lua'
}

client_scripts {
    'client.lua'
}

server_scripts {
    'server.lua'
}

dependencies {
    'es_extended'
}

Разберём поля, которые реально важны при установке чужого скрипта:

• fx_version — версия синтаксиса манифеста (актуальное значение на момент выхода статьи — 'cerulean'); если в старом скрипте стоит устаревшее значение, современный FXServer обычно всё равно его понимает, но при странном поведении ресурса стоит свериться с документацией самого скрипта на этот счёт.
• game — для GTA V всегда 'gta5'.
• shared_scripts / client_scripts / server_scripts — куда какой файл грузить. Перепутанный файл (например, серверная логика с обращением к базе, случайно попавшая в client_scripts) — частая причина, почему скрипт «не работает у всех игроков», хотя на самом деле упал только у сервера или наоборот.
• dependencies — список ресурсов, без которых этот скрипт не запустится. Именно это поле определяет, что должно быть установлено на сервере ДО данного ресурса — если в манифесте написано dependencies { 'es_extended' }, а ES Extended на сервере не установлен вообще, ресурс упадёт при старте с ошибкой о недостающей зависимости.
• ui_page и files — если у ресурса есть NUI-интерфейс (HTML/CSS/JS-меню поверх игры), сюда прописывается путь к html-файлу и связанным ресурсам интерфейса.

Открой fxmanifest.lua скачанного скрипта перед установкой — так сразу видно, есть ли у него зависимости и какой фреймворк он ожидает (ES Extended, QBCore или ни один из них — «standalone»-скрипты).

Куда класть ресурс и как подключить через server.cfg

Ресурс копируется целиком (папкой) в resources/ внутри твоего server-data — того же каталога, который мы разворачивали из cfx-server-data при базовой установке сервера (подробности — в статье про установку FiveM-сервера):

cd ~/fxserver/server-data/resources
git clone <ссылка_на_репозиторий_скрипта> my-resource

Если скрипт скачан архивом, а не через git — просто распакуй его так, чтобы fxmanifest.lua лежал прямо в корне папки ресурса, а не на уровень глубже (частая ошибка: внутри архива есть ещё одна вложенная папка с тем же именем, и в итоге путь получается resources/my-resource/my-resource/fxmanifest.lua, что сервер уже не подхватит).

Дальше — подключение в server.cfg:

ensure my-resource

Директива ensure — это, по сути, «start» с проверкой: если ресурс уже запущен, FXServer его перезапустит, если не запущен — запустит. Есть и более узкие варианты — start (запустить, не трогая уже работающий) и stop (остановить), но для 95% случаев в конфиге используют именно ensure. Изменения в server.cfg применяются либо при полном рестарте сервера, либо командой refresh (обновить список доступных ресурсов) с последующим ensure my-resource прямо в консоли txAdmin или через RCON — без даунтайма для остальных игроков.

Порядок загрузки: зависимости решают всё

Ресурсы в server.cfg запускаются строго в том порядке, в котором записаны строки ensure. Это не формальность — большинство ошибок при установке скриптов на самом деле не про сам скрипт, а про то, что он стартовал раньше, чем то, от чего он зависит.

Правило простое: всё, что указано в dependencies ресурса, должно иметь свою строку ensure выше по конфигу. Типичная цепочка для ES Extended-скрипта:

ensure mysql-async
ensure es_extended
ensure my-esx-script

Если поменять местами es_extended и my-esx-script, при старте второй ресурс попытается обратиться к глобальному объекту ES Extended, которого ещё нет в памяти сервера — и упадёт с ошибкой уровня «attempt to index a nil value». Та же логика для QBCore-скриптов относительно qb-core, и для любых кастомных билиотек, которые сам автор ресурса выносит в отдельный shared-ресурс, чтобы не дублировать код в каждом скрипте.

Полезная привычка — группировать server.cfg смысловыми блоками с комментариями (строка, начинающаяся с #, в конфиге игнорируется):

# Базовые компоненты FXServer
ensure mapmanager
ensure chat
ensure spawnmanager

# Framework
ensure oxmysql
ensure es_extended

# Кастомные скрипты (ждут es_extended)
ensure esx_banking
ensure esx_vehicleshop

Так при добавлении нового скрипта сразу видно, в какой блок его вписывать и что должно быть выше.

Проверяем лог сервера при старте

После каждого добавления нового ресурса — смотри консоль сразу при старте/рестарте, не жди жалоб игроков. В txAdmin это вкладка Live Console, при запуске через systemd — journalctl -u fxserver -f (юнит мы настраивали в статье про базовую установку). На что обращать внимание:

• Couldn't start resource my-resource — либо в папке нет fxmanifest.lua, либо структура вложена на уровень глубже, чем нужно (см. пункт про распаковку архива выше).
• Failed to load script client.lua / server.lua с указанием строки — синтаксическая ошибка в самом Lua-файле; если ресурс не редактировался руками, чаще всего это несовместимость со старой/новой версией FXServer или обрезанный при скачивании файл.
• Missing dependency или ошибка о неопределённой глобальной переменной/функции (attempt to call a nil value (global 'ESX') и подобные) — верный признак, что зависимость либо не установлена вообще, либо стоит ниже по server.cfg, чем сам ресурс.
• Ресурс стартовал без ошибок, но не работает в игре — это уже не про установку: смотри resmon в консоли клиента (открывается по ~/F8), не расходует ли ресурс аномально много кадрового времени, и проверяй права доступа/ACE-разрешения, если скрипт завязан на систему прав администратора.

Golden rule: один добавленный ресурс — один рестарт/refresh — один взгляд в лог. Если накидать сразу десяток скриптов и запустить всё скопом, разбираться, какой из них уронил сервер, будет заметно дольше.

Где искать готовые скрипты

Два основных источника рабочих ресурсов для FiveM:

• GitHub — большинство авторов, включая официальные ресурсы фреймворков (ES Extended, QBCore и их дочерние модули), публикуют код открыто, с README, где обычно сразу написаны зависимости и минимальная инструкция по установке. Поиск по GitHub с фильтром по языку Lua и ключевыми словами вроде fivem esx script или fivem qbcore script — рабочий способ найти актуальные версии.
• Специализированные форумы FiveM-разработки — сообщества, где публикуют как бесплатные, так и платные (paid) ресурсы, часто с демо-видео и обсуждением багов в комментариях. Названия конкретных площадок меняются, лучше искать актуальные через сам сайт fivem.net и его официальные каналы — там всегда есть свежие ссылки на признанное сообществом место.

Перед установкой стороннего скрипта, особенно с форумов, а не с GitHub, стоит быть внимательным: код исполняется на твоём сервере с полным доступом к базе данных и файловой системе, если ресурс запущен от того же пользователя, что и весь FXServer. Открой хотя бы бегло server.lua перед установкой — ищи явные обращения к внешним адресам (http.get/PerformHttpRequest на подозрительные домены) или обфусцированный (нечитаемый, «зашифрованный») код без исходников — это частый признак закладки в платных скриптах сомнительного происхождения. Обфускация сама по себе не всегда означает вредонос (некоторые авторы защищают так платные продукты), но раз код нельзя прочитать — доверять ему приходится вслепую.

Логика поиска зависимостей и проверки README во многом похожа на установку плагинов в других играх — например, Oxide/uMod для Rust устроен по похожему принципу «скачал — положил в папку — прописал в конфиге», хотя технически это два разных движка. Если раньше ставил аддоны из Steam Workshop в Garry's Mod, общая идея с зависимостями и порядком загрузки тоже покажется знакомой, хотя механизм подключения там другой.

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