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

MAATRIX GAMES

Ты определился с фреймворком, прочитал сравнение с ESX и решил ставить QBCore — но между «решил» и «сервер реально стартует без ошибок в консоли» лежит десяток шагов, на каждом из которых новичок обычно спотыкается: не в том порядке подключил ресурсы, забыл зависимость, не создал базу под правильной кодировкой. Разберём установку QBCore с нуля так, чтобы после первого рестарта ты увидел не портянку ошибок, а рабочий сервер с созданием персонажа.

Что должно быть готово до установки QBCore

QBCore — это не отдельный сервер, а слой ресурсов поверх уже работающего FiveM. Если у тебя ещё нет голого сервера с рабочим server.cfg и лицензионным ключом Cfx.re — сначала пройди установку FiveM-сервера, иначе ставить framework буквально не на что.

Дальше нужно ещё три вещи:

• MySQL или MariaDB, установленный и запущенный на том же VPS (или доступный по сети) — QBCore хранит игроков, инвентарь, транспорт и экономику в базе, без неё core не стартует.
• Git на сервере — почти все ресурсы QBCore ставятся клонированием репозиториев, а не скачиванием zip-архивов вручную.
• Свободные минимум 8 ГБ RAM под связку сервера и MySQL под нагрузкой — это ориентир из практики, не жёсткий минимум: на 4 ГБ голый QBCore тоже стартует, но начнёт подтормаживать уже на паре десятков игроков вместе с базой на том же VPS.

Держи под рукой доступ к консоли сервера (SSH или консоль txAdmin) — часть команд ниже выполняется именно там, а не в игре.

Клонируем qb-core и обязательные зависимости

QBCore принято раскладывать по папкам-категориям внутри resources/ — так удобнее ориентироваться, когда ресурсов становится много. Стандартная структура: [qb] для core-ресурсов фреймворка, [standalone] или просто корень resources/ для независимых зависимостей.

cd ~/fxserver/server-data/resources
mkdir -p "[qb]"
cd "[qb]"

git clone https://github.com/qbcore-framework/qb-core.git
git clone https://github.com/qbcore-framework/qb-multicharacter.git
git clone https://github.com/qbcore-framework/qb-spawn.git

qb-core — само ядро фреймворка, без него ничего не заработает. qb-multicharacter даёт игроку экран выбора/создания персонажа при заходе, qb-spawn отвечает за точку появления после выбора. Формально можно стартовать и без них, но тогда придётся писать логику спавна и мультихарактеров руками — для базовой настройки проще взять готовые ресурсы.

Дальше — обязательные внешние зависимости, без которых core упадёт при старте:

cd ~/fxserver/server-data/resources
mkdir -p "[standalone]"
cd "[standalone]"

git clone https://github.com/overextended/oxmysql.git
git clone https://github.com/overextended/ox_lib.git

oxmysql — асинхронный MySQL-драйвер, через него qb-core общается с базой; современные версии core рассчитаны именно на него, а не на устаревший mysql-async. ox_lib формально не всегда обязателен для голого core, но значительная часть community-ресурсов под QBCore (включая некоторые версии самого core) уже тянет его как зависимость — ставить сразу дешевле, чем потом ловить ошибку ox_lib not found в консоли.

Отдельно стоит qb-target — не обязателен для самого core, но это стандартный ресурс взаимодействия (клик по объекту/NPC вместо текстовых зон), под который написано огромное количество community-скриптов для QBCore:

git clone https://github.com/overextended/qb-target.git

База данных: создаём схему и подключаем oxmysql

Создай отдельную базу и пользователя под QBCore — не используй root и не сажай несколько проектов в одну базу, это усложнит бэкапы и восстановление при проблемах:

CREATE DATABASE qbcore CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'qbcore'@'localhost' IDENTIFIED BY 'СЛОЖНЫЙ_ПАРОЛЬ';
GRANT ALL PRIVILEGES ON qbcore.* TO 'qbcore'@'localhost';
FLUSH PRIVILEGES;

Кодировка utf8mb4 важна — без неё эмодзи и часть кириллицы в никах/чате может ломаться или обрезаться. Дальше пропиши строку подключения в server.cfg до строки ensure oxmysql:

set mysql_connection_string "mysql://qbcore:СЛОЖНЫЙ_ПАРОЛЬ@localhost/qbcore?charset=utf8mb4"

