Descripción general

Steam admite tablas de clasificación persistentes con entradas ordenadas automáticamente. Estas tablas de clasificación pueden usarse para mostrar tablas de clasificación mundiales y de amigos tanto en el juego como en la página web de la comunidad del juego. Cada título de Steamworks puede crear hasta 10 000 tablas de clasificación y cada una puede recuperarse inmediatamente después de que se haya insertado la puntuación de un jugador.

Cada jugador puede tener una sola entrada en una tabla de clasificación concreta. No hay límite para el número de jugadores por tabla de clasificación. Cada entrada contiene una puntuación para la tabla de clasificación (un entero de 32 bits) y, opcionalmente, hasta 64 enteros de 32 bits de datos asociados. Los datos asociados pueden usarse para almacenar información específica del juego sobre la sesión que produjo la entrada en la tabla de clasificación del usuario. Steam no clasifica ni analiza estos datos, los cuales, además, se sustituyen cuando se crea una tabla de clasificación nueva para el usuario.

Todas las funciones de las tablas de clasificación residen en ISteamUserGameStats.h y se han implementado tablas de clasificación de muestra en el ejemplo de Steamworks. También es posible ver y administrar las tablas de clasificación para un juego en el administrador de juegos de Steamworks.

Antes de empezar

Todas las funciones asíncronas de tablas de clasificación devuelven un identificador o handle para un resultado de llamada a la API de Steam. Puede encontrarse más información sobre cómo recibir estos resultados en la sección Resultados de llamada del documento Primeros pasos.

Crear una tabla de clasificación

Las tablas de clasificación son específicas para cada aplicación y se configuran en la página del administrador de juegos del sitio asociado de Steamworks, o bien a través de la API.

Creación a través de la web

Pueden crearse y gestionarse tablas de clasificación en el administrador de apps de Steamworks para el id. de aplicación yendo a Estadísticas y logros-> Tablas de clasificación.


Los siguientes campos deben completarse para definir una tabla de clasificación:

• Nombre: configúralo para que sea un nombre que tenga sentido como parte del desarrollo interno.
  
• Nombre en la comunidad: si la tabla de clasificación se muestra en el punto de encuentro, establece aquí el nombre visible al público. Si no se introduce ningún nombre, la tabla de clasificación no aparecerá.
  
• Método de clasificación: aquí se establece el orden para la tabla de clasificación. Para tablas de clasificación basadas en la posición, usa Ascendente. Para tablas de clasificación basadas en las puntuaciones más altas, usa Descendente.
  
• Tipo de presentación: determina los tipos de datos que se mostrarán en la tabla de clasificación. Se puede elegir entre "Numérico", "Segundos" o "Milisegundos".
  
• Escrituras: si se establece como "De confianza", los clientes no podrán establecer las puntuaciones de las tablas de clasificación, sino que tendrá que hacerse exclusivamente mediante la Web de API de SetLeaderboardScore. El valor predeterminado es false.
  
• Lecturas: si se establece como "Amigos", el juego solo puede leer las puntuaciones de las tablas de clasificación de los amigos del usuario. La Web de API puede leer siempre todas las puntuaciones. El valor predeterminado es false.

Creación a través de la API

Las tablas de clasificación de los juegos pueden crearse a través del administrador de apps de Steamworks o de forma de programática, llamando a ISteamUserStats::FindOrCreateLeaderboard. En Steam, todas las tablas de clasificación para un título de Steamworks están identificadas mediante un nombre único. El nombre de la tabla de clasificación solo se utiliza para la identificación en la API de Steamworks y no se ofrece a los usuarios a través de la Comunidad Steam. Cuando se crea una tabla de clasificación, es necesario elegir un:

• método de clasificación: k_ELeaderboardSortMethodAscending (la entrada superior es el usuario con la puntuación más baja) o k_ELeaderboardSortMethodDescending (la entrada superior es el usuario con la puntuación más alta).
  
