التكاملات

يمكن ربط cxg-tattoos بأطر عمل مختلفة لتحصيل ثمن المشتريات والتحقق من أذونات الإدارة. يعيد تكامل المظهر تطبيق الوشوم المحفوظة عند تحميل الشخصية أو تغيير مظهرها. يُضبط كل جزء على حدة.

راجع أيضًا المقدمة والتثبيت والإعداد والكتالوج والواجهة.

أطر العمل المتاحة

النظام	معرّف الإعداد	المورد الافتراضي	المدفوعات	الأذونات
Qbox	`qbx`	`qbx_core`	نعم	نعم
QBCore	`qbcore`	`qb-core`	نعم	نعم
ESX	`esx`	`es_extended`	نعم	نعم
من دون إطار عمل	`standalone`	لا ينطبق	عملية استدعاء مخصصة أو مشتريات مجانية	ACE أو تحقق مخصص

باستخدام auto، يكتشف المورد Qbox أو QBCore أو ESX إذا كان أي منها قيد التشغيل؛ وإذا لم يجد أيًا منها، يستخدم standalone. يمكنك تحديد إطار العمل صراحةً إذا كان الخادم يشغّل عدة أطر عمل أو يستخدم اسم مورد مختلفًا:

الكود

Config.Purchases.framework = 'qbx' -- auto | qbx | qbcore | esx | standalone
Config.Purchases.resources.qbx = 'qbx_core'
Config.Purchases.accounts = { 'cash', 'bank' }
Config.Purchases.esxAccountMap.cash = 'money'
Config.Purchases.esxAccountMap.bank = 'bank'
Config.Purchases.allowFreePurchases = false

تُجرّب الحسابات بالترتيب المحدد. يُخصم المبلغ من حساب واحد فقط؛ وإذا لم يكفِ رصيده، يُجرّب الحساب التالي. وفي ESX، يحوّل esxAccountMap اسم cash إلى اسم الحساب money.

يحدد Config.Purchases.reason وrefundReason سبب الحركات لدى موفّري الخدمات الذين يدعمون ذلك. وقيمتاهما الأوليتان هما tattoo-purchase وtattoo-purchase-refund. يتيح allowFreePurchases تخطي الخصم في محوّل standalone؛ لكنه لا يجعل المشتريات مجانية في أطر العمل الأخرى.

المدفوعات من دون إطار عمل

في وضع standalone، اربط tryCharge وrefund بمورد الاقتصاد في خادمك. يلزم كلا الإجرائين لقبول المشتريات: فإجراء الاسترداد يعيد المبلغ إذا فشل حفظ الوشم.

الكود

Config.Purchases.framework = 'standalone'
Config.Purchases.standalone.tryCharge = function(source, totalAmount, context)
    -- Sustituye esta llamada por la API de economía de tu servidor.
    local charged, receipt = MyEconomy.charge(source, totalAmount, context)
    if charged then
        return true, receipt
    end
    return false, 'No tienes saldo suficiente.'
end

Config.Purchases.standalone.refund = function(source, totalAmount, context, receiptData)
    -- Usa receiptData para devolver el mismo cobro aprobado.
    return MyEconomy.refund(source, totalAmount, receiptData) == true
end

يمثل MyEconomy واجهة الاقتصاد في خادمك؛ استبدله بالاسم والاستدعاءات الفعلية. للسماح عمدًا بالمشتريات المجانية، اضبط allowFreePurchases = true.

توفر محوّلات الدفع isAvailable(settings) وcharge(source, amount, context, settings) وrefund(source, amount, context, settings). يجب حفظ إيصال الدفع المعتمد في context.paymentReceipt؛ ويستخدمه cxg-tattoos لإرسال أي استرداد إلى نظام الدفع نفسه. أما عند استخدام اقتصاد خاص، فإجراءا tryCharge وrefund في standalone هما طريقة الإعداد المباشر.

أذونات الإدارة

يتحقق الخادم من الأذونات قبل فتح لوحة الإدارة واستخدامها. إخفاء واجهة العميل أو تعديلها لا يمنح صلاحية الوصول.

يستخدم الإعداد الأولي إطار العمل المكتشف وACE كخيار احتياطي:

الكود

Config.Permissions = {
    framework = 'auto', -- auto | qbx | qbcore | esx | standalone
    mode = 'hybrid',    -- framework | ace | hybrid | custom
    acePrefix = 'cxg-tattoos.',
    resources = {
        qbx = 'qbx_core',
        qbcore = 'qb-core',
        esx = 'es_extended',
    },
    bindings = {
        admin = {
            ace = { 'cxg-tattoos.admin', 'group.admin', 'admin' },
            qbx = { 'god', 'admin', 'group.admin' },
            qbcore = { 'god', 'admin', 'group.admin' },
            esx = { 'superadmin', 'admin' },
        },
    },
}

يستعلم الوضع framework عن أدوار إطار العمل. ويستخدم الوضع ace إدخالات ACE في ربط الصلاحية. أما hybrid فيقبل أيًا من المسارين. في وضع standalone، لا يتوفر التحقق عبر إطار العمل؛ لذا اضبط ACE أو أضف تحققًا مخصصًا.

على سبيل المثال، للسماح لأعضاء principal ACE group.admin:

الكود

add_ace group.admin cxg-tattoos.admin allow

لتفويض قرار الصلاحية إلى نظامك، استخدم mode = 'custom'. يتلقى الإجراء الراجع معرّف اللاعب والصلاحية وسياق العملية وربط الصلاحية المضبوط؛ ولا يمنح الإذن إلا إذا أعاد القيمة المنطقية true:

الكود

