---
type: reference
title: بيان caputchin.json
summary: كل حقل في بيان caputchin.json الذي يصف لعبة المتجر، وكتلة marketplace، ومؤشّرات التوزيع، وأداة إعادة تشغيل run، وكتل التهيئات، وملفّات .caputchin المقسّمة.
---

‏`caputchin.json` في جذر مستودعك هو مصدر حقيقة المؤلّف والمفهرِس للعبة المتجر. يقرؤه المفهرِس على الخادم ليعرف هويّة اللعبة، وأين تقيم حزمتها، وأيّ تهيئات تقدّم، وكيف يعيد تشغيلها. **لا** يُقرَأ في المتصفّح أبدًا؛ الـ SDK لا يحمّله وقت التشغيل.

هذه الصفحة مرجع الحقول. للبناء، انظر [ابنِ لعبة المتجر](/docs/marketplace-game-development/build-a-marketplace-game)؛ وللنشر، انظر [انشر إلى المتجر](/docs/marketplace-game-development/publish-to-the-marketplace). الأنواع الدقيقة مُصدَّرة من الـ SDK كـ `GameManifest` (انظر [مرجع الـ SDK](/docs/marketplace-game-development/game-sdk-reference)).

## لعبة واحدة دنيا

```json
{
  "terms_accepted": true,
  "license": "MIT",
  "marketplace": {
    "name": "Leaf Memory",
    "description": "Match pairs of tropical leaves before the timer runs out.",
    "preview": "preview.png"
  },
  "npm": "@your-org/leaf-memory",
  "entry": "dist/leaf-memory.js"
}
```

## الحقول الأعلى

