ゲームのセーブ

[アーティクル]
05/10/2023

XGameSave API により、ゲームがインターネットに接続されている場合は常にクラウドと同期するローカルストレージにゲームデータを保存できます。保存されたデータは同期された後、接続された他のすべてのデバイスで使用できます。保存されるデータの厳密な細分度は各ゲームによります。再開後も同じゲーム体験が続けられるように、ゲームの状態をできる限り正確に保存することをお勧めします。

単一のセーブデータを書き込むのではなく、ゲームのセーブデータを、単独で更新可能な論理グループに分割すべきです。これにより、さまざまな状況下でゲームから書き込むデータの量を少なくすることができるので、ローカルリソースの使用量と他の IO 使用量を削減できます。この API を使用すると、処理が全面的に成功するか、またはまったく何の効果も発生しないこと (保存処理の途中で致命的なエラーが発生した場合など) が保証されているアトミック操作で、複数のデータアイテムを更新することもできます。

Xbox One ではユーザーがタイトルをすばやく切り替えることができるため、ゲームを設計する際は、ほぼ常に発生する可能性のある Suspend イベントがいつ通知されてもいいように、すぐに現在の状態を保存できるようにしておく必要があります。 XGameSave API では、短い一時停止期間中のタイトルの書き込み速度を最大限に高めるために、タイトル用に予約されていない部分の RAM をストレージの最初のポイントとして使用します。その後、システムはデータを永続ストレージに保持して、最後のアップロード以降のその他のデータ書き込みと照合し、データのアップロードをスケジュールします。データが保存されてアップロード用のキューに入れられた後は、ネットワーク接続の喪失や停電などの障害が発生してもデータは失われません。

XGameSave API

XGameSave API は、以下の機能を提供します。

ユーザーごと、TitleID/サービス構成 ID (SCID) ごとに合計 256 MB のストレージを提供します。
電源障害時の処理を提供します。
データはクラウドと自動的に同期されます。
クラウドにバックアップされたデータは、Xbox One デバイス間で使用できます。
プラットフォームは、タイトルに依存しないデバイス間の同期および競合管理を処理します。
XGameSaveSubmitUpdate (または XGameSaveSubmitUpdateAsync) の呼び出しごとにアップロード可能なデータの量には 16 MB の制限があります。

ユーザーのストレージ容量の制限に達すると、XGameSaveSubmitUpdate および XGameSaveSubmitUpdateAsync の呼び出しは失敗します。使用可能なクォータの量をゲームから知る必要がある場合は、XGameSaveGetRemainingQuota または XGameSaveGetRemainingQuotaAsync を呼び出します。

XGameSave API は、優先するプログラミングモデルに応じて、非同期と同期 (ブロッキング) の両方の呼び出しをサポートします。この API では IO が実行されるため、呼び出しによっては実行に時間を要することがあります。重要なゲームエンジンスレッドから同期 API を呼び出さないでください。 XThreadSetTimeSensitive を呼び出すことによって、重要なゲームエンジンのスレッドをマークすることを検討してください。

ゲームを XGameSave 用に構成する

XGameSave API を使用する場合、すべての読み取りおよび書き込み操作は Xbox サービスプライマリ SCID と関連付けられます。 1 つのゲームに複数のサービス構成が存在し、構成ごとに独自の ID が割り当てられている場合があります。 XGameSave API の初期化には SCID が必要であり、XGameSaveInitializeProviderAsync に SCID を渡す必要があります。 XGameSave API で他のアクションを実行する前に、プロバイダーを初期化する必要があります。

デベロッパーアカウントマネージャー (DAM) を使用すると、別のゲームからセーブデータにアクセスすることもできます (たとえば、現在のバージョンのゲームで、以前のバージョンのゲームからセーブデータを読み取りたい場合)。

XGameSave の概念

API を正しく理解するために、次のような役立つ概念があります。

ストレージ領域:ストレージ領域は、ユーザーのすべてのセーブデータを表します。既定では、ユーザーの TitleID/SCID ごとに 256 MB に制限されています。
ストレージコンテナー: ストレージ領域は、複数のストレージコンテナーで構成できます。各ストレージコンテナーは、ユーザーのセーブデータまたはゲームに適したその他の論理ブロックを表すことができます。各ストレージコンテナーには名前があります。
ストレージ BLOB: 各ストレージコンテナーは、BLOB で構成されます。各 BLOB には名前があります。 BLOB は、ある特定のストレージコンテナーを構成するデータです。

XGameSave のストレージ領域

大まかに言えば、XGameSave システム内のすべてのデータは、1 人のユーザーまたは 1 台のマシン (個々の Xbox One 本体など) のいずれかに関連付けられます。特定のユーザーまたはマシンのアプリによって保存されたすべてのデータは、XGameSave ストレージ領域に保存されます。

