Documentação do Steamworks
Passo a passo: Conquistas

Introdução

A seguir, apresentamos um guia passo a passo rápido para integrar conquistas Steam bem básicas no seu aplicativo em menos de 10 minutos e com menos de 10 linhas de código integradas à sua base de código. O SDK do Steamworks vem com um ótimo aplicativo de exemplo denominado Spacewar que demonstra os diversos recursos do Steam e deve ser o primeiro lugar para ver todos os recursos do Steam em ação. Este tutorial detalha apenas as informações encontradas no Spacewar e na API de estatísticas e conquistas necessárias para estatísticas para que seja o mais direto possível. Por favor, observe que há muita coisa em comum entre estatísticas e conquistas, então se estiver integrando ambas, esteja ciente de que muitas chamadas podem ser consolidadas.

1º passo — Definição das conquistas do jogo

Conquistas são separadas por aplicativo e configuradas na página de configuração de conquistas no backend de administração de aplicativo do Steamworks. A seguir, está a lista de conquistas do aplicativo de exemplo do Steamworks, denominado Spacewar:
spacewar_achievements.png

2º passo — Encapsulamento do funcionamento de conquistas

O código a seguir independe do jogo e pode ser adicionado ao seu jogo da forma que achar melhor. A classe é completamente funcional, mas pode ser estendida para atender a necessidades adicionais. O código foi extraído dos arquivos de exemplo do Spacewar StatsAndAchievements.cpp/h. Strings literais e comentários foram traduzidos para uma melhor compreensão.

Arquivo de cabeçalho

Primeiro definimos uma estrutura para armazenar os dados de conquista recebidos do Steam e um atalho para criar objetos do tipo. Esses dados são mapeados diretamente aos existentes na página de configuração de conquistas.
#define _ACH_ID( id, name ) { id, #id, name, "", 0, 0 } struct Achievement_t { int m_eAchievementID; const char *m_pchAchievementID; char m_rgchName[128]; char m_rgchDescription[256]; bool m_bAchieved; int m_iIconImage; };

