Recree las tablas de clasificación de Steam en el GDK de XBOX mediante estadísticas basadas en eventos y reglas de estadísticas del Centro de partners, con ejemplos de código que comparan las dos API de tablas de clasificación.
Las tablas de clasificación de los servicios de XBOX se derivan de las estadísticas de usuario y se generan mediante consultas. Esto es diferente de las tablas de clasificación de Steam, que se basan en “puntuaciones” que se cargan en la API. De forma similar a los logros, el XBOX Game Development Kit (GDK) tiene dos API para las estadísticas: basadas en eventos y administradas por el título. A diferencia de los logros, recomendamos usar las estadísticas y tablas de clasificación basadas en eventos en lugar de las administradas por el título. En este tema nos centramos en esa API. Para obtener más información sobre las diferencias entre estas dos API, consulte Estadísticas basadas en eventos frente a estadísticas administradas por el título.Ambas plataformas definen las tablas de clasificación en sus portales. La diferencia es que los servicios de XBOX le piden que defina primero una regla de estadística en el Centro de partners y que, a continuación, cree una tabla de clasificación basada en la estadística que esa regla genera. Steam, en cambio, no distingue entre las dos cosas: crea una tabla de clasificación en su portal o mediante programación y, a continuación, carga las puntuaciones de los usuarios directamente en esa tabla de clasificación.Para ilustrar cómo puede usarse cada una de estas API en comparación con la API de tablas de clasificación de Steam, se proporcionan ejemplos de código sobre cómo crear una tabla de clasificación para la mayor distancia recorrida (el ejemplo procede de la documentación de la API de Steamworks) en el SDK de Steam y en la plataforma de estadísticas basadas en eventos del XBOX Game Development Kit (GDK). Las secciones siguientes explican la lógica paso a paso.
En el portal de administración de Steamworks, vaya a Stats & Achievements > Leaderboards. Complete el formulario como se muestra en la siguiente captura de pantalla (de la documentación de Steamworks).
XBOX Game Development Kit (GDK) (basado en eventos)
En el Centro de partners, vaya a su juego y seleccione XBOX services > Gameplay settings. En la barra de navegación del panel derecho, seleccione Player Stats > Stat Rules y agregue una regla de estadística como Show, configurándola para satisfacer las necesidades de su estadística. Como nuestras actualizaciones de la estadística incluirán un valor calculado de la distancia que ha recorrido el jugador (usuario) desde la última actualización, especificaremos un campo de medición del que el servicio obtendrá este valor.
No hay diferencia funcional si almacena los datos para actualizar un evento en el campo Measurements o Dimensions del evento. Los dos campos existen para su uso con Application Insights. Para obtener más información al respecto, consulte [Application Insights API for custom events and
metrics](https://learn.microsoft.com/en-us/azure/azure-monitor/app/api-custom-events-metrics).La siguiente captura de pantalla muestra el formulario que se usa para crear una regla de estadística en el Centro de partners.Después de guardar, seleccione Leaderboard en la barra superior del panel derecho y cree una nueva tabla de clasificación generada por la estadística que acaba de crear, como se muestra en la siguiente captura de pantalla.
En Steamworks, debe calcular el nuevo valor total de pies recorridos y enviarlo a la API mediante el método ISteamUserStats::UploaderLeaderboardScore.
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) (basado en eventos)
Con las estadísticas basadas en eventos del XBOX Game Development Kit (GDK), simplemente necesita pasar la diferencia de pies recorridos a XblEventsWriteInGameEvent, porque especificamos que queremos incrementar esta estadística al recibir un evento y hemos indicado dónde encontrar este valor diff en la cadena JSON de mediciones, como se muestra a continuación.
// 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());
Las tablas de clasificación globales pueden recuperarse con el SDK de Steamworks llamando a ISteamUserStats::GetLeaderboardEntries y, a continuación, llamando a ISteamUserStats::GetDownloadedLeaderboardEntry en la función callback para obtener cada entrada o “fila” de la tabla de clasificación.
XBOX Game Development Kit (GDK) (basado en eventos)
Las API del XBOX Game Development Kit (GDK) siguen un patrón similar. Cree una consulta especificando qué tabla de clasificación quiere, qué ámbito debe cubrir, cómo ordenarla, qué campos adicionales debe contener (si los hay) y más. Después de llamar a XblLeaderboardGetLeaderboardAsync con su consulta, puede usar XblLeaderboardGetLeaderboardResultSize y XblLeaderboardGetLeaderboardResult para colocar los resultados en el búfer que especifique e iterar sobre ellos, como se muestra en el siguiente ejemplo de código.
auto asyncBlock = std::make_unique<XAsyncBlock>();asyncBlock->queue = m_taskQueue;asyncBlock->context = nullptr;asyncBlock->callback = [](XAsyncBlock* asyncBlock){ std::unique_ptr<XAsyncBlock> asyncBlockPtr{ asyncBlock }; // Take over ownership of the XAsyncBlock* size_t resultSize; std::vector<uint8_t> 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 obtener más información, consulte lo siguiente:
En Steamworks, puede usar la enumeración ELeaderboardDataRequest::k_ELeaderboardDataRequestFriends para limitar el ámbito de la tabla de clasificación a los amigos del usuario actual.En el XBOX Game Development Kit (GDK), esto se conoce como una tabla de clasificación social. Para obtener una tabla de clasificación social de los servicios de XBOX, establezca xboxIUserId igual al identificador de usuario de XBOX (XUID) del usuario actual que ha iniciado sesión en los servicios de XBOX, leaderboardName en nullptr y socialGroup como XblSocialGroupType::People o XblSocialGroupType::Favorites en su estructura XblLeaderboardQuery. Llame a XblLeaderboardGetLeaderboardAsync como se mostró anteriormente.Para obtener más información, consulte XblSocialGroupType.
Además de las estadísticas de usuario habituales que se usan para generar tablas de clasificación similares a las de Steam, los servicios de XBOX tienen un concepto adicional llamado estadísticas destacadas (Featured Stats). Las estadísticas destacadas aparecen en varias superficies distintas del ecosistema de XBOX para su juego y pueden mostrar los valores de las estadísticas de los usuarios o de las tablas de clasificación que ya se han generado. Puede crear hasta 20 estadísticas destacadas para su juego.Para obtener más información sobre las estadísticas destacadas y cómo agregarlas, consulte Información general de las estadísticas destacadas y Configuración en el portal de estadísticas destacadas basadas en eventos.
Al escribir eventos, tenga cuidado de no llamar a la API de servicios de XBOX (XSAPI) con demasiada frecuencia, porque puede hacer que su juego alcance su límite de frecuencia. Esto puede causar un comportamiento inesperado y una mala experiencia para sus usuarios. Tenga en cuenta que esta es una preocupación de los servicios de XBOX que no supone un problema en Steam. Escribir valores de estadísticas en Steam no genera una llamada a la API del servidor hasta que su juego los sincroniza explícitamente.Para los eventos que ocurren con frecuencia, intente agrupar las llamadas a la API en lotes para que se disparen después de que se produzca un número determinado de eventos, o para que se actualicen en el servidor en un intervalo de tiempo determinado.Puede depurar sus llamadas a la API mediante el analizador de seguimiento de XBOX Live (XblTraceAnalyzer.exe).Para obtener más información sobre los límites de frecuencia en los servicios de XBOX, consulte Limitación de frecuencia específica.