# PlayDrop 游戏素材：内置文件、自有素材和共享素材包

随 PlayDrop 游戏提供图片、声音、视频和 3D：内置文件、在 catalogue.json 中声明的游戏自有素材、公开素材和素材包，以及用 sdk.assets 在运行时查找。

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

游戏可以通过三种方式携带图片和声音。选择能满足需求的最简单方式。

| 方式 | 适合 | 做法 |
|---|---|---|
| 内置文件 | 只有这款游戏使用的所有内容 | 放进包中，并通过相对路径加载 |
| 游戏自有素材 | 想在 PlayDrop 上列出、重复使用或出售的素材 | 在 `ownedAssets` 中声明 |
| 公开素材和素材包 | 重复使用其他创作者发布的素材 | 在 `uses` 中引用 |

## 内置文件

把文件放在游戏旁边，并通过相对路径加载，例如 `assets/music.mp3`。它们会随[包](https://www.playdrop.ai/zh-hans/create/learn/packaging)一起上传，并由浏览器和应用缓存。把启动所需的文件列在 `prefetch.required` 中，让应用可以提前下载（[生命周期](https://www.playdrop.ai/zh-hans/create/learn/lifecycle)）。简单 HTML 游戏则必须把素材内联到文件中。

## 游戏自有素材

在游戏的 catalogue 条目中声明游戏拥有的素材。每个素材都会成为一个 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`，以及用于出售素材的 `shopListed` 和 `shopPriceCredits`。

## 公开素材和素材包

按确切修订版本引用已发布的素材，按版本引用素材包：

```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 应用可以上传图片、视频、音频、精灵图和已烘焙的 3D 模型，包括已烘焙的程序化图片和精灵图。可执行的 3D 模型（带有 `procedural` 子类别或 `CUSTOM` 格式的 `MODEL_3D`）可以在 PlayDrop 自己的工具中运行，但会被连接器拒绝，因为 API 不会运行创作者的代码来验证它们。请将它们烘焙为 GLB 等标准格式，或引用 PlayDrop 上已发布的版本。

用 [AI 素材生成](https://www.playdrop.ai/zh-hans/create/learn/ai-assets)制作新的图片和声音。对于 PlayDrop 不认识的格式，请参阅[自定义素材格式](https://www.playdrop.ai/zh-hans/create/learn/custom-assets)。

## 相关指南

- [AI 素材生成](https://www.playdrop.ai/zh-hans/create/learn/ai-assets): 在 PlayDrop 中为游戏生成图片、音乐、音效、语音、视频和 3D 模型：可在浏览器中经玩家确认后生成，也可由游戏服务器生成并由创作者付费。
- [自定义格式和玩家作品](https://www.playdrop.ai/zh-hans/create/learn/custom-assets): 用素材规格定义你自己的素材格式，声明游戏可以读取或写入哪些格式，并通过 sdk.assets.custom 让玩家保存和发布关卡、角色等作品。
- [打包和 .play](https://www.playdrop.ai/zh-hans/create/learn/packaging): 整理一个根目录带有 catalogue.json 的已构建游戏文件夹、ZIP 或 .play，声明商店页面媒体和服务器，并用 prepare_catalogue_upload 上传。