Visão geral da API Achievements Manager do XBOX - XBOX Game Development Documentation

A API Achievements Manager do XBOX simplifica o acompanhamento e a atualização do estado das conquistas de um usuário do XBOX Live. O XBOX oferece uma maneira de acompanhar o progresso e as realizações de um usuário em seus jogos, concedendo conquistas em determinados momentos. Usar as APIs de conquistas da XBOX Services API (XSAPI) para manter atualizadas as informações de conquistas de cada usuário local pode ser complicado. Não fazer isso corretamente pode resultar em problemas de desempenho, dados desatualizados ou limitação de taxa por chamar os serviços de conquistas do XBOX com mais frequência do que o necessário. O Social Manager resolve esse problema:

Criando uma API simples de chamar.
Gerando informações atualizadas usando o serviço Real-Time Activity em segundo plano.
Permitindo que os desenvolvedores chamem a API Achievements Manager de forma síncrona sem nenhuma carga extra no serviço.

O Achievements Manager oculta a complexidade de lidar com várias assinaturas de RTA, atualizar os dados dos usuários e reduzir o número de chamadas ao serviço de conquistas, e permite que os desenvolvedores obtenham facilmente os dados de conquistas atualizados.

Recursos

O Achievements Manager fornece os seguintes recursos:

API de conquistas simplificada
Estado e progresso das conquistas atualizados para cada usuário
Redução do número de chamadas aos serviços XBOX
- Isso se correlaciona diretamente com a redução geral da latência na aquisição de dados
Thread-safe
Manutenção eficiente dos dados atualizados

Conceitos principais

Conquistas: uma conquista inclui gamerscore e outras recompensas, como arte digital, novos mapas, personagens e aprimoramentos de estatísticas, além do progresso atual para a conclusão. Para manter atualizado o estado das conquistas de um usuário, a função XblAchievementsManagerDoWork deve ser chamada a cada quadro.

No Windows, só pode haver um usuário local

Visão geral da API

Você usará com mais frequência as seguintes APIs principais. Você pode encontrar uma descrição completa das APIs do Achievements Manager na referência da API do XBOX Live. Você também pode encontrar as APIs na documentação do prefixo XblAchievementsManager.

Adicionando usuários locais ao Achievements Manager

Função da API C: XblAchievementsManagerAddLocalUser

Adicionar um usuário local ao Achievements Manager faz com que o estado de todas as conquistas desse usuário para o título atual seja buscado no serviço e salvo localmente. O Achievements Manager manterá atualizada cada uma das conquistas desse usuário para o título atual.

Obtendo o estado das conquistas de um usuário

Função da API C: XblAchievementsManagerGetAchievements

Chamar essa função retorna um identificador para as conquistas que correspondem aos critérios especificados. As conquistas apontadas pelo identificador são cópias thread-safe das conquistas correspondentes. Os dados apontados pelo identificador existirão até que o identificador seja fechado, mas poderão ficar desatualizados se o título mantiver o identificador após a próxima chamada a XblAchievementsManagerDoWork.

Uso

Usando eventos do Achievements Manager

O Achievements Manager informa o que aconteceu na forma de eventos. Você pode usar esses eventos para atualizar sua interface do usuário ou executar outra lógica. API C

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

Referência

Eventos retornados

Local User Initial State Synced: disparado quando o Achievements Manager termina de buscar o estado atual de todas as conquistas do título atual para o usuário.

API C: XblAchievementsManagerEventType::LocalUserInitialStateSynced

Achievement Progress Updated: disparado quando o progresso de um usuário em uma conquista do título atual é atualizado.

API C: XblAchievementsManagerEventType::AchievementProgressUpdated

Achievement Unlocked: disparado quando um usuário cumpre todos os requisitos de uma conquista do título atual.

API C: XblAchievementsManagerEventType::AchievementUnlocked

Detalhes adicionais

Em vez de buscar o estado das conquistas no serviço com frequência durante o loop do jogo, o Achievements Manager busca o estado de todas as conquistas de um usuário quando o usuário é registrado no Achievements Manager. Em seguida, o Achievements Manager recebe eventos do serviço que detalham as atualizações das conquistas de um usuário, que são então encaminhados ao título como events retornados pela função * XblAchievementsManagerDoWork. events é uma lista de XblAchievementsManagerEvent, e cada XblAchievementsManagerEvent contém uma alteração em uma conquista que ocorreu durante o último quadro. Mais informações podem ser encontradas na documentação da API XblAchievementsManagerEvent.

Registrar um usuário cujas conquistas serão acompanhadas

Neste cenário, você deseja registrar um usuário no Achievements Manager para começar a acompanhar as atualizações das conquistas desse usuário e armazenar em cache localmente o estado de todas essas conquistas. API C

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

