XBOX Achievements Manager API 개요 - XBOX Game Development Documentation

XBOX Achievements Manager API는 XBOX Live 사용자의 업적 상태를 추적하고 업데이트하는 것을 간소화합니다. XBOX는 특정 지점에서 업적을 부여함으로써 사용자의 게임에서의 진행 상황과 성취를 추적하는 방법을 제공합니다. XBOX Services API(XSAPI)의 achievements API를 사용하여 각 로컬 사용자의 업적 정보를 최신 상태로 유지하는 것은 복잡할 수 있습니다. 이를 올바르게 수행하지 않으면 성능 문제, 오래된 데이터 또는 필요보다 자주 XBOX achievement 서비스를 호출하여 스로틀링될 수 있습니다. Social Manager는 다음을 통해 이 문제를 해결합니다.

호출할 간단한 API를 만듭니다.
백그라운드에서 real time activity 서비스를 사용하여 최신 정보를 만듭니다.
개발자는 서비스에 추가 부담을 주지 않고 Achievements Manager API를 동기적으로 호출할 수 있습니다.

Achievements Manager는 여러 RTA 구독을 처리하는 복잡성, 사용자 데이터 새로 고침, achievements 서비스에 대한 호출 수를 줄이는 등의 복잡성을 마스킹하고 개발자가 최신 업적 데이터를 쉽게 얻을 수 있도록 합니다.

기능

Achievements Manager는 다음과 같은 기능을 제공합니다.

단순화된 Achievements API
각 사용자에 대한 최신 업적 상태 및 진행 상황
XBOX services에 대한 호출 수 감소
- 이는 데이터 획득의 전반적인 지연 시간 감소와 직접적인 관련이 있음
스레드 안전
효율적으로 데이터를 최신 상태로 유지

핵심 개념

업적: 업적에는 게이머스코어와 디지털 아트워크, 새 맵, 캐릭터, 스탯 부스트와 같은 기타 보상뿐만 아니라 완료를 향한 현재 진행 상황이 포함됩니다. 사용자의 업적 상태를 최신 상태로 유지하려면 매 프레임마다 XblAchievementsManagerDoWork 함수를 호출해야 합니다.

Windows에서는 로컬 사용자가 하나만 있을 수 있습니다

API 개요

다음의 주요 API를 가장 자주 사용하게 됩니다. Achievements Manager API에 대한 완전한 설명은 XBOX Live API 참조에서 찾을 수 있습니다. API는 XblAchievementsManager 접두사 문서에서도 찾을 수 있습니다.

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를 사용하여 Title Managed 업적만 업데이트할 수 있습니다. 이벤트 기반 업적을 업데이트하려면 이벤트 기반 업적을 구동하기 위한 이벤트 작성을 참조하세요.

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 정리