| الحقل | مطلوب | الغرض |
|---|---|---|
| `terms_accepted` | للفهرسة | يجب أن يكون `true` الحرفي لتأكيد قبولك [شروط تقديم المتجر](/legal/submission-terms). أي قيمة أخرى (أو غياب) تُسقط البيان من الفهرس. البيانات المستضافة-ذاتيًّا-فقط قد تحذفه. |
| `license` | للفهرسة | معرّف أو تعبير SPDX يغطّي كودك وأصولك المضمَّنة. يجب أن يقيّم إلى معرّف موافَق عليه (انظر [مرجع أخطاء النشر](/docs/marketplace-game-development/publish-failed-reference#approved-licenses)). |
| `marketplace` | للفهرسة | وجوده هو إشارة "افهرسني". غيابه يعني لعبة [مستضافة ذاتيًّا](/docs/custom-game-development/overview) صالحة يتجاهلها المتجر. انظر [كتلة marketplace](#the-marketplace-block). |
| `npm` | مع `entry` | إحداثي حزمة npm يحلّه المفهرِس إلى رابط jsDelivr. |
| `entry` | مع `npm` | مسار نسبيّ للمستودع إلى الحزمة المبنيّة. `entry`، أو `npm`، أو كلاهما يجب أن يوجد للعبة قابلة للتشغيل. |
| `games` | للمجموعات | مسارات بيانات فرعية لغلاف مجموعة. متنافٍ مع `entry` / `npm`. انظر [المجموعات](#collections). |
| `run` | اختياري | أداة إعادة تشغيل بلا واجهة مخصّصة. انظر [أداة run](#the-run-artifact). |
| `preferred` | اختياري | تلميحات عرض يحقّ للمضيف احترامها. انظر [كتلة preferred](#the-preferred-block). |
| `locales` / `skins` / `configurations` | اختياري | كتل تهيئات يستهلكها الـ SDK في الإطار. انظر [كتل التهيئات](#preset-blocks). |

لا حقل `version`: يثبّت المفهرِس الحزمة على مرجع غير قابل للتغيير بنفسه (نسخة npm المنشورة أو SHA الالتزام المحلول).

## كتلة marketplace [#the-marketplace-block]

| الحقل | الغرض |
|---|---|
| `name` | عنوان البطاقة. يرتدّ إلى اسم المستودع (واحدة / غلاف) أو اسم مجلّد الورقة (ابن مجموعة). |
| `description` | عنوان البطاقة الفرعي وجسم صفحة التفاصيل. |
| `preview` | مسار صورة (نسبيّ لجذر المستودع) أو رابط مطلق. نحو 600x315، الموضوع موسَّط. |
| `version` | سلسلة نسخة للعرض فقط لصفحة التفاصيل. اختيارية. |
| `support` | أعلام توافق يعلنها المؤلّف (`responsive`، و`touch`، و`accessible`، و`audio`، ...)، لا تتحقّق منها المنصّة أبدًا؛ تُعرَض كمرشّحات ورموز بطاقة. |
| `author` | اختياري `{ name?, url?, email? }`. `name` / `url` يُعرَضان كنسبة مؤلّف على صفحة التفاصيل؛ `email` لا يُعرَض أبدًا وهو **الاشتراك الطوعي** في [بريد إخفاق النشر](/docs/marketplace-game-development/publish-to-the-marketplace#get-notified-when-a-publish-fails). الحقول الفرعية الثلاثة مستقلّة. |

الكتلة اختيارية بالكامل. احذف `name` / `url` وتعرض صفحة التفاصيل ببساطة لا نسبة مؤلّف (مالك GitHub المعروض في مكان آخر على الصفحة هوية منفصلة حاضرة دائمًا، لا ارتداد لهذه النسبة). احذف `email` فلا تستقبل إشعارات إخفاق نشر. اضبط الحقول الفرعية التي تريدها فقط.

## مؤشّرات التوزيع

يثبّت المفهرِس حزمة كل لعبة على مرجع غير قابل للتغيير كي تبقى تجزئة السلامة المخزَّنة صالحة، ويعيد الحلّ في كل تشغيل (cron يوميّ إضافةً إلى "انشر أو حدّث" يدويًّا):

- `entry` + `npm` يُحلّان إلى `cdn.jsdelivr.net/npm/<npm>@<resolved-version>/<entry>`.
- `entry` وحده يُحلّ إلى `cdn.jsdelivr.net/gh/<owner>/<repo>@<commit-sha>/<entry>`.
- `npm` وحده يُحلّ إلى مدخل الحزمة الافتراضي عند النسخة المثبَّتة.

لا تثبيت نسخة من جانب المستخدم؛ لتجميد بناء، يستضيفه مستخدم ذاتيًّا عبر `game-src` الخاص بالأداة ([لعبة مخصّصة](/docs/custom-game-development/self-hosted-game)).

## أداة run [#the-run-artifact]

افتراضيًّا يشغّل الفحص الذاتي لإعادة التشغيل حزمة `entry` الحيّة خاصتك. حين تكون لعبتك كبيرةً أو قائمةً على إطار عمل أو WASM، اشحن أداة `run` بلا واجهة مخصّصة هزيلة بدلًا:

```json
{
  "run": {
    "entry": "dist/run.js",
    "modules": [
      { "name": "sim.wasm", "type": "wasm", "path": "dist/sim.wasm" }
    ]
  }
}
```

| الحقل | المعنى |
|---|---|
| `run.entry` | مسار نسبيّ للمستودع إلى حزمة `run` بلا واجهة (تصدير `run` بـ [عقد إعادة التشغيل](/docs/marketplace-game-development/replay-contract)). |
| `run.modules` | مصفوفة اختيارية من مدخلات الوحدات التي يستوردها run بـ `name`. |

### القيود التي يفرضها المفهرِس

تُتحقَّق وقت الفهرسة؛ ومخالفة تفشّل النشر بـ `manifest-error` (انظر [مرجع أخطاء النشر](/docs/marketplace-game-development/publish-failed-reference)).

**`run.entry`:**

- يجب أن يكون **JavaScript**: يجب أن يطابق الاسم الأساسي `[a-zA-Z0-9_-]+.js`. أداة run دائمًا JS (يُشحَن WASM كوحدة، أدناه).
- يجب أن يكون مسارًا نسبيًّا نظيفًا للمستودع: لا شرطة مائلة بادئة، ولا اجتياز `..`، ولا فراغ، ولا `?` / `#`، ولا بادئة `scheme://`.

**كل مدخل `run.modules[]`** هو `{ name, type, path }`:

- `name` يجب أن يطابق `[a-zA-Z0-9_-]+.(wasm|js)`، الوحدة إمّا **JS أو WASM**، لا شيء آخر. الـ `name` هو محدّد الاستيراد الذي يستخدمه المدخل.
- `type` يجب أن يتّفق مع الامتداد: `wasm` لاسم `.wasm`، و`js` لاسم `.js`.
- `name` يجب ألّا يكون اسمًا **محجوزًا** (`entry.js`، و`artifact.js`) يستخدمه مضيف إعادة التشغيل داخليًّا.
- `name` يجب أن يكون **فريدًا** داخل المصفوفة (لا تكرار).
- `path` يجب أن يكون مسارًا نسبيًّا نظيفًا للمستودع (القواعد نفسها كـ `run.entry`).
- **16** وحدة على الأكثر.

احذف `run` لإعادة تشغيل `entry` الحيّة مباشرةً. انظر [عقد إعادة التشغيل](/docs/marketplace-game-development/replay-contract) لما يجب أن تصدّره الأداة.

## كتلة preferred [#the-preferred-block]

كتلة `preferred` الاختيارية تحمل تلميحات عرض. كل مفتاح استشاريّ: يحقّ للمضيف احترامه، ولا يتجاوز أبدًا سمة تضمين صريحة.

```json
{
  "preferred": { "width": 360, "height": 480, "layout": "modal" }
}
```

لعبة متجاوبة ينبغي أن تمتدّ عبر حاويتها افتراضيًّا تستطيع إعلان `"full"` على أيّ محور:

```json
{
  "preferred": { "width": "full", "height": 480 }
}
```

| الحقل | المعنى |
|---|---|
| `width` / `height` | بصمة بكسلية، أو `"full"` الحرفي. تطبّقها الأداة حين يترك التضمين `width` / `height` غير مضبوط (قيمة تضمين صريحة، بما فيها `full`، تفوز بدلًا). قيمة بكسلية تحجّم الإطار إلى ذلك العدد؛ و`"full"` يمدّ ذلك المحور ليملأ الأب، الأثر نفسه الذي لتضمين `width="full"`. احذفه لترتدّ إلى بصمة الأداة الافتراضية المدمجة. |
| `layout` | الغلاف الذي تبنيه الأداة حول اللعبة: `inline`، أو `modal`، أو `fullscreen`. يُستخدَم فقط حين يترك التضمين `layout` غير مضبوط (افتراضيه `auto`). ترتيب الحلّ: سمة `layout` للتضمين، ثم هذا التخطيط المفضّل، ثم `inline`. |

تُحترَم هذه التلميحات فقط للألعاب التي تحلّها المنصّة على الخادم (ألعاب المتجر، أو معرّف لعبة مُعطًى بلا مفتاح موقع). حزمة `game-src` مستضافة ذاتيًّا لا تستطيع المنصّة قراءتها قبل التركيب تتجاهل البصمة وتلميح التخطيط معًا.

## كتل التهيئات [#preset-blocks]

`locales`، و`skins`، و`configurations` كلٌّ يعلن `schema` اختياريًّا (أنواع لكل مفتاح وتوثيق) إضافةً إلى `presets` (بنوك الخيارات المسمّاة). تحلّ الأداة خيار الزائر مقابلها وتسلّم لعبتك النتيجة المسطّحة كـ [`ctx`](/docs/marketplace-game-development/game-sdk-reference). كتالوج أنواع الحقول الكامل هو [مرجع مخطّط التخصيص](/docs/references/customization-schema) المشترك؛ الأنواع نفسها تقود [مخطّط لوحة التحكّم للعبة مخصّصة](/docs/custom-game-development/dashboard-schema).

حقل `skins.schema` قد يكون `color`، أو أصلًا (`image` / `audio` / `video`)، أو قياسيًّا (`boolean`، و`number`، و`range`، و`list`) مستخدمًا أشكال القيد نفسها كـ `configurations` (`{ "type": "range", "min": 0, "max": 24 }`، و`["dots","stripes"]`، وهكذا). قيم المظهر القياسية تُحلّ إلى قيمتها المكتوبة النوع في `ctx.skin` (الـ `number` عدد حقيقي)، تمامًا كقيمة إعداد؛ وقيم اللون والأصل تُحلّ إلى نصوص.

‏`_theme` تهيئة مظهر يعلن الوضع الذي تعمل فيه: `light`، أو `dark`، أو `any` (حذفه يعني `any`). تهيئة `light` أو `dark` تظهر في ذلك الوضع فقط؛ وتهيئة `any` تُقرَأ على أيّ خلفية ومؤهَّلة لكليهما. هناك افتراضي واحد لكل وضع. تهيئة موسومة `_default: true` هي الافتراضية للوضع/الأوضاع التي هي مؤهَّلة لها، فافتراضي `any` يغطّي كليهما؛ وحين تُوسَم عدّة تهيئات مؤهَّلة افتراضيةً لوضع، تفوز به الأولى بترتيب الإعلان. ضع تهيئةً خاصةً بوضع فوق تهيئة `any` لإعطاء ذلك الوضع مظهرًا مخصّصًا بينما تسقط تهيئة `any` إلى الآخر.

## ملفّات `.caputchin/` المقسّمة

كتل التهيئات (خصوصًا مجموعات اللغات الكاملة) تجعل `caputchin.json` طويلًا. انقل أي محور إلى ملفّه الخاص تحت مجلّد `.caputchin/`، تاركًا البيان قصيرًا:

```
caputchin.json
.caputchin/locales.json
.caputchin/skins.json
.caputchin/configurations.json
```

الكائن الأعلى لكل ملفّ **هو** كتلة ذلك المحور (`{ schema?, presets }`). الثلاثة اختيارية. الأسبقية استبدال للمحور كله، `caputchin.json` يفوز: إن أُعلِن محور مضمَّنًا وكملفّ معًا، تُستخدَم الكتلة المضمَّنة ويُتجاهَل الملفّ (النشر ينبّه كي تعرف أنه ميّت). أبقِ كل محور في مكان واحد بالضبط.

## المجموعات [#collections]

يستطيع مستودع شحن عدّة ألعاب. غلاف مجموعة يعلن مسارات أبناء بدل `entry` / `npm`:

```json
{
  "marketplace": { "name": "Caputchin Core Pack", "description": "The official pack." },
  "games": ["./packages/leaf-memory", "./packages/dino-runner"]
}
```

كل مسار يشير إلى مجلّد ابن يحمل `caputchin.json` الخاص. معرّفات الأبناء هي `owner/repo/<leaf-dir>`. احذف كتلة `marketplace` للغلاف لفهرسة الأبناء بلا صفحة مجموعة.

## انظر أيضًا

- [ابنِ لعبة المتجر](/docs/marketplace-game-development/build-a-marketplace-game): إنتاج الحزمة التي يشير إليها هذا البيان.
- [عقد إعادة التشغيل](/docs/marketplace-game-development/replay-contract): ما يجب أن تصدّره أداة `run`.
- [مرجع أخطاء النشر](/docs/marketplace-game-development/publish-failed-reference): كل خطأ تحقّق بيان وقائمة الرخص الموافَق عليها.
- [مرجع مخطّط التخصيص](/docs/references/customization-schema): أنواع الحقول التي تستخدمها كتل التهيئات.