# PlayDrop 的自訂素材格式與玩家創作

用素材規格定義自己的素材格式，宣告遊戲讀取或寫入哪些格式，並用 sdk.assets.custom 讓玩家儲存及發布關卡、角色等創作。

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

素材規格讓遊戲以檔案合約的形式定義自己的素材種類，例如關卡、角色或牌組。玩家接著可以用該格式製作、儲存並發布創作，其他支援此格式的遊戲也能開啟這些創作。

## 定義素材規格

素材規格宣告在 catalogue.json 的 `assetSpecs` 清單中，與 `apps` 並列：

```json
{
  "assetSpecs": [{
    "name": "moon-level",
    "version": "1.0.0",
    "displayName": "Moon Jump level",
    "symbol": "specs/moon-level.svg",
    "contract": "specs/moon-level.contract.json"
  }]
}
```

合約會列出每個素材的檔案，以及檢查這些檔案的方式：

```json
{
  "primaryRole": "level",
  "roles": [
    { "name": "level", "required": true, "contentTypes": ["application/json"], "mode": "TEXT",
      "jsonSchema": { "type": "object", "required": ["tiles"], "properties": { "tiles": { "type": "array" } } } },
    { "name": "thumbnail", "required": false, "contentTypes": ["image/png"], "mode": "BINARY" }
  ]
}
```

檔案角色可以附帶 JSON Schema，PlayDrop 每次儲存時都會檢查。格式變更時，請發布新的規格版本；舊素材會保留原本的版本。

## 宣告遊戲支援的格式

```json
{
  "assetSpecSupport": [
    { "assetSpec": "asset-spec:your-name/moon-level", "versionRange": "^1.0.0", "capabilities": ["READ", "WRITE"] }
  ]
}
```

可用的能力有 `READ`、`WRITE`、`EDIT`、`PREVIEW` 和 `IMPORT`。

## 儲存與載入玩家創作

```js
const levels = sdk.assets.custom.forSpec("asset-spec:your-name/moon-level");

await levels.saveDraft({ assetName: "crater-run", displayName: "Crater run",
  files: { level: new Blob([JSON.stringify(level)], { type: "application/json" }) } });
await levels.publish({ assetName: "crater-run", displayName: "Crater run", files: { level: levelBlob, thumbnail: pngBlob } });

const mine = await levels.listMine();
const latest = mine[0]?.latestPublicVersion;
if (latest) startLevel(await levels.loadJson({ assetRef: latest.assetRef, role: "level" }));

const community = await levels.listPublic({ limit: 20 }); // { assets, pagination }
```

- `saveDraft` 會保留私人草稿；`publish` 會將它公開。兩者都需要完整的檔案組。
- 素材參照的格式類似 `asset:creator/name@r2`。`loadJson`、`loadText` 和 `downloadFile` 讀取已發布的素材；`loadOwned`、`loadOwnedJson` 和 `loadOwnedFile` 讀取玩家自己的素材，包含草稿。
- `supports(versionRef, capability)` 會在開啟其他版本的素材前先行檢查。
- 錯誤使用 `custom_asset_capability_unsupported` 和 `custom_asset_role_type_mismatch` 等代碼。

玩家需要登入才能儲存。請像審查任何使用者內容一樣，審查玩家發布的內容：PlayDrop 的內容政策同樣適用。

## 連接器接受的內容

純資料的自訂素材與規格，上傳方式與其他檔案相同。可執行的模型，也就是 `procedural` 子類別或 `CUSTOM` 格式的 `MODEL_3D` 素材，會被連接器拒絕，因為 API 不會執行創作者的程式碼；請先將它們烘焙，或參照已發布的版本。請參閱[遊戲素材](https://www.playdrop.ai/zh-hant/create/learn/game-assets)。

## 相關指南

- [遊戲素材](https://www.playdrop.ai/zh-hant/create/learn/game-assets): 隨 PlayDrop 遊戲提供圖片、音效、影片與 3D：內附檔案、在 catalogue.json 宣告的遊戲自有素材、公開素材與素材包，以及用 sdk.assets 在執行時查找。
- [catalogue.json](https://www.playdrop.ai/zh-hant/create/learn/catalogue-json): PlayDrop 遊戲使用的 catalogue.json 欄位：身分、上架資訊、遊玩方式、顯示環境、登入、即玩、預先載入、媒體、翻譯、分數與伺服器。
- [用戶端 SDK](https://www.playdrop.ai/zh-hant/create/learn/sdk): PlayDrop 瀏覽器 SDK 參考：初始化、主機端生命週期、玩家身分與存檔、裝置與控制器、社群、多人連線、商店、廣告、排行榜、成就、素材與 AI。