XBOX Achievements Manager API の概要 - XBOX Game Development Documentation

XBOX Achievements Manager API は、XBOX Live ユーザーの実績状態の追跡および更新を簡素化します。 XBOX では、ゲーム中の特定のポイントで実績を付与することで、ユーザーの進行状況や達成を記録できます。 XBOX Services API (XSAPI) の実績 API を使用して、各ローカルユーザーの実績情報を最新に保つのは複雑になり得ます。これを正しく行わないと、パフォーマンス上の問題、古いデータ、あるいは必要以上に頻繁に XBOX 実績サービスを呼び出したことによるスロットリングが発生する可能性があります。 Social Manager は次の方法でこの問題を解決します。

呼び出しやすいシンプルな API の提供。
内部でリアルタイムアクティビティサービスを利用して最新情報を作成。
開発者はサービスへの余計な負荷をかけることなく、Achievements Manager API を同期的に呼び出せます。

Achievements Manager は、複数の RTA サブスクリプションの扱い、ユーザーデータの更新、実績サービスへの呼び出し回数の削減といった複雑さを隠蔽し、開発者が最新の実績データを簡単に取得できるようにします。

機能

Achievements Manager では次の機能が提供されます。

簡素化された実績 API
各ユーザーの最新の実績状態と進行状況
XBOX services への呼び出し回数の削減
- データ取得における全体的なレイテンシの低減に直結します
スレッドセーフ
データを効率的に最新に保つ

主要な概念

実績 (Achievements): 実績には Gamerscore や、デジタルアートワーク、新しいマップ、キャラクター、ステータスブーストなどのその他の報酬、および完了までの現在の進行状況が含まれます。ユーザーの実績状態を最新に保つには、XblAchievementsManagerDoWork 関数を毎フレーム呼び出す必要があります。

Windows ではローカルユーザーは 1 人しか存在できません。

API の概要

次に示す主要な API を最も頻繁に使用することになります。 Achievements Manager API の完全な説明は、XBOX Live API リファレンスにあります。また、XblAchievementsManager プレフィックスのドキュメントでも API を確認できます。

Achievements Manager へのローカルユーザーの追加

C API 関数: XblAchievementsManagerAddLocalUser

Achievements Manager にローカルユーザーを追加すると、現在のタイトルにおけるそのユーザーのすべての実績の状態がサービスから取得され、ローカルに保存されます。 Achievements Manager は、現在のタイトルにおけるそのユーザーの各実績を最新に保ちます。

ユーザーの実績状態の取得

C API 関数: XblAchievementsManagerGetAchievements

この関数を呼び出すと、指定した条件に一致する実績へのハンドルが返されます。ハンドルが指す実績は、一致する実績のスレッドセーフなコピーです。ハンドルが指すデータはハンドルが閉じられるまで存在しますが、XblAchievementsManagerDoWork の次の呼び出しをタイトルがハンドルを保持したまま超えると、古くなる可能性があります。

使用方法

Achievements Manager イベントの使用

Achievements Manager は、発生した内容をイベントの形式で通知します。これらのイベントを利用して 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: Achievements Manager が、ユーザーの現在のタイトルのすべての実績の現在の状態の取得を完了したときに発生します。

C API: XblAchievementsManagerEventType::LocalUserInitialStateSynced

Achievement Progress Updated: 現在のタイトルの実績に対するユーザーの進行状況が更新されたときに発生します。

C API: XblAchievementsManagerEventType::AchievementProgressUpdated

Achievement Unlocked: ユーザーが現在のタイトルの実績のすべての要件を完了したときに発生します。

C API: XblAchievementsManagerEventType::AchievementUnlocked

追加の詳細

ゲームループ中にサービスから頻繁に実績の状態を取得する代わりに、Achievements Manager は Achievements Manager にユーザーが登録された時点でそのユーザーのすべての実績の状態を取得します。その後、Achievements Manager はサービスからユーザーの実績の更新に関する詳細イベントを受信し、それらは XblAchievementsManagerDoWork 関数から返される events としてタイトルに転送されます。 events は XblAchievementsManagerEvent のリストであり、各 XblAchievementsManagerEvent には直前のフレーム中に発生した実績への変更が含まれています。詳細は XblAchievementsManagerEvent API ドキュメントを参照してください。

実績を追跡するユーザーの登録

このシナリオでは、Achievements Manager にユーザーを登録して、そのユーザーの実績への更新の追跡を開始し、そのユーザーのすべての実績の状態をローカルにキャッシュします。 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: Achievements Manager が、ユーザーの現在のタイトルのすべての実績の現在の状態の取得を完了したときに発生します。

C API: XblAchievementsManagerEventType::LocalUserInitialStateSynced

追加の詳細

上記の例では、ユーザーに対して Achievements Manager を初期化し、最新に保つ方法を示しています。ゲームループでは、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: Achievements Manager が、ユーザーの現在のタイトルのすべての実績の現在の状態の取得を完了したときに発生します。

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: Achievements Manager が、ユーザーの現在のタイトルのすべての実績の現在の状態の取得を完了したときに発生します。

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: Achievements Manager が、ユーザーの現在のタイトルのすべての実績の現在の状態の取得を完了したときに発生します。

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: Achievements Manager が、ユーザーの現在のタイトルのすべての実績の現在の状態の取得を完了したときに発生します。

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: Achievements Manager が、ユーザーの現在のタイトルのすべての実績の現在の状態の取得を完了したときに発生します。

C API: XblAchievementsManagerEventType::LocalUserInitialStateSynced

追加の詳細

XblAchievementsManagerUpdateAchievement を使用して更新できるのは、タイトルマネージド実績のみです。イベントベースの実績の更新については、イベントベースの実績を有効にするためのイベントの書き込みを参照してください。

Achievements Manager のクリーンアップ

Achievements Manager からユーザーを削除すると、Achievements Manager からそのユーザーのキャッシュされた実績が削除されます。削除されたユーザーについて、それ以降イベントは受信されないはずです。 C API

HRESULT hr = XblAchievementsManagerRemoveLocalUser(userHandle);

リファレンス

XblAchievementsManagerRemoveLocalUser

​機能

​主要な概念

​API の概要

​Achievements Manager へのローカル ユーザーの追加

​ユーザーの実績状態の取得

​使用方法

​Achievements Manager イベントの使用

​返されるイベント

​追加の詳細

​実績を追跡するユーザーの登録

​返されるイベント

​追加の詳細

​ユーザーの単一実績の取得

​返されるイベント

​ユーザーのすべての実績の取得

​返されるイベント

​ユーザーの実績の一部を取得

​返されるイベント

​ユーザーの特定の状態の実績のサブセットを取得

​返されるイベント

​ユーザーの実績の更新

​返されるイベント

​追加の詳細

​Achievements Manager のクリーンアップ

機能

主要な概念

API の概要

Achievements Manager へのローカルユーザーの追加

ユーザーの実績状態の取得

使用方法

Achievements Manager イベントの使用

返されるイベント

追加の詳細

実績を追跡するユーザーの登録

返されるイベント

追加の詳細

ユーザーの単一実績の取得

返されるイベント

ユーザーのすべての実績の取得

返されるイベント

ユーザーの実績の一部を取得

返されるイベント

ユーザーの特定の状態の実績のサブセットを取得

返されるイベント

ユーザーの実績の更新

返されるイベント

追加の詳細

Achievements Manager のクリーンアップ