遊戲體驗

PlayDrop 遊戲的雲端存檔

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

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

讀取與寫入

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

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）會將存檔保留在裝置上，並在連線時同步。

存檔不是什麼

存檔只屬於一位玩家與一款遊戲。它們與排行榜和成就分開，後兩者有各自的 API，並會顯示在 PlayDrop 上。玩家之間共享的狀態（例如一場對戰或一個世界）應放在遊戲伺服器上，存入你遊戲的 MongoDB 集合。

測試

存檔屬於已上傳的遊戲。請至少上傳一次私人版本，然後從回執的 url，或從從你的 AI App 發布中說明的本機 Dev 框架進行測試。