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

# October 2025 GDK での Game Saves の実装

> October 2025 GDK (2510) を使用した PlayFab Game Saves の実装に関する必須ガイド。新規実装の要件および移行ガイダンスを含みます。

<Info>
  このガイドでは、October 2025 GDK (バージョン 2510) を使用した PlayFab Game Saves の実装について説明します。Game Saves を初めて利用する方でも、以前の実装から移行する方でも、このドキュメントは Steam Deck サポートに特に注意を払いつつ、必須の要件とセットアップ手順を提供します。
</Info>

## 実装要件の概要

October 2025 GDK で PlayFab Game Saves を実装する際には、4 つの主要コンポーネントを理解する必要があります。

1. **新しい GDK フォルダー レイアウト**: プラットフォーム中心の SDK ディレクトリ構造
2. **XGameRuntime 統合**: 特定のデプロイ要件を持つクロス プラットフォーム ランタイム
3. **PlayFab Unified SDK**: すべての PlayFab コンポーネントのモダンな SDK アーキテクチャ
4. **その他の Unified SDK コンポーネント**: 更新された Party および Multiplayer コンポーネント (使用する場合)

最初の 3 つのコンポーネントは、October 2025 GDK 以降を使用したすべての Game Saves 実装 (Steam Deck サポートを含む) に **必須** です。4 番目のコンポーネントは、ゲームが PlayFab Party または Multiplayer 機能を使用する場合のみ適用されます。

<Note>
  **Game Saves を初めて利用しますか?** まず基本を理解するために [Game Saves の概要](/services/playfab/player-progression/game-saves/overview) と [クイックスタート ガイド](/services/playfab/player-progression/game-saves/quickstart) から始めてから、October 2025 GDK 固有の実装詳細についてここに戻ってきてください。
</Note>

## 1. GDK フォルダー レイアウトとパス構成

### 現在の GDK 構造

October 2025 GDK は、フラットでプラットフォーム中心のディレクトリ構造を使用します。このレイアウトを理解することは、ビルド システムを正しくセットアップするために不可欠です。

**October 2025 GDK のレイアウト**:

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

