# catalogue.json: البيانات الوصفية لألعاب PlayDrop والترجمة

مرجع لعناوين الألعاب وأوصافها ووسوم النوع وصور الصفحة وفيديوهاتها والترجمات وحقل server الاختياري بصيغة PlayDrop Connector.

Source: https://www.playdrop.ai/ar/create/learn/catalogue-json

يرسل [PlayDrop Connector](https://www.playdrop.ai/ar/create/connectors) بياناتك الوصفية `catalogue.json` مع ملفات اللعبة؛ ولا حاجة إلى أداة سطر أوامر. يتولى PlayDrop Cloud صيانة هذه البيانات لألعاب Studio.

## رفع خاص كامل باستخدام prepare_catalogue_upload

هذا طلب `prepare_catalogue_upload` كامل للعبة خاصة جديدة. استبدل مثال HTML بلعبتك المبنية واستخدم `requestId` فريدًا لكل عملية رفع مقصودة. الكائن `catalogue` هو محتوى `catalogue.json`؛ أما `files` و`expectedCurrentVersion` فتنتميان إلى طلب الأداة، خارج ذلك الكائن.

```json
{
  "requestId": "my-game-v1-unique-request",
  "catalogue": {
    "apps": [
      {
        "name": "my-game",
        "displayName": "My Game",
        "file": "index.html",
        "version": "1.0.0",
        "visibility": "PRIVATE",
        "authMode": "OPTIONAL",
        "surfaceTargets": {
          "desktop": true,
          "mobileLandscape": false,
          "mobilePortrait": false
        }
      }
    ]
  },
  "expectedCurrentVersion": {
    "my-game": null
  },
  "files": [
    {
      "path": "index.html",
      "text": "<!doctype html><html><head><title>My Game</title></head><body><button onclick=\"this.textContent=Number(this.textContent)+1\">0</button></body></html>"
    }
  ]
}
```

يجب أن يطابق `apps[].file` تمامًا أحد قيم `files[].path`. وإذا حُذف `file`، فالقيمة الافتراضية للمدخل هي `<name>.html`، لا `index.html`. `surfaceTargets` كائن يضم القيم المنطقية `desktop` و`mobileLandscape` و`mobilePortrait`؛ فعّل واجهة واحدة على الأقل جرّبتها. صرّح بالإصدار والظهور صراحةً. يستخدم المثال ملفًا نصيًا مضمّنًا؛ ويمكن للمرفقات أو عمليات رفع البايتات الموقّعة استخدام المسار نفسه.

بعد التحضير، أرسل بايتات أي ملفات مطلوبة واستدعِ `complete_catalogue_upload` بـ `requestId` نفسه. افتح الإصدار الخاص لتجربته. للتحديث، اقرأ `list_games`، وأبقِ `name` نفسه، وقدّم `version` جديدًا ولقطة كاملة، وعيّن `expectedCurrentVersion[name]` إلى الإصدار العام الحالي الذي أعاده الخادم (أو `null` إن لم يوجد). فهو فحص تعارض، وليس الإصدار الذي ترفعه. أعد محاولة عمليات الرفع المنقطعة بمعرّف الطلب الأصلي. انشر الإصدار المحتفظ به الذي جرّبته بـ `publish_game_version` عندما تكون جاهزًا.

## مثال التوافق القديم للعبة واحدة

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

أبقِ slug بالأحرف الصغيرة ثابتًا عند التحديث. أضف عنوانًا معروضًا ووصفًا دقيقًا وأدوات التحكم ولغة المصدر والوسوم المعروفة عند الحاجة. يستخدم المثال أدناه وسم نوع المنصّات الموجود.

```json
{
  "apps": [{
    "name": "moon-jump",
    "displayName": "Moon Jump",
    "description": "Jump between lunar platforms and reach the finish.",
    "controls": "Arrow keys to move. Space to jump.",
    "sourceLocale": "en",
    "tags": ["game-genre/platformer"]
  }]
}
```

## الحقول المدعومة والحدود

`name`: من 1 إلى 100 حرف صغير أو رقم أو شرطة، تبدأ بحرف أو رقم. `displayName`: عنوان غير فارغ. `subtitle`: حتى 120 حرفًا. `description`: حتى 3,000 حرف من Markdown، بلا عناوين H1 أو وسائط مضمّنة أو جداول. `inspirationPrompt`: حتى 400 حرف من نص عادي في سطر واحد. تحتسب حدود النصوص وحدات UTF-16 في JavaScript.

تشمل الحقول الاختيارية `controls` و`releaseNotes` و`makingOf` و`emoji` و`color` و`sourceRepository` و`license` و`tags` و`sourceLocale` و`listingLocalizations` و`listingMedia` و`server`. تستخدم الوسوم مراجع `group-slug/tag-slug` الموجودة، بحد أقصى 20 وسمًا فريدًا. يسرد `server` غرف Colyseus في ملف `server.js` المرفوع، مثل `"server": { "rooms": ["game"] }`؛ راجع [SDK للخادم](https://www.playdrop.ai/ar/create/learn/server-sdk). اسأل الموصّل عن قيم الترخيص المقبولة حاليًا وقواعد الحقول الكاملة قبل النشر. تلميحات اختيارية لتطبيقات النظام: يسرد `prefetch` الملفات المرفوعة التي يمكن لتطبيقات PlayDrop على iOS وmacOS وAndroid تنزيلها قبل اللعب، مثل `"prefetch": { "required": ["game.js"], "optional": ["music.mp3"] }` (تُضمَّن صفحة الدخول دائمًا)، ويتيح `"offlineSupported": true` لتلك التطبيقات عرض اللعبة دون اتصال بعد تخزين ملفاتها المطلوبة. تُتجاهل القيم غير الصالحة ولا تمنع الرفع أبدًا؛ وتحمّل المواقع الألعاب كالمعتاد.

ألعاب Instant: عيّن `"instant": true` عندما تكون اللعبة قابلة للعب خلال ثانيتين من 10 MB كحد أقصى من ملفات البدء (صفحة الدخول إضافة إلى `prefetch.required`، أو كل الملفات المرفوعة إذا لم يُدرج أي منها). تحمل ألعاب Instant شارة البرق وتُلعب في خلاصة Instant في تطبيقات PlayDrop للهاتف. ضع المراحل الأعمق والإضافات في `prefetch.optional`، وأنهِ تجميع المظلّلات وأي تهيئة أخرى قبل استدعاء `ready()`، واجعل المعاينة تعرض اللعب بدل شاشة العنوان، وأتح الضيوف (`authMode` بالقيمة `OPTIONAL` أو `NONE`) ليرى الجميع اللعبة في الخلاصة. يفحص PlayDrop الحجم عند الرفع ويزيل الشارة من الإصدارات التي تبدأ ببطء على الهواتف؛ واللعبة التي لا تبلغ المعيار تُنشر مع ذلك.

## صور الصفحة وفيديوهاتها

ارفع وسائط الصفحة ملفات بجوار `index.html`، مسمّاة بالمسار: `listing/icon.png` و`listing/hero-landscape.png` (16:9) و`listing/hero-portrait.png` (9:16) مع عنوان اللعبة في الرسم، ولقطات الشاشة مثل `listing/screenshots/landscape/0.png`، والفيديوهات `listing/videos/landscape/0.mp4` (المقطع الدعائي) و`listing/videos/portrait/0.mp4` (المقطع التشويقي للجوال). تُشغَّل الفيديوهات بلا صوت على بطاقات الألعاب وصفحة اللعبة، المقطع الدعائي على أجهزة الكمبيوتر والتلفاز والتشويقي على الهواتف، فهي أسرع طريقة لعرض اللعب وكسب أول مرة لعب. الصور بصيغة PNG والفيديوهات بصيغة MP4.

## ترجم صفحة اللعبة بدقة

انشر دائمًا الإنجليزية إضافة إلى لغتك إن اختلفت. عيّن `sourceLocale` إلى اللغة الأصلية. تدعم `listingLocalizations` الإنجليزية والفرنسية والألمانية والإسبانية والبرتغالية البرازيلية والإندونيسية واليابانية والكورية والصينية التقليدية والصينية المبسطة. تحتاج كل ترجمة إلى `locale` و`displayName`؛ وعند رفعها مع مصدرها يملأ PlayDrop قيمة `sourceHash`. ارفع الرسوم المترجمة تحت `listing/locales/<locale>/`، مثل `listing/locales/fr/hero-landscape.png` بالعنوان الفرنسي؛ وتُطابَق تلقائيًا مع ترجمتها. حدّث الترجمات بعد تغييرات المصدر. ترجمة صفحة اللعبة لا تترجم اللعبة نفسها.

## اللاعبون والمجموعات ووحدات التحكم

صرّح بكيفية لعب لعبتك بالحقول `types` و`party` و`controller` و`roomVoice` في كل مدخل لعبة:

```json
{
  "types": ["solo", "online", "party"],
  "party": { "local": [1, 2, 3, 4], "online": [1, 2, 3, 4] },
  "controller": { "support": "optional", "type": "simpler" },
  "roomVoice": true
}
```

يجمع `types` بين `solo` (يُلعب منفردًا) و`online` (يُلعب مع آخرين عبر الشبكة) و`party` (مجموعة تلعب معًا). يسرد `party.local` الأعداد الدقيقة للأشخاص الذين يمكنهم اللعب على شاشة واحدة؛ ويسرد `party.online` أحجام مجموعات الأصدقاء، حتى 4، التي يمكنها الدخول معًا عبر الإنترنت، وليس سعة الغرفة. الأحجام دقيقة: `[2, 4]` تستثني 3. يتطلب `party` النوع `party`، ويتطلب `party.online` النوع `online`، ويتطلب الرقم 1 في `party.local` النوع `solo`. يشغّل `roomVoice: true` صوت الغرفة ويتطلب `online`.

قيمة `controller.support` هي `off` (الافتراضية عند حذف `controller`) أو `optional` أو `required`. وعندما لا تكون `off`، يسمّي `controller.type` الحد الأدنى من أدوات التحكم التي تحتاجها اللعبة:

- `any`: الاتجاهات وConfirm وCancel؛ تعمل كل وحدة تحكم، بما فيها أجهزة التحكم عن بعد.
- `simpler`: عصا تناظرية واحدة وأربعة أزرار أمامية وMenu؛ تتأهل وحدات تحكم هاتف PlayDrop ووحدات التحكم القياسية.
- `standard`: D-pad وعصوان قابلتان للنقر وأربعة أزرار أمامية وزرا كتف وزرا زناد وMenu.
- `custom`: محجوز لعناصر تحكم هاتف خاصة باللعبة؛ غير متاح بعد.

مع تفعيل دعم وحدات التحكم، يجب أن يكون كل عدد محلي مُصرَّح به قابلًا للعب بوحدات التحكم؛ اقرأ مدخلات وحدات التحكم عبر [SDK](https://www.playdrop.ai/ar/create/learn/sdk). يمكن للألعاب الموجودة الاحتفاظ بـ `players` و`controllerMode` وما زالا يعملان، لكن الألعاب الجديدة تستخدم هذه الحقول، ولا يجوز لمدخل واحد الجمع بين الاثنين. يختار المضيف اللعب المحلي أو عبر الإنترنت، لا الاثنين معًا. تبقى هذه التصريحات عبر عمليات رفع Cloud وCLI وMCP والإصدارات الخاصة المحتفظ بها والنشر. وتعتمد الإتاحة أيضًا على الإطلاق التدريجي للمنصة وإصدار المضيف.

لعمليات رفع خادم MCP، قدّم حزمة ESM مبنية بصيغة `.mjs`/`.js` بوصفها واصف `SERVER` ووجّه `server.entry` إليها. تحتفظ مشاريع المصدر في Cloud/CLI بمدخل TypeScript الخاص بها. يوفّر PlayDrop بيئة تشغيل Colyseus وSDK للخادم؛ ولا تضمّن بيانات اعتماد مزوّد الصوت في أي لعبة أبدًا.