游戏存档简化包装器
现有 XGameSave API 使开发人员能够尽可能最好地控制他们管理游戏存档系统的方式。 API 提供了对有关如何同步化和事务性更新之性能、线程处理和策略的完全控制。 对于不需要此类控制的游戏和仅希望通过简单方式将可漫游存档集成到游戏中的开发人员，我们提供了 C++ 包装器，该包装器呈现的 API 要简单得多。
简化包装器以 .spp 文件的形式提供，可集成到游戏中：%GRDKLatest%GameKit\Include\xgamesavewrappers.hpp。
游戏应选择想要使用的解决方案：XGameSave API 或简化包装器。
除非游戏修改 .hpp 文件的源代码，否则不应将这两种解决方案混合到一起。
简化包装器遵循完整 API 的所有限制，因为它是使用 XGameSave API 实现的。
使用包装器
使用包装器非常简单，如以下步骤所示。
- 在项目中添加 xgamesavewrappers.hpp。
- 创建新的 Provider 类。 请务必在游戏生命周期内保留指向此对象的指针。
- 调用 Provider::Initialize 以同步游戏的用户存档。 在调用其他保存游戏包装器 API 前必须执行此操作。 不应在游戏的 UI 线程上对此调用进行调用，因为它可能会阻止显示 UI。
与完整的 XGameSave API 一样，游戏的存档是单个存储空间的一部分。 存储空间由多个容器组成，游戏可以选择定义这些容器。 每个容器均可由多个 blob 组成。 这些 blob 是游戏读取和写入的数据。
初始化 Provider 类后，游戏可以使用以下任意组合：
- 使用 Provider::QueryContainers 或 Provider::QueryContainerBlobs 枚举其容器和 blob。
- 使用 Provider::Load 加载 blob（文件）。
- 使用 Provider::Save 更新或新建 blob（文件）。
- 删除容器及其所有内容或删除容器中的所选 blob。
- 通过调用 Provider::GetQuota 查看剩余的空间大小。
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.
}
}
}