حزّم لعبة PlayDrop باستخدام catalogue.json و.play

ضع catalogue.json في الجذر، بجانب اللعبة المبنية. المسارات في الكتالوج نسبية إليه.

catalogue.json
index.html
assets/sprites.png
assets/music.mp3
listing/icon.png
listing/hero-landscape.png
listing/hero-portrait.png
listing/screenshots/landscape-1.png
listing/videos/portrait-1.mp4
achievements/first-win.png
server/index.mjs

ملف .play هو هذا المجلد مضغوطًا مع catalogue.json في جذر الأرشيف، لا داخل مجلد مغلّف، ومعاد تسميته بالامتداد .play. ولا يحتوي إلا على الملفات المبنية: دون node_modules، ودون خرائط مصدر لا تريدها عامة، ودون ملفات .env. احتفظ بالمشروع المصدري مع الشخص الذي تعمل معه؛ فلا يستطيع PlayDrop إعادته.

{
  "apps": [{
    "name": "moon-jump",
    "displayName": "Moon Jump",
    "subtitle": "Lunar platform hopping against the clock",
    "description": "Jump between lunar platforms, collect oxygen and reach the flag.",
    "controls": "Tap or press Space to jump. Swipe or use arrows to steer.",
    "file": "index.html",
    "version": "1.0.0",
    "visibility": "PRIVATE",
    "authMode": "OPTIONAL",
    "tags": ["game-genre/casual", "game-genre/platformer"],
    "types": ["solo"],
    "controller": { "support": "optional", "type": "simpler" },
    "surfaceTargets": { "desktop": true, "mobileLandscape": true, "mobilePortrait": true },
    "primarySurface": "MOBILE_PORTRAIT",
    "sourceLocale": "en",
    "listing": {
      "icon": "listing/icon.png",
      "heroLandscape": "listing/hero-landscape.png",
      "heroPortrait": "listing/hero-portrait.png",
      "screenshotsLandscape": ["listing/screenshots/landscape-1.png"],
      "videosPortrait": ["listing/videos/portrait-1.mp4"]
    },
    "leaderboards": [{ "key": "best-time", "displayName": "Best time", "description": "Fastest run to the flag",
      "scoreType": "TIME_MS", "sort": "ASC" }],
    "achievements": [{ "key": "first-win", "displayName": "First flag", "description": "Reach the flag once",
      "kind": "STANDARD", "icon": "achievements/first-win.png" }],
    "server": { "entry": "server/index.mjs", "rooms": ["game"] }
  }]
}

• file هو المسار الدقيق للصفحة التي تبدأ اللعبة. ودونه تكون صفحة الدخول الافتراضية <name>.html، لا index.html.
• version إصدار دلالي جديد لكل عملية رفع للعبة نفسها.
• تسرد surfaceTargets الواجهات التي اختبرتها؛ وprimarySurface هي الواجهة التي صُممت لها اللعبة.
• يطالب الكتالوج بوسائط صفحة اللعبة وأيقونات الإنجازات ومدخل الخادم: الملف الموجود تحت listing/ ولا يشير إليه أي حقل ليس من وسائط صفحة اللعبة، والملفات التي لا يطالب بها أي تطبيق تُرفض قبل نشر أي شيء.
• يشير server.entry إلى ملف مجمّع واحد لوحدة ES مبنية؛ راجع خوادم الألعاب الفورية.

تجد كل حقل وحدوده في مرجع catalogue.json. ولا يوجد حقل لإصدار الكتالوج يجب ضبطه.

أرسل prepare_catalogue_upload مع requestId جديد وexpectedCurrentVersion (null للعبة جديدة) وكائن الكتالوج الكامل وواصف واحد لكل ملف. يمكن أن تكون الملفات النصية الصغيرة text مضمّنًا. وكل ملف آخر هو رفع موقّع: احسب حجمه وSHA-256 (64 حرفًا ست عشريًا صغيرًا) وMD5 بترميز base64 محليًا من البايتات الدقيقة. هذا الطلب للعبة من ملفين كامل؛ استبدل العنصرين النائبين للبصمتين في الأيقونة بالقيم الحقيقية للأيقونة.

