QBCore, ESX или Standalone: как Agency Scripts работают с вашим фреймворком

Проблема совместимости платформ

Большинство скриптов FiveM поставляются с жёстко встроенным одним фреймворком. Если вы используете QBCore, то используете скрипты QBCore. Пользователи ESX ограничены скриптами ESX. Пользователи standalone в основном собирают всё вместе хаками. Agency Scripts построены на противоположной философии: фреймворк , это адаптер, а не предположение.

Паттерн Адаптера

Каждый скрипт Agency предоставляет небольшой набор функций поиска: getPlayerData, getInventory, addMoney, removeItem, getJob. Мы поставляем адаптеры, которые из коробки сопоставляют их с реализациями QBCore и ESX. Для standalone вы реализуете четыре или пять функций самостоятельно, обычно это работа на утро, и каждый скрипт Agency совместим.

Что это значит на практике

Когда вы переключаете сервер с QBCore на ESX (что действительно происходит каждые несколько лет по мере развития фреймворков), скрипты Agency не требуют переустановки или перенастройки. Вы меняете адаптер, всё остальное продолжает работать. Это крайне редко встречается в экосистеме FiveM и является главной причиной, по которой владельцы серверов стандартизируют наши инструменты на долгий срок.

Что означает метка Framework на наших страницах продуктов

Когда на странице продукта указано "QBCore, ESX", это значит, что мы поставляем готовые адаптеры для обеих систем. Когда указано "Standalone", это значит, что скрипт не зависит от фреймворка, ему не нужен адаптер и он работает на любом сервере. На практике почти каждый скрипт Agency можно использовать в standalone-средах с небольшим совместимым шимом.

Когда спрашивать перед покупкой

Если у вас необычная конфигурация, кастомный фреймворк, сильно модифицированный QBCore или что-то уникальное, откройте тикет в нашем Discord перед покупкой. Мы честно скажем, что будет работать, что требует лёгкой адаптации, а что не стоит хлопот. Без давления на покупку; нам важнее, чтобы вы купили один подходящий скрипт, чем три неподходящих.

Как работает паттерн Adapter на практике

Когда вы устанавливаете скрипт Agency, папка ресурса содержит framework подкаталог с минимум тремя файлами: qb.lua, esx.lua , и standalone.lua. Основной скрипт автоматически определяет, какой фреймворк присутствует, проверяя экспорт QBCore или ESX. Загружается соответствующий адаптер; остальные нет. Это автоопределение происходит до запуска игровой логики, нет накладных расходов во время работы из-за определения фреймворка.

Каждый адаптер реализует одинаковый внутренний API. Если скрипту нужно выдать игроку деньги, он вызывает Framework.AddMoney(src, amount) внутренне. Эта функция в qb.lua вызывает экспорт денег QBCore; в esx.lua вызывает систему аккаунтов ESX; в standalone.lua вызывает любую функцию, которую вы определили в config.lua. Один вызов, три реализации, никаких изменений скрипта между фреймворками.

Установка на QBCore

Для серверов на QBCore установка обычно состоит из трёх шагов: скачайте ресурс, поместите его в папку resources и добавьте в server.cfg. Определение фреймворка происходит автоматически. Если вы используете сильно модифицированный QBCore (кастомная система денег, кастомный инвентарь, кастомные работы), возможно, потребуется переопределить конкретные функции адаптера в config.lua вместо редактирования qb.lua напрямую. Подход с переопределением конфигурации означает, что вы не потеряете свои изменения при обновлениях ресурса.

Установка на ESX

Установка ESX следует той же схеме. Один дополнительный шаг, который иногда необходим: если ваша версия ESX значительно устарела (до 1.7), некоторые функции адаптера ссылаются на новые имена экспортов ESX. Ресурс поставляется с флагом совместимости legacy Config.ESXLegacy = true которые переключаются на старые вызовы API ESX во всех скриптах Agency, где это необходимо.

Установка на standalone

Standalone , это то, где большинство владельцев серверов исторически сталкивались с трудностями при использовании других скриптов. Путь standalone от Agency Scripts ясен и хорошо документирован. Для каждого скрипта файл адаптера standalone точно перечисляет, какие функции необходимо реализовать. Большинству скриптов требуется от четырёх до восьми функций. Каждая функция снабжена комментарием, объясняющим, что она должна возвращать. Типичная реализация standalone занимает от одного до трёх часов в зависимости от сложности вашей кастомной системы данных игроков.

После реализации адаптера для одного скрипта Agency последующие скрипты требуют гораздо меньше времени, часто одни и те же пользовательские функции применимы к нескольким ресурсам.

Почему это важно для долгосрочной работы сервера

Фреймворки FiveM не вечны. Сервера, работающие три и более года, вероятно, уже проходили через как минимум одно крупное изменение фреймворка, возможно, миграцию с community ESX форка на mainline ESX или с более старой версии QBCore на текущую. Скрипты, завязанные на фреймворк, требуют больших затрат при миграции: каждый скрипт нужно обновлять или заменять при значительных изменениях фреймворка.

Agency Scripts' adapter architecture means that a framework migration affects only the adapter layer. Your Agency-Phone data, Agency-Admin logs, Agency-Blackmarket transaction history, and player progression in Agency-Minerjob all survive intact. You swap the adapter files, update config.lua, and the scripts keep working. This is the actual long-term value of the compatibility approach, not just supporting multiple frameworks, but insulating your server from framework evolution.

Часто задаваемые вопросы

Используют ли все скрипты Agency один и тот же паттерн адаптера?

Да. Каждый платный скрипт Agency и большинство бесплатных используют этот шаблон. Единственные исключения , чисто UI-ресурсы, такие как Agency-Loadingscreen и Agency-Notify, которые не взаимодействуют с фреймворком и работают одинаково везде.

Могу ли я смешивать адаптеры фреймворков? Например, использовать деньги QBCore, но standalone инвентарь?

Да, через переопределения в конфиге. Установите обнаружение фреймворка на QBCore, затем переопределите конкретные функции адаптера в config.lua, чтобы вызывать вашу кастомную систему инвентаря вместо QBCore. Система переопределений создана именно для серверов с гибридными настройками.

Что если новая платформа станет популярной и пока не поддерживается?

Открыть тикет поддержки в Discord. Мы оцениваем запросы на поддержку новых фреймворков на основе их популярности в сообществе. Для фреймворков с большой аудиторией мы исторически добавляли поддержку в течение 2-4 недель. Тем временем путь с использованием standalone адаптера работает для любого фреймворка как временное решение.

Обновляются ли адаптеры фреймворков при обновлении самого фреймворка?

Да. Когда QBCore или ESX выпускают критическое обновление, мы выпускаем обновления адаптеров в течение нескольких дней после релиза фреймворка. Активные подписчики получают уведомления об обновлениях через Tebex. Это часть причины существования модели подписки: поддержка адаптеров , это постоянная работа, а не одноразовая стоимость.

Сводка требований по фреймворку

• QBCore любой актуальной версии QBCore. Автоматическое определение, нулевая конфигурация для стандартных установок.
• ESX , ESX Legacy 1.7+ или основная ветка ESX. Установите флаг legacy для старых версий.
• Standalone , реализуйте 4-8 функций на скрипт в config.lua. Одноразовая настройка, повторно используемая в скриптах Agency.
• Все настройки аккаунт cfx.re с действующей лицензией, сервер FiveM с Artifacts 5181 или выше рекомендуется.