QBCore، ESX أو Standalone: كيف تعمل Agency Scripts مع إطارك

The Framework Compatibility Problem

تأتي معظم سكربتات FiveM مدمجة بإطار عمل واحد. إذا كنت تستخدم QBCore، تستخدم سكربتات QBCore. مستخدمو ESX عالقون مع سكربتات ESX. مستخدمو standalone غالباً ما يجمعون الأشياء معاً بشكل عشوائي. تم بناء Agency Scripts بفلسفة معاكسة: الإطار هو محول، وليس افتراضاً.

نمط المحول

كل سكربت من Agency يكشف عن مجموعة صغيرة من دوال البحث: getPlayerData, getInventory, addMoney, removeItem, getJob. نشحن محولات تربط هذه بالتنفيذات الخاصة بـ QBCore و ESX مباشرة. بالنسبة للنظام المستقل، تقوم بتنفيذ الأربع أو الخمس دوال بنفسك، عادةً عمل صباح واحد، وكل سكربت من Agency متوافق.

ماذا يعني هذا عمليًا

عندما تحول خادمك من QBCore إلى ESX (وهو ما يحدث كل بضع سنوات مع تطور الأُطُر)، لا تحتاج سكربتات Agency إلى إعادة تثبيت أو إعادة تكوين. تستبدل المحول، ويستمر كل شيء آخر في العمل. هذا نادر جدًا في نظام FiveM وهو السبب الرئيسي الذي يجعل مالكي الخوادم يوحدون أدواتنا على المدى الطويل.

ما معنى تسمية الإطار على صفحات منتجاتنا

عندما تدرج صفحة منتج "QBCore, ESX" فهذا يعني أننا نوفر محولات جاهزة لكليهما. عندما تقول "Standalone" نعني أن السكريبت مستقل عن الإطار، لا يحتاج إلى محول ويعمل على أي خادم. عملياً، يمكن استخدام كل سكريبت من Agency تقريباً على إعدادات مستقلة مع طبقة توافق صغيرة.

متى تسأل قبل الشراء

إذا كنت تدير إعدادًا غير معتاد، إطار عمل مخصص، QBCore معدل بشكل كبير، أو شيء مخصص، افتح تذكرة على Discord قبل الشراء. سنخبرك بصراحة ما الذي سيعمل، وما يحتاج إلى تعديل بسيط، وما لا يستحق العناء. لا ضغط مبيعات؛ نفضل أن تشتري سكريبت واحد يناسبك بدلاً من ثلاثة لا تناسب.

كيف يعمل نمط المحول في التطبيق العملي

عندما تثبت سكربت Agency، يحتوي مجلد المورد على framework دليل فرعي يحتوي على ثلاثة ملفات على الأقل: qb.lua, esx.lua، و standalone.lua. يكتشف السكربت الرئيسي إطار العمل الموجود تلقائيًا بفحص وجود تصدير QBCore أو ESX. يتم تحميل ملف المحول المطابق؛ ولا يتم تحميل الملفات الأخرى. يحدث هذا الكشف التلقائي قبل تشغيل أي منطق لعب، ولا يوجد حمل وقت تشغيل من الكشف عن إطار العمل.

كل محول ينفذ نفس واجهة برمجة التطبيقات الداخلية. إذا كان النص يحتاج إلى منح لاعب مالًا، فإنه يستدعي Framework.AddMoney(src, amount) داخليًا. تلك الوظيفة في qb.lua تستدعي تصدير المال الخاص بـ QBCore؛ في esx.lua يستدعي نظام حسابات ESX؛ في standalone.lua يستدعي أي وظيفة قمت بتعريفها في config.lua. مكالمة واحدة، ثلاث تطبيقات، بدون تغييرات في السكريبت بين الأُطُر.

التثبيت على QBCore

لخوادم QBCore، التثبيت عادة ما يكون في ثلاث خطوات: تحميل المورد، وضعه في مجلد الموارد، وإضافته إلى server.cfg. الكشف عن الإطار يتم تلقائيًا. إذا كنت تستخدم QBCore معدل بشكل كبير (نظام مال مخصص، مخزون مخصص، وظائف مخصصة)، قد تحتاج إلى تجاوز وظائف المحول المحددة في config.lua بدلاً من التحرير qb.lua مباشرة. تعني طريقة تجاوز الإعدادات أنك لن تفقد تغييراتك عند تحديث الموارد.

