catalogue.json：PlayDrop 遊戲中繼資料與在地化
PlayDrop Connector 格式的參考文件，涵蓋遊戲標題、說明、類型標籤、上架圖片與影片、翻譯，以及選用的 server 欄位。
PlayDrop Connector 會將 catalogue.json 中繼資料與遊戲檔案一起傳送，不需要命令列工具。Studio 遊戲的中繼資料由 PlayDrop Cloud 管理。
使用 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 布林值的物件；請至少啟用一種經過測試的顯示環境。明確宣告版本和可見性。範例使用內嵌文字；附件或簽名上傳也可以使用相同路徑。
準備完成後，傳送所需檔案，並以同一 requestId 呼叫 complete_catalogue_upload。開啟私人版本進行測試。更新時，讀取 list_games，保留相同的 name，提供新的 version 和完整快照，並將 expectedCurrentVersion[name] 設為伺服器傳回的目前公開版本；若不存在則設為 null。此欄位用於衝突檢查，並非正在上傳的版本。使用原請求 ID 恢復中斷的上傳。準備就緒後，透過 publish_game_version 發佈已保留並測試的版本。
舊版單遊戲格式相容範例
以下範例使用舊版單遊戲格式。完整目錄也支援多個遊戲、資源、資源包與規格，請向連接器索取最新結構。每次更新都傳送完整快照，並明確指定版本與可見性。省略目錄項目不會刪除它們。
更新時請保持小寫 slug 不變。視需要加入顯示標題、準確的說明、操作方式、來源語言與已知標籤。下方範例使用現有的平台遊戲（platformer）類型標籤。
{
"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 個字元的單行純文字。文字長度限制以 JavaScript UTF-16 編碼單位計算。
選填欄位包括 controls、releaseNotes、makingOf、emoji、color、sourceRepository、license、tags、sourceLocale、listingLocalizations、listingMedia 與 server。標籤使用現有的 group-slug/tag-slug 參照，最多 20 個不重複標籤。server 列出已上傳 server.js 的 Colyseus 房間，例如 "server": { "rooms": ["game"] }；請參閱 伺服器 SDK。發布前，請向連接器查詢目前接受的授權值與完整的欄位規則。原生應用程式的選用提示：prefetch 列出 PlayDrop iOS、macOS 與 Android 應用程式可在遊玩前下載的已上傳檔案，例如 "prefetch": { "required": ["game.js"], "optional": ["music.mp3"] }（入口頁面一律包含在內）；"offlineSupported": true 讓這些應用程式在必要檔案儲存後離線提供遊戲。無效的值會被忽略，絕不會阻擋上傳；網站照常載入遊戲。
即玩遊戲：當遊戲能在 2 秒內以最多 10 MB 的啟動檔案（入口頁面加上 prefetch.required，若未列出則為所有上傳檔案）開始遊玩時，請設定 "instant": true。即玩遊戲會帶有閃電徽章，並在 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，party.local 包含 1 時需要 solo。roomVoice: true 會開啟房間語音，並且需要 online。
controller.support 為 off（省略 controller 時的預設值）、optional 或 required。不為 off 時，用 controller.type 指定遊戲所需的最低操控：
any：方向、確認和取消；所有控制器都能使用，包括遙控器。simpler：一個類比搖桿、四個功能鍵和選單鍵；PlayDrop 手機控制器和標準手把都符合要求。standard：方向鍵、兩個可按壓搖桿、四個功能鍵、兩個肩鍵、兩個扳機鍵和選單鍵。custom：保留給遊戲專屬的手機操控，目前尚未開放。
開啟控制器支援後，宣告的每個本機人數都必須能用控制器遊玩；請透過 SDK 讀取控制器輸入。現有遊戲可以繼續使用 players 和 controllerMode，它們仍然有效，但新遊戲應使用這些欄位，且同一條目不能混用兩種寫法。宿主只選擇本機或線上模式，不會同時啟用。宣告會保留在 Cloud、CLI 和 MCP 上傳、保留的私人版本以及發佈版本中。可用性還取決於平台開放範圍和宿主版本。
透過 MCP 上傳伺服器時，請提供建置好的 ESM .mjs/.js 套件作為 SERVER 描述項，並讓 server.entry 指向它。Cloud/CLI 原始碼專案保留 TypeScript 進入點。PlayDrop 提供 Colyseus 和伺服器 SDK 執行階段；切勿在遊戲中包含語音供應商憑證。