> ## 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.

# 使用 2025 年 10 月 GDK 實作 Game Saves

> 使用 2025 年 10 月 GDK (2510) 實作 PlayFab Game Saves 的重要指南，包括新實作的需求和移轉指引

> [!NOTE]
>
> 本指南涵蓋使用 2025 年 10 月 GDK (版本 2510) 實作 PlayFab Game Saves。無論您是 Game Saves 的新手，還是正從先前的實作進行移轉，本文件都會提供基本需求和設定指示，並特別關注 Steam Deck 支援。

## 實作需求概觀

使用 2025 年 10 月 GDK 實作 PlayFab Game Saves 時，您需要了解四個關鍵元件：

1. **新的 GDK 資料夾配置**：以平台為中心的 SDK 目錄結構
2. **XGameRuntime 整合**：具有特定部署需求的跨平台執行階段
3. **PlayFab Unified SDK**：適用於所有 PlayFab 元件的現代 SDK 架構
4. **其他 Unified SDK 元件**：更新的 Party 和 Multiplayer 元件 (如有使用)

對於 2025 年 10 月 GDK 及更新版本的所有 Game Saves 實作 (包括 Steam Deck 支援)，前三個元件都是**必要的**。第四個元件只有在您的遊戲使用 PlayFab Party 或 Multiplayer 功能時才適用。

> [!NOTE]
>
> \*\*初次使用 Game Saves？\*\*請從 [Game Saves 概觀](/zh-TW/services/playfab/player-progression/game-saves/overview)和[快速入門指南](/zh-TW/services/playfab/player-progression/game-saves/quickstart)開始了解基本概念，然後返回此處取得 2025 年 10 月 GDK 特定的實作詳細資料。

## 1. GDK 資料夾配置和路徑設定

### 目前的 GDK 結構

2025 年 10 月 GDK 使用扁平、以平台為中心的目錄結構。了解此配置對於正確設定建置系統至關重要。

**2025 年 10 月 GDK 配置**：

```
\Microsoft GDK\251000\windows\include
\Microsoft GDK\251000\xbox\lib\x64
\Microsoft GDK\251000\xbox\bin\x64
```

