XBOX 成就管理員 API 概觀 - XBOX Game Development Documentation

XBOX 成就管理員 API 可簡化 XBOX Live 使用者成就狀態的追蹤與更新。 XBOX 提供一種方式，透過在特定時間點授予成就，來追蹤使用者在遊戲中的進度與成就。使用 XBOX Services API (XSAPI) 中的成就 API 讓每位本機使用者的成就資訊保持最新，可能相當複雜。若未正確執行，可能會導致效能問題、資料過時，或因呼叫 XBOX 成就服務的頻率高於必要而遭到節流。 Social Manager 透過下列方式解決此問題：

建立簡單易呼叫的 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; 
        } 
    } 
} 

參考

傳回的事件

Local User Initial State Synced：當成就管理員已完成擷取使用者在目前遊戲中所有成就的目前狀態時觸發。

C API: XblAchievementsManagerEventType::LocalUserInitialStateSynced

Achievement Progress Updated：當使用者在目前遊戲中某項成就的進度已更新時觸發。

C API: XblAchievementsManagerEventType::AchievementProgressUpdated

Achievement Unlocked：當使用者完成目前遊戲中某項成就的所有需求時觸發。

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
    }
}

參考

傳回的事件

Local User Initial State Synced：當成就管理員已完成擷取使用者在目前遊戲中所有成就的目前狀態時觸發。

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); 

參考

傳回的事件

Local User Initial State Synced：當成就管理員已完成擷取使用者在目前遊戲中所有成就的目前狀態時觸發。

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); 

參考

傳回的事件

Local User Initial State Synced：當成就管理員已完成擷取使用者在目前遊戲中所有成就的目前狀態時觸發。

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); 

參考

傳回的事件

Local User Initial State Synced：當成就管理員已完成擷取使用者在目前遊戲中所有成就的目前狀態時觸發。

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); 

參考

傳回的事件

Local User Initial State Synced：當成就管理員已完成擷取使用者在目前遊戲中所有成就的目前狀態時觸發。

C API: XblAchievementsManagerEventType::LocalUserInitialStateSynced

更新使用者的成就

更新使用者某項成就的進度。 C API

HRESULT hr = XblAchievementsManagerAddLocalUser(userHandle, nullptr);

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

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

參考

傳回的事件

Local User Initial State Synced：當成就管理員已完成擷取使用者在目前遊戲中所有成就的目前狀態時觸發。

C API: XblAchievementsManagerEventType::LocalUserInitialStateSynced

其他詳細資料

只有遊戲管理型成就可以使用 XblAchievementsManagerUpdateAchievement 進行更新。如需更新事件型成就，請參閱寫入事件以驅動事件型成就。

清除成就管理員

從成就管理員移除使用者時，會從成就管理員中移除該使用者的快取成就。已移除的使用者應該不會再收到任何事件。 C API

HRESULT hr = XblAchievementsManagerRemoveLocalUser(userHandle);

參考

XblAchievementsManagerRemoveLocalUser

​功能

​核心概念

​API 概觀

​將本機使用者新增至成就管理員

​取得使用者的成就狀態

​使用方式

​使用成就管理員事件

​傳回的事件

​其他詳細資料

​註冊要追蹤成就的使用者

​傳回的事件

​其他詳細資料

​擷取使用者的單一成就

​傳回的事件

​擷取使用者的所有成就

​傳回的事件

​擷取使用者的部分成就

​傳回的事件

​擷取使用者處於特定狀態的部分成就

​傳回的事件

​更新使用者的成就

​傳回的事件

​其他詳細資料

​清除成就管理員

功能

核心概念

API 概觀

將本機使用者新增至成就管理員

取得使用者的成就狀態

使用方式

使用成就管理員事件

傳回的事件

其他詳細資料

註冊要追蹤成就的使用者

傳回的事件

其他詳細資料

擷取使用者的單一成就

傳回的事件

擷取使用者的所有成就

傳回的事件

擷取使用者的部分成就

傳回的事件

擷取使用者處於特定狀態的部分成就

傳回的事件

更新使用者的成就

傳回的事件

其他詳細資料

清除成就管理員