Config.Permissions.mode = 'custom'
Config.Permissions.custom = {
    hasPermission = function(source, permission, context, binding)
        return exports.my_permissions:hasPermission(source, permission) == true
    end,
}

كيّف my_permissions مع واجهة النظام المثبت في خادمك. إذا لم يكن الإجراء الراجع موجودًا، أو أخفق، أو أعاد قيمة أخرى، فسيُرفض الوصول.

يمكن أيضًا ضبط الأمر الذي يفتح اللوحة. يجب أن تطابق permission مفتاحًا في Config.Permissions.bindings:

الكود

Config.AdminCommand.enabled = true
Config.AdminCommand.name = 'tattooadmin'
Config.AdminCommand.permission = 'admin'

بهذه القيم، تحمي صلاحية admin الأمر /tattooadmin والإجراءات الإدارية. اضبط enabled = false لتعطيل الأمر؛ وسيظل التحقق من الصلاحية قائمًا في مسارات الإدارة الأخرى.

ملفات التكامل القابلة للتحرير

تجمع الجسور القابلة للتحرير الاتصالات بالأنظمة الخارجية. لإعداد إذن أو عملية دفع مخصصة، يُفضّل ضبط عمليات الاستدعاء الموضحة أعلاه. وإذا كنت ستكيّف جسرًا موجودًا، فحافظ على عقده:

الملف أو المجموعة	الاستخدام	عقد المحوّل
`bridge/permissions/server.lua`	اختيار إطار العمل وتطبيق الوضع `framework` أو `ace` أو `hybrid` أو `custom`	تعيد `TattooPermissions.Has(source, permission, context)` القيمة `true` عند السماح فقط
`bridge/permissions/registry.lua`	التسجيل وأدوات الأذونات المشتركة	`TattooPermissionBridge.register(name, adapter)`
`bridge/permissions/qbx.lua`, `qbcore.lua`, `esx.lua`, `standalone.lua`	عمليات التحقق لكل إطار عمل أو لوضع عدم استخدام إطار عمل	`isAvailable(settings)` و`hasPermission(source, binding, settings, permission)`؛ ويقبل `context` إضافيًا عند تكييفه
`bridge/payments/server.lua`	اختيار الموفّر والتحصيل والاسترداد	`Config.TryChargePlayer(source, totalAmount, context)` و`Config.RefundPlayer(source, totalAmount, context)`
`bridge/payments/registry.lua`	التسجيل وأدوات الدفع المشتركة	`TattooPaymentBridge.register(name, adapter)` وأدوات الإيصالات
`bridge/payments/qbx.lua`, `qbcore.lua`, `esx.lua`, `standalone.lua`	عمليات الدفع حسب إطار العمل أو عبر عمليات استدعاء مخصصة	`isAvailable(settings)` و`charge(...)` و`refund(...)`
`bridge/appearance.lua`	أحداث تحميل المظهر وطلب الوشوم المحفوظة	يطلب قائمة وشوم الشخصية ويعيد تطبيقها بعد اكتمال تحميل المظهر

يتلقى إجراء التحقق من الإذن أيضًا context وسيطًا خامسًا عند استدعائه من الجسر. يتضمن السجل الموفّرين المرفقين (qbx وqbcore وesx وstandalone)؛ ولا تتطلب الخيارات المخصصة إضافة موفّر آخر.

في محوّل الدفع، احتفظ بتسجيل الإيصال باستخدام TattooPaymentBridge.setReceipt(context, provider, account, amount, identifier, data). يجب أن يتحقق الاسترداد من الموفّر نفسه والمبلغ نفسه باستخدام getReceipt(context, provider, amount)، وأن يضع علامة على الإيصال بأنه مسترد بعد تأكيد الاسترداد. كيّف ملف الموفّر الذي تستخدمه بالفعل؛ ولإضافة تكامل خاص من دون تغيير المحوّلات، استخدم عمليات استدعاء standalone.

المظهر وتحميل الشخصية

يستمع المورد إلى الأحداث المعتادة في illenium-appearance وfivem-appearance وQBCore وESX وspawnmanager؛ ثم يستعيد الوشوم المحفوظة ويعيد تطبيقها. وفي Qbox، يستخدم إعداد معاينة تعدد الشخصيات playerskins.skin لعرض الوشوم المحفوظة عند اختيار الشخصية.

إذا كان نظام المظهر لديك يستخدم حدثًا مختلفًا، فاطلب تطبيق الوشوم بعد اكتمال تحميل المظهر:

الكود

TriggerServerEvent('cxg-tattoos:fetchMyTattoos')

يعيد الحدث إلى العميل وشوم الشخصية الحالية. لا ترسل القائمة من مصدر يختاره اللاعب؛ إذ تُحل الملكية ويجري التحقق منها على الخادم.

تُضبط معاينة تعدد الشخصيات في Qbox بهذه الحقول:

الكود

Config.QbxMulticharacterPreview.enabled = true
Config.QbxMulticharacterPreview.resource = 'qbx_core'
Config.QbxMulticharacterPreview.playerskinsTable = 'playerskins'
Config.QbxMulticharacterPreview.playersTable = 'players'
Config.QbxMulticharacterPreview.syncExistingOnStart = true

يفعّل enabled التكامل؛ ويحدد resource اسم Qbox المثبت. ويحدّد playerskinsTable وplayersTable جدولي المظهر والشخصيات المستخدمين في ذلك التثبيت. يتيح syncExistingOnStart مزامنة الوشوم المحفوظة مسبقًا عند بدء cxg-tattoos، لتظهر أيضًا في شاشة اختيار الشخصية المتعددة. إذا غيّر خادمك اسمي الجدولين، فحدّث هذين الحقلين. لا حاجة إلى تعديل qbx_core.