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

# PlayFab 游戏存档 Steam Deck 实现指南

> 使用 2025 年 10 月 GDK 在 Steam Deck 上实现 PlayFab 游戏存档的综合指南，包括身份验证、UI 回调和同步策略

<Info>
  本指南专门介绍使用 2025 年 10 月 GDK 在 Steam Deck 上实现 PlayFab 游戏存档的要求。在实现 Steam Deck 支持之前，请确保您已完成基本的 [2025 年 10 月 GDK 实现](/services/playfab/player-progression/game-saves/october-2025-gdk-changes)要求。
</Info>

## 概述

Steam Deck 游戏存档集成可以根据您的跨平台要求以不同的复杂度级别实现。您可以在简化的仅 Steam 方法与完整 XBOX 生态系统集成（具有更复杂的身份验证流程）之间进行选择。

<Info>
  **关键差异 - 同步行为**：Windows 上的游戏存档可以完全在进程外运行，并在游戏生命周期之外继续同步。在 Steam Deck 上，游戏存档仅在进程内运行。这意味着游戏关闭时存档同步将停止，需要游戏采用频繁同步模式以避免丢失未同步的进度。**所有平台的最佳实践**：虽然这些同步模式对 Steam Deck 是必需的，但强烈建议在所有平台上采用，特别是掌上设备或任何可能发生突然关闭的情形（电池耗尽、系统崩溃、强制关闭事件）。
</Info>

## 同步引擎行为差异

| 平台             | 同步模式 | 关闭后同步     | 推荐模式         |
| -------------- | ---- | --------- | ------------ |
| **Windows PC** | 进程外  | ✅ 游戏关闭后继续 | 建议频繁同步以提高可靠性 |
| **Steam Deck** | 进程内  | ❌ 游戏关闭时停止 | **必须频繁同步**   |

**通用同步建议**（对所有平台都有益）：

* 频繁同步存档数据（例如，在每个关卡、检查点或重大进度之后）
* 始终在显示"退出游戏"确认之前同步
* 考虑在游戏过渡期间进行后台同步
* 实现同步进度指示器，以确保在关闭之前完成
* 对于电池耗尽或突然关闭很常见的掌上设备尤其重要

## 前提条件

在实现 Steam Deck 支持之前，请确保您已经：

1. **完成 2025 年 10 月 GDK 设置**：遵循 [2025 年 10 月 GDK 实现指南](/services/playfab/player-progression/game-saves/october-2025-gdk-changes)
2. **Steam API 集成**：基本的 Steam API 初始化和 Steam Deck 检测
3. **选择集成方式**：在 XBOX 生态系统集成或自定义身份集成之间做出决定（见下文）
4. **所有必需的 DLL**：Unified SDK DLL 必须与您的 Steam 构建一起部署

## 实现方式

Steam Deck 提供两种实现方式，具有不同的复杂度级别和跨平台能力。PlayFab 游戏存档对于超出 Steam 生态系统的跨平台存档同步很有价值——您需要 XBOX Live 集成（方式 1）或您自己的自定义玩家身份系统（方式 2）。

### 方式 1：XBOX 生态系统集成（推荐）

**优势**：

* **完整的跨平台同步**：存档数据在 Steam Deck、XBOX 主机、Microsoft Store PC 和其他支持 XBOX 的平台之间同步
* **XBOX Live 集成**：玩家使用其 XBOX 玩家代号并可以访问 XBOX 社交功能
* **统一的玩家身份**：跨所有平台的相同玩家个人资料
* **成熟的身份验证**：利用 XBOX Live 成熟的身份验证基础架构
* **XBOX Game Studios 兼容性**：为 XBOX 第一方和合作伙伴工作室提供无缝集成

**复杂性**：

* **复杂的身份验证**：需要自定义 XUser 事件处理程序和 UI 回调
* **开发沙盒设置**：非零售测试环境所需
* **管理员权限**：沙盒设置期间修改注册表所需
* **额外的 UI 实现**：QR 码身份验证和玩家代号选择对话框

**何时选择**：面向包括 XBOX 主机在内的多个平台的游戏、XBOX Game Studios 作品，或需要完整 XBOX Live 生态系统集成的游戏。

