Pular para o conteúdo principal
Os placares de líderes do XBOX services são derivados de estatísticas de usuário e criados por consultas. Isso é diferente dos placares de líderes no Steam, que são orientados por “pontuações” carregadas na API. Assim como acontece com as conquistas, o XBOX Game Development Kit (GDK) tem duas APIs para estatísticas: baseada em eventos e gerenciada pelo título. Ao contrário das conquistas, recomendamos que você use estatísticas e placares de líderes baseados em eventos em vez dos gerenciados pelo título. Este tópico se concentra nessa API. Para obter mais informações sobre como essas duas APIs diferem, confira Estatísticas baseadas em eventos versus gerenciadas pelo título. Ambas as plataformas definem placares de líderes em seus portais. A diferença é que o XBOX services exige que você primeiro defina uma regra de estatística no Partner Center e, em seguida, crie um placar de líderes com base na estatística que essa regra controla. O Steam, por outro lado, não faz distinção entre os dois: você cria um placar de líderes no portal deles ou de forma programática e, em seguida, carrega as pontuações dos usuários diretamente nesse placar de líderes. Para ilustrar como cada uma dessas APIs pode ser usada em comparação com a API Steam Leaderboard, são fornecidos exemplos de código sobre como criar um placar de líderes para a maior distância percorrida (o exemplo é da documentação da API Steamworks) no SDK do Steam e na plataforma de estatísticas baseada em eventos do XBOX Game Development Kit (GDK). As seções a seguir explicam a lógica.

Criando uma estatística/placar de líderes no portal

Steamworks

No portal de administração do Steamworks, acesse Stats & Achievements > Leaderboards. Preencha o formulário conforme mostrado na captura de tela a seguir (da documentação do Steamworks). Captura de tela do formulário usado para criar um placar de líderes no Portal de Administração do Steamworks

XBOX Game Development Kit (GDK) (baseado em eventos)

No Partner Center, acesse seu jogo e selecione XBOX services > Gameplay settings. Na barra de navegação do painel direito, selecione Player Stats > Stat Rules e adicione uma regra de estatística como Show, configurando-a para atender às necessidades da sua estatística. Como nossas atualizações de estatística incluirão um valor calculado de quanto o jogador (usuário) se deslocou desde a última atualização, especificaremos um campo de medida do qual o serviço obterá esse valor.
Não há diferença funcional entre armazenar os dados para atualizar um evento no campo Measurements ou no campo Dimensions do evento. Os dois campos existem para uso com o Application Insights. Para obter mais informações sobre isso, confira [API do Application Insights para eventos e
métricas personalizados](https://learn.microsoft.com/en-us/azure/azure-monitor/app/api-custom-events-metrics). A captura de tela a seguir mostra o formulário usado para criar uma regra de estatística no Partner Center. Captura de tela do formulário usado para criar uma regra de estatística no Partner Center Depois de salvar, selecione Leaderboard na barra superior do painel direito e crie um novo placar de líderes orientado pela estatística que você acabou de criar, conforme mostrado na captura de tela a seguir. Captura de tela do formulário usado para criar um placar de líderes no Partner Center

Carregando uma pontuação

Steamworks

No Steamworks, você precisa calcular o novo valor total de pés percorridos e enviá-lo à API usando o método ISteamUserStats::UploaderLeaderboardScore.

XBOX Game Development Kit (GDK) (baseado em eventos)

Com as estatísticas baseadas em eventos no XBOX Game Development Kit (GDK), basta passar a diferença de pés percorridos para XblEventsWriteInGameEvent, pois especificamos que queremos incrementar essa estatística ao receber um evento e especificamos onde encontrar esse valor diff na cadeia de caracteres JSON de medidas, conforme mostrado a seguir.
Para obter mais informações, confira Gravando um evento para alimentar uma estatística baseada em eventos.

Obtendo um placar de líderes global

Placares de líderes globais podem ser obtidos com o SDK do Steamworks chamando ISteamUserStats::GetLeaderboardEntries e, em seguida, chamando ISteamUserStats::GetDownloadedLeaderboardEntry na função callback para obter cada entrada ou “linha” do placar de líderes.

Steamworks

XBOX Game Development Kit (GDK) (baseado em eventos)

As APIs do XBOX Game Development Kit (GDK) seguem um padrão semelhante. Crie uma consulta especificando qual placar de líderes você deseja, qual escopo ele deve abranger, como classificá-lo, quais campos adicionais ele deve conter (se houver) e muito mais. Depois de chamar XblLeaderboardGetLeaderboardAsync com sua consulta, você pode usar XblLeaderboardGetLeaderboardResultSize e XblLeaderboardGetLeaderboardResult para colocar os resultados no buffer especificado e iterar sobre eles, conforme mostrado no exemplo de código a seguir.
Para obter mais informações, confira o seguinte:

Obtendo um placar de líderes social

No Steamworks, você pode usar a enumeração ELeaderboardDataRequest::k_ELeaderboardDataRequestFriends para limitar o escopo do placar de líderes aos amigos do usuário atual. No XBOX Game Development Kit (GDK), isso é conhecido como placar de líderes social. Para obter um placar de líderes social do XBOX services, defina xboxIUserId como a ID de usuário do XBOX (XUID) do usuário atual conectado ao XBOX services, leaderboardName como nullptr e socialGroup como XblSocialGroupType::People ou XblSocialGroupType::Favorites na sua struct XblLeaderboardQuery. Chame XblLeaderboardGetLeaderboardAsync conforme mostrado anteriormente. Para obter mais informações, confira XblSocialGroupType.

Estatísticas em destaque

Além das estatísticas de usuário comuns usadas para gerar placares de líderes semelhantes aos do Steam, o XBOX services tem um conceito adicional chamado Estatísticas em destaque. As Estatísticas em destaque aparecem em várias superfícies diferentes do ecossistema XBOX para o seu jogo e podem mostrar os valores das estatísticas do usuário ou dos placares de líderes já gerados. Você pode criar até 20 Estatísticas em destaque para o seu jogo. Para obter mais informações sobre as Estatísticas em destaque e como adicioná-las, confira Visão geral das Estatísticas em destaque e Configuração no portal de Estatísticas em destaque baseadas em eventos.

Limitação de taxa

Ao gravar eventos, tome cuidado para não chamar a XBOX Services API (XSAPI) com muita frequência, pois isso pode fazer com que seu jogo atinja o limite de taxa. Isso pode causar comportamento inesperado e uma experiência ruim para os usuários. Observe que essa é uma preocupação do XBOX services que não é um problema no Steam. Gravar valores de estatísticas no Steam não gera uma chamada de API ao servidor até que seu jogo os sincronize explicitamente. Para eventos que ocorrem com frequência, tente agrupar chamadas de API para que sejam disparadas depois que um determinado número de eventos acontecer ou para atualizar no servidor em um determinado intervalo de tempo. Você pode depurar suas chamadas de API usando o XBOX Live Trace Analyzer (XblTraceAnalyzer.exe). Para obter mais informações sobre limitação de taxa no XBOX services, confira Limitação de taxa refinada.
Última modificação em 6 de outubro de 2026