# PlayDrop 上的自定义素材格式和玩家作品

用素材规格定义你自己的素材格式，声明游戏可以读取或写入哪些格式，并通过 sdk.assets.custom 让玩家保存和发布关卡、角色等作品。

Source: https://www.playdrop.ai/zh-hans/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-hans/create/learn/game-assets)。

## 相关指南

- [游戏素材](https://www.playdrop.ai/zh-hans/create/learn/game-assets): 随 PlayDrop 游戏提供图片、声音、视频和 3D：内置文件、在 catalogue.json 中声明的游戏自有素材、公开素材和素材包，以及用 sdk.assets 在运行时查找。
- [catalogue.json](https://www.playdrop.ai/zh-hans/create/learn/catalogue-json): PlayDrop 游戏使用的 catalogue.json 字段：标识、商店页面、游玩方式、显示形态、登录、即玩、预加载、媒体、翻译、分数和服务器。
- [客户端 SDK](https://www.playdrop.ai/zh-hans/create/learn/sdk): PlayDrop 浏览器 SDK 参考：初始化、宿主生命周期、玩家身份和存档、设备和控制器、社交、多人游戏、商店、广告、排行榜、成就、素材和 AI。