# Xuất bản game từ ứng dụng AI của bạn với PlayDrop MCP

Cách agent AI xuất bản lên PlayDrop qua MCP: cách đơn giản và cách dùng gói, thử riêng tư, publish_game_version, cập nhật, giới hạn và khôi phục.

Source: https://www.playdrop.ai/vi/create/learn/mcp-publishing

Máy chủ MCP của PlayDrop cho phép một ứng dụng AI xuất bản game lên tài khoản PlayDrop của người dùng và trả về một liên kết vẫn hoạt động qua mọi bản cập nhật. Hướng dẫn này trình bày thứ tự các bước. Mỗi bước liên kết đến hướng dẫn có đầy đủ chi tiết.

## Trước khi xây dựng

1. Gọi `get_documentation({topic:"index"})` và đọc hướng dẫn cho các tính năng game sẽ dùng, trước khi viết mã. Lên kế hoạch cho bố cục toàn màn hình, dữ liệu lưu và cách điều khiển ngay từ đầu giúp tránh phải viết lại game sau này. Để biết chính xác chữ ký phương thức, hãy đọc các chủ đề `sdk-types`, `server-sdk-types` và `shared-types`.
2. Gọi `list_games`. Nếu game đã tồn tại, bạn sẽ cập nhật nó và giữ nguyên `name`, để game giữ liên kết và người chơi của mình.
3. Chọn cách xuất bản. Một tệp HTML khép kín không dùng SDK PlayDrop thì đi theo [cách đơn giản](https://www.playdrop.ai/vi/create/learn/html-games). Mọi trường hợp khác, kể cả bất kỳ tính năng SDK nào, media giới thiệu hay máy chủ, đều dùng [một gói](https://www.playdrop.ai/vi/create/learn/packaging).

Hãy tự giữ dự án mã nguồn của nhà sáng tạo. PlayDrop chỉ nhận bản dựng: đây không phải nơi sao lưu mã nguồn và không thể trả lại mã nguồn.

## Cách đơn giản: upload_game

Gửi `requestId`, toàn bộ HTML (tối đa 10 MiB, tức 10.485.760 byte UTF-8) và một catalogue rút gọn. Truyền `gameId` để cập nhật một game hiện có. Số phiên bản tự động tăng. Xem [game HTML đơn giản](https://www.playdrop.ai/vi/create/learn/html-games) để biết các trường.

## Cách dùng gói: chuẩn bị, tải lên, hoàn tất

Gọi `prepare_catalogue_upload` với `requestId`, `expectedCurrentVersion` và một trong các dạng đầu vào sau:

- **Thư mục:** `catalogue` (nội dung của catalogue.json) cùng `files`, mỗi tệp một bộ mô tả kèm đường dẫn tương đối. Một bộ mô tả mang `text` nội tuyến, thông tin tải lên có chữ ký, một liên kết tới tệp đính kèm hoặc `reuse` một tệp từ phiên bản được lưu giữ.
- **ZIP hoặc .play cục bộ:** giải nén nó trên máy, rồi gửi catalogue ở thư mục gốc và các bộ mô tả thư mục. Không bao giờ đưa các byte lưu trữ dạng base64 vào lệnh gọi công cụ.
- **Tệp đính kèm ChatGPT:** truyền tệp ZIP hoặc .play mà host đã phân giải dưới dạng `archive`, với `download_url` và `file_id` thật của nó. Tệp có thể lên đến 20 MiB khi nén và cần catalogue.json ở thư mục gốc.

Với tải lên có chữ ký, mỗi bộ mô tả cung cấp `path`, `contentType`, `sizeBytes`, `sha256` (64 ký tự hex viết thường) và `md5Base64`, được tính trên máy từ chính xác các byte của tệp. PUT các byte đó lên từng URL được trả về kèm mọi header được trả về, rồi gọi `complete_catalogue_upload` với cùng `requestId`.

Trong ChatGPT, các tệp của thư mục có thể lấy từ tệp đính kèm, được gắn theo vị trí:

```
attachments: [htmlFile, iconFile]
files: [{path:"index.html", attachmentIndex:0}, {path:"listing/icon.png", attachmentIndex:1, role:"LISTING", app:"my-game"}]
```

Mỗi ứng dụng cần một `version` đã khai báo, một chế độ hiển thị (trên yêu cầu hoặc trên ứng dụng) và một mục trong `expectedCurrentVersion` với khóa là tên của nó: `null` để tạo mới, hoặc phiên bản đang xuất bản lấy từ `list_games` để cập nhật. Giá trị đã lỗi thời sẽ bị từ chối, nên một lần tải lên khác không bao giờ bị ghi đè do vô tình.

## Thử riêng tư, rồi phát hành

Hãy tải lên với `visibility: "private"` khi game dùng SDK hoặc máy chủ, hoặc khi người dùng của bạn muốn thử trước. Mở `url` của biên nhận để chơi đúng phiên bản đó bên trong PlayDrop với host SDK thật. Các chức năng của máy chủ được lưu trữ chỉ chạy trên phiên bản đã tải lên, vì vậy hãy thử chúng theo cách này.

Khi mọi thứ hoạt động, hãy phát hành đúng phiên bản đó bằng `publish_game_version`, truyền `gameId`, `version`, `expectedCurrentVersion` và, nếu người dùng của bạn đã chọn, `visibility` (`public` hoặc `unlisted`). Lệnh này dùng lại tệp, trang giới thiệu và kết quả kiểm duyệt đã được thử. Đừng tải game lên lại để phát hành nó.

Để thử một bản dựng cục bộ trong khung PlayDrop trước khi tải lên, hãy mở `https://www.playdrop.ai/@<username>/<slug>/dev?url=<URL-encoded local address>` trong một trình duyệt thông thường trên chính máy đang chạy máy chủ cục bộ.

## Chọn ai có thể chơi

`visibility` chấp nhận `public`, `unlisted` và `private`. Với game mới mà người dùng chưa chọn, hãy dùng cài đặt đã lưu của nhà sáng tạo: `upload_game` áp dụng cài đặt này khi bạn bỏ chế độ hiển thị, và `get_account` hiển thị nó dưới dạng `publishing.defaultVisibility`. Với một bản cập nhật, hãy giữ `gameVisibility` của game lấy từ `list_games` trừ khi người dùng của bạn thay đổi nó; `upload_game` tự làm điều này khi bạn bỏ chế độ hiển thị, còn một gói thì phải nêu rõ. Không công khai nghĩa là bất kỳ ai có liên kết đều chơi được; đó không phải danh sách bạn bè. Không bao giờ làm một game hiển thị rộng hơn ý định của người dùng. Chi tiết: [ai có thể chơi](https://www.playdrop.ai/vi/create/learn/distribution).

## Gửi lại đúng liên kết

Biên nhận của game công khai và không công khai có `shareUrl`, trang lâu dài của game: hãy đưa liên kết này cho người dùng của bạn. Một phiên bản riêng tư trả về `url`, liên kết tới đúng phiên bản đó dành cho chủ sở hữu. Biên nhận của gói liệt kê từng mục; các mục đã hoàn tất vẫn được xuất bản ngay cả khi một mục sau đó thất bại.

## Cập nhật game

Đọc `list_games` và phiên bản hiện tại, giữ nguyên `name`, và gửi một bản chụp đầy đủ: mọi tệp và toàn bộ metadata dự định, vì các trường bị bỏ qua sẽ không có trong phiên bản mới. Các mục catalogue bị bỏ qua không bao giờ bị xóa. Dùng `get_game_version` để đọc chính xác catalogue của phiên bản bạn đang thay đổi, kể cả trạng thái các giá trị tinh chỉnh của nó.

## Giới hạn

- Cách đơn giản: một tệp HTML tối đa 10 MiB.
- Gói: 512 bộ mô tả tệp thư mục hoặc 512 mục trong tệp nén (kể cả catalogue.json và các thư mục), 50 MiB mỗi tệp, tổng cộng 200 MiB khi giải nén và 1 MiB JSON catalogue.
- Tệp nén: chỉ chấp nhận đường dẫn tương đối an toàn; đường dẫn trùng lặp, liên kết tượng trưng, tệp nén mã hóa, nhiều phần và ZIP64 đều bị từ chối.
- Các lần tải lên đã chuẩn bị hết hạn sau 30 phút.

## Lỗi và thử lại

Lỗi mang `error`, `message`, `retryable`, `nextAction`, `docsUrl` và `documentationTopic`. Hãy làm theo `nextAction`. Sau khi mất phản hồi, hãy thử lại với nội dung y hệt và cùng `requestId`; nội dung đã thay đổi cần một ID mới. Xem [lỗi và cách khôi phục](https://www.playdrop.ai/vi/create/learn/errors).

Dùng `send_feedback` để báo một sự cố tái hiện được hoặc một bước gây khó hiểu, không kèm token hay URL có chữ ký.

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

- [Game HTML đơn giản](https://www.playdrop.ai/vi/create/learn/html-games): Xuất bản một tệp HTML khép kín tối đa 10 MiB bằng upload_game: những gì phù hợp, catalogue rút gọn, chế độ hiển thị, cập nhật và khi nào chuyển sang gói.
- [Đóng gói và .play](https://www.playdrop.ai/vi/create/learn/packaging): Sắp xếp thư mục game đã dựng, tệp ZIP hoặc .play có catalogue.json ở thư mục gốc, khai báo media giới thiệu, máy chủ, rồi tải lên bằng prepare_catalogue_upload.
- [Chế độ hiển thị và tiếp cận](https://www.playdrop.ai/vi/create/learn/distribution): Chọn ai mở được game PlayDrop, cách hoạt động của cài đặt mặc định và việc xuất bản phiên bản, cùng cách Boost, Trao đổi lượt chơi, Instant, tìm kiếm đem về người chơi.
- [Lỗi và cách khôi phục](https://www.playdrop.ai/vi/create/learn/errors): Cấu trúc lỗi mà các công cụ MCP của PlayDrop trả về, khi nào thử lại với cùng requestId, và cách khắc phục từng mã lỗi thường gặp.