ゲームの各ユーザーは XGameSave ストレージ領域を取得しますが、合計で 256 MB の容量に制限されます。これは単一のゲーム専用のストレージであることに注意してください。このストレージは他のゲームとは共有されません。

ストレージ領域を取得するには、ゲームで XGameSaveInitializeProvider または XGameSaveInitializeProviderAsync を呼び出します。 XUserHandle を渡した場合、プロバイダーはそのユーザーのストレージ領域を自動的に取得して同期します。領域の内部にあるすべてのコンテナーが同期されるため、この処理は、特にユーザーがあるデバイス上でデータを保存していて、別のデバイス上で初めてゲームプレイを再開する場合に、実行時間が長くなる可能性があります。この処理が完了した後、以降のストレージ領域との反復では、完了のためにクラウドからの応答を必要としなくなります。

プロバイダーを初期化するときに、ゲームは「オンデマンド同期」の使用を選択できます。このオプションを使用すると、初期同期ではコンテナーに関する必要なメタデータのみがクラウドからダウンロードされます。この処理は高速なので、良好なネットワーク条件下では、おそらくユーザーにロード画面は表示されません。フルダウンロードは、コンテナーに実際にアクセスしたとき (つまり、1 つ以上の BLOB が読み取られるか、BLOB クエリが実行されたとき) にのみ実行されます。

オンデマンドで同期するか、一度にすべてを同期するかの判断はゲームデベロッパーに任されます。ゲームによって保存されるデータの量が少ない場合、またはすべてのデータが同期されるときに 1 つのポイントだけが必要な場合は、「オンデマンド同期」を使用しないことを強くお勧めします。ただし、ゲームで特に大きなセーブデータが使用され、ユーザーがゲームをプレイするためにすべてのセーブデータを必要としない場合は、「オンデマンド同期」を使用すると、必要なときにのみデータを取得できるため、ユーザーエクスペリエンスが大幅に向上する可能性があります。

注意

"オンデマンド同期" を使用する場合、同期を必要とするコンテナーの各アクセスには、ユーザーのさまざまなダイアログボックス ("同期の進行状況" や "競合" など) が表示されます(現在デバイス上にあるものがクラウド内にある可能性のあるものと競合している場合)。

詳細については、オンデマンド同期 (NDA トピック)認可が必須ですの概要を参照してください。

XGameSave コンテナーと BLOB

XGameSave ストレージコンテナー (または単にコンテナー) はストレージの基本単位です。各 XGameSave ストレージ領域には多数のコンテナーを含めることができます。

データは、BLOB と呼ばれる 1 つ以上のバッファーとしてコンテナー内に保存されます。コンテナーごとに、コンテナー内の各 BLOB に対応するデータファイルへの参照を含むコンテナーファイルがあります。

この API のストレージ部分は、ゲームから永続ストレージに、安全で信頼できるトランザクショナルな方式でデータを簡単に転送できるように設計されています。コンテナーへのデータのバックアップには、常に整合性があることを確認する必要があります。そのため、操作全体がアトミックに成功または失敗する必要があります。一部の BLOB データがコンテナー内の他のデータと整合しなくなる部分的な更新が行われないようにする必要があります。これを実現するため、BLOB の書き込みと削除が送信される更新コンテキストが提供されます。準備ができたら、コンテキスト全体が送信されます。

コンテナーの更新を開始するために、ゲームで XGameSaveCreateContainer を呼び出して、先にコンテナーハンドルを取得する必要があります。つづいて、ゲームから XGameSaveCreateUpdate を呼び出して、更新コンテキストを取得する必要があります。ゲームが更新コンテキストを取得した後、XGameSaveSubmitBlobWrite または XGameSaveSubmitBlobDelete を呼び出すことができます。ゲームが変更のバッチを送信する準備ができたら、XGameSaveSubmitUpdate または XGameSaveSubmitUpdateAsync のいずれかを呼び出します。更新内で記述されているすべての変更はアトミックに適用されます。すべての BLOB が要求通りに更新されるか、操作全体が中止されてコンテナーが更新の開始前の状態のままになります。ゲームでは、更新ごとに最大 16 MB のデータに制限されます。

注意

API を XGameSave 使用するには、タイトルに TitleID と SCID が適切に構成されている必要があります。これらの必須 ID の詳細については、「サンドボックスのセットアップ」をご覧ください。パートナーセンターでゲームを Xbox サービス向けに有効にする必要があります。

SCID と TitleID が正しく構成されていない場合は、XSaveGame API を呼び出したときに次のエラーコードが返されます。

E_GS_NO_ACCESS - 0x80830002 - 操作は、タイトルがコンテナーストレージ領域へのアクセス権を持っていないために失敗しました。

次の方法で共有