Модификация сервера

Данная статья описывает установку ресурсов на сервер FiveM, настройку базы данных MySQL/MariaDB, подключение фреймворков ESX или QBCore, порядок загрузки ресурсов и частые ошибки при установке скриптов.

Что такое ресурсы FiveM

Ресурсы — это скрипты и дополнения для FiveM-сервера. Они могут добавлять работы, транспорт, HUD, инвентарь, экономику, автосалоны, фракции, админ-инструменты, карты, одежду, оружие и другие функции.

Обычно ресурсы размещаются в каталоге:

resources/

Запуск ресурсов настраивается в файле:

server.cfg

Перед установкой ресурсов

Перед установкой новых скриптов убедитесь, что:

• сервер FiveM уже установлен и запускается;
• указан действительный FIVEM_LICENSE;
• есть рабочий server.cfg;
• известен путь к каталогу resources/;
• если используется база данных, она создана во вкладке «Databases»;
• перед изменениями создана резервная копия.

Установка ресурса

1. Скачайте ресурс из надёжного источника: GitHub, Cfx.re Forum, Tebex или сайта разработчика.
2. Распакуйте архив, если ресурс скачан в ZIP/RAR/7z.
3. Найдите настоящую папку ресурса.
4. Загрузите папку ресурса в каталог resources/.
5. Откройте server.cfg.
6. Добавьте строку запуска ресурса.
7. Перезапустите сервер или загрузите ресурс через txAdmin.

Строка запуска ресурса

Для запуска ресурса используется команда:

ensure resource-name

Пример:

ensure my-new-resource

Внимание: имя в строке ensure должно совпадать с названием папки ресурса.

Если папка называется:

my-cars

то строка в server.cfg должна быть:

ensure my-cars

Правильная структура ресурса

Внутри папки ресурса должен находиться манифест.

Современный вариант:

fxmanifest.lua

Старый вариант:

__resource.lua

Правильная структура:

resources/my-resource/fxmanifest.lua
resources/my-resource/client.lua
resources/my-resource/server.lua

Неправильная структура:

resources/my-resource/my-resource/fxmanifest.lua

Если после распаковки получилась двойная вложенность папок, перенесите внутреннюю папку ресурса напрямую в resources/.

Манифест ресурса

FiveM использует манифест для понимания того, какие файлы должен загрузить ресурс.

Пример простого fxmanifest.lua:

fx_version 'cerulean'
game 'gta5'

client_script 'client.lua'
server_script 'server.lua'

Если в ресурсе нет fxmanifest.lua или __resource.lua, сервер не сможет его загрузить.

Порядок загрузки ресурсов

Ресурсы загружаются в том порядке, в котором они указаны в server.cfg.

Если один ресурс зависит от другого, зависимость должна быть выше.

Пример правильного порядка:

ensure oxmysql
ensure es_extended
ensure esx_basicneeds
ensure esx_jobs
ensure esx_vehicleshop

В этом примере сначала загружается база данных, затем фреймворк, затем ресурсы, которые зависят от фреймворка.

Частая ошибка порядка загрузки

Неправильно:

ensure esx_jobs
ensure esx_basicneeds
ensure es_extended
ensure oxmysql

В таком порядке ресурсы могут пытаться обратиться к базе данных или фреймворку до их загрузки. Это приведёт к ошибкам в консоли.

Организация ресурсов по папкам

В каталоге resources/ можно создавать папки-категории.

Пример структуры:

resources/
  [standalone]/
    chat/
    hud/
  [esx]/
    es_extended/
    esx_jobs/
  [cars]/
    police-car/
    sport-car/

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

ensure [standalone]
ensure [esx]
ensure [cars]

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

Горячая загрузка ресурсов через txAdmin

Если txAdmin включён, новый ресурс не всегда требует полного перезапуска сервера.

После загрузки папки ресурса выполните в Live Console:

refresh
ensure my-new-resource

refresh заставляет сервер заново просканировать каталог ресурсов.

ensure запускает ресурс.

Внимание: если ресурс требует базу данных, фреймворк или изменение server.cfg, надёжнее выполнить полноценный перезапуск.

Остановка и перезапуск ресурса

Через консоль сервера или txAdmin можно управлять отдельными ресурсами.

Настройка базы данных

Многие FiveM-сборки используют MySQL или MariaDB. База данных нужна для хранения игроков, транспорта, домов, инвентаря, денег, фракций, бизнесов и других данных.

Чаще всего база подключается через ресурс:

oxmysql

Более старые сборки могут использовать:

mysql-async
ghmattimysql

Где взять данные базы данных

1. Откройте сервер в панели управления.
2. Перейдите во вкладку «Databases».
3. Создайте базу данных, если она ещё не создана.
4. Скопируйте хост, порт, имя базы, имя пользователя и пароль.

Внимание: не используйте localhost или 127.0.0.1, если база данных находится на отдельном сервере. Используйте хост, указанный во вкладке «Databases».

Строка подключения MySQL

Строка подключения обычно задаётся в server.cfg.

Формат:

