> ## Documentation Index
> Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Game Saves 逐步解說與範例

> XBOX Game Saves 的逐步解說，涵蓋 Partner Center 設定、安全寫入模式、離線處理、測試同步案例與遊戲移轉。

本文提供使用 Game Saves 時常見開發與移轉案例的逐步指示。內容涵蓋 Microsoft Partner Center 中的基本設定、安全寫入資料的最佳做法、平台專屬的存檔管理，以及建議的測試程序。

## Partner Center 設定

### 為您的遊戲啟用 XBOX services 與 Game Saves

若要使用 Game Saves API，請在 Partner Center 中完成下列步驟。

* 啟用 XBOX services。
  1. 登入 [Partner Center](https://partner.microsoft.com/dashboard/home)。
  2. 前往您的遊戲，然後在設定中啟用 XBOX services。如需此步驟的詳細資訊，請參閱[在 Partner Center 設定應用程式或遊戲 (適用於受管理的合作夥伴)](/zh-TW/services/xbox-services/fundamentals/portal-config/live-setup-partner-center-partners#2-contact-your-microsoft-representative-to-enable-your-app-or-game)。
* 取得您的服務設定識別碼 (SCID)。所有讀取與寫入作業都必須與 SCID 相關聯。SCID 也用於 Game Saves 初始化。
  * 在 Partner Center 中，於遊戲的 **XBOX services** > **XBOX settings** 索引標籤下找到 SCID。您也可以在此頁面上找到您的 Microsoft 帳戶 (MSA) 應用程式識別碼 (MSAAppID)。
    <img src="https://mintcdn.com/microsoft-4404708b/UZTRJSf0emX1fheE/images/gdk/features/common/partner-center-xbox-services-view.png?fit=max&auto=format&n=UZTRJSf0emX1fheE&q=85&s=7ba30f0150039b4e968e6915ad0eb4dd" alt="Partner Center 的 XBOX services 檢視。" width="622" height="293" data-path="images/gdk/features/common/partner-center-xbox-services-view.png" />

取得 SCID 與 MSAAppID 之後，將此應用程式識別碼新增至遊戲的設定 (.mgc) 檔案。

如需遊戲設定檔的詳細資訊，請參閱[建立 Microsoft Game Config .mgc](/zh-TW/build/core-features/common/game-config/MicrosoftGameConfig-Overview)。

## 開發案例

### 我應該在程式碼的哪裡整合 Game Saves？

Game Saves 邏輯取決於使用者登入。請將 Game Saves 程式碼加在使用者登入流程旁邊。

### 如何確保我的遊戲存檔資料不會損毀？

若要安全地儲存資料並避免損毀，請遵循下列步驟。此指引適用於所有存檔作業。

1. 寫入暫存檔案。
   * 將存檔資料序列化到新檔案 (例如 `save.tmp`)，而不是覆寫目前使用中的存檔。此步驟可在處理程序於寫入途中遭到中斷時，保護現有的存檔。
2. 在寫入完全認可到磁碟之後，關閉寫入控制代碼。
3. 使用 Win32 [ReplaceFile](https://learn.microsoft.com/windows/win32/api/winbase/nf-winbase-replacefilea)，以不可部分完成的方式將舊存檔檔案取代為新的暫存檔案。

### 如何支援離線裝置？

您必須負責決定在初始化 Game Saves 之前與之後發生連線中斷時，遊戲的行為方式。

如需離線行為的詳細資訊，請參閱[了解 Game Saves 同步流程](/zh-TW/build/core-features/common/game-save/game-saves-syncing#connection-check)。

### 我需要注意哪些使用者互動？

當動作需要使用者輸入時，作業系統會顯示系統提示。如需這些提示的資訊，請參閱 [Game Saves 對話方塊](/zh-TW/build/core-features/common/game-save/game-saves-dialogues)。

### 是否有方法可以只在本機與裝置上儲存？

如果您將 `null` 使用者控制代碼傳遞給 Game Save 初始化程序，系統會建立僅限機器的提供者。資料會儲存在本機並保留在裝置上，上限為 256 MB。資料不會同步到雲端。

如需 Game Saves 儲存空間的詳細資訊，請參閱 [Game Saves 儲存系統](/zh-TW/build/core-features/common/game-save/game-saves-storage-systems)。

### 透過裝置管理遊戲存檔

#### 使用檔案總管存取 PC 上的本機遊戲存檔

如果您的遊戲在 PC 上執行，您可以直接存取檔案。視 Game Saves API 的實作而定，您可以在下列位置存取本機遊戲存檔。

| Game Saves API | 檔案路徑 |
| :- | :- |
| XGameSaveFiles | `%AppData%\Local\Packages\<PACKAGE_NAME>\SystemAppData\xgs\<HexXuid>_<Scid>\` |
| XGameSave | `%AppData%\Local\Packages\<PACKAGE_NAME>\SystemAppData\wgs\<HexXuid>_<Scid>\` |

當您在 PC 上操作資料時，同步邏輯仍然適用。例如，在遊戲沒有鎖定時修改資料會造成衝突。

#### 存取主機上的本機遊戲存檔

透過 XBOX UI 管理主機存檔資料。請使用下列步驟存取。

1. 選取 XBOX 控制器上的**首頁**按鈕。
2. 選取 **我的遊戲和應用程式** > **查看全部**。
3. 將游標停留在您的遊戲上，然後選取**檢視**按鈕。
4. 選取**已儲存的資料**。

<img src="https://mintcdn.com/microsoft-4404708b/sIrPFR_ir_sNKVEv/images/gdk/features/common/console-storage-management.png?fit=max&auto=format&n=sIrPFR_ir_sNKVEv&q=85&s=1440050534d3c4d168d1e964d3638afe" alt="主機儲存空間的 Game Saves 管理檢視。" width="1314" height="377" data-path="images/gdk/features/common/console-storage-management.png" />

直接在主機上操作資料時，請考慮下列事項。

* 使用系統 UI 刪除主機上的資料並不會移除儲存在雲端的複本。再次啟動遊戲時，遊戲會從雲端同步資料。
* 機器提供者資料會顯示為沒有名稱的使用者。此資料會保留在裝置上，不會同步到雲端，且繫結到裝置。

如需機器提供者的詳細資訊，請參閱 [Game Saves 儲存系統](/zh-TW/build/core-features/common/game-save/game-saves-storage-systems#game-saves-storage-systems)。

若要更詳細地控制遊戲存檔，請使用 [Game Saves 工具](/zh-TW/build/core-features/common/game-save/game-saves-tools#manipulating-game-saves)。

## 測試案例

建立測試案例時，請將資料驗證與遊戲存檔邏輯分開。

### 測試遊戲存檔是否正確地與雲端同步

使用下列步驟測試同步是否正確。測試流程會驗證行為。

`XGameSaveFiles`：

1. 確認 SCID 正確。
2. 確認您使用的是正確的使用者控制代碼。
3. 確認遊戲在目前的遊戲工作階段期間呼叫 `XGameSaveFilesGetFolderWithUIAsync`。如果遊戲從暫停狀態繼續，請呼叫此函式。
   1. 使用 Fiddler 確認已取得鎖定。
   2. 儲存此路徑，稍後用來確認資料正在上傳。
4. 將一些資料寫入 `XGameSaveFilesGetFolderWithUIAsync` 提供的檔案路徑。
5. 終止或暫停遊戲。
6. 等待 10 到 30 秒，讓作業系統自動將資料上傳到雲端並釋放鎖定。
   1. 使用 Fiddler 確認資料已上傳且鎖定已釋放。
7. 手動刪除 `XGameSaveFilesGetFolderWithUIAsync` 提供之資料夾中的資料。
   1. 在主機上，透過玩家設定存取此資料。
8. 再次啟動遊戲，然後嘗試讓使用者登入。
9. 會出現同步對話方塊，顯示正在從雲端進行下載同步。

若要協助測試同步是否成功，請參閱下列資源：

* [用於檢查流量與操作存檔的 Game Saves 工具](/zh-TW/build/core-features/common/game-save/game-saves-tools)
* [了解 Game Saves 同步流程](/zh-TW/build/core-features/common/game-save/game-saves-syncing)

### 測試遊戲存檔是否正確漫遊

如需確認資料是否漫遊的測試計畫，請參閱 [XR-052-06 測試計畫](https://learn.microsoft.com/build/store/policies/XR/XR052#052-06-cloud-storage-roaming)。

## 移轉案例

### 在遊戲之間共用遊戲存檔

若要從一個遊戲將資料轉移到另一個遊戲或存取其資料，請完成兩個步驟。

1. 在 Partner Center 中修改您要存取之遊戲的存取原則。
2. 在原始程式碼中為兩個遊戲初始化 Game Saves 提供者。

#### 修改存取原則

遊戲會透過設定存取原則，控制哪些遊戲可以存取其遊戲存檔資料。

1. 前往 [Partner Center](https://partner.microsoft.com/dashboard)。
2. 選取 **Apps and games** > **\<您的遊戲>** > **Gameplay settings**。
3. 在 **Gameplay Settings** 中選取 **Access Policies**，然後展開 **Connected Storage**。
4. 選取 **Add app/service**，然後新增您要提供存取權的遊戲。
5. 新增完遊戲後，選取 **Save**，然後選取 **Publish**。變更會在一小時內生效。

下列螢幕擷取畫面顯示讓 GameSaveSample 遊戲可完整存取 GameSaveFilesCombo 遊戲的範例。

<img src="https://mintcdn.com/microsoft-4404708b/UZTRJSf0emX1fheE/images/gdk/features/common/partner-center-access-policy.png?fit=max&auto=format&n=UZTRJSf0emX1fheE&q=85&s=25eae43c7e7d88b824558596d849cbfa" alt="用於修改遊戲存取原則的 Partner Center 檢視。" width="1280" height="598" data-path="images/gdk/features/common/partner-center-access-policy.png" />

#### 初始化 Game Save 提供者

現在您已獲得存取第一個遊戲的權限，可以從另一個遊戲讀取 `XGameSave` 資料。

* 如果您使用 `XGameSave`，請為每個遊戲呼叫 `XGameSaveInitializeProvider` 或 `XGameSaveInitializeProviderAsync`。
* 如果您使用 `XGameSaveFiles`，提供者會隱含地初始化。請為每個遊戲呼叫 `XGameSaveFilesGetFolderWithUiAsync`。

### XGameSave 與 XGameSaveFiles 之間的互通性

遊戲可能需要同時使用 `XGameSave` 與 `XGameSaveFiles`。常見原因可能如下：

* 發行者在主機上已有使用 `XGameSave` 的現有遊戲。
* 發行者不想將該現有遊戲更新為使用 `XGameSaveFiles`。
* 發行者認為將 `XGameSaveFiles` 新增至 PC 遊戲比使用 `XGameSave` 容易，但仍希望支援 PC、主機與 XBOX 遊戲串流之間的跨平台存檔。

在 `XGameSave` 與 `XGameSaveFiles` 之間移動相當簡單。當遊戲呼叫 [XGameSaveFilesGetFolderWithUiAsync](/zh-TW/reference/system/xgamesavefiles/functions/xgamesavefilesgetfolderwithuiasync) 時，會使用下列規則將容器與 Blob 對應到目錄與檔案：

* 容器名稱中的任何正斜線 (/) 都會建立檔案所在的目錄結構。
* 下列字元對 `XGameSaveFiles` 而言無效。如果系統遇到這些字元，會將其對應為底線 (\_)：
  * 從 \0 到 \001f (含) 的字元。
* 下列字元對 `XGameSaveFiles` 而言無效。如果系統遇到這些字元，會將其對應為句點 (.)：
  * 引號 (")
  * 小於符號 (\<)
  * 大於符號 (>)
  * 管道符號 (|)
  * 星號 (\*)
  * 問號 (?)
  * 反斜線 (\\)
* Blob 名稱中的斜線 (/) 會對應為檔案名稱中的句點 (.)。
* 檔案上限為 16 MB。`XGameSave` 支援的上傳大小上限為 16 MB。

當遊戲從 `XGameSaveFiles` 移回 `XGameSave` 時，如果檔案名稱保持不變或未移動，就會還原原始的容器與 Blob 名稱。

### 使用無程式碼雲端存檔將先前的遊戲移植到 PC Game Saves

您移植到 PC Game Pass 的某些遊戲可能需要無程式碼雲端存檔解決方案。在下列案例中可能會有此需求：

* 遊戲以 x86 應用程式的形式執行。它只以封裝形式使用 Microsoft Game Development Kit (GDK)。
* 遊戲在沒有自訂程式碼的情況下建立，使用 Unreal Engine 中的 Blueprint 或 Unity 中的 Bolt 等工具。

使用無程式碼雲端存檔的遊戲會透過標準 Win32 檔案 I/O API 讀取與寫入其指定的存檔目錄。系統會自動同步資料。您不需要撰寫特殊程式碼來處理同步與上傳。同步會在遊戲啟動之前進行。

無程式碼雲端存檔會在遊戲不再於 PC 上執行時上傳。符合下列其中一個條件時就會上傳：

* 遊戲遭到終止。
* 追蹤的使用者登出。
* PC 電源狀態變更。
* 自遊戲上次寫入指定的存檔區域後已經過 30 分鐘。

無程式碼雲端存檔解決方案建置在 `XGameSaveFiles` 之上，並共用其在檔案大小與每位使用者儲存空間限制方面的所有限制。檔案上限為 64 MB (如果需要與 `XGameSave` 或 Connected Storage 互通，則為 16 MB)。根據預設，每位使用者的儲存空間上限為 256 MB。需要更大每位使用者儲存空間上限的遊戲，可以與其開發人員合作夥伴經理 (DPM) 合作申請例外。

<Note>
  目錄與檔案名稱有特定的命名慣例與字元限制。如需詳細資訊，請參閱 [XGameSaveFiles 路徑邏輯](/zh-TW/build/core-features/common/game-save/xgamesavefiles#xgamesavefiles-path-logic)。
</Note>

無程式碼雲端存檔僅在 PC 上受支援。遊戲需要使用[簡化使用者模型](/zh-TW/build/core-features/common/user/users-opting-into-simplified-model)。它可確保在遊戲啟動之前已有使用者登入。如果無法讓使用者登入遊戲，遊戲就不會啟動。如果使用者在遊玩期間登出，遊戲會遭到終止。

<Info>
  無程式碼雲端存檔需要使用 `wdapp install` 將遊戲以封裝組建的形式啟動。直接啟動 `.exe` 不會啟用雲端存檔重新導向。

  封裝組建執行時，透過 `NoCodePCRoot` 寫入的存檔會重新導向到由 `XGameSaveFiles` 管理的儲存空間。之後直接啟動 `.exe` 時，會改為讀取實體的 `NoCodePCRoot` 資料夾，而該資料夾可能是空的，導致存檔看起來遺失了。若要避免此問題，請一律使用 `wdapp install` 以封裝組建測試無程式碼雲端存檔。
</Info>

### 啟用無程式碼雲端存檔

若要啟用無程式碼雲端存檔，請完成下列步驟：

1. 修改您的 `MicrosoftGame.config` 檔案。
2. 啟用簡化使用者模型。
3. 指定存檔檔案的根資料夾。
4. 提供遊戲對應的 SCID。

下列程式碼範例示範此程序。

```xml theme={null}
<Game configVersion="1">
   <Identity Name="SampleNameOne" Publisher="CN=NoPublisher"/>
   <SaveGameStorage>
      <NoCodePCRoot RelativeTo="SavedGames">test\path</NoCodePCRoot>
      <SCID>DF9D8061-4790-4B84-86B4-CD060B00B4DD</SCID>
      <MaxUserQuota>256</MaxUserQuota>
   </SaveGameStorage>
   <!-- Content removed for brevity -->
   
   <!-- Must also opt into requiring a default user at launch -->
   <AdvancedUserModel>false</AdvancedUserModel>
</Game>
```

您為 `NoCodePCRoot` 指定的根資料夾必須相對於少數幾個選項之一。

| RelativeTo | PC 上的資料夾位置 |
| - | - |
| `AppData` | 對應到環境變數 %APPDATA% |
| `Public` | 對應到環境變數 %PUBLIC% |
| `LocalAppData` | 對應到環境變數 %LOCALAPPDATA% |
| `LocalAppDataLow` | 對應到 %USERPROFILE%\AppData\LocalLow |
| `ProgramData` | 對應到環境變數 %PROGRAMDATA% |
| `SavedGames` | 對應到 %USERPROFILE%\Saved Games |
| `UserProfile` | 對應到環境變數 %USERPROFILE% |

<Info>
  請使用 `SavedGames` 作為 `RelativeTo` 值。Saved Games 資料夾 (`%USERPROFILE%\Saved Games`) 對應到 Windows 已知資料夾識別碼 `FOLDERID_SavedGames`。根據預設，OneDrive 不會同步此資料夾。

  請避免使用其他位置，例如 `AppData` (`%APPDATA%`)。OneDrive 可能會同步這些位置，並可能與雲端存檔同步發生衝突。

  如需 `FOLDERID_SavedGames` 的詳細資訊，請參閱 [SHGetKnownFolderPath](https://learn.microsoft.com/windows/win32/api/shlobj_core/nf-shlobj_core-shgetknownfolderpath)。
</Info>

*您無法將檔案直接放在根目錄中*。請將檔案巢狀放置在根資料夾下至少一個子資料夾內。例如，直接使用檔案名稱 (如 `<NoCodePCRoot RelativeTo="SavedGames">savegame1.sav</NoCodePCRoot>`) 是無效的，因為 savegame1.sav 會被忽略。`<NoCodePCRoot>` 的用途是定義目錄路徑，而不是特定檔案。

## 程式碼範例

* [GameSaveCombo](https://learn.microsoft.com/samples/microsoft/xbox-gdk-samples/gamesavecombo/)
* [GameSaveFilesCombo](https://learn.microsoft.com/samples/microsoft/xbox-gdk-samples/gamesavefilescombo/)

## 參考 API 文件

* [XGameSaveFiles (API 內容)](/zh-TW/reference/system/xgamesavefiles/xgamesavefiles_members)
  * 函式
    * [XGameSaveFilesGetFolderWithUiAsync](/zh-TW/reference/system/xgamesavefiles/functions/xgamesavefilesgetfolderwithuiasync)

## 另請參閱

[Game Saves 目錄](/zh-TW/build/core-features/common/game-save/game-saves-toc)


## Related topics

- [使用 GDKX 建置並執行你的第一個主機遊戲](/zh-TW/home/build-first-title/first-console-title-walkthrough.md)
- [開發新的 GDK 遊戲](/zh-TW/home/build-first-title/developing-new-titles.md)
- [認證 (Certify)](/zh-TW/publishing/game-publishing/concepts/certification/certification-overview.md)
- [Direct3D 12 程式設計指南](/zh-TW/build/gdk-and-engines/guides/directx-12-programming-guide.md)
- [認證逐步指南](/zh-TW/publishing/game-publishing/concepts/certification/certification-guide.md)