• tipo de presentación: ELeaderboardDisplayType se usa para describir lo que representa la puntuación de una tabla de clasificación y solo la emplea la comunidad para formatear la puntuación de las tablas de clasificación cuando estas son visibles.

Si se elige crear solo tablas de clasificación mediante el administrador de apps, puede usarse ISteamUserStats::FindLeaderboard para recuperar un handle para una tabla de clasificación concreta. FindLeaderboard y FindOrCreateLeaderboard son métodos asíncronos y devuelven el "handle" de la tabla de clasificación para la tabla especificada mediante un resultado de llamada para ISteamUserStats::LeaderboardFindResult_t.

Una vez que se ha creado una tabla de clasificación, pueden modificarse el método de clasificación y el tipo de presentación de la tabla a través del administrador de juegos. Cuando se llama a FindOrCreateLeaderboard para una tabla de clasificación existente, los parámetros del método de clasificación y del tipo de presentación se ignoran.

Cargar una puntuación

Para cargar una puntuación de la tabla de clasificación, se hace una llamada a ISteamUserStats::UploadLeaderboardScore pasando el "handle" de la tabla de clasificación de destino (recuperado mediante FindLeaderboard), la puntuación del usuario y, de forma opcional, cualquier dato asociado que se haya generado al establecer la nueva puntuación. Si se actualiza la puntuación de la tabla de clasificación del usuario, los datos asociados pasados a ISteamUserStats::UploadLeaderboardScore sustituirán a cualquier otro dato almacenado con anterioridad. Puede elegirse entre dos métodos de actualización cuando se carga la puntuación de la tabla de clasificación de un usuario:

• ISteamUserStats::k_ELeaderboardUploadScoreMethodKeepBest: Steam comparará la nueva puntuación del usuario con la puntuación ya almacenada en la tabla de clasificación y mantendrá la mejor puntuación (la más baja para tablas con un método de clasificación ascendente y la más alta para tablas con un método de clasificación descendente).
  
• ISteamUserStats::k_ELeaderboardUploadScoreMethodForceUpdate: Steam siempre sustituirá la puntuación del usuario en una tabla de clasificación con la puntuación nueva.
  
• ISteamUserStats::UploadLeaderboardScore es una llamada asíncrona y el resultado de la subida se devuelve en un resultado de llamada para LeaderboardScoreUploaded_t. El resultado contiene una marca que establece si la puntuación del usuario ha cambiado, y las clasificaciones globales nueva y antigua del usuario. Una vez cargadas, las tablas de clasificación de Steamworks se actualizan inmediatamente para reflejar la nueva puntuación y el nuevo orden de entrada puede recuperarse mediante DownloadLeaderboardEntries.

Asociar contenido generado por los usuarios

Después de que se haya subido una puntuación, se tiene la opción de asociar a la entrada contenido generado por los usuarios. Para ello, se llama simplemente a ISteamUserStats::AttachLeaderboardUGC. Este contenido podría ser una reproducción del usuario obteniendo una puntuación o un usuario fantasma contra el que se puede competir. El "handle" asociado estará disponible cuando se recupere la entrada y puede ser descargado por otros usuarios. Para crear y descargar contenido generado por los usuarios, véase la documentación de Steam Cloud.

Una vez asociado, el contenido estará disponible incluso si el usuario modifica o elimina el archivo subyacente en la nube.

Recuperar entradas de las tablas de clasificación

ISteamUserStats::DownloadLeaderboardEntries se usa para recuperar entradas de la tabla de clasificación empleando el "handle" de la tabla recuperado mediante ISteamUserStats::FindLeaderboard.

Una vez que se hayan recuperado todas las entradas descargadas desde GetDownloadedLeaderboardEntry, se liberarán los datos de entrada y las SteamLeaderboardEntries_t en LeaderboardScoresDownloaded_t ya no serán válidas.

Recuperar información de las tablas de clasificación

Con un "handle" de la tabla de clasificación devuelto por FindLeaderboard puede recuperarse información sobre la tabla por medio de las siguientes funciones:

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