> ## Documentation Index > Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt > Use this file to discover all available pages before exploring further. # Placares de líderes > Recrie placares de líderes do Steam no XBOX GDK usando estatísticas baseadas em eventos e regras de estatísticas do Partner Center, com exemplos de código comparando as duas APIs de placares de líderes. 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](/pt-BR/services/xbox-services/player-data/stats-leaderboards/index). 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](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`. ```cpp theme={null} int32 newFeetTraveled; // Calculate this however you want. const int32* scoreDetails = {}; // Extra values pertaining to the score. SteamLeaderboard_t leaderboard; // Handle for the leaderboard to upload the score to... SteamAPICall_t result = UploadLeaderboardScore( leaderboard, ISteamUserStats::k_ELeaderboardUploadScoreMethodForceUpdate, 100, scoreDetails, int 0); STEAM_CALLBACK(MyGameClass, OnLeaderboardScoreUploaded, LeaderboardScoreUploaded_t); // Handle errors in the OnLeaderboardScoreUploaded callback function. ``` ### 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`](/pt-BR/reference/live/xsapi-c/events_c/events_c_members), 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. ```cpp theme={null} // Assume that this holds the feet that the user has traveled since the last update. int diffFeetTraveled; std::stringstream ss; ss << "{ \"feet\": " << diffFeetTraveled << " }"; std::string measurements = ss.str(); HRESULT hr = XblEventsWriteInGameEvent( m_xboxLiveContext, "FeetTraveled", "", measurements.c_str() ); ``` Para obter mais informações, confira [Gravando um evento para alimentar uma estatística baseada em eventos](/pt-BR/services/xbox-services/player-data/stats-leaderboards/index). ## 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 ```cpp theme={null} class MyGameClass { void OnFindLeaderboardCompleted(LeaderboardFindResult_t *callback); SteamAPICall_t m_getLoaderboardCall; SteamAPICall_t m_getEntriesCall; }; m_getLoaderboardCall = SteamUserStats()->FindLeaderboard(leaderboardName); STEAM_CALLBACK(MyGameClass, OnFindLeaderboardCompleted, LeaderboardFindResult_t); // ... void MyGameClass::OnFindLeaderboardCompleted(LeaderboardFindResult_t *callback) { if (callback->bLeaderboardFound) { auto handle = callback->m_hSteamLeaderboard; const char *leaderboardName = SteamUserStats()->GetLeaderboardName(handle); m_getEntriesCall = SteamUserStats()->GetLeaderboardEntries(handle, ELeaderboardDataRequest::k_ELeaderboardDataRequestGlobal, 0, 100); STEAM_CALLBACK(MyGameClass, OnLeaderboardScoresDownloaded, LeaderboardScoresDownloaded_t); } else { // Leaderboard wasn't found. } void MyGameClass::OnLeaderboardScoresDownloaded(LeaderboardScoresDownloaded_t *callback) { int numScores = callback->m_cEntryCount; for (int i = 0; i < numScores; i++) { LeaderboardEntry_t entry; bool result = SteamUserStats()->GetDownloadedLeaderboardEntry(callback->m_hSteamLeaderboardEntries, i, &entry, nullptr, 0); if (!result) { // Handle error. } CSteamID userId = entry.m_steamIDUser; int32 rank = entry.m_nglobalRank; int32 score = entry.m_nScore; // Do something with the data. } } ``` ### 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`](/pt-BR/reference/live/xsapi-c/leaderboard_c/leaderboard_c_members) com sua consulta, você pode usar [`XblLeaderboardGetLeaderboardResultSize`](/pt-BR/reference/live/xsapi-c/leaderboard_c/leaderboard_c_members) e [`XblLeaderboardGetLeaderboardResult`](/pt-BR/reference/live/xsapi-c/leaderboard_c/leaderboard_c_members) para colocar os resultados no buffer especificado e iterar sobre eles, conforme mostrado no exemplo de código a seguir. ```cpp theme={null} auto asyncBlock = std::make_unique(); asyncBlock->queue = m_taskQueue; asyncBlock->context = nullptr; asyncBlock->callback = [](XAsyncBlock* asyncBlock) { std::unique_ptr asyncBlockPtr{ asyncBlock }; // Take over ownership of the XAsyncBlock* size_t resultSize; std::vector leaderboardBuffer; HRESULT hr = XblLeaderboardGetLeaderboardResultSize(asyncBlock, &resultSize); if (SUCCEEDED(hr)) { leaderboardBuffer.resize(resultSize); XblLeaderboardResult* leaderboard{}; hr = XblLeaderboardGetLeaderboardResult(asyncBlock, resultSize, leaderboardBuffer.data(), &leaderboard, nullptr); if (SUCCEEDED(hr)) { // Use XblLeaderboardResult in result. for (int row = 0; row < leaderboard->rowsCount; row++) { uint64_t xuid = leaderboard->rows[row].xboxUserId; uint32_t rank = leaderboard->rows[row].rank; const char** values = leaderboard->rows[row].columnValues; // Do something with the data. } } } }; XblLeaderboardQuery leaderboardQuery = {}; strcpy(&leaderboardQuery.scid[0], m_scid.c_str()); leaderboardQuery.leaderboardName = leaderboardName.c_str(); leaderboardQuery.xboxUserId = 0; leaderboardQuery.order = XblLeaderboardSortOrder::Descending; leaderboardQuery.skipResultToRank = 0; leaderboardQuery.maxItems = 100; leaderboardQuery.statName = "MyStatName"; leaderboardQuery.socialGroup = XblLeaderboardQueryType::None; // See the link as follows for more options in XblLeaderboardQuery. HRESULT hr = XblLeaderboardGetLeaderboardAsync( xboxLiveContext, leaderboardQuery, asyncBlock.get()); if (SUCCEEDED(hr)) { // The call succeeded, so release the std::unique_ptr ownership of XAsyncBlock* since the callback will take over ownership. // If the call fails, the std::unique_ptr will keep ownership and delete the XAsyncBlock* asyncBlock.release(); } ``` Para obter mais informações, confira o seguinte: * [Código de exemplo para placares de líderes baseados em eventos](/pt-BR/services/xbox-services/player-data/stats-leaderboards/index) * [XblLeaderboardQuery](/pt-BR/reference/live/xsapi-c/leaderboard_c/leaderboard_c_members) ## 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`](/pt-BR/reference/live/xsapi-c/leaderboard_c/leaderboard_c_members). Chame `XblLeaderboardGetLeaderboardAsync` conforme mostrado anteriormente. Para obter mais informações, confira [XblSocialGroupType](/pt-BR/reference/live/xsapi-c/leaderboard_c/leaderboard_c_members). ## 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](/pt-BR/services/xbox-services/player-data/stats-leaderboards/index) e [Configuração no portal de Estatísticas em destaque baseadas em eventos](/pt-BR/services/xbox-services/player-data/stats-leaderboards/index). ## 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)](/pt-BR/tools/tools-services/live-trace-analyzer). Para obter mais informações sobre limitação de taxa no XBOX services, confira [Limitação de taxa refinada](/pt-BR/services/xbox-services/develop/best-practices/live-fine-grained-rate-limiting). ## Related topics - [Documentação do PlayFab Community](/pt-BR/services/playfab/community/index.md) - [Serviços opcionais](/pt-BR/build/gdk-and-engines/optional-services.md) - [Fazendo mais com placares de líderes](/pt-BR/services/playfab/community/leaderboards/doing-more-with-leaderboards.md) - [Referência de API de placares de líderes](/pt-BR/services/playfab/community/leaderboards/api-reference.md) - [Configurar placares de líderes no Partner Center](/pt-BR/publishing/game-publishing/how-to/data-platform-2013/how-to-configure-leaderboards-2013.md)