catalogue.json: البيانات الوصفية لألعاب PlayDrop والترجمة
مرجع لعناوين الألعاب وأوصافها ووسوم النوع وصور الصفحة وفيديوهاتها والترجمات وحقل server الاختياري بصيغة PlayDrop Connector.
يرسل PlayDrop Connector بياناتك الوصفية catalogue.json مع ملفات اللعبة؛ ولا حاجة إلى أداة سطر أوامر. يتولى PlayDrop Cloud صيانة هذه البيانات لألعاب Studio.
رفع خاص كامل باستخدام prepare_catalogue_upload
{
"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>"
}
]
}هذا طلب prepare_catalogue_upload كامل للعبة خاصة جديدة. استبدل مثال HTML بلعبتك المبنية واستخدم requestId فريدًا لكل عملية رفع مقصودة. الكائن catalogue هو محتوى catalogue.json؛ أما files وexpectedCurrentVersion فتنتميان إلى طلب الأداة، خارج ذلك الكائن.
يجب أن يطابق 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 بالأحرف الصغيرة ثابتًا عند التحديث. أضف عنوانًا معروضًا ووصفًا دقيقًا وأدوات التحكم ولغة المصدر والوسوم المعروفة عند الحاجة. يستخدم المثال أدناه وسم نوع المنصّات الموجود.
{
"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 للخادم. اسأل الموصّل عن قيم الترخيص المقبولة حاليًا وقواعد الحقول الكاملة قبل النشر. تلميحات اختيارية لتطبيقات النظام: يسرد 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 في كل مدخل لعبة:
{
"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. يمكن للألعاب الموجودة الاحتفاظ بـ players وcontrollerMode وما زالا يعملان، لكن الألعاب الجديدة تستخدم هذه الحقول، ولا يجوز لمدخل واحد الجمع بين الاثنين. يختار المضيف اللعب المحلي أو عبر الإنترنت، لا الاثنين معًا. تبقى هذه التصريحات عبر عمليات رفع Cloud وCLI وMCP والإصدارات الخاصة المحتفظ بها والنشر. وتعتمد الإتاحة أيضًا على الإطلاق التدريجي للمنصة وإصدار المضيف.
لعمليات رفع خادم MCP، قدّم حزمة ESM مبنية بصيغة .mjs/.js بوصفها واصف SERVER ووجّه server.entry إليها. تحتفظ مشاريع المصدر في Cloud/CLI بمدخل TypeScript الخاص بها. يوفّر PlayDrop بيئة تشغيل Colyseus وSDK للخادم؛ ولا تضمّن بيانات اعتماد مزوّد الصوت في أي لعبة أبدًا.