\*\*從較早的 GDK 移轉？\*\*先前的資料夾結構 (`$(GDK)\GRDK\ and $(GDK)\GXDK\`) 已被取代。請相應地更新您的建置指令碼。

### 設定您的建置系統

#### 必要的路徑設定

設定您的建置系統以使用正確的平台特定路徑：

#### 建置系統設定範例

**CMake 設定**：

```cmake theme={null}
# Configure GDK paths for your target platform
if(CMAKE_SYSTEM_NAME STREQUAL "Windows")
    set(GDK_INCLUDE_DIR "${GDK_PATH}/windows/include")
    set(GDK_LIB_DIR "${GDK_PATH}/windows/lib/x64")
elseif(XBOX)
    set(GDK_INCLUDE_DIR "${GDK_PATH}/xbox/include")
    set(GDK_LIB_DIR "${GDK_PATH}/xbox/lib/x64")
endif()
```

**MSBuild 設定**：

```xml theme={null}
<!-- Set include paths for Game Saves development -->
<IncludePath>$(GDK)\windows\include;$(IncludePath)</IncludePath>
<LibraryPath>$(GDK)\windows\lib\x64;$(LibraryPath)</LibraryPath>
```

#### 平台支援詳細資料

* **XBOX**：所有近代 XBOX 主機世代都使用 `xbox` 資料夾
* **Windows**：所有 Windows 平台 (PC、Steam PC、Steam Deck-Proton) 都使用 `windows` 資料夾
* **Steam Deck**：雖然執行 SteamOS，但為了與 Proton 模擬相容，使用 `windows` 資料夾

### 實作步驟

1. **設定您的建置系統**
   * 使用新的 GDK 結構設定 include 和程式庫路徑
   * 如果以多個平台為目標，請新增平台偵測邏輯
   * 在所有目標平台上測試編譯

2. **驗證 Game Saves 整合**
   * 確保所有必要的程式庫都正確連結
   * 在您的目標平台上測試功能
   * 確認 PlayFab 服務連線

## 2. XGameRuntime 整合

### 了解 XGameRuntime

XGameRuntime 為所有平台上的 XBOX Live 服務和 Game Saves 功能提供基礎。以下是您需要了解的內容：

#### 核心元件

**xgameruntime.lib (匯入程式庫)**

* 在編譯時連結至您的遊戲專案
* 自動找到並載入執行階段 DLL
* 處理服務探索 (本機與系統)

**xgameruntime.dll (執行階段程式庫)**

* 實作 XBOX Live 和 Game Saves 功能
* 位置：`{GDK}\windows\bin\xgameruntime.dll`
* **對 Steam 組建至關重要**：必須與您的遊戲一起部署

### 實作需求

#### 1. 基本整合

所有 Game Saves 實作都需要初始化 XGameRuntime：

```cpp theme={null}
// Initialize XGameRuntime - required for all Game Saves implementations
HRESULT hr = XGameRuntimeInitialize();
if (FAILED(hr)) {
    // Handle initialization failure
    return hr;
}
```

#### 2. Steam 平台需求

**Steam 組建的必要項目**：
為 Steam 建置時，您**必須**在遊戲目錄中包含 `xgameruntime.dll`。如果沒有此 DLL，在 Steam Deck 上執行時：

* XBOX Live 驗證將會失敗
* Game Saves 功能將無法使用

**部署結構**：

```
YourGame/
├── YourGame.exe
├── xgameruntime.dll          // Required for Steam/Steam Deck
├── Steam_api64.dll
└── Other game files...
```

> [!NOTE]
>
> **Microsoft Store 組建**會自動從系統載入 XGameRuntime，不需要部署 DLL。

#### 3. 自動化 DLL 部署

**CMake 設定**：

```cmake theme={null}
# Automatically copy XGameRuntime DLL for Steam builds
if(STEAM_BUILD)
    add_custom_command(TARGET ${PROJECT_NAME} POST_BUILD
        COMMAND ${CMAKE_COMMAND} -E copy_if_different
        "${GDK_PATH}/windows/bin/xgameruntime.dll"
        $<TARGET_FILE_DIR:${PROJECT_NAME}>)
endif()
```

**MSBuild 設定**：

```xml theme={null}
<Target Name="CopySteamRuntimeDll" AfterTargets="Build" Condition="'$(SteamBuild)'=='true'">
  <Copy SourceFiles="$(GDK)\windows\bin\xgameruntime.dll" 
        DestinationFolder="$(OutDir)" />
</Target>
```

### 平台特定的執行階段行為

| 平台 | DLL 來源 | 執行階段模式 | Game Saves 支援 | 同步行為 |
| - | - | - | - | - |
| Microsoft Store | 系統 DLL | GRTS | 完整支援 | 跨處理序，在關閉後繼續 |
| Steam PC | 系統 DLL | GRTS | 完整支援 | 跨處理序，在關閉後繼續 |
| Steam Deck | 本機 DLL | 本機服務 | 遊戲存留期間支援 | **僅限同處理序，在關閉時停止** |

> [!NOTE]
>
> Steam Deck 支援特別需要部署本機 DLL。系統無法像其他平台一樣回復到系統服務。此外，同步引擎在同處理序中執行，這表示遊戲必須確保在關閉之前同步重要的存檔資料。

## 3. PlayFab Unified SDK 整合

### 什麼是 PlayFab Unified SDK？

PlayFab Unified SDK 是一個現代、一致的 SDK，將所有 PlayFab 元件整合在單一架構下。Game Saves 現在是此統一系統的一部分，提供：
**對 Game Saves 開發的好處**：

* 跨所有 PlayFab 元件的統一記憶體管理
* 一致的非同步作業模式
* 整合的追蹤和診斷
* 模組化元件載入 (只包含您需要的內容)

\*\*初次使用 PlayFab？\*\*Unified SDK 透過在所有 PlayFab 服務中提供單一、一致的 API 模式來簡化整合。如果您是第一次實作 Game Saves 或任何其他 PlayFab 服務，您會想要從這個現代架構開始。

### 必要的 SDK 元件

Game Saves 實作需要這些 Unified SDK 元件：

**基本元件**：

* **libHttpClient**：跨平台 HTTP/WebSocket 通訊
* **PlayFab Core**：驗證、實體管理和設定
* **PlayFab GameSave**：Game Saves 特定功能

**選用元件**：

* **PlayFab Services**：用於 LiveOps、帳戶管理和其他進度系統的共用服務 (如果使用其他 PlayFab 服務，建議使用)

### 程式庫和 DLL 需求

#### 連結所需的程式庫

```
Link these .lib files in your project:
- libHttpClient.lib
- PlayFabCore.lib 
- PlayFabServices.lib (optional, but recommended for additional PlayFab features)
- PlayFabGameSave.lib
- xgameruntime.lib
```

#### 部署所需的 DLL

```
Deploy these .dll files with Steam builds:
- libHttpClient.dll
- PlayFabCore.dll
- PlayFabServices.dll (optional, but recommended)
- PlayFabGameSave.dll
- xgameruntime.dll
```

### 建置系統設定

#### MSBuild 設定

設定您的 Visual Studio 專案以連結 Unified SDK：

```xml theme={null}
<!-- Link all required Unified SDK libraries -->
<AdditionalDependencies>
  libHttpClient.lib;
  PlayFabCore.lib;
  PlayFabServices.lib;
  PlayFabGameSave.lib;
  xgameruntime.lib;
  %(AdditionalDependencies)
</AdditionalDependencies>

<!-- Automatically deploy DLLs for Steam builds -->
<Target Name="CopyUnifiedSDKDlls" AfterTargets="Build" Condition="'$(SteamBuild)'=='true'">
  <ItemGroup>
    <UnifiedSDKDlls Include="$(GDK)\windows\bin\libHttpClient.dll" />
    <UnifiedSDKDlls Include="$(GDK)\windows\bin\PlayFabCore.dll" />
    <UnifiedSDKDlls Include="$(GDK)\windows\bin\PlayFabServices.dll" />
    <UnifiedSDKDlls Include="$(GDK)\windows\bin\PlayFabGameSave.dll" />
    <UnifiedSDKDlls Include="$(GDK)\windows\bin\xgameruntime.dll" />
  </ItemGroup>
  </ItemGroup>
  <Copy SourceFiles="@(UnifiedSDKDlls)" DestinationFolder="$(OutDir)" />
</Target>
```

\*\*從較早的 GDK 移轉？\*\*請將 `$(GDK)\GRDK\...\include` 之類的舊路徑取代為上方顯示的新結構。

#### CMake 設定

對於以 CMake 為基礎的專案，請設定相依性和部署：

```cmake theme={null}
# Link all required Unified SDK libraries
target_link_libraries(${PROJECT_NAME} PRIVATE
    libHttpClient
    PlayFabCore
    PlayFabServices
    PlayFabGameSave
    xgameruntime
)

# Automatically deploy DLLs for Steam builds
if(STEAM_BUILD)
    set(UNIFIED_SDK_DLLS
        "${GDK_PATH}/windows/bin/libHttpClient.dll"
        "${GDK_PATH}/windows/bin/PlayFabCore.dll"
        "${GDK_PATH}/windows/bin/PlayFabServices.dll"
        "${GDK_PATH}/windows/bin/PlayFabGameSave.dll"
        "${GDK_PATH}/windows/bin/xgameruntime.dll"
    )
    
    foreach(DLL ${UNIFIED_SDK_DLLS})
        add_custom_command(TARGET ${PROJECT_NAME} POST_BUILD
            COMMAND ${CMAKE_COMMAND} -E copy_if_different
            ${DLL} $<TARGET_FILE_DIR:${PROJECT_NAME}>)
    endforeach()
endif()
```

### 程式碼實作

#### 必要的標頭

在您的專案中包含必要的 Unified SDK 標頭：

```cpp theme={null}
// Essential headers for Game Saves implementation
#include <playfab/core/PFCore.h>
#include <playfab/services/PFServices.h>
#include <playfab/gamesave/PFGameSave.h>
#include <XGameRuntimeInit.h>
```

#### 初始化順序

依照此初始化順序進行正確的 Game Saves 設定：

```cpp theme={null}
// 1. Initialize XGameRuntime (foundation for Xbox Live services)
HRESULT hr = XGameRuntimeInitialize();
if (FAILED(hr)) {
    // Handle initialization failure
    return hr;
}

// 2. Initialize PlayFab Core (authentication and entity management)
hr = PFInitialize(nullptr);
if (FAILED(hr)) {
    // Handle PlayFab Core initialization failure
    return hr;
}

// 3. Initialize PlayFab Services (optional - only if using other PlayFab services)
hr = PFServicesInitialize(nullptr);
if (FAILED(hr)) {
    // Handle PlayFab Services initialization failure
    return hr;
}

// 4. Create service configuration (connects to your PlayFab title)
PFServiceConfigHandle serviceConfigHandle{ nullptr };
hr = PFServiceConfigCreateHandle(
    "https://YOUR_TITLE_ID.playfabapi.com",    // Replace with your endpoint
    "YOUR_TITLE_ID",                           // Replace with your Title ID
    &serviceConfigHandle);
if (FAILED(hr)) {
    // Handle service config creation failure
    return hr;
}

// 5. Initialize Game Saves with your service configuration
hr = PFGameSaveFilesInitialize(serviceConfigHandle);
if (FAILED(hr)) {
    // Handle Game Saves initialization failure
    return hr;
}

// Game Saves is now ready for use!
```

> [!TIP]
>
> 從 [PlayFab Game Manager](https://developer.playfab.com) 中遊戲的設定下取得您的遊戲識別碼和 API 端點。

#### 正確的清除順序

關閉應用程式時，請以相反的順序清除資源：

```cpp theme={null}
// Clean up Game Saves
PFGameSaveFilesUninitialize();

// Close service configuration
PFServiceConfigCloseHandle(serviceConfigHandle);
serviceConfigHandle = nullptr;

// Async cleanup for PlayFab Services (only if initialized)
XAsyncBlock async{};
HRESULT hr = PFServicesUninitializeAsync(&async);
hr = XAsyncGetStatus(&async, true);  // Wait for completion

// Async cleanup for PlayFab Core
hr = PFUninitializeAsync(&async);
hr = XAsyncGetStatus(&async, true);  // Wait for completion

// Clean up XGameRuntime
XGameRuntimeUninitialize();
```

> [!NOTE]
>
> 一律對 PlayFab Services 和 Core 使用非同步清除模式，以確保正確釋放資源。

## 4. 其他 PlayFab Unified SDK 元件

### Party 和 Multiplayer API 變更

雖然 Game Saves 功能不直接需要它們，但 2025 年 10 月 GDK 也包含作為 Unified SDK 一部分的 PlayFab Party 和 PlayFab Multiplayer 元件更新版本。這些元件有新的 API，能更好地與統一驗證系統整合。

#### 與獨立 SDK 相比的主要變更

**驗證整合**：

* **舊版模式**：先前，使用獨立 Party/Multiplayer SDK 的遊戲必須從 PlayFab 登入結果手動管理 `EntityID` 和 `EntityToken`，並將其傳遞給 Party/Multiplayer API
* **Unified SDK 模式**：Party 和 Multiplayer 現在直接接受 `PFEntityHandle`，不再需要手動管理權杖

**可用的新 API**：

* Party：接受 `PFEntityHandle` 進行使用者驗證的新 API
* Multiplayer：接受 `PFEntityHandle` 進行大廳和配對作業的新 API

**移轉的好處** (如果使用 Party/Multiplayer)：

* 透過自動權杖重新整理簡化驗證流程
* 跨所有 PlayFab 元件的一致錯誤處理模式
* 統一的記憶體管理和非同步作業模式

> [!NOTE]
>
> **Party 和 Multiplayer 元件**：如果您的遊戲使用 PlayFab Party 或 Multiplayer，請考慮移轉至直接接受 `PFEntityHandle` 的新統一 API，以改善整合。不過，Game Saves 功能並不需要這麼做——如果您只使用 Game Saves，可以放心略過第 4 節。

## 5. Steam Deck 實作

PlayFab Game Saves 的 Steam Deck 支援除了標準 PC 組建之外，還需要大量額外的實作，包括自訂驗證流程、完整的 UI 回呼和謹慎的同步策略。

> [!NOTE]
>
> **Steam Deck 實作的複雜度**：Steam Deck 整合涉及自訂驗證流程、UI 回呼實作，以及重要的同步行為差異。由於實作需求的複雜度和篇幅，Steam Deck 實作有其[專屬指南](/zh-TW/services/playfab/player-progression/game-saves/steam-deck-implementation)。

### Steam Deck 的關鍵考量

**重要的同步行為差異**：

* **Windows PC**：Game Saves 跨處理序執行，可以在遊戲關閉後繼續同步
* **Steam Deck**：Game Saves 只在同處理序中執行，並在遊戲關閉時停止同步

**實作需求**：

* 所有 Unified SDK DLL 都必須與您的 Steam 組建一起部署
* 具有 UI 回呼的自訂 XUser 驗證流程
* 用於非零售沙箱測試的登錄設定
* 頻繁的同步模式以防止資料遺失

**通用同步建議** (對所有平台都有益)：
雖然這些模式是 Steam Deck 所必需的，但強烈建議所有平台都使用，特別是經常突然關機的手持裝置：

* 經常同步存檔資料 (在每個關卡、檢查點或重大進度之後)
* 一律在顯示「結束遊戲」確認之前進行同步
* 考慮在遊戲轉換期間進行背景同步
* 實作同步進度指標，以確保在關閉之前完成

### 完整的 Steam Deck 實作

如需完整的 Steam Deck 實作詳細資料，包括：

* 詳細的驗證流程設定
* 完整的 UI 回呼實作
* 逐步初始化順序
* 疑難排解指南
* 範例程式碼參考

**請參閱專屬的 [Steam Deck 實作指南](/zh-TW/services/playfab/player-progression/game-saves/steam-deck-implementation)**

> [!TIP]
>
> 請先從本文件中的需求開始，然後再前往 Steam Deck 指南取得平台特定的實作詳細資料。

## 6. 實作檢查清單

### 開始使用 (新實作)

* [ ] **設定 2025 年 10 月 GDK** 並確認安裝
* [ ] 使用正確的 GDK 路徑和程式庫參考**設定建置系統**
* [ ] 將 **Unified SDK 程式庫新增**至您的專案連結設定
* [ ] 在原始程式碼中**包含必要的標頭**
* [ ] 依照 Unified SDK 模式**實作初始化順序**
* [ ] 為 Steam 組建**設定 DLL 部署** (4 個必要 DLL，1 個選用)
* [ ] 在您的目標平台上**測試基本功能**

### 移轉 (現有實作)

* [ ] 將**建置系統路徑**從舊的 GDK 結構**更新**為新的配置
* [ ] 以 Unified SDK 元件**取代獨立程式庫**
* [ ] **更新標頭 include** 以使用新的 Unified SDK 標頭
* [ ] **修改初始化順序**以使用新的 Unified SDK API
* [ ] 以正確的非同步清除模式**更新清除順序**
* [ ] 將**其他 DLL 新增**至 Steam 部署 (1 個 DLL → 4-5 個 DLL)
* [ ] **確認功能**在移轉後保持完整

### 建置系統設定

* [ ] **Include 路徑**：設定為 `$(GDK)\windows\include` (或平台對等路徑)
* [ ] **程式庫路徑**：設定為 `$(GDK)\windows\lib\x64` (或平台對等路徑)
* [ ] **連結程式庫**：將必要的 .lib 檔案新增至連結器相依性 (4 個必要，1 個選用)
* [ ] **DLL 部署**：為 Steam 組建設定自動複製
* [ ] **平台偵測**：如果為多個平台建置，請新增邏輯

### 程式碼實作工作

* [ ] **標頭**：包含所有必要的 Unified SDK 標頭
* [ ] **初始化**：實作正確的 5 步驟初始化順序
* [ ] **錯誤處理**：為每個初始化步驟新增適當的錯誤檢查
* [ ] **清除**：使用非同步模式實作反向順序的清除
* [ ] **設定**：以您的 PlayFab 遊戲識別碼和端點取代硬式編碼的值

### 測試需求

* [ ] **Windows PC**：確認 Game Saves 功能
* [ ] **Steam Deck**：使用 [Steam Deck 實作指南](/zh-TW/services/playfab/player-progression/game-saves/steam-deck-implementation)完成實作
* [ ] **Microsoft Store**：確認功能沒有退化
* [ ] **跨平台**：測試所有平台 (PC、Steam Deck、XBOX) 之間的存檔同步

## 7. 資源和支援

### 文件連結

* [Game Saves 概觀](/zh-TW/services/playfab/player-progression/game-saves/overview)
* [Game Saves 快速入門](/zh-TW/services/playfab/player-progression/game-saves/quickstart)
* [Steam Deck 實作指南](/zh-TW/services/playfab/player-progression/game-saves/steam-deck-implementation)

### 範例程式碼參考

* **Windows Game Saves 範例**：[PlayFabGameSaveSample-Windows](https://github.com/PlayFab/PlayFab-Samples/tree/master/Samples/All/PlayFabGameSaveSample-Windows)
  * `GameSaveIntegration.cpp/.h` - 核心 Game Saves 整合
  * `SteamIntegration.cpp/.h` - Steam Deck 特定實作 (請參閱 Steam Deck 指南)
  * `GameSaveIntegrationUI.cpp/.h` - UI 回呼實作 (請參閱 Steam Deck 指南)


## Related topics

- [使用玩家自訂屬性進行進階區段](/zh-TW/services/playfab/live-service-management/game-configuration/segmentation/advanced-segmentation.md)
- [PlayFab Game Saves 的 Steam Deck 實作指南](/zh-TW/services/playfab/player-progression/game-saves/steam-deck-implementation.md)
- [GDK 標頭和程式庫目錄結構](/zh-TW/build/gdk-and-engines/guides/gdk-directory-structure.md)
- [PlayFab Services SDK 2025 版本資訊](/zh-TW/services/playfab/release-notes/2025.md)
- [XBOX 遊戲的 XBOX 需求](/zh-TW/publishing/certification/xbox-requirements.md)