# PlayDrop 的遊戲素材：內附檔案、自有素材與共用素材包

隨 PlayDrop 遊戲提供圖片、音效、影片與 3D：內附檔案、在 catalogue.json 宣告的遊戲自有素材、公開素材與素材包，以及用 sdk.assets 在執行時查找。

Source: https://www.playdrop.ai/zh-hant/create/learn/game-assets

遊戲可以用三種方式攜帶美術與音效。請選擇能滿足需求的最簡單方式。

| 方式 | 適合用途 | 做法 |
|---|---|---|
| 內附檔案 | 只有這款遊戲使用的所有內容 | 放進套件中，並以相對路徑載入 |
| 遊戲自有素材 | 想在 PlayDrop 上架、可重複使用或販售的素材 | 在 `ownedAssets` 中宣告 |
| 公開素材與素材包 | 重複使用其他創作者發布的素材 | 在 `uses` 中參照 |

## 內附檔案

將檔案放在遊戲旁邊，並以相對路徑載入，例如 `assets/music.mp3`。它們會隨[套件](https://www.playdrop.ai/zh-hant/create/learn/packaging)一起上傳，並由瀏覽器和 App 快取。在 `prefetch.required` 中列出開始時需要的檔案，讓 App 能提早下載（[生命週期](https://www.playdrop.ai/zh-hant/create/learn/lifecycle)）。簡易 HTML 遊戲則必須改為將素材內嵌。

## 遊戲自有素材

在遊戲的目錄項目中宣告遊戲擁有的素材。每一個都會成為附屬於此遊戲、擁有專屬頁面的 PlayDrop 素材：

```json
{
  "ownedAssets": [
    { "name": "moon-theme", "runtimeKey": "music.main", "displayName": "Moon theme",
      "category": "AUDIO", "files": { "primary": "assets/moon-theme.mp3" } },
    { "name": "astronaut", "runtimeKey": "sprites.player", "displayName": "Astronaut",
      "category": "SPRITESHEET", "files": { "atlas": "assets/astronaut.png", "manifest": "assets/astronaut.json" } }
  ]
}
```

- `category` 為 `IMAGE`、`VIDEO`、`AUDIO`、`SPRITESHEET`、`MODEL_3D` 或 `CUSTOM`；`subcategory` 和 `format` 可進一步細分。
- `files` 將檔案角色對應到路徑。音訊需要 `primary`；精靈圖表需要 `atlas` 和 `manifest`。
- `runtimeKey` 是遊戲在執行時用來找到素材的名稱。
- 選用：`visibility`、`license`、`tags`，以及搭配 `shopPriceCredits` 的 `shopListed`，用來販售素材。

## 公開素材與素材包

依確切修訂版參照已發布的素材，依版本參照素材包：

```json
{
  "uses": {
    "assets": [{ "ref": "asset:someone/forest-tiles@r3", "runtimeKey": "tiles.forest" }],
    "packs": ["pack:someone/ui-kit@1.2.0"]
  }
}
```

可以在 [PlayDrop 素材](https://www.playdrop.ai/assets)瀏覽，或使用 `sdk.assets.catalog.listPublic()`、`sdk.assets.packs.listPublic()` 和 `sdk.search.query()`。公開遊戲只能使用公開的素材與素材包；請遵守每個素材的授權。

## 在執行時尋找素材

```js
const music = sdk.assets.resolveAppAsset("music.main");
const file = music.files.find((entry) => entry.role === "primary");
audioElement.src = file.url;

for (const asset of sdk.assets.listAppAssets()) console.log(asset.runtimeKey, asset.sourceType);
```

每個結果都有 `assetRef`、`runtimeKey`、`sourceType`（`OWNED`、`DIRECT` 或 `PACK`），以及包含 `role`、`url`、`contentType` 和 `sizeBytes` 的 `files`。

## 連接器接受的內容

你的 AI App 可以上傳圖片、影片、音訊、精靈圖表和已烘焙的 3D 模型，包括已烘焙的程序化圖片與精靈圖表。可執行的 3D 模型（`procedural` 子類別或 `CUSTOM` 格式的 `MODEL_3D`）可以在 PlayDrop 自己的工具中執行，但會被連接器拒絕，因為 API 不會執行創作者的程式碼來驗證它們。請將它們烘焙成 GLB 等標準格式，或參照已在 PlayDrop 上發布的版本。

用 [AI 素材生成](https://www.playdrop.ai/zh-hant/create/learn/ai-assets)製作新的美術與音效。PlayDrop 無法辨識的格式，請參閱[自訂素材格式](https://www.playdrop.ai/zh-hant/create/learn/custom-assets)。

## 相關指南

- [AI 素材生成](https://www.playdrop.ai/zh-hant/create/learn/ai-assets): 在 PlayDrop 為遊戲生成圖片、音樂、音效、語音、影片與 3D 模型：可從瀏覽器經玩家確認後生成，或從遊戲伺服器生成並由創作者付費。
- [自訂格式與玩家創作](https://www.playdrop.ai/zh-hant/create/learn/custom-assets): 用素材規格定義自己的素材格式，宣告遊戲讀取或寫入哪些格式，並用 sdk.assets.custom 讓玩家儲存及發布關卡、角色等創作。
- [打包與 .play](https://www.playdrop.ai/zh-hant/create/learn/packaging): 安排根目錄含 catalogue.json 的建置遊戲資料夾、ZIP 或 .play，宣告上架媒體與伺服器，並用 prepare_catalogue_upload 上傳。