### 方式 2：自定义身份实现（备选方案）

**优势**：

* **可能降低登录复杂性**：无需 XBOX 用户身份验证
* **无需注册表配置**：无需沙盒设置
* **无需 XUser API**：消除复杂的事件处理程序
* **自定义身份灵活性**：实现您自己的跨平台玩家身份系统

**复杂性**：

* **手动玩家管理**：必须实现您自己的跨平台玩家身份系统
* **有限的生态系统集成**：无法访问 XBOX Live 社交功能或现有的 XBOX 玩家群
* **平台桥接**：需要自定义解决方案来连接不同平台上的玩家
* **额外的身份基础架构**：需要构建或集成第三方身份系统

**何时选择**：以 Steam 为中心的游戏、具有现有自定义身份系统的游戏，或不需要或不希望进行 XBOX Live 集成的开发场景。

**OpenID Connect**：对于方式 2，PlayFab 通过 `LoginWithOpenIdConnect` API 调用支持 OpenID Connect 身份验证，可与支持 OpenID Connect 标准的自定义身份提供程序集成。

## 通用设置（两种方式）

无论选择哪种实现方式，以下设置步骤都是必需的。

## 1. DLL 部署要求

Steam Deck 要求所有 Unified SDK DLL 与您的游戏一起部署：

**必需的 DLL**：

* `libHttpClient.dll` - HTTP 操作
* `PlayFabCore.dll` - 身份验证和核心服务
* `PlayFabGameSave.dll` - 游戏存档功能
* `xgameruntime.dll` - 核心 SDK 功能和 XBOX 登录

**可选 DLL**：

* `PlayFabServices.dll` - 其他 PlayFab 服务（推荐）

**Steam Deck 部署结构**：

```
YourGame/
├── YourGame.exe
├── libHttpClient.dll     // Required for HTTP operations
├── PlayFabCore.dll       // Required for authentication
├── PlayFabServices.dll   // Optional: For additional PlayFab services
├── PlayFabGameSave.dll   // Required for Game Saves
├── xgameruntime.dll      // Required for Xbox Live services
├── Steam_api64.dll
└── Other game files...
```

## 2. Steam 集成前提条件

### Steam API 集成

```cpp theme={null}
// Initialize Steam API
bool steamAvailable = SteamAPI_Init();
```

### 平台检测

在初始化早期实现平台检测：

```cpp theme={null}
bool DetectSteamDeck() {
    if (!SteamAPI_Init()) {
        return false;
    }
    
    return SteamUtils()->IsSteamRunningOnSteamDeck();
}
```

## 3. UI 回调实现

<Info>
  **Steam Deck UI 要求**：无论选择哪种实现方式，Steam Deck 上都**必需**实现所有 PlayFab 游戏存档 UI 回调。这是因为 Steam Deck 没有可用于游戏存档操作的内置 UI，所以您的应用必须提供所有 UI 对话框。
</Info>

### 游戏存档 UI 回调（两种方式都需要）

自定义身份和 XBOX 生态系统实现都需要相同的 PlayFab 游戏存档 UI 回调：

```cpp theme={null}
// Required Game Saves UI callbacks for Steam Deck (both approaches)
PFGameSaveUICallbacks callbacks{};
callbacks.progressCallback = OnPFGameSaveFilesUiProgress;                    // Sync progress
callbacks.syncFailedCallback = OnPFGameSaveFilesUiSyncFailed;               // Sync errors
callbacks.activeDeviceContentionCallback = OnPFGameSaveFilesUiActiveDeviceContention;  // Device conflicts
callbacks.conflictCallback = OnPFGameSaveFilesUiConflict;                   // Save conflicts
callbacks.outOfStorageCallback = OnPFGameSaveFilesUiOutOfStorage;           // Storage quota

HRESULT hr = PFGameSaveFilesSetUiCallbacks(&callbacks);
if (FAILED(hr)) {
    // Handle callback setup failure
}

// Optional: Additional active device changed callback
hr = PFGameSaveFilesSetActiveDeviceChangedCallback(&OnActiveDeviceChanged, nullptr);
```

**必需的游戏存档 UI 对话框**（两种方式）：