set mysql_connection_string "mysql://USERNAME:PASSWORD@HOST:PORT/DATABASE_NAME?charset=utf8mb4"

Пример:

set mysql_connection_string "mysql://u123_fivem:MyPassword@database.example.net:3306/s123_fivem?charset=utf8mb4"

Специальные символы в пароле

Если пароль базы данных содержит специальные символы, их нужно URL-кодировать.

Пример: если пароль выглядит так:

My@Password#1

в строке подключения он должен быть:

My%40Password%231

Подключение oxmysql

Ресурс oxmysql должен загружаться до фреймворка и ресурсов, которые используют базу данных.

Пример:

set mysql_connection_string "mysql://USERNAME:PASSWORD@HOST:PORT/DATABASE_NAME?charset=utf8mb4"

ensure oxmysql
ensure qb-core
ensure my-resource

Если используется ESX:

set mysql_connection_string "mysql://USERNAME:PASSWORD@HOST:PORT/DATABASE_NAME?charset=utf8mb4"

ensure oxmysql
ensure es_extended
ensure esx_basicneeds
ensure esx_jobs

Выбор MySQL-ресурса

Не устанавливайте несколько MySQL-ресурсов одновременно без необходимости. Это может привести к конфликтам и ошибкам подключения.

Фреймворки FiveM

Фреймворк — это основа RP-сервера. Он отвечает за игроков, деньги, профессии, инвентарь, транспорт, дома, фракции и другие базовые системы.

Внимание: не смешивайте ESX и QBCore в одной сборке. Ресурсы ESX обычно не работают на QBCore, а ресурсы QBCore — на ESX.

Порядок загрузки ESX

Пример базового порядка для ESX:

set mysql_connection_string "mysql://USERNAME:PASSWORD@HOST:PORT/DATABASE_NAME?charset=utf8mb4"

ensure oxmysql
ensure es_extended

ensure esx_menu_default
ensure esx_menu_list
ensure esx_menu_dialog

ensure esx_basicneeds
ensure esx_status
ensure esx_jobs
ensure esx_vehicleshop

Точный порядок зависит от версии ESX и документации конкретной сборки.

Порядок загрузки QBCore

Пример базового порядка для QBCore:

set mysql_connection_string "mysql://USERNAME:PASSWORD@HOST:PORT/DATABASE_NAME?charset=utf8mb4"

ensure oxmysql
ensure qb-core
ensure qb-smallresources
ensure qb-inventory
ensure qb-garages
ensure qb-policejob
ensure qb-ambulancejob

Точный порядок зависит от версии QBCore и установленных ресурсов.

Импорт SQL-файлов

Некоторые ресурсы требуют импортировать SQL-файл в базу данных.

Обычно SQL-файл находится в папке ресурса и называется:

install.sql
database.sql
.sql

Перед запуском ресурса импортируйте SQL в вашу базу данных через доступный инструмент управления базой.

Если SQL не импортирован, ресурс может выдавать ошибки вида:

Unknown table
Unknown column
Table doesn't exist

Частые ошибки ресурсов

Ресурс не видит фреймворк

Если ресурс пишет, что не найден ESX, QBCore или shared object, проверьте:

• фреймворк установлен;
• фреймворк запускается выше зависимого ресурса;
• ресурс совместим с вашим фреймворком;
• используется правильная версия ресурса;
• в конфигурации ресурса выбран правильный framework.

Ресурс не видит базу данных

Проверьте:

• создана база данных;
• строка mysql_connection_string указана до ensure oxmysql;
• oxmysql установлен и запускается;
• используется правильный хост базы данных;
• не используется localhost;
• логин, пароль и имя базы указаны верно;
• специальные символы в пароле закодированы.

Резервное копирование перед установкой

Перед установкой крупных ресурсов, фреймворка или обновлением сборки сделайте резервную копию.

Минимально сохраните:

server.cfg
resources/
txData/
logs/

Если используется база данных, также сделайте дамп базы.

Рекомендуемый порядок установки нового ресурса

1. Сделайте резервную копию server.cfg.
2. Сделайте резервную копию базы данных, если ресурс её использует.
3. Загрузите ресурс в resources/.
4. Проверьте наличие fxmanifest.lua.
5. Импортируйте SQL, если он есть.
6. Добавьте ensure resource-name в server.cfg.
7. Проверьте зависимости и порядок загрузки.
8. Перезапустите сервер или выполните refresh и ensure resource-name.
9. Проверьте консоль на ошибки.

Рекомендации

• добавляйте новые ресурсы по одному;
• не устанавливайте ресурсы из неизвестных источников без проверки;
• проверяйте манифест ресурса перед загрузкой;
• не смешивайте ESX и QBCore;
• загружайте oxmysql перед фреймворком;
• держите важные зависимости выше зависимых ресурсов;
• не используйте localhost для внешней базы данных;
• после ошибок всегда проверяйте последние строки консоли;
• перед установкой крупных скриптов создавайте резервную копию.

Файлы и каталоги, которые чаще всего используются при установке ресурсов:

server.cfg
resources/
resources/[standalone]/
resources/[esx]/
resources/[qb]/
txData/
logs/