---
type: reference
title: مرجع مخطّط التخصيص
summary: نموذج نوع الحقل والتهيئة المشترك خلف كل سطح قابل للتخصيص، وأنواع الحقول التي يسمح بها كل محور، والقيم التي يقبلها كلٌّ، وكيف تُعرَّف المخطّطات والتهيئات وتُحلّ.
---

هذا المرجع الوحيد لـ**نموذج نوع الحقل والتهيئة** في Caputchin، الأساس المشترك تحت كل سطح قابل للتخصيص:

- [تخصيص اللعبة](/docs/game-customization/overview): لغة لعبة المتجر ومظهرها وإعدادها.
- [مخطّطات اللعبة المخصّصة](/docs/custom-game-development/dashboard-schema): المخطّط الذي تؤلّفه بنفسك للعبة مخصّصة.
- [بيانات لعبة المتجر](/docs/marketplace-game-development/the-caputchin-json-manifest): كتل `locales` / `skins` / `configurations` التي يعلنها مؤلّف لعبة.
- [تبييض علامة الأداة](/docs/widget-customization/white-label): المخطّط المدمج لغلاف الأداة.

الأربعة جميعًا تستخدم أنواع الحقول نفسها ونموذج التهيئة نفسه الموصوف هنا. يُبنى التخصيص من **تهيئات**، والتهيئة كيس **حقول** مكتوبة الأنواع.

## أنواع الحقول حسب المحور

كل محور يسمح بمجموعة ثابتة من أنواع الحقول:

| المحور | أنواع الحقول المسموحة |
|---|---|
| الإعداد | `boolean`، و`number`، و`range`، و`list`، و`string`، و`link` |
| اللغة | `string` فقط |
| المظهر | `color`، و`image`، و`audio`، و`video`، و`boolean`، و`number`، و`range`، و`list` |

المظهر ليس ألوانًا وأصولًا فقط: يستطيع أيضًا كشف المقابض القياسية `boolean`،
و`number`، و`range`، و`list` (مبدّل "ظلال"، وعدد نصف-قطر-الزاوية، وخيار "نمط").
تتصرّف هذه تمامًا كنظائرها في الإعداد وتُحلّ إلى قيمتها المكتوبة النوع (الـ
`boolean` يبقى `true`، والـ `number` يبقى `8`)؛ وقيم `color` والأصول تُحلّ إلى نصوص.
المظهر لا يسمح بـ `string` أو `link` (النصّ الحرّ ينتمي للّغة؛ وهدف رابط
إعدادٌ).

## ما الذي يقبله كل نوع

| النوع | القيمة | القواعد |
|---|---|---|
| `string` | نصّ حرّ | أي نصّ. |
| `boolean` | مبدّل | `true` أو `false`. |
| `number` | عدد | أي عدد منتهٍ. |
| `range` | عدد محدود | عدد منتهٍ ضمن أدنى الحقل وأقصاه. الخطوة راحة منزلق؛ القيم خارج-الخطوة ما زالت مقبولة. |
| `list` | خيار واحد | يجب أن يكون أحد خيارات الحقل المدرَجة. |
| `link` | رابط | رابط `http` أو `https`. الاعتمادات المضمَّنة مرفوضة. |
| `color` | لون | لون ست عشري (`#rgb`، أو `#rgba`، أو `#rrggbb`، أو `#rrggbbaa`) أو قيمة `rgb()` / `rgba()`. الألوان المسمّاة ومساحات الألوان الأخرى غير مقبولة. |
| `image` | صورة | ملفّ مرفوع أو رابط `https` ينتهي بـ `.png`، أو `.jpg`، أو `.jpeg`، أو `.webp`، أو `.svg`، أو `.gif`. |
| `audio` | مقطع صوتيّ | ملفّ مرفوع أو رابط `https` ينتهي بـ `.mp3`، أو `.ogg`، أو `.wav`. |
| `video` | فيديو | ملفّ مرفوع أو رابط `https` ينتهي بـ `.mp4` أو `.webm`. |

يتحقّق Caputchin من كل قيمة حين تحفظ، فقيمة لا تناسب نوعها تُرفَض قبل أن تبلغ زائرًا.

## المفاتيح المحجوزة

إلى جانب حقول محتواها، تحمل التهيئة بضعة **مفاتيح بيانات وصفية** محجوزة (كلٌّ مسبوق بشرطة سفلية) تتحكّم بكيف تُختار وتُحلّ، لا بما تعرضه. كيف تضبطها يعتمد على السطح: [مؤلّف لعبة المتجر](/docs/marketplace-game-development/the-caputchin-json-manifest) يكتبها حرفيًّا في `caputchin.json`؛ وفي محرّر لوحة التحكّم (الألعاب المخصّصة، والعلامة البيضاء) تضبطها عبر ضوابط ولا تكتب المفتاح أبدًا. في الحالتين المعنى نفسه.