* **进度对话框**：在存档操作期间显示同步进度
* **错误处理**：显示同步失败消息和重试选项
* **冲突解决**：处理设备之间的存档冲突
* **设备争用**：处理多设备访问场景
* **存储管理**：通知用户存储配额问题

***

## 方式 1：XBOX 生态系统集成 - 完整实现

此方式在 Steam Deck、XBOX 主机、Microsoft Store PC 和其他支持 XBOX 的平台之间提供完整的跨平台同步。如果您的游戏面向 XBOX 平台或需要 XBOX Live 集成，请选择此方式。

### 概述

**前提条件**：

* 完成通用设置（上文第 1-3 节）
* 用于测试的开发沙盒访问权限
* 用于注册表配置的管理员权限（仅限开发/测试）

### 1. 注册表配置

Steam Deck 需要 XBOX Live 沙盒配置以进行非零售沙盒测试：

```cpp theme={null}
// Set sandbox before Xbox Live services initialization
// Only required when testing with non-retail sandboxes
if (isSteamDeck) {
    HRESULT hr = SteamIntegration::SetSandboxForSteamDeck("XDKS.1");
    if (FAILED(hr)) {
        // Handle sandbox setup failure - requires admin privileges
        return hr;
    }
}
```

**配置详情**：

* **键**：`HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\XboxLive\Sandbox`
* **值**：开发沙盒 ID（例如，"XDKS.1"）
* **时机**：必须在 XBOX Live 服务初始化之前设置
* **权限**：需要管理员访问权限
* **用途**：仅在非零售沙盒（开发/测试环境）中测试时需要

### 2. XUser 平台事件处理程序

Steam Deck 需要两组关键的事件处理程序来进行 XBOX 身份验证：

#### A. 远程连接事件处理程序

处理远程身份验证流程（QR 码/URL 显示）：

```cpp theme={null}
// Handle remote authentication flow (QR code/URL)
XUserPlatformRemoteConnectEventHandlers remoteConnect{};
remoteConnect.context = nullptr;
remoteConnect.show = &OnRemoteConnectShow;     // Display QR code/URL dialog
remoteConnect.close = &OnRemoteConnectClose;   // Close authentication dialog
HRESULT hr = XUserPlatformRemoteConnectSetEventHandlers(nullptr, &remoteConnect);
if (FAILED(hr)) {
    // Handle event handler setup failure
}
```

#### B. SPOP（登录提示）事件处理程序

处理当用户帐户已在另一台设备上登录时使用的 SPOP 登录提示：

```cpp theme={null}
// Handle SPOP sign-in prompt. See sample: ShowSpopPromptDialogForXUserOnSteamDeck
HRESULT hr = XUserPlatformSpopPromptSetEventHandlers(nullptr, &OnSpopPrompt, nullptr);
if (FAILED(hr)) {
    // Handle SPOP setup failure
}
```

处理程序必须显示一个 UI，让玩家选择一个操作（在此登录、切换帐户或取消），并使用所选结果调用 `XUserPlatformSpopPromptComplete(operation, result)`。

### 3. 身份验证 UI 实现

除了游戏存档 UI 回调（第 3 节）外，XBOX 生态系统集成还需要：

* **远程连接对话框**：显示 QR 码和 URL，供用户在另一台设备上进行身份验证
* **SPOP 提示对话框**：允许用户选择/确认其 XBOX 玩家代号

### 4. 初始化顺序

对 XBOX 生态系统集成遵循以下初始化顺序：

```cpp theme={null}
// 1. Check Steam availability and platform
bool steamAvailable = SteamIntegration::CheckSteamAvailability();
bool isSteamDeck = SteamIntegration::CheckIfSteamDeck();

// 2. Set Xbox Live sandbox (Steam Deck only, required for non-retail sandbox testing)
if (isSteamDeck) {
    HRESULT hr = SteamIntegration::SetSandboxForSteamDeck("XDKS.1");
    if (FAILED(hr)) {
        // Handle sandbox setup failure
        return hr;
    }
}

// 3. Initialize Xbox runtime
hr = XGameRuntimeInitialize();
if (FAILED(hr)) {
    return hr;
}

// 4. Initialize PlayFab Core and Services
hr = PFInitialize(nullptr);
if (FAILED(hr)) {
    return hr;
}
hr = PFServicesInitialize(nullptr); // Optional

// 5. Initialize XUser for Steam Deck
if (isSteamDeck) {
    hr = SteamIntegration::InitializeXUserForSteamDeck();
    if (FAILED(hr)) {
        return hr;
    }
}

// 6. Initialize Game Saves with appropriate callbacks
bool setUiCallbacks = isSteamDeck;
hr = InitializeGameSaves(setUiCallbacks);
if (FAILED(hr)) {
    return hr;
}
```

