XBOX 成就管理器 API 概述

XBOX 成就管理器 API 简化了跟踪和更新 XBOX Live 用户成就状态的过程。 XBOX 通过在特定时刻授予成就来提供跟踪用户在其游戏中进度和成就的方法。使用 XBOX 服务 API (XSAPI) 中的成就 API 来保持每个本地用户的成就信息为最新可能很复杂。如果不正确地执行此操作,可能会导致性能问题、数据过时或由于调用 XBOX 成就服务的频率高于必要频率而被限流。社交管理器通过以下方式解决此问题:

创建一个易于调用的 API。
在后台使用实时活动服务创建最新的信息。
开发人员可以同步调用成就管理器 API,而不会对服务造成额外的压力。

成就管理器掩盖了处理多个 RTA 订阅、刷新用户数据以及减少对成就服务的调用次数的复杂性,让开发人员能够轻松获取最新的成就数据。

功能

成就管理器提供以下功能:

简化的成就 API
每个用户的最新成就状态和进度
减少对 XBOX 服务的调用次数
- 这直接关系到数据获取的整体延迟减少
线程安全
高效地保持数据为最新

核心概念

成就:成就包括游戏得分和其他奖励,例如数字美术品、新地图、角色和统计信息提升,以及朝向完成的当前进度。要保持用户成就的状态为最新,必须每帧调用函数 XblAchievementsManagerDoWork。

在 Windows 上只能有一个本地用户

API 概述

您将最常使用以下关键 API。您可以在 XBOX Live API 参考中找到成就管理器 API 的完整说明。您还可以在 XblAchievementsManager 前缀文档中找到这些 API。

将本地用户添加到成就管理器

C API 函数:XblAchievementsManagerAddLocalUser

将本地用户添加到成就管理器会使当前游戏中该用户所有成就的状态从服务中获取并本地保存。成就管理器将为当前游戏保持该用户每个成就的最新状态。

获取用户的成就状态

C API 函数:XblAchievementsManagerGetAchievements

调用此函数将返回与指定条件匹配的成就的句柄。句柄指向的成就是匹配成就的线程安全副本。句柄指向的数据将存在,直到句柄关闭为止,但如果游戏在下一次调用 XblAchievementsManagerDoWork 之后保持句柄,则可能会过时。

用法

使用成就管理器事件

成就管理器以事件的形式告知您发生了什么。您可以使用这些事件来更新 UI 或执行其他逻辑。 C API

// some update loop in the game
while(true) 
{ 
    size_t eventsCount{}; 
    const XblAchievementsManagerEvent* events{}; 
    HRESULT hr = XblAchievementsManagerDoWork(&events, &eventsCount); 
    if (FAILED(hr))
    {
        // handle the error
    }

    for (uint32_t i = 0; i < eventsCount; ++i) 
    { 
        // act on the event
        switch (events[i].eventType) 
        { 
        case XblAchievementsManagerEventType::LocalUserInitialStateSynced: 
            // ...
            break; 
        case XblAchievementsManagerEventType::AchievementProgressUpdated: 
            // ...
            break; 
        case XblAchievementsManagerEventType::AchievementUnlocked: 
            // ...
            break; 
        default: 
            break; 
        } 
    } 
} 

参考

返回的事件

本地用户初始状态已同步:当成就管理器完成获取用户当前游戏所有成就的当前状态时触发。

C API:XblAchievementsManagerEventType::LocalUserInitialStateSynced

成就进度已更新:当用户在当前游戏成就上的进度已更新时触发。

C API:XblAchievementsManagerEventType::AchievementProgressUpdated

成就已解锁:当用户完成当前游戏成就的所有要求时触发。

C API:XblAchievementsManagerEventType::AchievementUnlocked

其他详细信息

成就管理器不是在游戏循环期间频繁地从服务中获取成就状态,而是在用户向成就管理器注册时获取该用户的所有成就的状态。然后,成就管理器从服务接收有关用户成就更新的事件,然后将这些事件作为由 XblAchievementsManagerDoWork 函数返回的 events 转发给游戏。 events 是 XblAchievementsManagerEvent 的列表,每个 XblAchievementsManagerEvent 包含在上一帧期间发生的成就更改。有关更多信息,请参阅 XblAchievementsManagerEvent API 文档。

注册要跟踪成就的用户