| المفتاح | المحور | المعنى |
|---|---|---|
| `_lang` | اللغة | وسم لغة BCP-47 الذي تخدمه تهيئة لغة (`en`، و`es`، وهكذا). تُجمَّع التهيئات به؛ وقد تتشارك عدّة تهيئات `_lang` واحدًا (مثلًا متغيّرا إنجليزية). |
| `_direction` | اللغة | `ltr` أو `rtl`. اختياري، مشتقّ تلقائيًّا من `_lang` للغات من اليمين إلى اليسار (`ar`، و`he`، و`fa`، و`ur`، و`yi`، و`ps`، و`sd`)؛ نادرًا ما يُضبَط يدويًّا. |
| `_theme` | المظهر | `light`، أو `dark`، أو `any`. تهيئة `light` / `dark` تظهر تحت تلك الخلفية فقط؛ وتهيئة `any` تعمل تحت كليهما ومؤهَّلة لأيٍّ. الافتراضي `light` عند الغياب. |
| `_default` | الكلّ | تَسِم التهيئة التي يختارها الخادم لمجموعتها حين لا يختار الزائر واحدة. افتراضي واحد لكل مجموعة (لكل وضع للمظهر)؛ ويمكن لمظهر `any` أن يكون الافتراضي للفاتح، أو الداكن، أو كليهما. |
| `_extends` | الكلّ | يسمّي تهيئة أخرى للوراثة منها. انظر [توسيع تهيئة](#extending-a-preset). |

مفاتيح البيانات الوصفية المحجوزة **تُزال أثناء الحلّ**: `_extends` و`_default` لا تبلغان اللعبة أبدًا، ولا يُسلَّم سوى البيانات الناجية (`_lang`، و`_direction`، و`_theme`) إضافةً إلى حقول المحتوى المسطّحة.

## توسيع تهيئة [#extending-a-preset]

`_extends` يتيح لتهيئة وراثة كل قيمة من أخرى، فتؤلّف الحقول المختلفة فقط بدل تكرار تهيئة كاملة. اضبط `_extends` على **اسم تهيئة أخرى في المحور نفسه**؛ تبدأ التهيئة الموسِّعة من كل قيم تلك التهيئة وتتجاوز المفاتيح التي تضبطها بنفسها.

```json
{
  "skins": {
    "presets": {
      "brand-light": { "_theme": "light", "accent": "#2da44e", "bg": "#ffffff" },
      "brand-light-warm": { "_extends": "brand-light", "accent": "#d97706" }
    }
  }
}
```

هنا `brand-light-warm` يرث `bg` من `brand-light` ويغيّر `accent` فقط.

تفصيلان:

- **اختصار سمة المظهر.** على تهيئة مظهر، يستطيع `_extends` بدلًا تسمية سمة (`light` أو `dark`) لا تهيئة. ذلك الشكل يُحلّ إلى أيّ تهيئة هي `_default` لتلك السمة، طريقة مريحة لتأسيس متغيّر على "المظهر الفاتح الافتراضي" دون تسميته.
- **يُحلّ بعيدًا.** يُتبَع `_extends` ثم يُزال؛ تستقبل اللعبة النتيجة المدموجة كليًّا، لا مفتاح `_extends` نفسه أبدًا.

## من أين يأتي مخطّط

مجموعة الحقول التي تستطيع تهيئة ملؤها (**مخطّطها**) لها ثلاثة مصادر، كلها تستخدم أنواع الحقول نفسها أعلاه:

- **لعبة المتجر**: يأتي المخطّط من بيان مؤلّف اللعبة، مجلوبًا حين تفتح المحرّر. تتجاوز تهيئات اللعبة لكن لا تغيّر مخطّطها.
- **لعبة مخصّصة**: تعرّف المخطّط بنفسك في لوحة التحكّم، ثم تؤلّف تهيئات مقابله. انظر [الألعاب المخصّصة](/docs/game-customization/custom-games).
- **غلاف الأداة (العلامة البيضاء)**: مخطّط ثابت مدمج. تتجاوز تهيئاته؛ مجموعة الحقول ليست مُعلَنة من المؤلّف. انظر [بيّض علامة الأداة](/docs/widget-customization/white-label).

## التهيئات والحلّ

داخل محور، تُجمَّع الحقول في تهيئات مسمّاة، ويحلّ الخادم تهيئةً فعّالةً واحدةً لكل مجموعة من النطاقات المطبَّقة، مفتاح الموقع فوق الفريق فوق الافتراضي المضمَّن، محسوبًا لكل قيمة. المختارات تختلف بالمحور: اللغة تُختار بلغة متصفّح الزائر، والمظهر بتفضيل الزائر الفاتح أو الداكن (تهيئة وضعها `any` مؤهَّلة لأيٍّ)، والإعداد موثوق من الخادم (لا يستطيع الزائر اختياره). انظر [النظرة العامة](/docs/game-customization/overview#troop-and-site-key-scope) لنموذج النطاق.

## انظر أيضًا

- [نظرة عامة على تخصيص اللعبة](/docs/game-customization/overview): تسجيل الألعاب وإدارتها، إضافةً إلى أدلّة كل محور لـ [الإعدادات](/docs/game-customization/configurations)، و[اللغة](/docs/game-customization/locale)، و[المظهر](/docs/game-customization/skin).
- [مخطّط لوحة التحكّم للعبة مخصّصة](/docs/custom-game-development/dashboard-schema): تأليف مخطّط بنفسك للعبة مخصّصة.
- [بيان caputchin.json](/docs/marketplace-game-development/the-caputchin-json-manifest): إعلان هذه الكتل كمؤلّف لعبة المتجر.
- [بيّض علامة الأداة](/docs/widget-customization/white-label): الأنواع نفسها مطبَّقةً على غلاف الأداة.