Актуальные версии qb-core создают базовые таблицы (players, gangs, jobs и часть справочников) автоматически при первом старте через oxmysql — вручную импортировать дамп обычно не требуется. Но перед первым запуском загляни в README конкретной версии qb-core, которую склонировал: если в репозитории лежит отдельный .sql-файл с пометкой про ручной импорт, значит для этой сборки автосоздание не покрывает всё, и дамп нужно залить через mysql -u qbcore -p qbcore < qb-core.sql до старта сервера. Версии core меняются, и полагаться на то, что «раньше было именно так», не стоит — проверяй по актуальной документации репозитория.

server.cfg: порядок ресурсов и обязательные ensure-строки

Здесь новички теряют больше всего времени: QBCore чувствителен к порядку загрузки ресурсов. Если qb-core попытается стартовать раньше oxmysql, он не найдёт функцию подключения к базе и упадёт с ошибкой в консоли ещё до того, как остальные ресурсы вообще подгрузятся.

Правильный порядок в server.cfg:

# Зависимости — до core
ensure oxmysql
ensure ox_lib

# Ядро фреймворка
ensure qb-core

# Ресурсы, зависящие от core
ensure qb-multicharacter
ensure qb-spawn
ensure qb-target

Общее правило: всё, от чего зависит core (или другой ресурс) — идёт строкой ensure выше в конфиге. Сам qb-core всегда должен быть выше любого ресурса с префиксом qb- или community-скрипта, написанного под QBCore, — иначе такой ресурс не найдёт объект QBCore в момент своего старта и вывалится с ошибкой в консоли.

Если позже будешь добавлять сторонние скрипты под QBCore с GitHub или Tebex — процесс тот же самый: клонируешь в resources/, добавляешь ensure строго после qb-core (и после всех зависимостей конкретно этого ресурса, если они указаны в его README). Подробнее про установку кастомных ресурсов и типичные грабли — в отдельном гайде по установке кастомных скриптов на FiveM.

Чем событийная система QBCore ощущается иначе, чем в ESX

Если раньше трогал ESX, разница на уровне установки чувствуется в двух местах. Во-первых, обращение к API идёт не через глобальный объект вроде ESX.GetPlayerFromId(), а через exports['qb-core']:GetCoreObject(), который в клиентских и серверных скриптах обычно один раз сохраняют в переменную QBCore и дальше вызывают QBCore.Functions.GetPlayer(source). Технически это тоже событийная модель поверх AddEventHandler/TriggerEvent, но сам core активнее используют именно через export, а не события напрямую — это стоит учитывать, читая чужие ресурсы: если скрипт не находит QBCore, почти всегда причина в порядке ensure, который мы разобрали выше, а не в баге самого скрипта.

Во-вторых — встроенные системы работ и банд. В ESX добавление работы обычно означает правку таблицы jobs в базе плюс отдельный ресурс. В QBCore работы и банды описаны прямо в файлах core: qb-core/shared/jobs.lua и qb-core/shared/gangs.lua. Это значит, что на базовом этапе настройки тебе не нужен отдельный ресурс, чтобы завести новую фракцию — правишь Lua-файл внутри уже установленного core и перезапускаешь ресурс командой refresh + restart qb-core в консоли. Удобно для старта, но при обновлении core важно не потерять свои правки — сравнивай файл при апдейте, а не просто перезаписывай его новой версией из репозитория. Более подробное сравнение архитектуры и экономики двух фреймворков — в статье ESX и QBCore: сравнение фреймворков, если решение ещё не окончательное.

Первый запуск и проверка

Всё разложено, server.cfg собран — запускай:

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

Смотри консоль внимательно. Правильный запуск выглядит так: сначала стартует oxmysql с подтверждением подключения к базе, следом qb-core без ошибок про отсутствующие функции, затем qb-multicharacter. Заходи клиентом по connect IP:30120 — если всё встало верно, вместо мгновенного спавна на улице увидишь экран создания персонажа от qb-multicharacter. Создай тестового персонажа и убедись, что он появляется через qb-spawn, а не падает в текстуру или зависает на чёрном экране.

Частая ошибка новичка на этом шаге — сервер стартует, но при попытке зайти в игру консоль сыплет SCRIPT ERROR про несуществующую таблицу или обрыв соединения с MySQL. Если дело именно в базе — отдельно разобрали типичные причины и способы починки в статье про проблему с подключением к базе MySQL на FiveM. Если ошибка про конкретный ресурс — почти всегда это порядок ensure или пропущенная зависимость из списка выше, а не проблема с самим core.

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