用 PlayDrop MCP 從你的 AI App 發布遊戲

1. 在撰寫程式碼之前，呼叫 get_documentation({topic:"index"})，閱讀遊戲會用到的功能指南。從一開始就規劃全螢幕版面、存檔和操控，可以避免之後重寫遊戲。若需要確切的方法簽章，請閱讀主題 sdk-types、server-sdk-types 和 shared-types。
2. 呼叫 list_games。如果遊戲已經存在，你要更新它並保留它的 name，讓它保有原本的連結和玩家。
3. 選擇方式。不使用 PlayDrop SDK 的單一獨立 HTML 檔案採用簡易方式。其他所有情況，包括任何 SDK 功能、上架媒體或伺服器，都使用套件。

請自行保管創作者的原始專案。PlayDrop 只接收建置後的輸出：它不是原始碼備份，也無法傳回原始碼。

傳送 requestId、完整的 HTML（最多 10 MiB，即 10,485,760 個 UTF-8 位元組）和迷你目錄。傳入 gameId 可更新現有遊戲。版本會自動遞增。欄位說明請參閱簡易 HTML 遊戲。

呼叫 prepare_catalogue_upload，附上 requestId、expectedCurrentVersion 和一種輸入形式：

• 資料夾： catalogue（catalogue.json 的內容）加上 files，每個檔案一個描述項，附上它的相對路徑。描述項可攜帶內嵌的 text、簽名上傳說明、附件綁定，或對保留版本中檔案的 reuse。
• 本機 ZIP 或 .play： 在本機解壓縮，然後傳送根目錄中 catalogue.json 的目錄內容，以及資料夾的檔案描述項。絕不要把 base64 編碼的壓縮檔位元組放進工具呼叫。
• ChatGPT 附件： 將主機端解析的 ZIP 或 .play 作為 archive 傳入，附上它真正的 download_url 和 file_id。壓縮後最多 20 MiB，且根目錄需要有 catalogue.json。

簽名上傳時，每個描述項都要提供 path、contentType、sizeBytes、sha256（64 個小寫十六進位字元）和 md5Base64，這些值都要在本機根據確切的位元組計算。將這些位元組連同每個傳回的標頭 PUT 到每個傳回的網址，然後以相同的 requestId 呼叫 complete_catalogue_upload。

在 ChatGPT 中，資料夾檔案可以來自依位置綁定的附件：

attachments: [htmlFile, iconFile]
files: [{path:"index.html", attachmentIndex:0}, {path:"listing/icon.png", attachmentIndex:1, role:"LISTING", app:"my-game"}]

每款遊戲都需要宣告的 version、可見性（在請求或遊戲上），以及 expectedCurrentVersion 中以其名稱為鍵的項目：建立時為 null，更新時則為 list_games 中目前發布的版本。過時的值會被拒絕，因此絕不會意外覆蓋另一次上傳。

當遊戲使用 SDK 或伺服器，或你的使用者想先試玩時，請以 visibility: "private" 上傳。開啟回執的 url，就能在 PlayDrop 中搭配真正的 SDK 主機端遊玩該確切版本。託管伺服器功能只會在已上傳的版本上執行，所以請用這種方式測試。

運作正常後，用 publish_game_version 發布該確切版本，傳入 gameId、version、expectedCurrentVersion，以及你的使用者選擇的 visibility（public 或 unlisted）（若有選擇）。它會沿用已測試的檔案、上架資訊與審查結果。不要為了發布而重新上傳遊戲。

若要在上傳前於 PlayDrop 框架中試玩本機建置版本，請在執行本機伺服器的電腦上，用一般瀏覽器開啟 https://www.playdrop.ai/@<username>/<slug>/dev?url=<URL-encoded local address>。

visibility 接受 public、unlisted 和 private。對於沒有指定的新遊戲，請使用創作者已儲存的設定：省略可見性時，upload_game 會套用此設定，get_account 則以 publishing.defaultVisibility 顯示它。更新時，除非你的使用者要變更，否則請保留 list_games 中遊戲的 gameVisibility；省略可見性時 upload_game 會這樣做，套件則要明確寫出。不公開代表任何有連結的人都能玩；它不是好友名單。絕不要讓遊戲比你的使用者預期的更容易被看到。詳細說明：誰可以玩。

公開與不公開遊戲的回執包含 shareUrl，也就是遊戲的長期頁面：請把這個連結交給你的使用者。私人版本則傳回 url，也就是給擁有者的確切版本連結。套件回執會列出每個項目；即使後面的項目失敗，已完成的項目仍會維持發布狀態。

讀取 list_games 和目前版本，保留 name，並傳送完整快照：所有預計的檔案和所有預計的中繼資料，因為省略的欄位不會出現在新版本中。省略的目錄項目絕不會被刪除。使用 get_game_version 讀取你要變更的版本的確切目錄，包括它的可調數值（Tweaks）狀態。

• 簡易方式：一個最多 10 MiB 的 HTML 檔案。
• 套件：512 個資料夾檔案描述項或 512 個壓縮檔項目（包括 catalogue.json 和資料夾）、每個檔案 50 MiB、解壓縮後總計 200 MiB，以及 1 MiB 的目錄 JSON。
• 壓縮檔：只接受安全的相對路徑；重複路徑、符號連結、加密、分割和 ZIP64 壓縮檔都會被拒絕。
• 準備好的上傳會在 30 分鐘後過期。

錯誤包含 error、message、retryable、nextAction、docsUrl 和 documentationTopic。請遵循 nextAction。回應遺失後，以相同的 requestId 重試完全相同的內容；內容變更則需要新的 ID。請參閱錯誤與復原。

使用 send_feedback 回報可重現的問題或令人困惑的步驟，內容不要包含權杖或簽名網址。