次の方法で共有

セーブデータのシンプルなラッパー

  • [アーティクル]

開発者は、既存の XGameSave API を使用して、セーブ データ システムの管理方法を最大限に管理できます。 API を使用すると、パフォーマンス、スレッド処理、同期方法に関するポリシー、およびトランザクションの細かい制御が可能になります。 このような制御を必要としないゲームや、ローミング可能なセーブを自分のゲームに統合する簡単な方法を求めている開発者のために、API をはるかに使いやすくする C++ ラッパーを提供します。

簡素化されたラッパーは、ゲームに統合できる .spp ファイルとして提供されます (%GRDKLatest%GameKit\Include\xgamesavewrappers.hpp)。

ゲームは、使用するソリューションとして、XGameSave API または簡素化されたラッパーのどちらかを選択する必要があります。 ゲームが .hpp ファイルのソース コードを変更しない限り、この 2 つのソリューションを混在すべきではありません。

簡素化されたラッパーは、XGameSave API を使用して実装されるため、完全な API のすべての制限に従います。

ラッパーの使用

ラッパーの使用は、次の手順に示すように簡単です。

  1. プロジェクトに xgamesavewrappers.hpp を含めます。
  2. 新しい Provider クラスを作成します。 ゲームの有効期間中、このオブジェクトへのポインターを保持するようにしてください。
  3. Provider::Initialize を呼び出して、ゲームのユーザーのセーブを同期します。 この操作は、他のセーブ ゲーム ラッパー API のいずれかを呼び出す前に行う必要があります。 この呼び出しは、ブロックしたり、UI を表示したりする可能性があるため、ゲームの UI スレッドでは呼び出さないでください。

完全な XGameSave API と同様に、ゲームのセーブは単一の記憶領域の一部です。 記憶領域は、ゲームが定義のために選択できる複数のコンテナーで構成されます。 各コンテナーは複数の BLOB から構成されている場合があります。 これらの BLOB は、ゲームが読み取り、書き込みを行うデータです。

Provider クラスの初期化後に、ゲームは次の操作を組み合わせて行うことができます。

Load メソッドの例

次のコード例は、Load メソッドの使用例を示しています。

using Microsoft::Xbox::Wrappers::GameSave;

Provider provider = new Provider();

// NOTE: Initialize will throw an exception if called on the UI thread.
if(SUCCEEDED(provider->Initialize(userHandle, mySCID))
{
   // Note that container names can't contain spaces.
   std::vector<std::string> containers = provider->QueryContainers("Save_slot_1");
   if(containers.size() == 1)
   {
      BlobData data = provider->Load("Save_slot_1", "progress");
      if(!data.empty())
      {
         // Read the data into the game.
      }
      else
      {
         // This is unexpected in this use case because the sample
         // code assumes that there is just one blob in the
         // container. 
      }
   }
}

Save 関数の例

次のコード例は、Save 関数の使用例を示しています。

using Microsoft::Xbox::Wrappers::GameSave;

std::vector<uint8_t> saveData; // Contains the user's data.

Provider provider = new Provider();

// NOTE: Initialize will throw an exception if called on the UI thread.
if(SUCCEEDED(provider->Initialize(userHandle, mySCID))
{  
   // Note that container names can't contain spaces.
   HRESULT hr = provider->Save("Save_slot_1", "progress", saveData.size(), saveData.data());
   if(FAILED(hr))
   {
      if(hr == E_GS_QUOTA_EXCEEDED)
      {
         // Message that the user must clear out saves for this game.
      }
      else if(hr == E_GS_OUT_OF_LOCAL_STORAGE)
      {
         // Message to the user that they have run out of save space on the local device.
      }
      else if(hr == E_GS_UPDATE_TOO_BIG)
      {
         // This is really a development-time item to catch. Your save size was too 
         // big for a given call to save. Each such call is limited to 16 MB (GS_MAX_BLOB_SIZE).
      }
      else if(hr == E_GS_HANDLE_EXPIRED)
      {
         // Need to re-create the provider and try again.
      }
      else
      {
         // Log error.
      }
   }
}

関連項目

XGameSave API リファレンス