セーブ データを使用した Win32 ファイル IO (XGameSaveFiles)
XGameSaveFiles は、本体、PC、xCloud 上へのクラウド保存の代替ソリューションを提供します。 XGameSaveFiles を使用すると、開発者が自身の保存システム内で、通常の Win32 ファイル IO 関数 (CreateFile や WriteFile など) を使用することができます。
XGameSaveFiles と XGameSave の比較
次の表は、XGameSaveFiles と XGameSave の違いを示しています
| 機能 | XGameSaveFiles | XGameSave |
|---|---|---|
| Win32 ファイル IO API のサポート | はい | なし |
| バッチ処理された更新のサポート | いいえ | はい |
| ゲームプレイ中の更新のアップロード | いいえ | はい |
| オンデマンド同期のサポート | いいえ | はい |
| Xbox/xCloud でのクロス VM 書き込み | いいえ | はい |
| 初期化 API | XGameSaveFilesGetFolderWithUiAsync | XGameSaveInitalizeProviderAsync |
| ユーザーあたりの既定の容量の上限 | 256 MB | 256 MB |
| ファイルのサイズ制限 | 64 MB* | 16 MB |
* ゲームが XGameSaveFiles と XGameSave の間の相互運用をサポートする必要がある場合、ゲームはファイル サイズを 16 MB に制限する必要があります。
ゲームでは、XGameSaveFiles の使用法と XGameSave の使用法を混在させることはできません。 ゲームは、使用するクラウド保存システムを選択します。 ゲームが XGameSaveFiles を使用しており、後で XGameSaveInitializeProvider を呼び出すと、E_GS_PROVIDER_MISMATCH でエラーが発生します。 同様に、ゲームが XGameSave を使用しており、後で XGameSaveFilesGetFolderWithUiAsync を呼び出すと、これも E_GS_PROVIDER_MISMATCH でエラーが発生します。
XGameSaveFiles と XGameSave のどちらを使用するかを選択する
XGameSave と XGameSaveFiles はどちらも、本体、PC、および xCloud 間で共有できるクラウド保存を可能にする保存システムを提供します。
上記の表で強調表示されている違いに加えて、XGameSave は、開発者が書き込みを簡単にバッチ処理し、それらの書き込みがアトミック アクションとして確実に行われるようにする最も堅牢なソリューションを提供します。 XGameSaveFiles は、既に PC に Win32 スタイルの保存システムがあり、そのソリューションを PC Game Pass で機能するものに移植するコストを最小限に抑えたい開発者に最適です。
XGameSaveFiles を使用して更新プログラムがアップロードされる場合
セーブ データに対する更新はゲーム側の責任ではなく、ゲームが "アクティブ" でないときに自動的に処理されます。 "アクティブ" でないという意味は、プラットフォームによって異なります。
本体または xCloud で "アクティブ" でないとは、以下を意味します。
- ゲームが一時停止した
- ゲームが終了した
- セーブ データが追跡されているユーザーがサインアウトした
PC で "アクティブ" でないとは、以下を意味します。
- ゲームが終了した
- セーブ データが追跡されているユーザーがサインアウトした
- PC 上の電源状態の変更
- ゲームがバックグラウンドにあるか、XGameSaveFiles に対して新しい書き込みを行っていない状態で 30 分が経過した
XGameSaveFiles の使用
XGameSaveFiles を使用するには、開発者は XGameSaveFilesGetFolderWithUiAsync を呼び出す必要があります。これにより、セーブ データを管理するユーザーの XUser ハンドルと、ゲームの SCID (Xbox サービス サービス構成 ID) が渡されます。 その後、開発者が XGameSaveFilesGetFolderWithUiResult を呼び出すと、CreateFile、WriteFile などの標準の Win32 ファイル IO API を使用して、そのフォルダーへの読み取りと書き込みの両方で、ゲームセーブに使用できるフォルダーが取得されます。
ゲームが再開されると、開発者は XGameSaveFilesGetFolderWithUiAsync を呼び出して、保存データが完全に最新の状態になるようにする必要があります。
開発者は、Win32 ファイル IO API によって次のエラーが返されることに注意する必要があります。
| エラー | XGameSaveFiles のコンテキストでの説明 |
|---|---|
| STATUS_NAME_TOO_LONG | ディレクトリ名が長すぎます |
| STATUS_OBJECT_NAME_INVALID | ディレクトリ名に、クラウド サービスで無効な文字が含まれています |
| STATUS_NAME_TOO_LONG | ファイル名 (ディレクトリを除く) が長すぎます |
| STATUS_FILE_TOO_LARGE | ファイル サイズが 64 MB を超えました |
| STATUS_FILE_TOO_LARGE | ゲームが、ユーザーあたりのセーブ データの最大クォータを超えました |
| STATUS_INSUFFICIENT_RESOURCES | ゲームが、デバイス上に割り当てられた記憶領域を超えました |
開発者は、XGameSaveFilesGetRemainingQuota を呼び出して、ユーザーあたりの残りのクォータ量を確認することができます。
XGameSaveFiles でのディレクトリとファイル名の制限
XGameSaveFiles では、クラウド保存システムの詳細の大部分が開発者に表示されませんが、ディレクトリおよびファイル名は Azure Blob Storage によってサポートされているため、制限があります。 大まかに言うと、完全なディレクトリ パスはコンテナーにマップされ、ファイル名は BLOB にマップされます。 ゲーム セーブで使用される例を次に示します。
[ROOT]/Save1/BraveNewWorld/state001.dat
- 「[ROOT]」は、XGameSaveFilesGetFolderWithUiAsync によって返されます。
- 最後のスラッシュを含む「[ROOT]」に続くすべてのものは、コンテナーにマップされます。
- コンテナー名は、大文字 (A ～ Z)、小文字 (a ～ z)、数字 (0 ～ 9)、アンダースコア (_)、ピリオド (.)、ハイフン (-)、スラッシュ (/) に制限されます
- コンテナー名は 256 文字以下に制限されます
- コンテナー名の末尾をピリオドにすることはできません。また、ピリオドを 2 つ連続して使用したり、ピリオドまたはハイフンで始めたりすることもできません。
- 最後のスラッシュに続くすべて (ファイル名) が BLOB にマップされます
- ファイル名は 65 文字に制限されていますが、それ以外は NTFS でサポートされている Unicode 文字を使用できます
- ファイル名を含む完全なパス (ただし、「[ROOT]」) はMAX_PATH (260 文字) 未満である必要があります
XGameSaveFiles 開発ツール
XGameSaveFiles では、XGameSave と同じ開発ツールが使用されます。 API は異なりますが、使用する XGameSave 記憶領域とデータはまったく同じです。 次のツールは、XGameSaveFiles の開発に役立ちます。
- xbstorage
- xgamesaveutil
- Fiddler
xbstorage を使用した本体上での XGameSave データの管理
Xbstorage.exe は、開発用 PC から Xbox 開発キット上のローカル XGameSave データを管理できる開発ツールです。
このツールでは、ローカル XGameSave 記憶領域をハード ドライブから消去したり、XML ファイルを使用して個々のユーザーの接続またはマシンの接続ストレージ領域をインポートおよびエクスポートしたりできます。
ローカルの XGameSave ストレージ領域で操作が実行されると、システムは、その処理がアプリ自体によって実行された場合と同様に動作します。 XGameSave 記憶領域からローカル ファイルにデータをコピーすると、コピーの前にクラウドとの同期が行われます。
同様に、開発用 PC 上の .xml ファイルから Xbox One 開発キット上の XGameSave ストレージ コンテナーにデータをコピーすると、そのデータをクラウドにアップロードする処理が本体によって開始されます。 例外があります。開発キットがロックを取得できない場合、つまり、本体上のコンテナーとクラウド上のコンテナーの間で競合がある場合です。 そのような場合、本体は、(保持するコンテナーのバージョンを選択するなどして) ユーザーが競合を解決しないと決定した場合と同様に動作し、次にタイトルが起動されるまで、オフラインでプレイする場合と同様に動作します。
xbstorage reset コマンドは、すべてのサービス構成識別子 (SCID) とユーザーのゲーム セーブ データのローカル記憶域を消去しますが、クラウドに格納されているデータは変更しません。 これは、ユーザーが別の本体にローミングして、タイトルのプレイ時にクラウドからデータをダウンロードする状態に本体を設定する際に役立ちます。
xbstorage.exe の詳細については、本体上での XGameSave データの管理 (xbstorage.exe) (NDA トピック)認可が必須です に関するページをご覧ください。
xgamesaveutil を使用した PC 上の XGameSave データの管理
Xgamesaveutil.exe は、PC 上で実行されているゲームのローカル XGameSave データを管理できる開発ツールです。 本体上のセーブ データの管理に使用される xbstorage ツールと同じ機能があります。
xgamesaveutil.exe の詳細については、PC 上での XGameSave データの管理 (xgamesaveutil.exe) に関するページをご覧ください。
Fiddler を使用した XGameSave ネットワーク アクティビティの監視
クラウド ストレージの処理の実行時に、お使いのデバイスがサービスとやり取りしているかどうかを確認できると便利な場合があります。 Fiddler を使用すると、お使いのデバイスでサービスの呼び出しが正常に行われているかどうか、または本体で承認エラーが発生しているかどうかの確認に役立ちます。
本体での Fiddler のセットアップ方法については、Xbox 本体で Fiddler を使用する方法に関するページをご覧ください。
PC 上での Fiddler のセットアップ方法については、Windows PC 上の Fiddler に関するページをご覧ください。
XGameSaveFiles および XGameSave と接続ストレージの間の相互運用
XGameSave と接続ストレージは、ゲームで記述されたコードなしでセーブ状態を簡単に共有できますが、XGameSaveFiles を利用しているゲームに同じセーブ データを移動しようとしても、必ずしも同じようにはいきません。 これは一般的なシナリオではありませんが、ゲームで XGameSaveFiles との相互運用が必要になることもあります。 一般的な理由は次のとおりです。
- 発行元の本体上の既存のゲームが、既に接続ストレージまたは XGameSave のいずれかを使用している
- 発行元が、XGameSaveFiles を使用するように既存のゲームを更新したくない
- 発行元が、XGameSaveFiles を PC ゲームに追加する方が XGameSave を追加するよりも簡単だと思っているが、PC と本体と xCloud の間のクロスセーブの進行状況をサポートしたいと考えている
XGameSave と XGameSaveFiles の間の移動は非常に簡単です。 タイトルが XGameSaveFilesGetFolderWithUiAsyncを呼び出すと、次のルールを使用して、コンテナーと BLOB がディレクトリとファイルにマッピングされます。
- コンテナー名内のスラッシュ (L'/') は、ファイルが配置されるディレクトリ構造を作成するために使用されます
- 次の文字は XGameSaveFiles では無効であり、検出された場合はアンダースコア (L'_') にマップされます
- L'\0' から L'\001f' までのすべての文字 (両端を含む)
- 次の文字は XGameSaveFiles では無効であり、検出された場合はピリオド (L'.') にマップされます
- 二重引用符 (L'"')
- より小さい (L'<')
- より大きい (L'>')
- パイプ記号 (L'|')
- アスタリスク (L'*')
- 疑問符 (L'?')
- バック スラッシュ (L'\')
- BLOB 名のスラッシュ (L'/') は、ファイル名のピリオド (L'.') にマップされます
XGameSaveFiles から XGameSave に戻るとき、ファイル名が変更または移動されなかったと仮定すると、元のコンテナー名と BLOB 名が復元されます。