### 5. 登出实现

Steam Deck 需要特殊的登出处理来清除存储的 XBOX 凭据：

```cpp theme={null}
void SignOutFromSteamDeck() {
    // Enumerate and delete Windows credentials with target names starting with "Xbl"
    DWORD count = 0;
    PCREDENTIALW* credentials = nullptr;
    
    if (CredEnumerateW(L"Xbl*", 0, &count, &credentials)) {
        for (DWORD i = 0; i < count; i++) {
            CredDeleteW(credentials[i]->TargetName, credentials[i]->Type, 0);
        }
        CredFree(credentials);
    }
    
    // Close Xbox user handles
    if (xboxUser) {
        XUserCloseHandle(xboxUser);
        xboxUser = nullptr;
    }
    
    // Close PlayFab user handles
    if (pfUser) {
        PFLocalUserCloseHandle(pfUser);
        pfUser = nullptr;
    }
    
    // Reset authentication state for clean re-authentication
    authenticationState = AuthState::NotAuthenticated;
}
```

### 6. 测试清单

使用此清单验证您的 XBOX 生态系统实现：

* [ ] **身份验证流程**：测试远程连接（QR 码/URL）身份验证
* [ ] **UI 回调**：验证所有游戏存档 UI 对话框正确显示
* [ ] **SPOP 提示**：测试玩家代号选择和确认
* [ ] **凭据持久性**：测试跨应用重启的登录持久性
* [ ] **登出**：验证登出时正确清理凭据
* [ ] **同步行为**：测试频繁同步模式和关闭前同步
* [ ] **数据丢失防护**：验证强制关闭场景期间进度丢失最少
* [ ] **跨平台同步**：测试 Steam Deck、XBOX 主机和 Microsoft Store PC 之间的存档同步
* [ ] **注册表配置**：验证沙盒配置在开发环境中有效
* [ ] **XUser 事件处理程序**：确认远程连接和 SPOP 处理程序正常工作

***

## 方式 2：自定义身份实现 - 完整实现

此方式允许您使用自己的玩家身份系统，而无需 XBOX Live 集成。如果您的游戏以 Steam 为中心，或者您有现有的自定义身份系统，请选择此方式。

### 概述

**前提条件**：

* 完成通用设置（上文第 1-3 节）
* 用于生产的自定义玩家身份系统

**优势**：

* 无需 XBOX 身份验证
* 无需注册表配置
* 无需管理员权限
* 更简单的 UI（无 QR 码或玩家代号选择）

**限制**：

* 必须实现自己的跨平台玩家身份
* 无 XBOX Live 社交功能
* 需要自定义平台桥接解决方案

### 1. 自定义身份验证

实现您自己的身份系统以进行跨平台玩家身份验证：

```cpp theme={null}
// Custom identity authentication
if (isSteamDeck) {
    // Development/Testing: Use Steam user identity temporarily
    // Production: Implement your own cross-platform player identity system
    // Required for production since Steam Cloud handles Steam-only sync
    
    // Option 1: OpenID Connect Integration (Recommended)
    // If your identity system supports OpenID Connect, use LoginWithOpenIdConnect:
    // PFAuthenticationLoginWithOpenIdConnectRequest request = {};
    // request.connectionId = "YourOpenIdConnectConnectionId";
    // request.idToken = "YourOpenIdConnectToken";
    // PFAuthenticationLoginWithOpenIdConnectAsync(serviceConfigHandle, &request, ...);
    
    // Option 2: Custom Integration
    // Initialize your custom authentication system
    // Connect to your user accounts/login system
    // Integrate with PlayFab Game Saves using your player identity
    
    // Initialize Game Saves with your custom identity system
    // (Implementation details depend on your specific identity integration)
}
```

