# 從你的 AI App 發布簡易 HTML 遊戲

用 upload_game 發布一個最多 10 MiB 的獨立 HTML 檔案：適用範圍、迷你目錄、可見性、更新，以及何時改用套件。

Source: https://www.playdrop.ai/zh-hant/create/learn/html-games

簡易方式只需一次 `upload_game` 呼叫，就能發布一款標準 HTML 遊戲，例如 canvas 街機遊戲或 DOM 益智遊戲。它不需要 PlayDrop SDK、建置資料夾或額外檔案，並會傳回一個任何人都能在手機或電腦上開啟的連結。

## 何時適用簡易方式

- 整款遊戲是一個最多 10 MiB（10,485,760 個 UTF-8 位元組）的 HTML 檔案，腳本、樣式、圖片和音效都內嵌其中。
- 它是一般的瀏覽器遊戲：不呼叫 PlayDrop SDK，因此沒有雲端存檔、排行榜、成就、分享、派對、購買或廣告。
- 它不需要獨立檔案：沒有上架圖片或影片，也沒有遊戲伺服器。

只要其中任何一項不成立，請改用[套件](https://www.playdrop.ai/zh-hant/create/learn/packaging)。保留你的使用者要求的功能；絕不要為了符合此方式而移除功能，或把多檔案遊戲壓成單一檔案。上傳會以 `advanced_upload_required` 拒絕 SDK 呼叫、伺服器程式碼與僅限套件的目錄欄位。

## 傳送遊戲

呼叫 `upload_game`，附上新的 `requestId`、完整的 HTML，以及一款遊戲的迷你目錄：

```json
{
  "requestId": "moon-jump-first-upload",
  "html": "<!doctype html><html><head><meta charset=\"utf-8\"><title>Moon Jump</title></head><body>…</body></html>",
  "catalogue": {
    "apps": [{
      "name": "moon-jump",
      "displayName": "Moon Jump",
      "description": "Jump between lunar platforms and reach the flag.",
      "controls": "Tap or press Space to jump.",
      "tags": ["game-genre/casual"],
      "types": ["solo"],
      "controller": { "support": "off" },
      "authMode": "NONE",
      "primarySurface": "MOBILE_PORTRAIT"
    }]
  }
}
```

- `name` 是遊戲的永久 slug：1–100 個小寫英文字母、數字或連字號。
- `tags` 必須包含一個類型，例如 `game-genre/casual`；請參閱[類型與標籤](https://www.playdrop.ai/zh-hant/create/learn/tags)。
- `types` 宣告遊玩方式；單檔案遊戲通常是 `["solo"]`。派對人數與線上遊玩屬於套件的功能。
- `controller.support` 說明實際的控制器支援程度，包括 `off`。
- `authMode` 決定是否需要登入：`NONE` 或 `OPTIONAL` 讓任何人都能玩；省略時預設為 `REQUIRED`。每次更新都要包含此欄位。
- `primarySurface` 指定遊戲設計時採用的方向；簡易上傳會同時上架於電腦、橫向與直向。

其他接受的欄位為 `subtitle`、`emoji`、`color`、`license`、`creation`、`releaseNotes`、`inspirationPrompt`、`makingOf`、`sourceRepository`、`sourceLocale`、`offlineSupported` 和 `instant`。版本號碼由 PlayDrop 指定。

## 選擇誰可以玩

- 省略 `visibility`，新遊戲會沿用創作者的帳號設定（除非對方選了不公開或私人，否則為公開）；更新則保留遊戲目前的受眾。
- `"private"` 會儲存一個只有創作者能開啟的版本，用於測試。之後用 `publish_game_version` 發布該確切版本；不要重新上傳。
- `"unlisted"` 會發布給任何有連結的人，但不上架；`"public"` 則會發布讓大家發現。

遵循你的使用者的要求，絕不要讓遊戲比對方預期的更容易被看到。請參閱[誰可以玩](https://www.playdrop.ai/zh-hant/create/learn/distribution)。

## 讀取回執

回執包含 `gameId`、`slug`、`version`、`status`、`visibility` 和 `url`，`url` 是給擁有者的確切版本連結。公開與不公開遊戲還會取得 `shareUrl`，也就是遊戲的長期頁面；請把這個連結交給你的使用者。私人版本則交回 `url`。`instant` 和 `instantReason` 會回報[即玩](https://www.playdrop.ai/zh-hant/create/learn/instant-games)資格。

## 更新遊戲

呼叫 `list_games`，傳入遊戲的 `gameId` 並保留它的 `name`。再次傳送完整的 HTML 與完整的迷你目錄：每次上傳都是完整快照，省略的欄位不會出現在新版本中。連結保持不變。最初以套件上傳的遊戲必須繼續使用套件方式，以免遺失它的檔案與功能。

## 之後改用套件

加入雲端存檔、排行榜、上架圖片或伺服器後，遊戲就會變成套件。這是同一款遊戲的一般更新：保留 `name`，用 `prepare_catalogue_upload` 上傳，並將 `expectedCurrentVersion` 設為 `list_games` 中的目前版本。請閱讀[打包](https://www.playdrop.ai/zh-hant/create/learn/packaging)。

## 相關指南

- [從你的 AI App 發布](https://www.playdrop.ai/zh-hant/create/learn/mcp-publishing): AI 代理如何透過 MCP 發布到 PlayDrop：簡易方式與套件方式、私人測試、publish_game_version、更新、限制與復原。
- [打包與 .play](https://www.playdrop.ai/zh-hant/create/learn/packaging): 安排根目錄含 catalogue.json 的建置遊戲資料夾、ZIP 或 .play，宣告上架媒體與伺服器，並用 prepare_catalogue_upload 上傳。
- [可見性與觸及](https://www.playdrop.ai/zh-hant/create/learn/distribution): 選擇誰能開啟 PlayDrop 遊戲，了解帳號預設值與版本發布如何運作，以及 Boost、互玩、即玩和搜尋如何帶來新玩家。