XGameSave API を使用すると、Game Saves データを管理するために BLOB とコンテナーを管理できます。Microsoft Game Development Kit (GDK) タイトルの Game Saves では、XGameSaveFiles の使用をお勧めします。XGameSaveFiles を使えない場合は XGameSave を使用してください。
XGameSave のシステム API リファレンスについては、XGameSave (API 目次) を参照してください。
XGameSave では、次の用語がよく登場します。
- ロック: 特定のユーザーが現在アクティブに使用しているデバイス上で、タイトルの Game Saves への排他アクセスを付与するメカニズムです。これは、ロックが保持されている間、他のデバイスがそのユーザーの Game Saves を変更できないようにします。
- たとえば、ユーザーがデバイス A でタイトル T をプレイしている場合、そのユーザーのタイトル T に対するロックを持っています。
- プロバイダー: Game Save システムと通信する仲介プロセスで、タイトル データの管理を担当します。プロバイダーはデバイス上のユーザーのロックも管理します。
- コンテナー: フォルダーに相当します。
- BLOB: 個別のファイルに相当します。
プロバイダーの管理
ストレージ スペースを取得するために、ゲームはプロバイダーを初期化する必要があります。接続後、タイトルはXGameSaveInitializeProvider または XGameSaveInitializeProviderAsync を呼び出して、タイトルのクラウド ストレージへのロックの取得を試みます。
接続喪失によりクラウドからの同期に失敗した場合、ユーザーがオフライン モードでプレイを続行できるかを判断してください。
タイトルは、中断または終了時に XGameSaveCloseProvider でプロバイダーを閉じる必要があります。プロバイダーは中断-再開の境界を越えて再利用することはできません。
この問題は
XGameSave にのみ該当します。XGameSaveFiles は自動的にプロバイダーを閉じます。コンテナー管理
同期完了前にコンテナーを作成するなど、コンテナーへのアクセス時のデータ損失を避けるには、XGameSaveEnumerateContainerInfo または XGameSaveEnumerateContainerInfoByName を呼び出して、ユーザーが持っているコンテナーを表示します。
XGameSaveCreateContainer を使用して、新規または既存のコンテナーへのコンテナー ハンドルを取得します。コンテナーが既に存在する場合は、そのハンドルが提供されます。コンテナーが存在しない場合は、新しいコンテナーが作成され、そのハンドルが提供されます。
コンテナーを削除するには、XGameSaveDeleteContainer を使用します。コンテナー内のすべての BLOB も削除されます。
ハンドル リークを防ぐため、コンテナーが使用されなくなったとき、またはタイトルが中断もしくは終了するときには、XGameSaveCloseContainer ですべてのコンテナー ハンドルを閉じてください。
BLOB 管理
コンテナー内のデータの操作は、XGameSaveCreateUpdate を呼び出して行います。
次の詳細では、XGameSaveUpdate がコンテナー内の BLOB 変更をどのように管理し、各更新がどのように作成、変更、および送信されるかを概説しています。
- 更新は 1 つのコンテナーに適用されます。
- 更新は最大で GS_MAX_BLOB_SIZE (16 MB) まで書き込めます。
- 単一の更新で複数の BLOB を変更できます。
- 単一の BLOB に対しては、1 回の更新につき 1 つの変更しか行えません。
-
更新を送信すると、
XGameSaveUpdateハンドルが消費されます。送信が成功したか失敗したかに関わらず、ハンドルを閉じてください。 - 更新は原子的です。どこか一部でも失敗すると、更新全体が失敗します。
-
XGameSaveCreateUpdateは、すべての BLOB 変更を保存するための更新コンテキストを作成します。 -
XGameSaveSubmitBlobWriteは、新規または既存の BLOB にデータを書き込み、更新コンテキストが必要です。 -
XGameSaveSubmitBlobDeleteは BLOB を削除します。 -
XGameSaveSubmitUpdateは更新コンテキストを送信します。 -
XGameSaveCloseUpdateは更新ハンドルを閉じます。リークを防ぐため、タイトルは毎回の送信後にこれを呼び出します。 -
コンテナー内のすべての BLOB にアクセスするには、
XGameSaveEnumerateBlobInfoまたはXGameSaveEnumerateBlobInfoByNameを使用します。
BLOB に書き込まれたデータは、XML でエクスポートされる際に
Base64 として表現されます。実装
次の手順は、XGameSave の実装の一般的なフローを示します。
- タイトル起動または再開時に、プロバイダーを初期化します。
- コンテナー ハンドルを列挙および作成します。
- BLOB 変更を伴う
XGameSaveUpdatesを定期的に送信し、送信時に更新ハンドルをクリーンアップします。 - タイトルの中断または終了時にコンテナーおよびプロバイダー ハンドルを閉じます。
タイトル起動時と再開時に
XGameSaveInitializeProvider を呼び出してください。この呼び出しにより、プロバイダーが正しく初期化され、タイトルの実行中はアクティブなままとなります。これを呼び出さないと、タイトルの動作が予測できなくなる可能性があります。コード サンプル
XGameSave API の使用方法を示すコード サンプルについては、GameSaveCombo を参照してください。
Game Saves フロー
以下は、簡略化された Game Saves フローのフローチャートです。以下のように説明されます。タイトル開始
タイトル開始は、ユーザーがタイトルを起動または再開したときに発生します。ユーザー サインイン
タイトルはユーザー サインインを開始します。この呼び出しは、XGameSaveInitializeProvider を呼び出す場所でもあります。
ユーザーのセットアップの詳細については、ユーザー モデル を参照してください。
接続チェック
タイトルは XBOX ネットワークに接続できるかを判定します。接続できない場合、タイトルの オフライン モード を有効にするかどうかはあなた次第です。データ所有権チェック
デバイスは、ユーザーが現在他のデバイスでプレイしていないかを確認します。特定のタイトルのユーザーのデータには、一度に 1 つのデバイスのみがアクセスできます。クラウドとのデータ同期
デバイスは、Game Saves のローカル ストレージ データをクラウドと同期します。競合がある場合、システムは競合解決ダイアログでユーザーに確認を求めます。 ダイアログ: どちらを使用しますか? デバイス上のデータがクラウドのデータより新しい場合、タイトルは、ローカル データを使うかクラウド データを使うかをユーザーに選択するよう求めます。ゲームプレイ ループ
タイトルは、Game Saves のローカル ストレージへの読み書きを自由に行えます。ゲーム セッションの終了
ゲーム セッションが終了すると、システムは自動的にデータのクラウドへのアップロードを試みます。プロバイダーが初期化されたまま残らないように、タイトルの終了フローでXGameSaveUninitializeProvider を呼び出すようにしてください。整然としたシャットダウンにより、終了する前にデータがクリーンに保存されるようになります。
同期の詳細については、Game Saves の同期フローについて を参照してください。
制限とクォータ
制限
XGameSaveUpdate は各更新を 16 MB に制限しています。その結果、XGameSave は最大 16 MB までの個別ファイル更新のみを管理できます。この制限は、64 MB までのファイルをサポートする XGameSaveFiles とは異なります。
クォータ
ユーザーがタイトルごとに保存できる最大データは 256 MB です。残りのクォータを取得するには、XGameSaveGetRemainingQuota を使用します。タイトルのストレージ拡張を取得するには、開発パートナー マネージャー (DPM) に連絡してください。ベスト プラクティス
- データを保存した直後に、同じデータを問い合わせて要求しないでください。
- コンテナー間のデータ依存関係は信頼できません。各
XGameSaveSubmitUpdate呼び出しは、すべての変更を原子的に適用するか、まったく適用しないかのどちらかです。 - 1 回の更新呼び出しで使用する BLOB が多いほど、データを保存するために必要なファイル システム操作の原子的な操作を完了するのに必要な時間が長くなります。
よくある質問
Game Saves の実装をアップグレードしています。正しいアプローチは何ですか?
XGameSaveFiles を使用してください。XGameSave を XGameSaveFiles と一緒に使用できますか?
はい。ただし、これは移行の場合にのみ行ってください。詳細については、XGameSave と XGameSaveFiles の相互運用性 を参照してください。XGameSave はどのファイル パスに保存されますか?
コンソール: タイトルがアクティブな間に一時的なパスが提供されます。コンソール ファイルにはエクスプローラーを使用してアクセスできません。 PC:%AppData%\Local\Packages\<PACKAGE_NAME>\SystemAppData\wgs\<HexXuid>_<SCID>\
XGameSave の PC パスは XGameSaveFiles とは異なることに注意してください。xgs を使用します。