**以前の GDK から移行しますか?** 以前のフォルダー構造 (`$(GDK)\GRDK\ および $(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 構造を使用してインクルード パスとライブラリ パスをセットアップします
   * 複数のプラットフォームを対象とする場合はプラットフォーム検出ロジックを追加します
   * すべてのターゲット プラットフォームでコンパイルをテストします

2. **Game Saves 統合を検証する**
   * すべての必須ライブラリが正しくリンクされることを確認します
   * ターゲット プラットフォームで機能をテストします
   * PlayFab サービス接続を検証します

## 2. XGameRuntime の統合

### XGameRuntime の理解

XGameRuntime は、すべてのプラットフォームで XBOX Live サービスと Game Saves 機能の基盤を提供します。以下は知っておくべき内容です。

#### コア コンポーネント

**xgameruntime.lib (インポート ライブラリ)**

* コンパイル時にゲーム プロジェクトにリンクされます
* ランタイム DLL を自動的に検出してロードします
* サービス検出を処理します (ローカル vs. システム)

**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 のデプロイは必要ありません。
</Note>

#### 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 | ローカル サービス | ゲーム ライフタイム サポート | **プロセス内のみ、シャットダウンで停止** |

<Info>
  Steam Deck のサポートには、ローカル DLL のデプロイが特に必要です。他のプラットフォームのようにシステム サービスにフォールバックすることはできません。さらに、同期エンジンはプロセス内で実行されるため、ゲームはシャットダウン前に重要なセーブ データが同期されていることを確認する必要があります。
</Info>

## 3. PlayFab Unified SDK の統合

### PlayFab Unified SDK とは?

PlayFab Unified SDK は、すべての PlayFab コンポーネントを単一のアーキテクチャの下にまとめたモダンで統一された SDK です。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>
  タイトルの設定にあるタイトル ID と API エンドポイントは [PlayFab Game Manager](https://developer.playfab.com) から取得してください。
</Tip>

#### 適切なクリーンアップ シーケンス

アプリケーションをシャットダウンするときは、リソースを逆順でクリーンアップします。

```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();
```

<Info>
  適切なリソースのリリースを確保するために、PlayFab Services および Core には常に非同期のクリーンアップ パターンを使用してください。
</Info>

## 4. その他の PlayFab Unified SDK コンポーネント

### Party および Multiplayer API の変更

Game Saves 機能に直接必要というわけではありませんが、October 2025 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 を安全にスキップできます。
</Note>

## 5. Steam Deck の実装

PlayFab Game Saves の Steam Deck サポートには、カスタム認証フロー、包括的な UI コールバック、注意深い同期戦略を含む、標準の PC ビルドを超えた重要な追加実装が必要です。

<Info>
  **Steam Deck 実装の複雑さ**: Steam Deck 統合には、カスタム認証フロー、UI コールバックの実装、そして重要な同期動作の違いが含まれます。実装要件の複雑さと長さのため、Steam Deck の実装には独自の [専用ガイド](/services/playfab/player-progression/game-saves/steam-deck-implementation) があります。
</Info>

### 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 実装ガイド](/services/playfab/player-progression/game-saves/steam-deck-implementation) を参照してください**

<Tip>
  まずこのドキュメントの要件から始めて、次にプラットフォーム固有の実装詳細のために Steam Deck ガイドに移動してください。
</Tip>

## 6. 実装チェックリスト

### はじめに (新規実装)

* [ ] **October 2025 GDK をセットアップ** し、インストールを確認します
* [ ] 正しい GDK パスとライブラリ参照で **ビルド システムを構成** します
* [ ] プロジェクトのリンク構成に **Unified SDK ライブラリを追加** します
* [ ] ソース コードに **必要なヘッダーをインクルード** します
* [ ] Unified SDK パターンに従って **初期化シーケンスを実装** します
* [ ] Steam ビルドの **DLL デプロイをセットアップ** します (必須 4 個、任意 1 個)
* [ ] ターゲット プラットフォームで **基本機能をテスト** します

### 移行 (既存の実装)

* [ ] 古い GDK 構造から新しいレイアウトへ **ビルド システム パスを更新** します
* [ ] スタンドアロン ライブラリを Unified SDK コンポーネントに **置き換え** ます
* [ ] 新しい Unified SDK ヘッダーを使用するように **ヘッダー インクルードを更新** します
* [ ] 新しい Unified SDK API を使用するように **初期化シーケンスを変更** します
* [ ] 適切な非同期クリーンアップ パターンで **クリーンアップ シーケンスを更新** します
* [ ] Steam デプロイに **追加の DLL を追加** します (DLL 1 個 → 4〜5 個)
* [ ] 移行後も **機能が損なわれていないことを確認** します

### ビルド システム構成

* [ ] **インクルード パス**: `$(GDK)\windows\include` (またはプラットフォーム相当) に設定します
* [ ] **ライブラリ パス**: `$(GDK)\windows\lib\x64` (またはプラットフォーム相当) に設定します
* [ ] **リンク ライブラリ**: リンカーの依存関係に必要な .lib ファイルを追加します (必須 4 個、任意 1 個)
* [ ] **DLL デプロイ**: Steam ビルドの自動コピーを構成します
* [ ] **プラットフォーム検出**: 複数のプラットフォーム用にビルドする場合はロジックを追加します

### コード実装タスク

* [ ] **ヘッダー**: 必要なすべての Unified SDK ヘッダーをインクルードします
* [ ] **初期化**: 適切な 5 ステップの初期化シーケンスを実装します
* [ ] **エラー処理**: 各初期化ステップに適切なエラー チェックを追加します
* [ ] **クリーンアップ**: 非同期パターンで逆順のクリーンアップを実装します
* [ ] **構成**: ハードコードされた値を PlayFab タイトル ID とエンドポイントに置き換えます

### テスト要件

* [ ] **Windows PC**: Game Saves 機能を検証します
* [ ] **Steam Deck**: [Steam Deck 実装ガイド](/services/playfab/player-progression/game-saves/steam-deck-implementation) を使用して実装を完了します
* [ ] **Microsoft Store**: 機能にリグレッションがないことを確認します
* [ ] **クロス プラットフォーム**: すべてのプラットフォーム間 (PC、Steam Deck、XBOX) のセーブ同期をテストします

## 7. リソースとサポート

### ドキュメントのリンク

* [Game Saves の概要](/services/playfab/player-progression/game-saves/overview)
* [Game Saves クイックスタート](/services/playfab/player-progression/game-saves/quickstart)
* [Steam Deck 実装ガイド](/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

- [PlayFab Game Saves の Steam Deck 実装ガイド](/ja-jp/services/playfab/player-progression/game-saves/steam-deck-implementation.md)
- [XGameSave](/ja-jp/reference/system/xgamesave/xgamesave_members.md)
- [XStoreGameLicense](/ja-jp/reference/system/xstore/structs/xstoregamelicense.md)
- [XGameSaveFiles API の概要](/ja-jp/build/core-features/common/game-save/xgamesavefiles.md)
- [クロスネットワークマルチプレイヤーの実装例](/ja-jp/services/xbox-services/multiplayer/concepts/live-console-xr007-multiplayer-example.md)