# Định dạng tài nguyên tùy chỉnh và sáng tạo của người chơi trên PlayDrop

Định nghĩa định dạng tài nguyên riêng bằng asset spec, khai báo định dạng game đọc hoặc ghi, và cho người chơi lưu, xuất bản sáng tạo bằng sdk.assets.custom.

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

Asset spec cho phép một game định nghĩa loại tài nguyên riêng, như một màn chơi, một nhân vật hay một bộ bài, dưới dạng một hợp đồng về tệp. Khi đó người chơi có thể làm, lưu và xuất bản các sáng tạo theo định dạng đó, và những game khác hỗ trợ định dạng này có thể mở chúng.

## Định nghĩa một asset spec

Asset spec được khai báo trong danh sách `assetSpecs` của catalogue.json, cạnh `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"
  }]
}
```

Hợp đồng nêu tên các tệp của mỗi tài nguyên và cách kiểm tra chúng:

```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" }
  ]
}
```

Các vai trò có thể kèm một JSON Schema, được PlayDrop kiểm tra ở mỗi lần lưu. Hãy xuất bản một phiên bản spec mới khi định dạng thay đổi; tài nguyên cũ giữ nguyên phiên bản của chúng.

## Khai báo những gì game hỗ trợ

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

Các khả năng gồm `READ`, `WRITE`, `EDIT`, `PREVIEW` và `IMPORT`.

## Lưu và tải sáng tạo của người chơi

```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` giữ một bản nháp riêng tư; `publish` đưa nó lên công khai. Cả hai đều cần đầy đủ bộ tệp.
- Tham chiếu tài nguyên có dạng `asset:creator/name@r2`. `loadJson`, `loadText` và `downloadFile` đọc tài nguyên đã xuất bản; `loadOwned`, `loadOwnedJson` và `loadOwnedFile` đọc tài nguyên của chính người chơi, kể cả bản nháp.
- `supports(versionRef, capability)` kiểm tra trước khi mở một tài nguyên từ phiên bản khác.
- Lỗi dùng các mã như `custom_asset_capability_unsupported` và `custom_asset_role_type_mismatch`.

Người chơi cần đăng nhập để lưu. Hãy kiểm duyệt những gì người chơi xuất bản như với mọi nội dung do người dùng tạo: chính sách nội dung của PlayDrop áp dụng cho chúng.

## Những gì connector chấp nhận

Tài nguyên tùy chỉnh và spec chỉ chứa dữ liệu được tải lên như các tệp khác. Mô hình thực thi được, tức là tài nguyên `MODEL_3D` có danh mục con `procedural` hoặc định dạng `CUSTOM`, bị connector từ chối vì API không chạy mã của nhà sáng tạo; hãy bake chúng hoặc tham chiếu một phiên bản đã xuất bản. Xem [tài nguyên game](https://www.playdrop.ai/vi/create/learn/game-assets).

## Hướng dẫn liên quan

- [Tài nguyên game](https://www.playdrop.ai/vi/create/learn/game-assets): Đưa hình ảnh, âm thanh, video và 3D vào game PlayDrop: tệp đi kèm, tài nguyên do game sở hữu, tài nguyên và gói tài nguyên công khai, tra cứu lúc chạy bằng sdk.assets.
- [catalogue.json](https://www.playdrop.ai/vi/create/learn/catalogue-json): Các trường catalogue.json game PlayDrop dùng: định danh, trang giới thiệu, chế độ chơi, màn hình, đăng nhập, Instant, tải trước, media, bản dịch, điểm và máy chủ.
- [SDK client](https://www.playdrop.ai/vi/create/learn/sdk): Tài liệu tham khảo SDK trình duyệt PlayDrop: vòng đời host, danh tính và lưu game, tay cầm, xã hội, nhiều người chơi, cửa hàng, quảng cáo, bảng xếp hạng, tài nguyên, AI.