在此场景中,您希望向成就管理器注册用户以开始跟踪该用户成就的更新,并在本地缓存该用户所有成就的状态。 C API

HRESULT hr = XblAchievementsManagerAddLocalUser(userHandle, nullptr);

if (!SUCCEEDED(hr))
{
    return;
}

// some update loop in the game 
while(true)
{
    const XblAchievementsManagerEvent* events{ nullptr };
    size_t eventCount{ 0 };
    HRESULT hr = XblAchievementsManagerDoWork(&events, &eventCount);
    if (SUCCEEDED(hr))
    {
        return;   
    }
    for (size_t i = 0; i < eventCount; i++)
    {
        // Act on the event
    }
}

参考

返回的事件

本地用户初始状态已同步:当成就管理器完成获取用户当前游戏所有成就的当前状态时触发。

C API:XblAchievementsManagerEventType::LocalUserInitialStateSynced

其他详细信息

上面的示例展示了如何为用户初始化成就管理器,并保持其为最新状态。在游戏循环中,XblAchievementsManagerDoWork 函数处理并应用对用户成就所做的任何更新。

检索用户的单个成就

在此场景中,您希望获取用户的单个成就的状态。 C API

HRESULT hr = XblAchievementsManagerAddLocalUser(userHandle, nullptr);

if (!XblAchievementsManagerIsUserInitialized(xboxUserId))
{
    return;
}

const XblAchievement* achievement = nullptr; 
uint64_t size; 
XblAchievementsManagerResultHandle resultHandle; 

HRESULT hr = XblAchievementsManagerGetAchievement( 
    xboxUserId, 
    achievementId, 
    &resultHandle 
); 

if(FAILED(hr)) 
{ 
    return; 
} 

hr = XblAchievementsManagerResultGetAchievements( 
    resultHandle, 
    &achievement, 
    &size 
); 
if(FAILED(hr)) 
{ 
    return; 
} 

// make use of achievement struct

XblAchievementsManagerResultCloseHandle(resultHandle); 

参考

返回的事件

本地用户初始状态已同步:当成就管理器完成获取用户当前游戏所有成就的当前状态时触发。

C API:XblAchievementsManagerEventType::LocalUserInitialStateSynced

检索用户的所有成就

在此场景中,您希望获取用户所有成就的状态。 C API

HRESULT hr = XblAchievementsManagerAddLocalUser(userHandle, nullptr);

if (!XblAchievementsManagerIsUserInitialized(xboxUserId))
{
    return;
}

XblAchievementsManagerResultHandle resultHandle; 
const XblAchievement* achievements; 
uint64_t achievementsCount; 

hr = XblAchievementsManagerGetAchievements( 
    xboxUserId, 
    XblAchievementOrderBy::DefaultOrder, 
    XblAchievementsManagerSortOrder::Unsorted, 
    &resultHandle 
); 

if(FAILED(hr)) 
{ 
    return; 
} 

hr = XblAchievementsManagerResultGetAchievements( 
    resultHandle, 
    &achievements, 
    &achievementsCount 
); 

if(FAILED(hr)) 
{ 
    return; 
} 
 
for (uint32_t i = 0; i < achievementsCount; ++i) 
{ 
    // ... 
} 
XblAchievementsManagerResultCloseHandle(resultHandle); 

参考

返回的事件

本地用户初始状态已同步:当成就管理器完成获取用户当前游戏所有成就的当前状态时触发。

C API:XblAchievementsManagerEventType::LocalUserInitialStateSynced

检索用户的成就子集

在此场景中,您希望获取用户成就子集的状态。 C API

HRESULT hr = XblAchievementsManagerAddLocalUser(userHandle, nullptr);

if (!XblAchievementsManagerIsUserInitialized(xboxUserId))
{
    return;
}

XblAchievementsManagerResultHandle resultHandle; 
const XblAchievement* achievements; 
uint64_t achievementsCount; 

hr = XblAchievementsManagerGetAchievements( 
    xboxUserId, 
    XblAchievementOrderBy::UnlockTime, 
    XblAchievementsManagerSortOrder::Descending, 
    &resultHandle 
); 

if(FAILED(hr)) 
{ 
    return; 
} 

hr = XblAchievementsManagerResultGetAchievements( 
    resultHandle, 
    &achievements, 
    &achievementsCount 
); 