Referência

Eventos retornados

Local User Initial State Synced: disparado quando o Achievements Manager termina de buscar o estado atual de todas as conquistas do título atual para o usuário.

API C: XblAchievementsManagerEventType::LocalUserInitialStateSynced

Detalhes adicionais

O exemplo acima mostra como inicializar o Achievements Manager para um usuário e mantê-lo atualizado. No loop do jogo, a função XblAchievementsManagerDoWork processa e aplica todas as atualizações feitas nas conquistas dos usuários.

Recuperando uma única conquista de um usuário

Neste cenário, você deseja obter o estado de uma única conquista de um usuário. API C

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

Referência

Eventos retornados

Local User Initial State Synced: disparado quando o Achievements Manager termina de buscar o estado atual de todas as conquistas do título atual para o usuário.

API C: XblAchievementsManagerEventType::LocalUserInitialStateSynced

Recuperando todas as conquistas de um usuário

Neste cenário, você deseja obter o estado de todas as conquistas de um usuário. API C

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

Referência

Eventos retornados

Local User Initial State Synced: disparado quando o Achievements Manager termina de buscar o estado atual de todas as conquistas do título atual para o usuário.

API C: XblAchievementsManagerEventType::LocalUserInitialStateSynced

Recuperando um subconjunto de conquistas de um usuário

Neste cenário, você deseja obter o estado de um subconjunto de conquistas de um usuário. API C

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

Referência

Eventos retornados

Local User Initial State Synced: disparado quando o Achievements Manager termina de buscar o estado atual de todas as conquistas do título atual para o usuário.

API C: XblAchievementsManagerEventType::LocalUserInitialStateSynced

Recuperando um subconjunto de conquistas em um estado específico de um usuário

Neste cenário, você deseja obter o estado de um subconjunto de conquistas em um estado de progresso específico de um usuário. API C

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

Referência

Eventos retornados

Local User Initial State Synced: disparado quando o Achievements Manager termina de buscar o estado atual de todas as conquistas do título atual para o usuário.

API C: XblAchievementsManagerEventType::LocalUserInitialStateSynced

Atualizando uma conquista de um usuário

Atualiza o progresso de uma conquista de um usuário. API C

HRESULT hr = XblAchievementsManagerAddLocalUser(userHandle, nullptr);

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

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

Referência

Eventos retornados

Local User Initial State Synced: disparado quando o Achievements Manager termina de buscar o estado atual de todas as conquistas do título atual para o usuário.

API C: XblAchievementsManagerEventType::LocalUserInitialStateSynced

Detalhes adicionais

Somente conquistas gerenciadas pelo título podem ser atualizadas usando XblAchievementsManagerUpdateAchievement. Consulte Gravando um evento para viabilizar uma conquista baseada em eventos para atualizar conquistas baseadas em eventos.

Limpando o Achievements Manager

Remover um usuário do Achievements Manager remove as conquistas em cache desse usuário do Achievements Manager. Nenhum outro evento deverá ser recebido para o usuário removido. API C

HRESULT hr = XblAchievementsManagerRemoveLocalUser(userHandle);

Referência

XblAchievementsManagerRemoveLocalUser

​Recursos

​Conceitos principais

​Visão geral da API

​Adicionando usuários locais ao Achievements Manager

​Obtendo o estado das conquistas de um usuário

​Uso

​Usando eventos do Achievements Manager

​Eventos retornados

​Detalhes adicionais

​Registrar um usuário cujas conquistas serão acompanhadas

​Eventos retornados

​Detalhes adicionais

​Recuperando uma única conquista de um usuário

​Eventos retornados

​Recuperando todas as conquistas de um usuário

​Eventos retornados

​Recuperando um subconjunto de conquistas de um usuário

​Eventos retornados

​Recuperando um subconjunto de conquistas em um estado específico de um usuário

​Eventos retornados

​Atualizando uma conquista de um usuário

​Eventos retornados

​Detalhes adicionais

​Limpando o Achievements Manager

Recursos

Conceitos principais

Visão geral da API

Adicionando usuários locais ao Achievements Manager

Obtendo o estado das conquistas de um usuário

Uso

Usando eventos do Achievements Manager

Eventos retornados

Detalhes adicionais

Registrar um usuário cujas conquistas serão acompanhadas

Eventos retornados

Detalhes adicionais

Recuperando uma única conquista de um usuário

Eventos retornados

Recuperando todas as conquistas de um usuário

Eventos retornados

Recuperando um subconjunto de conquistas de um usuário

Eventos retornados

Recuperando um subconjunto de conquistas em um estado específico de um usuário

Eventos retornados

Atualizando uma conquista de um usuário

Eventos retornados

Detalhes adicionais

Limpando o Achievements Manager