Руководство по установке Agency Phone: полная установка и настройка FiveM

Это руководство проведет вас через полный процесс установки и настройки Agency Phone на вашем FiveM сервере. Независимо от того, используете ли вы QBCore, ESX или полностью кастомный фреймворк, здесь вы найдете все необходимое: от предварительных требований до первого запуска и тонкой настройки конфигурации. Для полного технического справочника смотрите официальную документацию на docs.agencyg.de/phone.

Требования

Перед установкой Agency Phone убедитесь, что ваша серверная среда соответствует следующим требованиям:

• Артефакт сервера FiveM: версия 6633 или новее (рекомендуется: всегда держать артефакты в актуальном состоянии)
• База данных: MySQL 5.7+ или MariaDB 10.3+, с oxmysql (рекомендуется) или mysql-async установлен и настроен
• CFX Keymaster: ключ лицензии вашего сервера должен быть зарегистрирован и активен на keymaster.fivem.net
• Фреймворк (опционально): QBCore или ESX, если вам нужна глубокая интеграция с фреймворком. Не требуется для standalone-работы.
• Активная покупка Agency Phone: ресурс поставляется через портал CFX после покупки

Шаг 1: Купите и скачайте

После завершения покупки на Agency Scripts shop , ваша лицензия автоматически регистрируется в вашем аккаунте CFX. Для загрузки:

1. Войти в keymaster.fivem.net с учётной записью CFX, связанной с вашей покупкой.
2. Перейти к Предоставленные активы и найдите agency-phone.
3. Клик Скачать получить последний релиз в формате zip.
4. Если вы приобрели мост QBCore или ESX, также скачайте agency-phone-bridge-qb или agency-phone-bridge-esx из того же списка.

Шаг 2: Структура папок

Распакуйте zip-файл(ы). Ваш resources каталог должен выглядеть так после извлечения:

resources/
  [agency]/
    agency-phone/
      client/
      server/
      html/
      config.lua
      fxmanifest.lua
    agency-phone-bridge-qb/   (QBCore only)
      client/
      server/
      fxmanifest.lua

Параметр [agency] папка , это категория (квадратные скобки говорят FiveM, что это группа ресурсов). Она не обязательна, вы можете разместить agency-phone напрямую в resources/ но использование папок по категориям сохраняет порядок.

Шаг 3: Настройка базы данных

Agency Phone creates its own database tables on first launch using the auto-migration system built into oxmysql. You do not need to manually import any SQL files. Simply ensure your database connection is configured in server.cfg:

# server.cfg, database connection string (oxmysql example)
set mysql_connection_string "mysql://user:password@localhost/fivem_db?charset=utf8mb4"

При первом запуске сервера Agency Phone создаст следующие таблицы: phone_contacts, phone_messages, phone_calls, phone_gallery, phone_social_posts , и phone_settings. Если вы используете новую базу данных, таблицы будут созданы автоматически. Если вы мигрируете с другого скрипта телефона, убедитесь, что в вашей существующей схеме нет конфликтов имён.

Шаг 4: Записи в server.cfg

Добавьте следующие строки ensure в ваш server.cfg. Порядок важен, oxmysql должен загрузиться до Agency Phone:

# Dependencies
ensure oxmysql

# Agency Phone (standalone or with framework bridge)
ensure agency-phone

# Only add if using QBCore bridge:
# ensure qb-core
# ensure agency-phone-bridge-qb

# Only add if using ESX bridge:
# ensure es_extended
# ensure agency-phone-bridge-esx

Если вы используете QBCore или ESX, убедитесь, что сам фреймворк загружается до ресурс-мост, как показано в комментариях выше. Автономное ядро (agency-phone) всегда должен быть обеспечен перед любым bridge-ресурсом.

Шаг 5: Конфигурация (config.lua)

Открыто agency-phone/config.lua в текстовом редакторе. Это основной конфигурационный файл, который контролирует почти все аспекты поведения телефона. Вот подробное руководство по самым важным настройкам:

Config = {}

-- ============================================================
-- FRAMEWORK
-- "standalone" | "qbcore" | "esx"
-- ============================================================
Config.Framework = "standalone"

-- ============================================================
-- PHONE NUMBERS
-- ============================================================
-- Format string for auto-generated numbers. X = random digit.
Config.PhoneNumberFormat = "555-XXXX"

-- Allow players to pay in-game currency to change their number
Config.AllowNumberChange = true
Config.NumberChangeCost   = 500  -- default currency (adjust per framework)

-- ============================================================
-- APPS: enable/disable individual apps
-- ============================================================
Config.EnableBankingApp   = true
Config.EnableSocialApp    = true
Config.EnableGPSApp       = true
Config.EnableCameraApp    = true
Config.EnableMDT          = false   -- set true only for LEO servers
Config.EnableNotesApp     = true

-- ============================================================
-- MDT (only relevant when Config.EnableMDT = true)
-- ============================================================
-- Jobs that can access the MDT app
Config.MDTJobs = { "police", "sheriff", "highway_patrol" }

-- ============================================================
-- SOCIAL MEDIA
-- ============================================================
-- Rename the social app to match your server's lore
Config.SocialAppName = "Chirper"
-- Max post length in characters
Config.SocialPostMaxLength = 280

