# Lưu đám mây cho game PlayDrop

Lưu và tải tiến trình người chơi bằng sdk.me.appData và updateAppData, cho khách và người chơi đã đăng nhập, kèm quy tắc ghi, xem trước và chơi ngoại tuyến.

Source: https://www.playdrop.ai/vi/create/learn/cloud-saves

Lưu đám mây giữ tiến trình của từng người chơi trong game của bạn trên PlayDrop, để tiến trình đi theo họ từ trang web đến các ứng dụng. Mỗi người chơi và mỗi game được lưu một đối tượng JSON; không cần máy chủ hay phòng nhiều người chơi.

## Đọc và ghi

Sau `init()`, `sdk.me.appData` là ảnh chụp trạng thái đã lưu: `{ data, seq, ts_event, ts_arrival }`, hoặc `null` trước lần lưu đầu tiên. Đọc đối tượng của bạn từ `data`. Ghi toàn bộ đối tượng bằng `updateAppData`, phương thức này trả về ảnh chụp trạng thái đã lưu và cập nhật `sdk.me.appData`.

```js
const sdk = await playdrop.init();
let progress = { level: 1, coins: 0, ...(sdk.me.appData?.data ?? {}) };
let queue = Promise.resolve();

// Resolves with the saved snapshot; rejects when the save failed.
function save(changes) {
  progress = { ...progress, ...changes };
  const snapshot = { ...progress };
  const attempt = queue.then(() => sdk.me.updateAppData(snapshot));
  queue = attempt.catch(() => {}); // a failed save must not block the next one
  return attempt;
}

try {
  await save({ level: 2 });
  showSaved();
} catch (error) {
  showSaveError(); // progress stays in memory; the next save sends it again
}
```

- Mỗi lần ghi thay thế toàn bộ đối tượng đã lưu: hãy giữ lại mọi trường bạn vẫn cần.
- Thực hiện các lần ghi tuần tự như trên, để một lần lưu cũ không bao giờ ghi đè lên lần lưu mới hơn, và giữ hàng đợi tiếp tục chạy sau khi có lỗi.
- Chỉ hiển thị “Đã lưu” sau khi promise hoàn tất. Thay đổi `appData.data` trong bộ nhớ không lưu gì cả.
- `appData` không có các phương thức `get`, `set` hay `save`.

## Khi nào nên lưu

Hãy lưu ở các điểm kiểm tra, cuối màn và khi mua hàng thay vì ở mỗi khung hình. Không bao giờ lưu trong bản xem trước hay khi ghi hình: chỉ ghi khi `sdk.host.phase` là `play`. Giữ dữ liệu lưu nhỏ gọn và có phiên bản bằng trường của riêng bạn, chẳng hạn `saveVersion: 2`, để phiên bản game sau này có thể chuyển đổi nó.

## Khách và người chơi đã đăng nhập

Bạn không cần kiểm tra `sdk.me.isLoggedIn` trước khi lưu: khách trên PlayDrop cũng giữ được dữ liệu lưu. Một người chơi hoàn toàn không có phiên sẽ giữ dữ liệu lưu trong bộ nhớ cho lượt truy cập đó, nên một lần ghi hoàn tất không chứng minh dữ liệu đã lên đám mây. Chỉ dùng `isLoggedIn` cho các tính năng cần tài khoản thật, như mua hàng và chơi nhiều người trên máy chủ được lưu trữ.

## Ngoại tuyến

Trong trình duyệt, việc lưu cần kết nối mạng và không có hàng đợi ngoại tuyến: hãy tiếp tục cho chơi khi lưu thất bại và thử lại ở điểm kiểm tra tiếp theo. Các host có hỗ trợ dữ liệu trên thiết bị, như các ứng dụng PlayDrop chơi được ngoại tuyến, giữ dữ liệu lưu trên thiết bị và đồng bộ khi có mạng.

## Dữ liệu lưu không dùng cho việc gì

Dữ liệu lưu là riêng tư với một người chơi và một game. Nó tách biệt với [bảng xếp hạng](https://www.playdrop.ai/vi/create/learn/leaderboards) và [thành tích](https://www.playdrop.ai/vi/create/learn/achievements), vốn có API riêng và hiển thị trên PlayDrop. Trạng thái dùng chung giữa nhiều người chơi, như một trận đấu hay một thế giới, thuộc về [máy chủ game](https://www.playdrop.ai/vi/create/learn/game-servers), trong các collection MongoDB của game bạn.

## Thử nghiệm

Dữ liệu lưu thuộc về một game đã tải lên. Hãy tải lên một phiên bản riêng tư ít nhất một lần, rồi thử từ `url` của biên nhận hoặc từ khung Dev cục bộ được mô tả trong [xuất bản từ ứng dụng AI của bạn](https://www.playdrop.ai/vi/create/learn/mcp-publishing).

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

- [Bảng xếp hạng](https://www.playdrop.ai/vi/create/learn/leaderboards): Khai báo bảng xếp hạng trong catalogue.json, gửi điểm bằng sdk.leaderboards, hiển thị hạng đầu và người chơi xung quanh. Loại điểm, giới hạn và quy tắc cập nhật.
- [Thành tích](https://www.playdrop.ai/vi/create/learn/achievements): Khai báo thành tích thường và thành tích tích lũy kèm biểu tượng trong catalogue.json, mở khóa và báo tiến trình bằng sdk.achievements.
- [Máy chủ game thời gian thực](https://www.playdrop.ai/vi/create/learn/game-servers): Chạy máy chủ Colyseus 0.17 được lưu trữ kèm cơ sở dữ liệu MongoDB cho game, kết nối từ trình duyệt bằng SDK, thử với hai người chơi và nắm rõ giới hạn.