# catalogue.json：PlayDrop 遊戲中繼資料與在地化

PlayDrop Connector 格式的參考文件，涵蓋遊戲標題、說明、類型標籤、上架圖片與影片、翻譯，以及選用的 server 欄位。

Source: https://www.playdrop.ai/zh-hant/docs/catalogue-json

[PlayDrop Connector](https://www.playdrop.ai/zh-hant/docs/connectors) 會搭配一個精簡的 `catalogue.json` 發布你的遊戲：這是一個含有 `apps` 的 JSON 物件，其中必須恰好包含一款遊戲。只有 `name` 為必填。代理會將它作為 catalogue 參數，與遊戲檔案一起傳送；不需要任何命令列工具。PlayDrop Cloud 會為你維護這些中繼資料。

## 最精簡的發布範例

更新時請保持小寫 slug 不變。視需要加入顯示標題、準確的說明、操作方式、來源語言與已知標籤。下方範例使用現有的平台遊戲（platformer）類型標籤。

```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`：最多 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](https://www.playdrop.ai/zh-hant/docs/server-sdk)。發布前，請向連接器查詢目前接受的授權值與完整的欄位規則。

## 上架圖片與影片

將上架媒體以檔案形式上傳到 `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`；它會自動對應到相應的翻譯。來源變更後請更新翻譯。上架資訊翻譯不會翻譯遊戲本身。