Game Saves 離線模式

​

連線模式

​

已連線至雲端模式

• 所有 API 都能正常運作，並具備完整的雲端同步
• 存檔資料上傳如預期般運作
• 可取得儲存空間配額資訊
• 作用中裝置監視正常運作

​

離線模式 (未連線至雲端)

​

處理初始同步期間的網路失敗

// Handle sync failure callback
void MyPFGameSaveFilesUiSyncFailedCallback(PFLocalUserHandle localUserHandle, PFGameSaveFilesSyncState syncState, HRESULT error, void* context)
{
    // Tell the user something like this:
    std::cout << "We couldn't sync your data with the cloud just now" << std::endl;
    std::cout << "Try syncing again or use this game offline" << std::endl;
    std::cout << "[Try Again]" << std::endl;
    std::cout << "[Use Offline]" << std::endl;

    // if user chooses [Try Again], call PFGameSaveFilesSetUiSyncFailedResponse(localUserHandle, PFGameSaveFilesUiSyncFailedUserAction::Retry);
    // if user chooses [Use Offline], call PFGameSaveFilesSetUiSyncFailedResponse(localUserHandle, PFGameSaveFilesUiSyncFailedUserAction::UseOffline);

    // These API calls can happen inside or outside of this callback
}

• 再試一次 (Retry)：重試網路呼叫。如果重試也失敗，此回呼會再次觸發，使用者必須再次回應。在每次重試迴圈中，XAsyncBlock 回呼都會保持延遲。
• 離線使用 (UseOffline)：XAsyncBlock 回呼會以 S_OK 觸發，但系統會進入離線模式 (可使用 PFGameSaveFilesIsConnectedToCloud() 偵測)。
• 取消：XAsyncBlock 回呼會以 E_PF_GAMESAVE_USER_CANCELLED 觸發。

​

離線模式中的 API 行為

​

正常運作的 API

• PFGameSaveFilesGetFolder() - 傳回本機存檔資料夾路徑

​

功能有限的 API

• PFGameSaveFilesUploadWithUiAsync() - 立即傳回 S_OK，但非同步完成時會傳回 E_PF_GAMESAVE_DISCONNECTED_FROM_CLOUD
• PFGameSaveFilesGetRemainingQuota() - 傳回 E_PF_GAMESAVE_DISCONNECTED_FROM_CLOUD
• PFGameSaveFilesSetActiveDeviceChangedCallback() - 可以設定，但永遠不會觸發

​

返回線上模式

• 再次呼叫 PFGameSaveFilesAddUserWithUiAsync() 以嘗試重新連線
• 不需要完全重新初始化 Game Saves 系統
• 如果網路仍無法使用，會再次顯示失敗 UI
• 在重試之後，使用 PFGameSaveFilesIsConnectedToCloud() 確認連線狀態

​

Game Saves 何時會進入離線模式或傳回錯誤

• 離線模式是成功的結果，而不是錯誤。 只有在明確選擇 Use Offline 時才會進入此模式，且非同步作業會以 S_OK 完成。請使用 PFGameSaveFilesIsConnectedToCloud() 偵測此模式。
• 暫時性/技術性失敗會透過同步失敗 UI 呈現，而不是直接從 PFGameSaveFilesAddUserWithUiAsync 傳回。接著，使用者 (或您的自動回應) 會選擇 Retry、UseOffline 或 Cancel，最後解析為上述三種結果之一。
• 取消是最終結果，且不會產生存檔資料夾。 請將「已取消」(或任何未留下資料夾的失敗) 視為不允許遊玩。
• 玩家取消和遊戲取消會傳回不同的代碼。 只有玩家在提示中選擇 Cancel 才會產生 E_PF_GAMESAVE_USER_CANCELLED。如果您的遊戲自行使用 XAsyncCancel 取消作業，則會以 E_ABORT 完成。如果您想以相同方式處理兩者，請同時檢查兩者。

​

Game Saves 錯誤碼

​

其他連線狀態情境

• 同步期間網路無法使用：使用者明確選擇離線遊玩
• 作用中裝置已變更：另一部裝置接手成為作用中裝置，自動將此裝置置於離線模式

​

離線支援的最佳做法

1. 一律實作同步失敗回呼，以妥善處理網路問題
2. 在嘗試雲端作業之前，使用 PFGameSaveFilesIsConnectedToCloud() 定期檢查連線狀態
3. 在離線模式下運作時通知玩家，讓他們了解存檔不會同步
4. 在網路連線恢復時提供重試選項
5. 本機存檔一律可運作 - 無論網路狀態為何，玩家都能繼續遊玩
6. 監視中斷連線 - 請記住，當另一部裝置變成作用中時，裝置可能會中斷連線

​

已連線模式中的上傳行為

1. PFGameSaveFilesUiSyncFailedCallback 會附帶錯誤詳細資料觸發。
2. XAsyncBlock 回呼尚未觸發。在系統等候回應期間，作業會暫停。
3. 如果使用者選取 Retry，上傳會重試。如果再次失敗，回呼會再次觸發，使用者必須再次回應。
4. 如果使用者選取 Cancel，XAsyncBlock 回呼會以 E_PF_GAMESAVE_USER_CANCELLED 觸發。
5. 如果重試成功，XAsyncBlock 回呼會以 S_OK 觸發。

​

上傳何時會使工作階段離線

• 工作階段原本就處於離線狀態。 上傳不會執行，並以 E_PF_GAMESAVE_DISCONNECTED_FROM_CLOUD 完成，即使網路已恢復亦然。
• 雲端有較新的存檔。 如果服務在上傳完成時回報已從另一部裝置認可較新的存檔，Game Saves 會將工作階段置於離線狀態、觸發作用中裝置變更回呼，並以 E_PF_GAMESAVE_DISCONNECTED_FROM_CLOUD 完成上傳。
• 玩家在重新鎖定提示中選擇 Use Offline。 如果先前的上傳已認可其資料但之後失敗，下一次上傳必須先重新取得存檔鎖定。在該步驟期間出現的同步失敗提示可以用 UseOffline 回應，這會使工作階段離線，並以 E_PF_GAMESAVE_DISCONNECTED_FROM_CLOUD 完成上傳。

​

取消上傳