-- ============================================================
-- ENCRYPTED MESSAGING
-- Requires players to hold a specific inventory item
-- ============================================================
Config.EncryptedChat     = false
Config.EncryptedChatItem = "burner_phone"

-- ============================================================
-- UI
-- ============================================================
-- Default theme: "dark" or "light"
Config.DefaultTheme = "dark"
-- Notification display duration in milliseconds
Config.NotificationDuration = 5000
-- Phone open keybind (FiveM key name)
Config.PhoneKey = "F1"

Особенности QBCore

При использовании моста QBCore (Config.Framework = "qbcore" ), банковское приложение автоматически получает данные о балансе и транзакциях из экономики QBCore. Разрешения приложений на основе работы (например, доступ к MDT) используют нативную систему работы QBCore, дополнительная настройка не требуется, кроме добавления названий работ в Config.MDTJobs. Номера телефонов хранятся на каждого персонажа и привязаны к идентификатору персонажа QBCore.

Особенности ESX

С мостом ESX (Config.Framework = "esx" ), банковское приложение подключается к аккаунтам ESX (по умолчанию: bank ). Если ваша настройка ESX использует пользовательские названия аккаунтов, настройте их в собственных config.lua. Ранги работы ESX учитываются для доступа к MDT, нужно указать только названия работ; все ранги внутри этой работы получают доступ автоматически, если вы не настроите ограничения по рангу в конфигурации моста.

Шаг 6: Проверка при первом запуске

Запустите ваш сервер и наблюдайте вывод консоли. Успешная загрузка Agency Phone выглядит так:

[agency-phone] Database tables verified/created, OK
[agency-phone] Framework: standalone
[agency-phone] Loaded 0 contacts, 0 messages (fresh install)
[agency-phone] Resource started successfully, v2.x.x

Если на этом этапе вы видите ошибки, проверьте раздел устранения неполадок ниже. После запуска сервера подключитесь клиентом и нажмите F1 (или ваша настроенная клавиша телефона) для открытия телефона. При первом использовании телефон предложит игроку установить номер, если он ещё не назначен.

Распространённые ошибки и их исправления

Ошибка: "oxmysql не запущен"

Это означает, что oxmysql не гарантирован перед agency-phone в вашем server.cfg. Переместите ensure oxmysql line above ensure agency-phone и перезапустите сервер.

Ошибка: "Не удалось создать таблицу phone_contacts: Таблица уже существует"

Это предупреждение, а не критическая ошибка, оно означает, что вы переустанавливаете поверх существующей базы данных. Существующие данные сохраняются. Вы можете безопасно игнорировать это предупреждение. Если вы хотите чистую установку, вручную удалите phone_* таблицы в вашей базе данных сначала.

Интерфейс телефона не открывается при нажатии клавиши

Сначала проверьте, что ресурс запустился без ошибок в консоли сервера. Во-вторых, убедитесь, что никакой другой ресурс не использует ту же клавишу (по умолчанию: F1). Вы можете изменить клавишу в config.lua под Config.PhoneKey. Во-вторых, проверьте конфликты фокуса NUI, если другой ресурс одновременно захватывает фокус NUI, телефон может не получить нажатие клавиши корректно.

Банковское приложение показывает $0 / пустой баланс

Если вы используете standalone режим, банковское приложение по умолчанию использует внутренний кошелёк. Чтобы подключить его к экономике QBCore или ESX, необходимо использовать соответствующий мост и установить Config.Framework корректно. Если мост обеспечен, но баланс всё ещё показывает ноль, проверьте, что персонаж игрока полностью загружен в фреймворке до инициализации телефона (порядок загрузки фреймворка в server.cfg).

Приложение MDT не видно для полицейских офицеров

Подтвердите, что Config.EnableMDT = true в config.lua и что текущее имя работы игрока точно совпадает с одной из записей в Config.MDTJobs. Совпадение имени работы чувствительно к регистру. Используйте точную строку имени работы, как определено в конфиге работы вашего фреймворка.

Дополнительные параметры настройки

Agency Phone has many more configuration options beyond what is covered in this guide. Some of the most useful advanced settings include:

• Config.MaxContactsPerPlayer", ограничение на количество контактов, которые игрок может сохранить (по умолчанию: неограниченно)",
• Config.GPSUpdateInterval , как часто обновляется метка игрока на общем GPS (в миллисекундах).
• Config.SocialPostCooldown", минимальное время между публикациями в социальных сетях для предотвращения спама (в секундах)",
• Config.AllowAnonCalls", разрешать ли игрокам совершать звонки с скрытым номером для получателя.
• Config.CameraPhotoQuality , уровень качества скриншотов NUI (1-10, влияет на размер изображений в игровой галерее)

Полный аннотированный конфигурационный файл со всеми опциями доступен в официальной документации по адресу docs.agencyg.de/phone. Документация обновляется с каждым релизом и включает заметки по миграции, специфичные для версии, когда настройки меняются.

Обновление Agency Phone

Когда выходит новая версия, вы получите уведомление в своем аккаунте CFX keymaster. Для обновления скачайте новый zip с страницы Granted Assets, распакуйте и замените существующий agency-phone папка на вашем сервере. Всегда читайте changelog обновлений перед обновлением на живом сервере, там перечислены изменения ключей config.lua, требующие вашего внимания. Ваша база данных и существующие данные игроков никогда не удаляются обновлением.