### 2. 初始化顺序

```cpp theme={null}
// 1. Check Steam availability and platform
bool steamAvailable = SteamIntegration::CheckSteamAvailability();
bool isSteamDeck = SteamIntegration::CheckIfSteamDeck();

// 2. Initialize Xbox runtime (still required for Game Saves infrastructure)
HRESULT hr = XGameRuntimeInitialize();
if (FAILED(hr)) {
    return hr;
}

// 3. Initialize PlayFab Core and Services
hr = PFInitialize(nullptr);
if (FAILED(hr)) {
    return hr;
}
hr = PFServicesInitialize(nullptr); // Optional

// 4. Initialize your custom player identity system
hr = InitializeCustomPlayerIdentity();
if (FAILED(hr)) {
    return hr;
}

// 5. Initialize Game Saves with custom identity system
// Option A: OpenID Connect (if your identity system supports it)
// hr = PFAuthenticationLoginWithOpenIdConnectAsync(serviceConfigHandle, &openIdRequest, ...);
// Option B: Custom authentication integration
hr = InitializeGameSavesWithCustomIdentity();
if (FAILED(hr)) {
    return hr;
}
```

### 3. 登出实现

```cpp theme={null}
void SignOutFromSteamDeck() {
    // Sign-out for custom identity implementation
    // No Xbox credential cleanup needed
    
    // Clean up your custom identity system
    SignOutFromCustomIdentitySystem();
    
    // Close PlayFab user handles
    if (pfUser) {
        PFLocalUserCloseHandle(pfUser);
        pfUser = nullptr;
    }
    
    // Clear local game state as needed
    ClearLocalGameState();
}
```

### 4. 测试清单

使用此清单验证您的自定义身份实现：

* [ ] **自定义身份系统**：测试您的自定义玩家身份验证和身份系统
* [ ] **PlayFab 身份验证**：使用 LoginWithOpenIdConnect（如果使用 OpenID Connect）或自定义身份验证方法测试 PlayFab 登录
* [ ] **跨平台游戏存档同步**：测试所有目标平台上的存档同步
* [ ] **UI 回调**：验证所有游戏存档 UI 对话框正确显示
* [ ] **冲突解决**：测试不同平台设备之间的存档冲突
* [ ] **同步行为**：测试频繁同步模式和关闭前同步
* [ ] **数据丢失防护**：验证强制关闭场景期间进度丢失最少
* [ ] **自定义身份验证**：测试您的身份系统的登录/登出流程
* [ ] **平台覆盖**：在您游戏面向的所有平台上进行测试（不仅仅是 Steam 设备）
* [ ] **网络场景**：测试离线/在线转换
* [ ] **性能**：验证同步操作不影响游戏性能

***

## 示例代码参考

有关两种方式的完整实现示例，请参阅示例项目：

* **位置**：[PlayFabGameSaveSample-Windows](https://github.com/PlayFab/PlayFab-Samples/tree/master/Samples/All/PlayFabGameSaveSample-Windows)
* **关键文件**：
  * `SteamIntegration.cpp/.h` - Steam Deck 检测、注册表设置、身份验证处理程序
  * `GameSaveIntegrationUI.cpp/.h` - 两种方式的 UI 回调实现

***

## 相关文档

* [2025 年 10 月 GDK 实现指南](/services/playfab/player-progression/game-saves/october-2025-gdk-changes)
* [游戏存档概述](/services/playfab/player-progression/game-saves/overview)
* [游戏存档快速入门](/services/playfab/player-progression/game-saves/quickstart)


## Related topics

- [游戏存档 UI 回调](/zh-CN/services/playfab/player-progression/game-saves/ui-callbacks.md)
- [游戏存档概述](/zh-CN/services/playfab/player-progression/game-saves/overview.md)
- [游戏存档快速入门](/zh-CN/services/playfab/player-progression/game-saves/quickstart.md)
- [XR-037 内容包的依赖关系](/zh-CN/publishing/certification/xr/xr-037.md)
- [游戏存档](/zh-CN/build/core-features/common/game-save/index.md)