# PlayDrop 游戏的云存档

用 sdk.me.appData 和 sdk.me.updateAppData 保存和读取玩家进度，适用于访客和已登录玩家，并了解写入、预览和离线游玩的规则。

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

云存档会在 PlayDrop 上保存每位玩家在你游戏中的进度，让进度从网站跟随玩家到应用中。每位玩家在每款游戏中保存一个 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 应用，会把存档保存在设备上，并在联网时同步。

## 存档不能做什么

存档仅属于一位玩家和一款游戏。它与[排行榜](https://www.playdrop.ai/zh-hans/create/learn/leaderboards)和[成就](https://www.playdrop.ai/zh-hans/create/learn/achievements)相互独立，后两者有自己的 API，并会显示在 PlayDrop 上。玩家之间共享的状态，例如一场对局或一个世界，应放在[游戏服务器](https://www.playdrop.ai/zh-hans/create/learn/game-servers)上你游戏的 MongoDB 集合中。

## 测试

存档属于已上传的游戏。请至少上传一次私密版本，然后通过回执中的 `url` 测试，或使用[从你的 AI 应用发布](https://www.playdrop.ai/zh-hans/create/learn/mcp-publishing)中介绍的本地 Dev 框架测试。

## 相关指南

- [排行榜](https://www.playdrop.ai/zh-hans/create/learn/leaderboards): 在 catalogue.json 中声明排行榜，用 sdk.leaderboards 提交分数，并显示前几名和玩家附近的排名。包括分数类型、限制和更新规则。
- [成就](https://www.playdrop.ai/zh-hans/create/learn/achievements): 在 catalogue.json 中声明带图标的普通成就和累进成就，并用 sdk.achievements 解锁成就、上报进度。
- [实时游戏服务器](https://www.playdrop.ai/zh-hans/create/learn/game-servers): 为你的游戏运行托管的 Colyseus 0.17 服务器和 MongoDB 数据库，用 SDK 从浏览器连接，用两位玩家测试，并了解各项限制。