Em seguida, definimos uma classe auxiliar que encapsulará todas as chamadas à API de estatísticas do Steam, assim como criará todos os retornos de chamada do Steam.
class CSteamAchievements { private: int64 m_iAppID; // Nosso AppID atual Achievement_t *m_pAchievements; // Dados das conquistas int m_iNumAchievements; // Quantidade de conquistas bool m_bInitialized; // Chamamos a funcao RequestStats e recebemos o retorno de chamada? public: CSteamAchievements(Achievement_t *Achievements, int NumAchievements); ~CSteamAchievements(); bool RequestStats(); bool SetAchievement(const char* ID); STEAM_CALLBACK( CSteamAchievements, OnUserStatsReceived, UserStatsReceived_t, m_CallbackUserStatsReceived ); STEAM_CALLBACK( CSteamAchievements, OnUserStatsStored, UserStatsStored_t, m_CallbackUserStatsStored ); STEAM_CALLBACK( CSteamAchievements, OnAchievementStored, UserAchievementStored_t, m_CallbackAchievementStored ); };

Arquivo de código

Construtor

Parâmetros — O construtor recebe um ponteiro para um vetor de conquistas e o tamanho do mesmo. A formatação do vetor será abordada no código principal do jogo, mais adiante.
Retorna — Nada
O que faz — O construtor inicializa alguns membros e recupera o AppID em execução. Além disso, ele associa os métodos de retorno de chamada para tratar chamadas assíncronas feitas ao Steam. Por último, realiza uma chamada inicial à função RequestStats() para recuperar as estatísticas e conquistas do usuário atual.
CSteamAchievements::CSteamAchievements(Achievement_t *Achievements, int NumAchievements): m_iAppID( 0 ), m_bInitialized( false ), m_CallbackUserStatsReceived( this, &CSteamAchievements::OnUserStatsReceived ), m_CallbackUserStatsStored( this, &CSteamAchievements::OnUserStatsStored ), m_CallbackAchievementStored( this, &CSteamAchievements::OnAchievementStored ) { m_iAppID = SteamUtils()->GetAppID(); m_pAchievements = Achievements; m_iNumAchievements = NumAchievements; RequestStats(); }

RequestStats()

Parâmetros — Nenhum
Retorna — um bool que representa o sucesso da chamada. Se a chamada falhou, a causa comum é a não inicialização do Steam. Confirme que há uma instância do cliente Steam aberta ao realizar esta chamada e que a função SteamAPI_Init foi chamada anteriormente.
O que faz — Este método basicamente encapsula uma chamada à função ISteamUserStats::RequestCurrentStats, que é uma chamada assíncrona ao Steam requisitando as estatísticas e conquistas do usuário atual. Esta chamada deve ser realizada antes de definir qualquer estatística ou conquista. A chamada inicial a este método é realizada no construtor. É possível chamá-la posteriormente, quando quiser, caso deseje verificar se há estatísticas ou conquistas atualizadas.
bool CSteamAchievements::RequestStats() { // Steam carregado? Caso contrario, nao podemos recuperar estatisticas. if ( NULL == SteamUserStats() || NULL == SteamUser() ) { return false; } // Usuario com sessao inciada? Caso contrario, nao podemos recuperar estatisticas. if ( !SteamUser()->BLoggedOn() ) { return false; } // Recuperar estatisticas do usuario. return SteamUserStats()->RequestCurrentStats(); }

SetAchievement()

Parâmetros — A string que identifica a conquista a ser definida (ex: "CONQ_VENCER_UMA_PARTIDA")
Retorna — um bool que representa o sucesso da chamada. Se a chamada falhou, então o Steam não está inicializado ou o processamento do retorno da primeira chamada à função RequestStats ainda não foi realizado. Não é possível definir conquistas até o recebimento do retorno de chamada.
O que faz — Este método define uma dada conquista como alcançada e envia os resultados ao Steam. É possível definir uma dada conquista várias vezes, então não se preocupe em definir conquistas já alcançadas. Esta é uma chamada assíncrona que disparará dois retornos de chamada: OnUserStatsStored() e OnAchievementStored().
bool CSteamAchievements::SetAchievement(const char* ID) { // Ja recebemos o retorno de chamada do Steam? if (m_bInitialized) { SteamUserStats()->SetAchievement(ID); return SteamUserStats()->StoreStats(); } // Caso contrario, ainda nao podemos definir conquistas return false; }

OnUserStatsReceived()

Parâmetros — Nenhum
Retorna — Nada
O que faz — Este método é um retorno de chamada que é chamado toda vez que você tentar recuperar estatísticas. Estatísticas e conquistas são recuperadas por meio da função RequestStats(). O método atualiza a variável-membro m_pAchievements para apontar aos dados de estatísticas e conquistas mais recentes do Steam.
void CSteamAchievements::OnUserStatsReceived( UserStatsReceived_t *pCallback ) { // Podemos receber retornos de chamada de estatisticas de outros jogos, ignore-os if ( m_iAppID == pCallback->m_nGameID ) { if ( k_EResultOK == pCallback->m_eResult ) { OutputDebugString("Recebeu estatisticas e conquistas do Steam\\n"); m_bInitialized = true; // Carregar conquistas for ( int iAch = 0; iAch < m_iNumAchievements; ++iAch ) { Achievement_t &ach = m_pAchievements[iAch]; SteamUserStats()->GetAchievement(ach.m_pchAchievementID, &ach.m_bAchieved); _snprintf( ach.m_rgchName, sizeof(ach.m_rgchName), "%s", SteamUserStats()->GetAchievementDisplayAttribute(ach.m_pchAchievementID, "name")); _snprintf( ach.m_rgchDescription, sizeof(ach.m_rgchDescription), "%s", SteamUserStats()->GetAchievementDisplayAttribute(ach.m_pchAchievementID, "desc")); } } else { char buffer[128]; _snprintf( buffer, 128, "RequestStats - falhou, %d\\n", pCallback->m_eResult ); OutputDebugString( buffer ); } } }

OnUserStatsStored()

Parâmetros — Nenhum
Retorna — Nada
O que faz — Este método é um retorno de chamada disparado toda vez que você armazenar estatísticas no Steam.
void CSteamAchievements::OnUserStatsStored( UserStatsStored_t *pCallback ) { // Podemos receber retornos de chamada de estatisticas de outros jogos, ignore-os if ( m_iAppID == pCallback->m_nGameID ) { if ( k_EResultOK == pCallback->m_eResult ) { OutputDebugString( "Estatisticas do Steam armazenadas\\n" ); } else { char buffer[128]; _snprintf( buffer, 128, "StatsStored - falha, %d\\n", pCallback->m_eResult ); OutputDebugString( buffer ); } } }

OnAchievementStored()

Parâmetros — Nenhum
Retorna — Nada
O que faz — Este método é um retorno de chamada, disparado sempre que conquistas são armazenadas com sucesso no Steam.
void CSteamAchievements::OnAchievementStored( UserAchievementStored_t *pCallback ) { // Podemos receber retornos de chamada de estatisticas de outros jogos, ignore-os if ( m_iAppID == pCallback->m_nGameID ) { OutputDebugString( "Conquista do Steam armazenada\\n" ); } }

3º passo — Integração com o jogo

A seguir, encontra-se uma listagem completa de trechos de códigos que precisam ser integrados ao jogo nos locais apropriados.

Defines e globais

A seguir, está uma lista de includes necessários para a construção com conquistas, uma enumeração com as conquistas específicas do jogo e um ponteiro global ao nosso objeto auxiliar. Por favor, observe que as conquistas devem ter o mesmo nome que o "Nome na API" na página de administração do Steamworks.
... #include "steam_api.h" // Definicao das conquistas enum EAchievements { ACH_WIN_ONE_GAME = 0, ACH_WIN_100_GAMES = 1, ACH_TRAVEL_FAR_ACCUM = 2, ACH_TRAVEL_FAR_SINGLE = 3, }; // Vetor de conquistas, para armazenar dados e o estado das conquistas Achievement_t g_Achievements[] = { _ACH_ID( ACH_WIN_ONE_GAME, "Vencedor" ), _ACH_ID( ACH_WIN_100_GAMES, "Campeao" ), _ACH_ID( ACH_TRAVEL_FAR_ACCUM, "Interestelar" ), _ACH_ID( ACH_TRAVEL_FAR_SINGLE, "Orbitador" ), }; // Acesso global ao objeto auxiliar de conquistas CSteamAchievements*g_SteamAchievements = NULL; ...

Inicialização

Esta chamada à função SteamAPI_Init inicializará a base do Steam e deve ser chamada antes de qualquer outra função da API. Se for bem-sucedida, então criamos o objeto auxiliar passando o vetor de conquistas e o tamanho do vetor.
... // Inicializacao do Steam bool bRet = SteamAPI_Init(); // Criacao do objeto SteamAchievements se o Steam foi inicializado com sucesso if (bRet) { g_SteamAchievements = new CSteamAchievements(g_Achievements, 4); } ...

Processamento de retornos de chamada

Para garantir o processamento de todos os retornos de chamada do Steam, precisamos sempre verificar se há novas mensagens. Para tal, adicionamos a chamada a seguir ao ciclo de vida do jogo.
... SteamAPI_RunCallbacks(); ...

Disparo de conquistas

Disparar uma conquista é tão simples quanto chamar uma função com o identificador da mesma.
... if (g_SteamAchievements) g_SteamAchievements->SetAchievement("ACH_WIN_100_GAMES"); ...

Encerramento

O seu código já deve ter uma chamada à função SteamAPI_Shutdown. Ela encerra o Steam e deve ser chamada antes do encerramento do aplicativo. Por último, excluímos o objeto auxiliar criado.
... // Encerramento do Steam SteamAPI_Shutdown(); // Exclusao do objeto SteamAchievements if (g_SteamAchievements) delete g_SteamAchievements; ...

4º passo — Testes e solução de problemas

Este código de amostra imprime dados de depuração ao console de depuração, facilitando a compreensão de quais chamadas estão funcionando e quais estão falhando. A seguir, apresentamos algumas mensagens de falha comuns, assim como correções:

This application has failed to start because steam_api.dll was not found. Re-installing the application may fix this problem.
(O aplicativo falhou em iniciar porque steam_api.dll não foi encontrado. Reinstalar o aplicativo pode corrigir este problema.)
Confirme que o arquivo steam_api.dll está no mesmo diretório do executável.

[S_API FAIL] SteamAPI_Init() failed; unable to locate a running instance of Steam, or a local steamclient.dll
([S_API FAIL] SteamAPI_Init() falhou; não foi possível encontrar uma instância local do Steam ou um arquivo steamclient.dll local)
É possível que não haja um cliente Steam em execução. Inicie o Steam e inicie a sessão.

[S_API FAIL] SteamAPI_Init() failed; no appID found.
([S_API FAIL] SteamAPI_Init() falhou; nenhum AppID encontrado.)
É possível que o arquivo steam_appid.txt não esteja no lugar certo. Coloque-o na pasta de códigos-fonte e certifique-se que ele contém o número do AppID.