دليل إعداد Agency Phone: التثبيت والتكوين الكامل لـ FiveM

يرشدك هذا الدليل خلال العملية الكاملة لتثبيت وتكوين Agency Phone على خادم FiveM الخاص بك. سواء كنت تستخدم QBCore، ESX، أو إطار عمل مخصص بالكامل، ستجد كل ما تحتاجه هنا، من المتطلبات الأساسية إلى الإقلاع الأولي إلى ضبط التكوين بدقة. للمرجع الفني الكامل، راجع الوثائق الرسمية على docs.agencyg.de/phone.

المتطلبات المسبقة

قبل تثبيت Agency Phone، تأكد من أن بيئة الخادم الخاصة بك تلبي المتطلبات التالية:

• مورد خادم FiveM: الإصدار 6633 أو أحدث (موصى به: حافظ دائمًا على تحديث artifacts)
• قاعدة البيانات: MySQL 5.7+ أو MariaDB 10.3+، مع oxmysql (موصى به) أو mysql-async مثبت ومُكوّن
• CFX Keymaster: يجب تسجيل مفتاح ترخيص خادمك وتفعيله على keymaster.fivem.net
• الإطار (اختياري): QBCore أو ESX إذا كنت تريد تكامل إطار أعمق. غير مطلوب للتشغيل المستقل.
• شراء هاتف Agency نشط: يتم تسليم المصدر عبر بوابة أصول 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

أضف خطوط التأكد التالية إلى 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) يجب التأكد منه دائمًا قبل أي مورد جسر.

الخطوة 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 السطر أعلاه ensure agency-phone وأعد تشغيل الخادم.

خطأ: "فشل إنشاء جدول phone_contacts: الجدول موجود بالفعل"

هذا تحذير، ليس خطأ قاتل، يعني أنك تعيد التثبيت فوق قاعدة بيانات موجودة. يتم الحفاظ على البيانات الحالية. يمكنك تجاهل هذا التحذير بأمان. إذا كنت تريد تثبيتًا نظيفًا، قم بحذف phone_* الجداول في قاعدة بياناتك أولاً.

واجهة الهاتف لا تفتح عند الضغط على المفتاح

أولاً، تحقق من أن المورد بدأ بدون أخطاء في وحدة تحكم الخادم. ثانيًا، تحقق من أن لا مورد آخر يستخدم نفس مفتاح الاختصار (الافتراضي: F1). يمكنك تغيير مفتاح الاختصار في config.lua تحت Config.PhoneKey. ثالثًا، تحقق من تعارضات تركيز NUI، إذا كان مورد آخر يلتقط تركيز NUI في نفس الوقت، قد لا يستقبل الهاتف ضغطات المفاتيح بشكل صحيح.

تطبيق البنك يعرض رصيد $0 / فارغ

إذا كنت تستخدم الوضع المستقل، يستخدم تطبيق البنك محفظة داخلية بشكل افتراضي. للاتصال باقتصاد 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 المجلد على خادمك. اقرأ دائمًا سجل التغييرات قبل التحديث على خادم مباشر، فهو يسرد أي تغييرات على مفاتيح config.lua التي تتطلب انتباهك. قاعدة بياناتك وبيانات اللاعبين الحالية لا يتم حذفها أبدًا بواسطة التحديث.