# كتالوج الوشوم

يجمع الكتالوج وشوم CXG Base والحزم التي ثبتّها. الحزم الخارجية اختيارية؛ يمكنك تفعيل أي عدد منها. إذا كانت إحدى الحزم غير موجودة أو متوقفة، تُخفى وشومها من المتجر، بينما يظل كتالوج CXG Base متاحًا.

راجع أيضًا [المقدمة](https://docs.cxgstudios.com/docs/ar/01-cxg-tattoos/01-introduccion.md) و[التثبيت](https://docs.cxgstudios.com/docs/ar/01-cxg-tattoos/02-instalacion.md) و[الإعداد](https://docs.cxgstudios.com/docs/ar/01-cxg-tattoos/03-configuracion.md) و[التكاملات](https://docs.cxgstudios.com/docs/ar/01-cxg-tattoos/05-integraciones.md) و[الواجهة](https://docs.cxgstudios.com/docs/ar/01-cxg-tattoos/06-interfaz.md).

## الحزم الاختيارية

يتضمن الإعداد الأولي المصادر الاختيارية التالية:

| المعرّف | المورد | ملف الكتالوج |
| --- | --- | --- |
| `xgc-classic` | `xgc_TattooClasic` | `tatoo_clasic_full_packconfigdump.json` |
| `xgc-gangs` | `xgc_TattooGangs` | `gangs_full_packconfigdump.json` |
| `xgc-japanese-mafia` | `xgc_TattooJapaneseMafia` | `japanese_mafia_full_packconfigdump.json` |
| `xgc-police` | `xgc_TattooPolice` | `police_full_packconfigdump.json` |
| `xgc-world-countries` | `xgc_TattooWorldCountries` | `world_country_full_packconfigdump.json` |
| `cxg-blackout` | `CXGtatoo_balckout` | `blackout_full_packconfigdump.json` |

ثبّت الحزم التي تملكها فقط وشغّلها قبل `cxg-tattoos`. أبقِ اسم المورد ومساره كما هما في خادمك، مع مراعاة الأحرف الكبيرة والصغيرة. لإخفاء مصدر مؤقتًا، غيّر `enabled` فيه إلى `false`؛ ولإظهاره مجددًا، اجعله `true` وتأكد من تشغيل المورد.

يستخدم CXG Base الملف `shared/tattoos.json` الموجود داخل المورد. ويحصل المصدر `native-game` على التصاميم من وشوم اللعبة الأصلية، ويكون معطلًا افتراضيًا. لاستخدامه، اضبط أيضًا مصادر التحقق في `native.serverMetas` بحسب الموارد والملفات الفعلية في خادمك. يشير المدخل في المثال إلى `tatto` و`shop_tattoo.meta`؛ ولا يفترض أن هذا المورد مثبت. تفعيل `enabled` وحده لا يضمن إمكانية شراء تلك التصاميم.

## إضافة مصدر JSON

يضبط كل عنصر من `Config.TattooCatalog.sources` مصدرًا واحدًا. يتبع هذا المثال بنية موارد الحزم، ويمكن تكييفه باستخدام اسم المورد وملفه الفعليين:

```lua
{
    id = 'mi-pack',
    label = 'Mi Pack',
    color = '#62b6cb',
    enabled = true,
    resource = 'mi_pack',
    path = 'tattoos.json',
    thumbnailPattern = 'miniatures/{Name}.webp',
    root = { mode = 'auto', field = 'Overlays' },
    defaults = {
        collection = 'mi_pack_overlays',
        zone = 'ZONE_TORSO',
        price = 5000,
        requiredLevel = 1,
        overlayTarget = 'male',
    },
}
```

يجب أن يعرّف `id` المصدر بمعرّف ثابت؛ ويُستخدم `label` و`color` للتعرف إليه في الواجهة. يشير `resource` و`path` إلى ملف JSON. يجب أن يكون الملف داخل مورد متاح. لا تضف التصميم نفسه في مصدرين إلا إذا أردت ظهوره مرتين؛ إذ يتيح `deduplicateAcrossSources` إزالة التكرار بين المصادر.

توجد هذه الإعدادات العامة في `Config.TattooCatalog`:

| الحقل | القيمة الأولية | الاستخدام |
| --- | --- | --- |
| `deduplicate` | `true` | يزيل التصاميم المكررة داخل المصدر الواحد. |
| `deduplicateAcrossSources` | `false` | يتيح إبقاء التصاميم من المصادر المختلفة منفصلة. |
| `serverFallback` | `true` | يطلب من الخادم مصدرًا لا يستطيع العميل قراءته. |
| `serverFallbackTimeoutMs` | `7000` | أقصى مهلة انتظار لذلك الطلب، بالمللي ثانية. |

لا يجعل الرجوع إلى الخادم للقراءة حزمة متوقفة متاحة.

## تنسيق كل وشم

يمكن أن يكون الملف مصفوفة JSON أو كائنًا تحتوي إحدى خصائصه على المصفوفة. مع `root.mode = 'auto'`، يقبل القارئ كلا التنسيقين؛ ومع `root.mode = 'field'`، يحدد `root.field` موضع القائمة. أما `root.mode = 'array'` فيفرض وجود مصفوفة في جذر الملف.

تعرض هذه المصفوفة تنسيق JSON. مجموعة الوشوم وقيم التجزئة في المثال وهمية؛ استبدلها بالأسماء الفعلية في الحزمة المثبتة. إضافة مدخل إلى JSON لا تثبّت طبقات الرسومات.

```json
[
  {
    "Collection": "mi_pack_overlays",
    "Name": "Rosa del desierto",
    "HashNameMale": "MP_MI_PACK_ROSE_M",
    "HashNameFemale": "MP_MI_PACK_ROSE_F",
    "Zone": "ZONE_TORSO",
    "Price": 5000,
    "Xp": 15,
    "RequiredLevel": 2
  }
]
```

يلزم وجود `Collection` وقيمة تجزئة واحدة على الأقل للطبقة للتعرف على التصميم. أدرج `HashNameMale` و`HashNameFemale` إذا كان للوشم متغير لكل شخصية. استخدم إحدى هذه المناطق: `ZONE_HEAD` أو `ZONE_TORSO` أو `ZONE_LEFT_ARM` أو `ZONE_RIGHT_ARM` أو `ZONE_LEFT_LEG` أو `ZONE_RIGHT_LEG`. الاسم الذي يراه المشتري هو `Name`. إذا حذفت `Price`، يُستخدم السعر الافتراضي للمصدر؛ وإذا حذفت `RequiredLevel`، تُستخدم قيمة `defaults.requiredLevel`، وقيمتها الأولية 1. ويمكن تحديد XP في الوشم أو إعداد المستويات.

للملفات التي تستخدم أسماء حقول أخرى، عدّل `fields` في `Config.TattooCatalog`. كل عنصر في هذا الجدول قائمة من الأسماء البديلة التي يجري فحصها للعثور على القيمة المناسبة. على سبيل المثال، يمكن تعيين ملف يستخدم `OverlayHash` و`Cost` و`BodyZone` كما يلي:

```lua
fields = {
    collection = { 'Collection', 'CollectionName' },
    name = { 'Name', 'DisplayName' },
    overlay = { 'OverlayHash' },
    hashNameMale = { 'MaleOverlay' },
    hashNameFemale = { 'FemaleOverlay' },
    zone = { 'BodyZone' },
    price = { 'Cost' },
    xp = { 'Xp', 'Experience' },
    requiredLevel = { 'RequiredLevel' },
}
```

يمكنك أيضًا تعيين قيم مشتركة باستخدام `rootFields`، مثل اسم مجموعة أو منطقة محددة مرة واحدة في الكائن الجذر. وتُكمل `defaults` لكل مصدر القيم الناقصة. إذا احتوى JSON على حقل عام واحد، مثل `OverlayHash`، فإن `defaults.overlayTarget` يحدد هل يُعامل كوشم ذكوري (`male`) أم أنثوي (`female`).

يمكن تحويل التنسيقات المختلفة جدًا باستخدام الدالتين الاختياريتين `converters.decode(decoded, settings)` أو `converters.entry(entry, context)` ضمن الإعدادات. تكيّف الأولى المستند بأكمله؛ والثانية تكيّف كل تصميم. أعد جدولًا يحتوي على الحقول الجاهزة للتعيين المعتاد.

## الصور المصغرة

لاستخدام الصور الموجودة ضمن الحزمة نفسها، احتفظ بمجلد `miniatures/` في ذلك المورد وحدد نمطًا مثل:

```lua
thumbnailPattern = 'miniatures/{Name}.webp'
```

تُستبدل `{Name}` و`{HashNameMale}` و`{HashNameFemale}` و`{HashName}` ببيانات الوشم. يجب أن يكون الملف الناتج موجودًا داخل المورد، مثل `miniatures/Rosa del desierto.webp`، وأن يكون المورد قيد التشغيل. تطلب الواجهة كل صورة مصغرة عند الحاجة؛ فلا تنسخ الصور إلى حزمة CXG.

يمكنك أيضًا وضع `Thumbnail` أو `ThumbnailUrl` في أحد المدخلات لتحديد صورة بعينها. تُستخدم عناوين URL التي تبدأ بـ `http://` أو `https://` أو `data:` كما هي. يجب أن يتوافق مسار الصورة المصغرة المحلية للحزمة مع `thumbnailPattern`؛ كما يجب أن يكون الملف موجودًا وأن يستطيع المورد تقديمه إلى NUI. ينبغي أن تحتفظ الموارد الخارجية بملفاتها داخل الحزمة.

## التغييرات من الإعداد ومن لوحة الإدارة

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

تظل الوشوم التي اشتراها اللاعب مرتبطة بشخصيته حتى عند إيقاف الحزمة التي وفرتها مؤقتًا. ولن تظهر الحزمة في المتجر مجددًا إلا بعد أن تصبح متاحة.