Vista geral

O Steam permite a criação de tabelas de liderança persistentes e organizadas automaticamente. Estas tabelas podem ser usadas para apresentar as classificações globais e de amigos no seu jogo e na respetiva Central Comunitária. Cada jogo no Steamworks pode criar até 10 000 tabelas de liderança e cada tabela pode ser obtida imediatamente após a pontuação de um jogador ser inserida.

Um jogador pode ter uma só entrada em cada tabela. Não existe um limite no número de jogadores por tabela. Cada entrada contém uma pontuação para a tabela (um valor int32) e, opcionalmente, até 64 valores int32 de dados associados. Os dados associados podem ser usados para armazenar informações específicas sobre a sessão que resultou na entrada do utilizador na tabela de liderança. Estes dados não são ordenados nem analisados pelo Steam e são substituídos quando uma nova entrada na tabela é criada para o utilizador.

Todas as funções de tabelas de liderança estão na interface ISteamUserGameStats.h e duas amostras de tabelas de liderança foram implementadas no exemplo do Steamworks. Também é possível visualizar e administrar tabelas de liderança para o seu jogo no painel de administração do jogo no Steamworks.

Antes de começar

Todas as funções assíncronas de tabelas de liderança retornam um handle para um resultado de chamada à API do Steam. Pode encontrar mais informações sobre como receber estes resultados na secção "Resultados de chamada (CallResults)" do artigo "Vista geral da API do Steamworks".

Criação de uma tabela de liderança

As tabelas de liderança são específicas para cada aplicação e configuradas na respetiva página de administração no site de parceiros Steamworks ou através da API.

Criação através da web

Pode criar e gerir tabelas de liderança na página de administração do seu AppID no Steamworks ao aceder a Estatísticas e proezas -> Tabelas de liderança.


Os seguintes campos devem ser preenchidos para definir uma tabela de liderança:

• Nome – Defina um nome que faça sentido como parte do desenvolvimento interno.
  
• Nome na Comunidade – Se pretende que a tabela de liderança apareça na Central Comunitária do jogo, defina aqui um nome visível para o público. Se não for introduzido um nome, a tabela de liderança não irá aparecer.
  
• Método de ordenação – Defina o modo de ordenação da tabela. No caso de tabelas de liderança baseadas em posição, use "Crescente". Já no caso de tabelas baseadas na pontuação mais alta, use "Descrescente".
  
• Tipo de apresentação – Determina os tipos de dados que serão apresentados na tabela de liderança. Opções: "Numérico", "Segundos" ou "Milissegundos".
  
• Escritas – Se definido como "Confiável", as pontuações da tabela não poderão ser definidas por clientes, apenas pela Web API SetLeaderboardScore. Predefinição: -.
  
• Leituras – Se definido como "Amigos", o jogo só poderá ler pontuações de amigos do utilizador. Todas as pontuações podem ser sempre lidas pela Web API. Predefinição: -.

Criação através da API

Tabelas de liderança podem ser criadas na página de administração de aplicações no Steamworks ou programaticamente ao chamar a função ISteamUserStats::FindOrCreateLeaderboard. No Steam, todas as tabelas de liderança de um jogo Steamworks têm um nome diferente. O nome da tabela só é usado para identificação na API do Steamworks e não é apresentado aos utilizadores na Comunidade Steam. Ao criar uma tabela de liderança, terá de definir o:

• método de ordenação – k_ELeaderboardSortMethodAscending (a primeira entrada é do utilizador com a pontuação mais baixa) ou k_ELeaderboardSortMethodDescending (a primeira entrada é do utilizador com a pontuação mais alta).
  
• tipo de apresentação – ELeaderboardDisplayType é usado para para descrever o que uma pontuação na tabela representa e só é usado pela comunidade para gerir o formato das pontuações ao apresentar a tabela.

Se decidir criar tabelas apenas pela página de administração de aplicações, pode usar ISteamUserStats::FindLeaderboard para obter um handle de uma tabela específica. As funções "FindLeaderboard" e "FindOrCreateLeaderboard" são métodos assíncronos e retornam o handle da tabela de liderança especificada através de um resultado de chamada ISteamUserStats::LeaderboardFindResult_t.

Uma vez criada uma tabela de liderança, pode modificar o método de ordenação e o tipo de apresentação na página de administração do jogo. Quando a função "FindOrCreateLeaderboard" for chamada para uma tabela existente, o método de ordenação e o tipo de apresentação são ignorados.

Como enviar uma pontuação

Para enviar uma pontuação para a tabela de liderança, basta chamar a função ISteamUserStats::UploadLeaderboardScore com os seguintes argumentos: o handle da tabela pretendida (obtido através da função FindLeaderboard), a pontuação do utilizador e quaisquer dados associados gerados com a nova pontuação. Se a pontuação de um utilizador na tabela for atualizado, os dados associados passados à função ISteamUserStats::UploadLeaderboardScore irão substituir quaisquer dados armazenados anteriormente. Tem dois métodos de atualização à disposição ao enviar a pontuação de um utilizador:

• ISteamUserStats::k_ELeaderboardUploadScoreMethodKeepBest – O Steam irá comparar a nova pontuação do utilizador com a respetiva pontuação já armazenada na tabela e irá manter a pontuação melhor (a mais baixa no caso de tabelas com ordem crescente e a mais alta no caso de tabelas com ordem decrescente).
  
• ISteamUserStats::k_ELeaderboardUploadScoreMethodForceUpdate – O Steam irá substituir sempre a pontuação do utilizador na tabela pela mais recente.
  
• ISteamUserStats::UploadLeaderboardScore é uma chamada assíncrona e o resultado do envio é retornado num resultado de chamada LeaderboardScoreUploaded_t. O resultado irá indicar se a pontuação do utilizador foi alterada, assim como a posição global antiga e nova do utilizador na tabela. Uma vez enviada, a tabela de liderança será atualizada imediatamente para conter a nova pontuação e a nova ordem das entradas pode ser obtida através da função "DownloadLeaderboardEntries".

Como anexar conteúdo gerado por utilizadores

Após o envio de uma pontuação, tem a opção de anexar conteúdo gerado pelo utilizador à entrada. Para tal, chame a função ISteamUserStats::AttachLeaderboardUGC. O conteúdo pode ser uma repetição da sessão em que o utilizador alcançou a nova pontuação ou um "ghost" de um jogo de corridas, por exemplo. O handle anexado estará disponível quando a entrada for obtida e pode ser descarregado por outros utilizadores. Para criar e descarregar conteúdo gerado por utilizadores, consulte a documentação sobre a Steam Cloud.

Uma vez anexado, o conteúdo estará disponível mesmo se o ficheiro da Cloud for alterado ou eliminado pelo utilizador.

Como obter entradas da tabela de liderança

A função ISteamUserStats::DownloadLeaderboardEntries é usada para obter entradas da tabela de liderança ao usar o handle da tabela obtido através da função ISteamUserStats::FindLeaderboard.

Depois de obter todas as entradas descarregadas através da função "GetDownloadedLeaderboardEntry", os dados de entradas serão libertados e "SteamLeaderboardEntries_t" em "LeaderboardScoresDownloaded_t" deixará de ser válido.

Como obter informações da tabela de liderança

Com um handle da tabela de liderança retornado pela função FindLeaderboard, pode obter informações sobre a tabela através das seguintes funções:

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