用 catalogue.json 和 .play 打包 PlayDrop 遊戲
安排根目錄含 catalogue.json 的建置遊戲資料夾、ZIP 或 .play，宣告上架媒體與伺服器，並用 prepare_catalogue_upload 上傳。
套件是遊戲的建置輸出，加上描述它的 catalogue.json。所有 PlayDrop 功能都要透過套件：多個檔案、SDK、上架圖片與影片、排行榜、成就、素材和託管伺服器。從你的 AI App 以資料夾、ZIP 或 .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、你不想公開的 source map，或 .env 檔案。原始專案請留在你的使用者那裡；PlayDrop 無法傳回它。
撰寫 catalogue.json
{
"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 個小寫十六進位字元）和 base64 MD5。下面這個兩檔案遊戲的請求是完整的；請將圖示上的兩個摘要預留值換成圖示的真實值。
{
"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 到該網址，然後以相同的 requestId 呼叫 complete_catalogue_upload。回執的 url 會開啟私人版本。
上傳 ZIP 或 .play
- 有檔案系統的代理會在本機解壓縮壓縮檔，然後如上所述以資料夾上傳。
- 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 會在自己的工具中執行可執行的 3D 模型（procedural 子類別或 CUSTOM 格式的 MODEL_3D 素材），但連接器會拒絕它們，因為 API 無法驗證它們的程式碼。請將它們烘焙成支援的格式，或參照已在 PlayDrop 上發布的素材。烘焙後的程序化圖片和精靈圖表可以接受。請參閱遊戲素材。