素材
PlayDrop 上的自定义素材格式和玩家作品
用素材规格定义你自己的素材格式，声明游戏可以读取或写入哪些格式，并通过 sdk.assets.custom 让玩家保存和发布关卡、角色等作品。
素材规格让游戏可以把自己的素材类型（例如关卡、角色或卡组）定义为一份文件约定。之后，玩家就能用这种格式制作、保存和发布作品，其他支持该格式的游戏也能打开它们。
定义素材规格
素材规格在 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 不运行创作者的代码；请将其烘焙，或引用已发布的版本。请参阅游戏素材。