التثبيت على ESX

يتبع تثبيت ESX نفس النمط. خطوة إضافية واحدة قد تكون مطلوبة أحيانًا: إذا كانت نسخة ESX الخاصة بك أقدم بكثير (قبل 1.7)، تشير بعض وظائف المحول إلى أسماء تصدير ESX الأحدث. المورد يأتي مع علم توافق قديم Config.ESXLegacy = true الذي يتحول إلى استدعاءات API القديمة لـ ESX عبر جميع سكربتات Agency التي تحتاجها.

التثبيت على Standalone

كان المستقل هو المكان الذي واجه فيه معظم مالكي الخوادم تاريخيًا صعوبات مع السكريبتات الأخرى. مسار Agency Scripts المستقل واضح وموثق جيدًا. لكل سكريبت، يسرد ملف المحول المستقل بالضبط الوظائف التي تحتاج إلى تنفيذها. معظم السكريبتات تحتاج بين أربع إلى ثماني وظائف. لكل وظيفة تعليق يشرح ما يجب أن تُرجع. يستغرق تنفيذ مستقل نموذجي من ساعة إلى ثلاث ساعات حسب مدى تعقيد نظام بيانات اللاعب المخصص لديك.

بمجرد تنفيذ المحول لسكربت Agency واحد، تستغرق السكربتات اللاحقة وقتاً أقل بكثير، وغالباً ما تنطبق نفس الوظائف المخصصة عبر موارد متعددة.

لماذا هذا مهم لتشغيل الخادم على المدى الطويل

أُطُر FiveM ليست دائمة. الخوادم التي تعمل لمدة ثلاث سنوات أو أكثر قد تكون قد تعاملت بالفعل مع اعتبار إطار عمل رئيسي واحد على الأقل، ربما بالانتقال من فرع ESX المجتمعي إلى 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 ومعظم المجاني يستخدم هذا النمط. الاستثناءات الوحيدة هي الموارد التي تعتمد فقط على واجهة المستخدم مثل Agency-Loadingscreen وAgency-Notify، التي لا تتفاعل مع الإطار على الإطلاق وتعمل بشكل متماثل في كل مكان.

هل يمكنني مزج محولات الأُطُر؟ على سبيل المثال، استخدام أموال QBCore ولكن مخزون standalone؟

نعم، من خلال تجاوزات التكوين. اضبط اكتشاف الإطار على QBCore، ثم تجاوز وظائف المحول المحددة في config.lua لاستدعاء نظام الجرد المخصص الخاص بك بدلاً من QBCore. نظام التجاوز موجود خصيصاً للسيرفرات ذات الإعدادات الهجينة.

ماذا لو أصبح إطار عمل جديد شائعًا ولم يتم دعمه بعد؟

افتح تذكرة دعم على Discord. نقوم بتقييم طلبات دعم الأُطُر الجديدة بناءً على تبني المجتمع. للأُطُر التي لديها مجتمعات كبيرة، أضفنا الدعم خلال 2-4 أسابيع تاريخياً. في هذه الأثناء، يعمل مسار المحول المستقل لأي إطار كحل مؤقت.

هل يتم تحديث محولات الأُطُر عند تحديث الإطار نفسه؟

نعم. عندما يصدر QBCore أو ESX تغييرًا جوهريًا، نقوم بدفع تحديثات المحول خلال أيام من إصدار الإطار. يتلقى المشتركون النشطون إشعارات التحديث عبر Tebex. هذا جزء من سبب وجود نموذج الاشتراك، صيانة المحول عمل مستمر، وليس تكلفة لمرة واحدة.

ملخص المتطلبات لكل إطار عمل

• QBCore، أي إصدار حديث من QBCore. الكشف التلقائي، بدون تكوين للإعدادات القياسية.
• ESX ، ESX Legacy 1.7+ أو ESX الرئيسي. قم بتعيين علم legacy للإصدارات الأقدم.
• مستقل، تنفيذ 4-8 وظائف لكل سكربت في config.lua. إعداد لمرة واحدة، قابل لإعادة الاستخدام عبر سكربتات Agency.
• جميع الإعدادات، حساب cfx.re مع ترخيص صالح، خادم FiveM مع Artifacts 5181 أو أعلى موصى به.