{
  "requestId": "moon-jump-1.0.0",
  "expectedCurrentVersion": { "moon-jump": null },
  "catalogue": {
    "apps": [{
      "name": "moon-jump",
      "displayName": "Moon Jump",
      "file": "index.html",
      "version": "1.0.0",
      "visibility": "PRIVATE",
      "authMode": "OPTIONAL",
      "tags": ["game-genre/casual"],
      "types": ["solo"],
      "controller": { "support": "off" },
      "surfaceTargets": { "desktop": true, "mobileLandscape": false, "mobilePortrait": true },
      "listing": { "icon": "listing/icon.png" }
    }]
  },
  "files": [
    { "path": "index.html",
      "text": "<!doctype html><html><head><meta charset=\"utf-8\"><title>Moon Jump</title></head><body><canvas id=\"game\"></canvas><script>/* built game */</script></body></html>" },
    { "path": "listing/icon.png", "contentType": "image/png", "sizeBytes": 50211,
      "sha256": "REPLACE_WITH_ICON_SHA256_HEX", "md5Base64": "REPLACE_WITH_ICON_MD5_BASE64" }
  ]
}

يسرد الرد رابط رفع وترويسات لـ listing/icon.png. أرسل البايتات الدقيقة للأيقونة بطلب PUT إلى ذلك الرابط مع كل ترويسة مُعادة، ثم استدعِ complete_catalogue_upload بـ requestId نفسه. ويفتح url في الإيصال الإصدار الخاص.

• الوكلاء الذين لديهم نظام ملفات يفكّون ضغط الأرشيف محليًا ويرفعونه بوصفه مجلدًا، كما في الأعلى.
• ChatGPT يمرّر الأرشيف الذي يأخذه من المحادثة بوصفه archive، مع download_url وfile_id الحقيقيين، ودون catalogue أو files. يمكن أن يصل حجم الأرشيف إلى 20 MiB مضغوطًا.

يجب أن تكون الأرشيفات ملفات ZIP عادية: دون تشفير أو أجزاء متعددة أو ZIP64 أو روابط رمزية أو مسارات مكررة أو مسارات مطلقة أو ... وتُرفض الملفات الفارغة وملفات catalogue.json المتداخلة.

512 ملفًا أو مدخلًا في الأرشيف (بما في ذلك catalogue.json والمجلدات)، و50 MiB لكل ملف، و200 MiB بعد فك الضغط، و1 MiB لـ JSON الكتالوج. وملف الخادم المستضاف المجمّع 2 MiB كحد أقصى.

اقرأ list_games، واحتفظ بـ name لكل تطبيق، وزِد قيمة version الخاصة به، واضبط expectedCurrentVersion على الإصدار المنشور الحالي. أرسل اللقطة الكاملة: كل ملف وحقل يجب أن يحتويه الإصدار الجديد. يمكن إرسال الملفات التي لم تتغير من إصدار محفوظ باستخدام reuse: { gameId, version, path } بدل بايتاتها. ولا يمكن حذف مفاتيح لوحات المتصدرين والإنجازات أو تغيير نوعها؛ أوقف أحدها باستخدام "status": "RETIRED".

يشغّل PlayDrop النماذج ثلاثية الأبعاد القابلة للتنفيذ (أصول MODEL_3D ذات الفئة الفرعية procedural أو الصيغة CUSTOM) في أدواته الخاصة، لكن الموصّل يرفضها لأن الواجهة البرمجية لا تستطيع التحقق من الكود الخاص بها. حوّلها مسبقًا إلى صيغة مدعومة، أو أشر إلى أصل منشور بالفعل على PlayDrop. وتُقبل الصور الإجرائية وأوراق الرسوم المتحركة المحوّلة مسبقًا. راجع أصول اللعبة.