# PlayDrop 遊戲的雲端存檔

用 sdk.me.appData 與 sdk.me.updateAppData 儲存及載入玩家進度，適用於訪客與已登入玩家，並說明寫入、預覽與離線遊玩的規則。

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

雲端存檔會在 PlayDrop 上保存每位玩家在你遊戲中的進度，讓進度從網站跟著玩家到 App。每位玩家在每款遊戲中會儲存一個 JSON 物件；不需要伺服器或多人連線房間。

## 讀取與寫入

在 `init()` 之後，`sdk.me.appData` 就是已儲存的快照：`{ data, seq, ts_event, ts_arrival }`；第一次儲存前則為 `null`。從 `data` 讀取你的物件。用 `updateAppData` 寫入整個物件，它會傳回已儲存的快照並更新 `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
}
```

- 每次寫入都會取代整個已儲存的物件：請保留所有仍需要的欄位。
- 像上例一樣依序執行寫入，讓較舊的存檔絕不會在較新的存檔之後寫入，並在失敗後讓佇列繼續運作。
- 只在 promise 完成後才顯示「已儲存」。在記憶體中修改 `appData.data` 不會儲存任何內容。
- `appData` 沒有 `get`、`set` 或 `save` 方法。

## 何時儲存

在檢查點、關卡結束與購買時儲存，而不是每一幀都儲存。絕不要在預覽或擷取期間儲存：只在 `sdk.host.phase` 為 `play` 時寫入。讓存檔保持精簡，並用你自己的欄位標示版本，例如 `saveVersion: 2`，讓之後的遊戲版本可以遷移它。

## 訪客與已登入玩家

儲存前不需要檢查 `sdk.me.isLoggedIn`：PlayDrop 訪客也能保留存檔。完全沒有工作階段的玩家只會在該次造訪中把存檔保留在記憶體裡，因此寫入正常完成並不代表存檔已送達雲端。只有購買與託管多人連線等需要真實帳號的功能，才使用 `isLoggedIn`。

## 離線

在瀏覽器中，存檔需要網路連線，而且沒有離線佇列：失敗時繼續遊戲，並在下一個檢查點重試。宣告支援裝置資料的主機端（例如支援離線的 PlayDrop App）會將存檔保留在裝置上，並在連線時同步。

## 存檔不是什麼

存檔只屬於一位玩家與一款遊戲。它們與[排行榜](https://www.playdrop.ai/zh-hant/create/learn/leaderboards)和[成就](https://www.playdrop.ai/zh-hant/create/learn/achievements)分開，後兩者有各自的 API，並會顯示在 PlayDrop 上。玩家之間共享的狀態（例如一場對戰或一個世界）應放在[遊戲伺服器](https://www.playdrop.ai/zh-hant/create/learn/game-servers)上，存入你遊戲的 MongoDB 集合。

## 測試

存檔屬於已上傳的遊戲。請至少上傳一次私人版本，然後從回執的 `url`，或從[從你的 AI App 發布](https://www.playdrop.ai/zh-hant/create/learn/mcp-publishing)中說明的本機 Dev 框架進行測試。

## 相關指南

- [排行榜](https://www.playdrop.ai/zh-hant/create/learn/leaderboards): 在 catalogue.json 中宣告排行榜，用 sdk.leaderboards 提交分數，並顯示前幾名與玩家周邊的排名。包含分數類型、限制與更新規則。
- [成就](https://www.playdrop.ai/zh-hant/create/learn/achievements): 在 catalogue.json 中宣告附圖示的標準成就與累進成就，並用 sdk.achievements 解鎖成就及回報進度。
- [即時遊戲伺服器](https://www.playdrop.ai/zh-hant/create/learn/game-servers): 為你的遊戲執行附帶 MongoDB 資料庫的託管 Colyseus 0.17 伺服器，用 SDK 從瀏覽器連線，用兩位玩家測試，並了解各項限制。