XGameSaveFilesGetFolderWithUIAsync の初期化方法を説明します。また、推奨される Win32 の自動クラウド同期動作、デバッグ手順、クォータおよび診断のガイダンス、パフォーマンスのベスト プラクティス、およびよくある質問への回答についても説明します。
XGameSaveFiles は、タイトルがユーザー データを読み書きし、セッション間で永続化し、クラウドとシームレスに同期して、プレイヤーが任意のデバイスでデータを使用できるようにする API を提供します。Microsoft Game Development Kit (GDK) タイトルのゲーム セーブには XGameSaveFiles を使用してください。シナリオで XGameSaveFiles が利用できない場合にのみ XGameSave を使用してください。
XGameSaveFiles のシステム API リファレンスについては、XGameSaveFiles (API 目次) を参照してください。
XGameSaveFiles では、次の用語がよく登場します。
- ロック: 特定のユーザーが現在アクティブに使用しているデバイス上で、タイトルの Game Saves への排他アクセスを付与するメカニズムです。これは、ロックが保持されている間、他のデバイスがそのユーザーのゲーム セーブを変更できないようにします。
- たとえば、ユーザーがデバイス A でタイトル T をプレイしている場合、そのユーザーのタイトル T に対するロックを持っています。
- プロバイダー: Game Save システムと通信する仲介プロセスで、タイトル データの管理を担当します。プロバイダーはデバイス上のユーザーのロックも管理します。
- コンテナー: フォルダーに相当します。
- BLOB: 個別のファイルに相当します。
XGameSaveFiles のパス ロジック
XGameSaveFiles は、Game Saves システムとやり取りするために使用できるファイル パスを提供します。ファイル パスはクラウド同期と統合されているため、そのパスに保存されたデータは自動的にクラウドに同期されます。提供されたパスに対して Win32 の FileIO API を使用してください。GDK タイトルでは、Game Saves のアプローチとして XGameSaveFiles を使用してください。XGameSaveFiles は、コンテナーをフォルダーに、BLOB をファイルにマッピングします。
XGameSaveFiles はクラウド セーブ システムの複雑さのほとんどを隠していますが、機能が Microsoft Azure Blob Storage に依存しているため、ディレクトリおよびファイル名の制限は依然として適用されます。タイトルがセーブに使用する可能性のある次のサンプル コードを検討してください。
XGameSaveFilesGetFolderWithUiAsyncは [ROOT] を返します。- [ROOT] に続くすべて (最終スラッシュを含む) は、コンテナーにマッピングされます。
- コンテナー名は、大文字 (A-Z)、小文字 (a-z)、数字 (0-9)、アンダースコア (_)、ピリオド (.)、ハイフン (-)、スラッシュ (/) に制限されます。
- コンテナー名は 256 文字までに制限されます。
- コンテナー名は、ピリオドで終わったり、連続する 2 つのピリオドを含んだり、ピリオドまたはハイフンで始まったりすることはできません。
- ファイル名の最終スラッシュ以降のすべてが、BLOB にマッピングされます。
- ファイル名は 65 文字に制限されますが、New Technology File System (NTFS) がサポートするその他の Unicode 文字は使用できます。
- ファイル名を含む完全な結果パス ([ROOT] は含まない) は、
MAX_PATH(260 文字) 未満である必要があります。
XGameSaveFiles の実装
次の手順は、XGameSaveFiles の一般的な実装を示します。
- タイトルの起動または再開時に、
XGameSaveFilesGetFolderWithUIAsyncを呼び出してプロバイダーを初期化し、ファイル パスを取得します。 - ゲーム プレイ中にファイル パスを自由に読み書きします。
XGameSaveFilesGetFolderWithUIAsync は、Game Saves プロバイダーのライフタイムを自動的に管理し、Game Saves ローカル ストレージ スペースをセットアップします。
タイトル起動時と再開時に
XGameSaveFilesGetFolderWithUIAsync を呼び出してください。この呼び出しにより、Game Saves プロバイダーが初期化され、ゲーム セッションの実行中はアクティブなままとなります。この手順をスキップすると、システムが予測できない動作をする可能性があります。コード サンプル
XBOX のフォルダーにアクセスするためにXGameSaveFiles API を使用する方法を示すコード サンプルについては、GameSaveFilesCombo を参照してください。
Game Saves フロー
以下は、簡略化された Game Saves フローのフローチャートです。タイトル開始
タイトル開始は、ユーザーがタイトルを起動または再開したときに発生します。ユーザー サインイン
タイトルはユーザーのサインイン プロセスを開始します。この操作は、XGameSaveFilesGetFolderWithUIAsync を呼び出す場所でもあります。ユーザー セットアップの詳細については、ユーザー モデル を参照してください。
接続チェック
タイトルは XBOX ネットワークに接続できるかを判定します。できない場合は、タイトルの オフライン モード を有効にする必要があります。データ所有権チェック
デバイスは、ユーザーが現在他のデバイスでプレイしていないかを確認します。特定のタイトルのユーザーのデータには、一度に 1 つのデバイスのみがアクセスできます。クラウドとのデータ同期
デバイスは、Game Saves のローカル ストレージ データをクラウドと同期します。競合がある場合、システムは競合解決ダイアログでユーザーに確認を求めます。 ダイアログ: どちらを使用しますか? デバイス上のデータがクラウドのデータより新しい場合、タイトルは、ローカル データを使うかクラウド データを使うかをユーザーに選択するよう求めます。ゲームプレイ ループ
タイトルは、XGameSaveFilesGetFolderWithUIAsync から提供されたフォルダー パスに対して自由に読み書きできます。
ゲーム セッションの終了
ゲーム セッションが終了すると、システムは自動的にデータのクラウドへのアップロードを試みます。このプロセスはタイトル終了後、およそ 10 ～ 30 秒後に発生します。 同期の詳細については、Game Saves の同期フローについて を参照してください。制限とクォータ
制限
XGameSaveFiles を使用して保存できる最大ファイル サイズは 64 MB です。この動作は、各ファイルを 16 MB に制限する XGameSave とは異なります。
クォータ
ユーザーがタイトルごとに保存できる最大データは 256 MB です。残りのクォータを取得するには、XGameSaveFilesGetRemainingQuota を使用します。タイトルのユーザーごとのストレージ制限を大きくするストレージ拡張を取得するには、開発プログラム マネージャー (DPM) に連絡してください。よくある質問
XGameSaveFiles を XGameSave と一緒に使用できますか?
はい。ただし、このアプローチは移行の場合にのみ使用してください。詳細については、XGameSave と XGameSaveFiles の相互運用性 を参照してください。XGameSaveFiles はどのファイル パスに保存しますか?
コンソール: タイトルがアクティブな間に一時的なパスを提供します。コンソール ファイルにはエクスプローラーを使用してアクセスできません。 PC:%AppData%\Local\Packages\<PACKAGE_NAME>\SystemAppData\xgs\<HexXuid>_<SCID>\
XGameSaveFiles の PC パスは XGameSave とは異なります。wgs を使用します。
データが保存されるパスを指定できますか?
はい、ただし PC のみです。このアプローチは、別のタイトルからソリューションを移植する場合にのみお勧めします。このソリューションでは、ノーコード クラウド セーブ を使用します。リファレンス API ドキュメント
関連項目
Game Saves 目次 はい、ただし PC のみです。別のタイトルからソリューションを移植する場合には、このアプローチが必要になることがあります。このソリューションでは、ノーコード クラウド セーブ を使用します。ノーコード クラウド セーブでは、タイトルが
wdapp install を使用してパッケージ ビルドとして起動されている必要があります。.exe を直接起動しても、クラウド セーブのリダイレクトは有効になりません。パッケージ起動と直接 .exe 起動を交互に行うと、セーブ データが失われたように見えることがあります。詳細については、ノーコード クラウド セーブによる以前のタイトルの PC Game Saves への移植 を参照してください。