Visão geral

O Steam permite a criação de tabelas de classificações persistentes com entradas automaticamente ordenadas. Essas tabelas podem ser usadas para exibir classificações mundiais e de amigos no seu jogo e na sua página da Comunidade. Cada título no Steamworks pode criar até 10 mil tabelas de classificações e cada tabela pode ser recuperada imediatamente após inserir a pontuação de um jogador.

Um jogador pode ter uma entrada em cada tabela. Não há limite de jogadores por tabela. Cada entrada contém uma pontuação para a tabela (um int32) e opcionalmente até 64 dados associados (cada um int32). Os dados associados podem ser usados para armazenar dados específicos sobre a sessão que resultou na entrada do usuário na tabela. Esses dados associados não são ordenados ou lidos pelo Steam e são substituídos quando uma nova entrada é criada para o usuário na tabela.

Todas as funções de classificações estão na interface ISteamUserGameStats.h e duas tabelas de amostra foram implementadas no exemplo do Steamworks. Também é possível visualizar e administrar tabelas do jogo na página de administração de jogo no Steamworks.

Antes de começar

Todas as funções assíncronas de classificações retornam um handle para um resultado de chamada à API do Steam. Para mais informações sobre como receber tais resultados, consulte a seção "Resultados de chamada" do documento "Primeiros passos".

Como criar uma tabela de classificações

Tabelas de classificações são separadas por aplicativo e são configuradas na página de administração do site de parceiros Steamworks ou por meio da API.

Criação pela web

Para criar e gerenciar tabelas de classificações na página de administração de aplicativo para o AppID no Steam, acesse Estatísticas e conquistas -> Classificações.


Os campos a seguir devem ser preenchidos para definir uma tabela de classificações:

• Nome — Um nome que faça sentido como parte do desenvolvimento interno;
  
• Nome na Comunidade — Se a tabela deverá ser exibida na Central da Comunidade, defina o nome público aqui. Se não houver um nome preenchido, a tabela não será exibida;
  
• Forma de ordenação — Define a forma de ordenação da tabela. Para tabelas baseadas em posição, use crescente. Para recordes de pontuação, use decrescente;
  
• Tipo de exibição — Determina o tipo de dado que será exibido na tabela. Selecione entre numérico, segundos ou milissegundos;
  
• Escritas — Se definido como "Fontes confiáveis" as pontuações da tabela não poderão ser definidas por clientes, apenas pela Web API SetLeaderboardScore. Padrão: false;
  
• Leituras — Se definido como "Amigos", o jogo só poderá consultar as pontuações de amigos do usuário. A Web API sempre terá acesso a todas as pontuações na tabela. Padrão: false.

Criação pela API

Tabelas de classificação podem ser criadas para o jogo pela administração de aplicativo no Steamworks ou programaticamente, por uma chamada à função ISteamUserStats::FindOrCreateLeaderboard. No Steam, todas as tabelas de classificações de um jogo têm um nome único. O nome da tabela só é usado para identificação na API do Steamworks e não é apresentado aos usuários pela Comunidade Steam. Ao criar uma tabela de classificações, será necessário informar os seguintes argumentos:

• forma de ordenação — k_ELeaderboardSortMethodAscending (a entrada no topo é do usuário com a menor pontuação) ou k_ELeaderboardSortMethodDescending (a entrada no topo é do usuário com a maior pontuação);
  
• tipo de exibição — A enumeração ELeaderboardDisplayType é usada para descrever o que uma pontuação da tabela representa e é usada apenas pela comunidade para formatar as pontuações ao exibir a tabela.

Se escolher criar tabelas apenas pela administração de aplicativo, use a função ISteamUserStats::FindLeaderboard para recuperar um handle da tabela de classificação. As funções FindLeaderboard e FindOrCreateLeaderboard são assíncronas e retornam o handle da tabela de classificações especificada por um resultado de chamada ISteamUserStats::LeaderboardFindResult_t.

Uma vez que criar a tabela de classificações, é possível modificar a forma de ordenação e o tipo de exibição pela administração de aplicativo. Quando a função FindOrCreateLeaderboard for chamada para uma tabela existente, os parâmetros de forma de ordenação e tipo de exibição são ignorados.

Como enviar uma pontuação

Para enviar uma pontuação à tabela de classificações, basta chamar a função ISteamUserStats::UploadLeaderboardScore passando como argumentos o handle da tabela-alvo (recuperada pela função FindLeaderboard), a pontuação do usuário e quaisquer dados associados gerados com a nova pontuação. Se a pontuação de um usuário na tabela for atualizado, os dados associados à função ISteamUserStats::UploadLeaderboardScore substituirão quaisquer dados previamente armazenados. Há duas formas de atualização ao enviar a pontuação de um usuário:

• ISteamUserStats::k_ELeaderboardUploadScoreMethodKeepBest — O Steam comparará a nova pontuação do usuário com a pontuação já armazenada na tabela e manterá a melhor das duas (a menor para tabelas com ordem crescente; a maior para tabelas com ordem decrescente);
  
• ISteamUserStats::k_ELeaderboardUploadScoreMethodForceUpdate — O Steam sempre substituirá a pontuação do usuário na tabela pela nova;
  
• ISteamUserStats::UploadLeaderboardScore é uma chamada assíncrona e o resultado do envio é retornado em um resultado de chamada LeaderboardScoreUploaded_t. O resultado também indicará se a pontuação do usuário foi alterada e a colocação global antiga e nova do usuário. Uma vez enviada, a tabela de classificações será atualizada imediatamente para conter a nova pontuação e a nova ordem de entradas pode ser recuperada por meio da função DownloadLeaderboardEntries.

Como anexar conteúdo gerado pelo usuário

Após uma pontuação ser enviada, há a opção de anexar conteúdo gerado pelo usuário à entrada. Para tal, chame a função ISteamUserStats::AttachLeaderboardUGC. O conteúdo pode ser um replay da sessão da nova pontuação ou um fantasma de um jogo de corrida. O handle anexado estará disponível quando a entrada for recuperada e pode ser baixado por outros usuários. Para criar e baixar conteúdo gerado por usuários, consulte a documentação sobre a Nuvem Steam.

Uma vez anexado, o conteúdo estará disponível mesmo se o arquivo da Nuvem for alterado ou excluído pelo usuário.

Como recuperar entradas da tabela de classificações

ISteamUserStats::DownloadLeaderboardEntries é usada para recuperar entradas da tabela de classificações usando o handle da tabela recuperado por meio da função ISteamUserStats::FindLeaderboard.

Depois de recuperar todas as entradas baixadas por meio da função GetDownloadedLeaderboardEntry, os dados de entrada serão liberados e o objeto SteamLeaderboardEntries_t em LeaderboardScoresDownloaded_t não será mais válido.

Como recuperar dados da tabela de classificações

Com um handle da tabela retornado pela função FindLeaderboard, é possível recuperar dados sobre a tabela pelas seguintes funções:

ISteamUserStats::GetLeaderboardName
ISteamUserStats::GetLeaderboardEntryCount
ISteamUserStats::GetLeaderboardSortMethod
ISteamUserStats::GetLeaderboardDisplayType