Introdução

Proezas podem ser usadas como uma forma de encorajar e recompensar interações e metas de jogadores no seu jogo. Muitas vezes, são usadas para marcar o número de vítimas, distância percorrida, tesouros abertos e outras ações comuns no jogo. Além disso, podem ser usadas para ajudar os jogadores a descobrir formas diferentes de jogar o jogo. Quando uma proeza é alcançada, uma notificação irá surgir no canto da janela do jogador e a proeza ficará registada na página de proezas do jogador.

Vista geral técnica

O presente artigo é um guia passo a passo rápido para integrar proezas básicas do Steam na sua aplicação em menos de 10 minutos e com menos de 10 linhas de código integradas na sua base de código. O SDK do Steamworks vem com uma boa aplicação de exemplo, intitulada Spacewar, que demonstra toda a gama de funcionalidades do Steam e que deve ser o seu ponto de referência para ver todas as funcionalidades do Steam em ação. Este tutorial tenta ser o mais direto possível ao resumir as informações encontradas no Spacewar e na API de estatísticas e proezas a apenas o necessário para estatísticas do Steam. Tenha em atenção que estatísticas e proezas têm muito em comum. Por isso, se estiver a integrar ambas, esteja ciente que muitas das chamadas poderão ser consolidadas.

Passo 1 – Definição das proezas do jogo

As proezas são específicas para cada aplicação e configuradas na página de configuração de proezas, situada na página de administração da aplicação no Steamworks. Segue-se abaixo uma lista de proezas do Spacewar, a aplicação de exemplo do Steamworks:

Passo 2 – Encapsulamento do funcionamento das proezas

O seguinte código não depende de nenhum jogo e pode ser adicionado ao seu jogo como quiser. A classe é completamente funcional, mas pode ser expandida facilmente para atender a quaisquer outras necessidades. Todo este código foi retirado diretamente dos ficheiros de exemplo do Spacewar StatsAndAchievements.cpp/h.

Ficheiro de cabeçalho

Primeiro, definimos uma estrutura para armazenar os dados das proezas recebidos do Steam e um macro para criar objetos desse tipo. Estes dados são mapeados diretamente para os existentes na página de configuração de proezas.

De seguida, definimos uma classe helper, que irá encapsular todas as chamadas à API de estatísticas do Steam assim como criar todos os callbacks do Steam.

Ficheiro de código

Construtor

Parâmetros – O construtor recebe um ponteiro para um array de proezas, juntamente com o tamanho do array. O formato do array será abordado no código principal do jogo, mais adiante.
Retorna – Não aplicável
O que faz – O construtor inicializa alguns membros e obtém o AppID que estamos a executar atualmente. Além disso, o construtor faz hook aos métodos de callback para gerir chamadas assíncronas realizadas ao Steam. Por último, realiza uma chamada inicial à função RequestStats() para obter as estatísticas e as proezas do utilizador atual.

RequestStats()

Parâmetros – Nenhum
Retorna – Um valor booleano que representa o resultado da chamada. Se a chamada falhou, é provável que o Steam não tenha sido inicializado. Assegure-se de que tem uma aplicação Steam aberta quando tentar realizar esta chamada e que a função SteamAPI_Init foi chamada antes disso.
O que faz – Este método basicamente encapsula uma chamada à função ISteamUserStats::RequestCurrentStats, que é uma chamada assíncrona ao Steam a pedir as estatísticas e proezas do utilizador atual. Esta chamada precisa de ser realizada antes de poder definir qualquer estatística ou proeza. A chamada inicial a este método é realizada no construtor. Pode realizar a chamada mais tarde, se quiser verificar estatísticas ou proezas atualizadas.

SetAchievement()

Parâmetros – Uma string que identifica a proeza que quer definir (por exemplo, "ACH_WIN_ONE_GAME")
Retorna – Um valor booleano que representa o resultado da chamada. Se a chamada falhou, isso é porque o Steam não foi inicializado ou porque ainda não processou o callback da primeira chamada à função RequestStats. Não pode definir proezas enquanto o callback não for recebido.
O que faz – Este método define uma determinada proeza como alcançada e envia os resultados para o Steam. Como é possível definir uma determinada proeza várias vezes, não precisa de se preocupar em tentar definir apenas aquelas que ainda não foram definidas. Esta é uma chamada assíncrona que irá ativar dois callbacks: OnUserStatsStored() e OnAchievementStored().

OnUserStatsReceived()

Parâmetros – Não aplicável
Retorna – Não retorna nada
O que faz – Este método é um callback que é realizado sempre que tentar pedir estatísticas. Estatísticas e proezas são pedidas através da função RequestStats(). O método atualiza a variável membro m_pAchievements para refletir os dados de estatísticas e proezas mais recentes do Steam.

OnUserStatsStored()

Parâmetros – Não aplicável
Retorna – Não retorna nada
O que faz – Este método é um callback que é realizado sempre que tentar armazenar estatísticas no Steam.

OnAchievementStored()

Parâmetros – Não aplicável
Retorna – Não retorna nada
O que faz – Este método é um callback que é realizado sempre que proezas forem armazenadas com sucesso no Steam.

Passo 3 – Integração no jogo

Segue-se uma listagem completa de excertos de código que precisam de ser integrados nos locais apropriados do jogo.

Defines e globais

Segue-se uma lista de "includes" necessários para a criação com proezas, uma enumeração (enum) com as proezas específicas do jogo e um ponteiro global para o nosso objeto helper. Note que as proezas devem ter o mesmo nome presente na página de administração no Steamworks.

Inicialização

A chamada à função SteamAPI_Init inicializa o Steam e deve ser chamada antes de qualquer outra função. Se a chamada for bem-sucedida, criamos o objeto helper ao passar o array de proezas e o tamanho do array.

Processamento de callbacks

De forma a garantir o processamento de todos os callbacks do Steam, precisamos de verificar regularmente se há novas mensagens. Para tal, adicionamos a seguinte chamada ao ciclo do jogo.

Acionamento de proezas

Acionar uma proeza é tão simples como chamar uma função com o identificador da proeza.

Encerramento

Provavelmente, já deve ter uma chamada à função SteamAPI_Shutdown no seu código. Esta função encerra o Steam e deve ser chamada antes do encerramento da sua aplicação. Por último, eliminamos o objeto helper que criámos.

Passo 4 – Testes e resolução de problemas

Para definir ou limpar estatísticas e proezas sem adicionar código ao seu jogo, pode usar a consola da aplicação Steam. Inicie o Steam com "steam.exe -console" no atalho e escreva o seguinte na consola:

• achievement_clear <AppID> <nome da proeza>
  
• reset_all_stats <AppID>