if(FAILED(hr)) 
{ 
    return; 
} 
 
for (uint32_t i = 0; i < achievementsCount; ++i) 
{ 
    // ... 
} 
XblAchievementsManagerResultCloseHandle(resultHandle); 

参考

返回的事件

本地用户初始状态已同步:当成就管理器完成获取用户当前游戏所有成就的当前状态时触发。

C API:XblAchievementsManagerEventType::LocalUserInitialStateSynced

检索用户特定状态的成就子集

在此场景中,您希望获取用户特定进度状态下的成就子集的状态。 C API

HRESULT hr = XblAchievementsManagerAddLocalUser(userHandle, nullptr);

if (!XblAchievementsManagerIsUserInitialized(xboxUserId))
{
    return;
}

XblAchievementsManagerResultHandle resultHandle; 
const XblAchievement* achievements; 
uint64_t achievementsCount; 

hr = XblAchievementsManagerGetAchievementsByState( 
    xboxUserId, 
    XblAchievementOrderBy::DefaultOrder, 
    XblAchievementsManagerSortOrder::Unsorted, 
    XblAchievementProgressState::NotStarted, 
    &resultHandle 
); 

if(FAILED(hr)) 
{ 
    return; 
} 

hr = XblAchievementsManagerResultGetAchievements( 
    resultHandle, 
    &achievements, 
    &achievementsCount 
); 

if(FAILED(hr)) 
{ 
    return; 
} 
 
for (uint32_t i = 0; i < achievementsCount; ++i) 
{ 
    // ... 
} 
XblAchievementsManagerResultCloseHandle(resultHandle); 

参考

返回的事件

本地用户初始状态已同步:当成就管理器完成获取用户当前游戏所有成就的当前状态时触发。

C API:XblAchievementsManagerEventType::LocalUserInitialStateSynced

更新用户的成就

更新用户的成就进度。 C API

HRESULT hr = XblAchievementsManagerAddLocalUser(userHandle, nullptr);

if (!XblAchievementsManagerIsUserInitialized(xboxUserId))
{
    return;
}

XblAchievementsManagerUpdateAchievement(xboxUserId, achievementId.c_str(), progress);

参考

返回的事件

本地用户初始状态已同步:当成就管理器完成获取用户当前游戏所有成就的当前状态时触发。

C API:XblAchievementsManagerEventType::LocalUserInitialStateSynced

其他详细信息

只有游戏管理的成就可以使用 XblAchievementsManagerUpdateAchievement 进行更新。有关更新基于事件的成就,请参阅写入事件以驱动基于事件的成就。

清理成就管理器

从成就管理器中删除用户会从成就管理器中删除用户的缓存成就。不应为已删除的用户接收进一步的事件。 C API

HRESULT hr = XblAchievementsManagerRemoveLocalUser(userHandle);

参考

XblAchievementsManagerRemoveLocalUser

XBOX Services

PlayFab

功能

核心概念

API 概述

将本地用户添加到成就管理器

获取用户的成就状态

用法

使用成就管理器事件

返回的事件

其他详细信息

注册要跟踪成就的用户

返回的事件

其他详细信息

检索用户的单个成就

返回的事件

检索用户的所有成就

返回的事件

检索用户的成就子集

返回的事件

检索用户特定状态的成就子集

返回的事件

更新用户的成就

返回的事件

其他详细信息

清理成就管理器

​功能

​核心概念

​API 概述

​将本地用户添加到成就管理器

​获取用户的成就状态

​用法

​使用成就管理器事件

​返回的事件

​其他详细信息

​注册要跟踪成就的用户

​返回的事件

​其他详细信息

​检索用户的单个成就

​返回的事件

​检索用户的所有成就

​返回的事件

​检索用户的成就子集

​返回的事件

​检索用户特定状态的成就子集

​返回的事件

​更新用户的成就

​返回的事件

​其他详细信息

​清理成就管理器

功能

核心概念

API 概述

将本地用户添加到成就管理器

获取用户的成就状态

用法

使用成就管理器事件

返回的事件

其他详细信息

注册要跟踪成就的用户

返回的事件

其他详细信息

检索用户的单个成就

返回的事件

检索用户的所有成就

返回的事件

检索用户的成就子集

返回的事件

检索用户特定状态的成就子集

返回的事件

更新用户的成就

返回的事件

其他详细信息

清理成就管理器