เอกสารอ้างอิงทางเทคนิค

catalogue.json: ข้อมูลเมตาและการแปลของเกม PlayDrop

เอกสารอ้างอิงสำหรับชื่อเกม คำอธิบาย แท็กประเภท ภาพและวิดีโอของหน้าเกม คำแปล และฟิลด์เซิร์ฟเวอร์แบบไม่บังคับในรูปแบบ PlayDrop Connector

PlayDrop Connector ส่งข้อมูลเมตา catalogue.json ของคุณไปพร้อมกับไฟล์เกม ไม่ต้องใช้เครื่องมือบรรทัดคำสั่ง PlayDrop Cloud ดูแลข้อมูลเมตานี้ให้เกม Studio

อัปโหลดส่วนตัวแบบสมบูรณ์ด้วย prepare_catalogue_upload

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>"
    }
  ]
}

นี่คือคำขอ 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 หากไม่มี) นี่คือการตรวจสอบความขัดแย้ง ไม่ใช่เวอร์ชันที่กำลังอัปโหลด ลองอัปโหลดที่ถูกขัดจังหวะอีกครั้งด้วย ID คำขอเดิม เผยแพร่เวอร์ชันที่ทดสอบและเก็บไว้ด้วย 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: Markdown ไม่เกิน 3,000 ตัวอักษร โดยไม่มีหัวข้อ 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 เมื่อเกมเล่นได้ภายใน 2 วินาทีจากไฟล์เริ่มต้นไม่เกิน 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: ทิศทาง ยืนยัน และยกเลิก; ทุกคอนโทรลเลอร์ใช้ได้ รวมถึงรีโมต
simpler: อนาล็อกสติ๊กหนึ่งตัว ปุ่มหน้าสี่ปุ่ม และเมนู; คอนโทรลเลอร์บนโทรศัพท์ของ PlayDrop และเกมแพดมาตรฐานเข้าเกณฑ์
standard: D-pad สติ๊กกดได้สองตัว ปุ่มหน้าสี่ปุ่ม ปุ่มไหล่สองปุ่ม ทริกเกอร์สองตัว และเมนู
custom: สงวนไว้สำหรับการควบคุมบนโทรศัพท์เฉพาะเกม ยังใช้ไม่ได้

เมื่อเปิดรองรับคอนโทรลเลอร์ ทุกจำนวนผู้เล่นในเครื่องที่ประกาศต้องเล่นด้วยคอนโทรลเลอร์ได้ อ่านอินพุตคอนโทรลเลอร์ผ่าน SDK เกมที่มีอยู่อาจคง players และ controllerMode ไว้ ซึ่งยังทำงานอยู่ แต่เกมใหม่ใช้ฟิลด์เหล่านี้ และหนึ่งรายการผสมทั้งสองแบบไม่ได้ โฮสต์เลือกการเล่นในเครื่องหรือออนไลน์ ไม่ใช่ทั้งสองอย่าง การประกาศเหล่านี้คงอยู่ผ่านการอัปโหลดจาก Cloud, CLI และ MCP เวอร์ชันส่วนตัวที่เก็บไว้ และการเผยแพร่ ความพร้อมใช้งานยังขึ้นกับการเปิดตัวของแพลตฟอร์มและบิลด์ของโฮสต์

สำหรับการอัปโหลดเซิร์ฟเวอร์ MCP ให้ส่งบันเดิล ESM .mjs/.js ที่สร้างแล้วเป็นตัวบรรยาย SERVER และชี้ server.entry ไปที่ไฟล์นั้น โปรเจกต์ซอร์สสำหรับ Cloud/CLI คงจุดเข้า TypeScript ไว้ PlayDrop จัดหารันไทม์ Colyseus และ SDK ฝั่งเซิร์ฟเวอร์ ห้ามใส่ข้อมูลรับรองผู้ให้บริการเสียงในเกมเด็ดขาด

อัปโหลดส่วนตัวแบบสมบูรณ์ด้วย prepare_catalogue_upload

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>"
    }
  ]
}

ตัวอย่างความเข้ากันได้แบบเกมเดียวรุ่นเก่า

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"]
  }]
}

ฟิลด์ที่รองรับและขีดจำกัด

ภาพและวิดีโอของหน้าเกม

แปลหน้าเกมอย่างถูกต้อง

ผู้เล่น ปาร์ตี้ และคอนโทรลเลอร์

json

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

any: ทิศทาง ยืนยัน และยกเลิก; ทุกคอนโทรลเลอร์ใช้ได้ รวมถึงรีโมต
simpler: อนาล็อกสติ๊กหนึ่งตัว ปุ่มหน้าสี่ปุ่ม และเมนู; คอนโทรลเลอร์บนโทรศัพท์ของ PlayDrop และเกมแพดมาตรฐานเข้าเกณฑ์
standard: D-pad สติ๊กกดได้สองตัว ปุ่มหน้าสี่ปุ่ม ปุ่มไหล่สองปุ่ม ทริกเกอร์สองตัว และเมนู
custom: สงวนไว้สำหรับการควบคุมบนโทรศัพท์เฉพาะเกม ยังใช้ไม่ได้