Creación de una tabla de clasificación básica

En este tutorial, le mostramos cómo crear una tabla de clasificación básica con nuestro nuevo servicio de tablas de clasificación. Empecemos con un ejemplo de un juego arcade en el que el objetivo es derrotar a tantos enemigos como sea posible hasta que le derroten. Cuando eso sucede, se le asigna una puntuación. Ahora, queremos crear una tabla de clasificación para ayudar a este juego a determinar quién es el mejor jugador.

Creación de una tabla de clasificación

El primer paso es crear una definición de tabla de clasificación que incluya los elementos principales para clasificar a los jugadores. Para nuestro juego arcade, solo necesitamos una columna para la puntuación. En el ejemplo siguiente se muestra cómo crear la definición de la tabla de clasificación con el SDK de C#.

public static async Task CreateLeaderboardDefinitionAsync(PlayFabAuthenticationContext context, string leaderboardName)
{
    PlayFabProgressionInstanceAPI leaderboardsAPI = new PlayFabProgressionInstanceAPI(context);
    CreateLeaderboardDefinitionRequest leaderboardDefinitionRequest = new CreateLeaderboardDefinitionRequest()
    {
        AuthenticationContext = context,
        Name = leaderboardName,
        SizeLimit = 1000,
        EntityType = "title_player_account",
        VersionConfiguration = new VersionConfiguration()
        {
            MaxQueryableVersions = 1,
            ResetInterval = ResetInterval.Manual,
        },
        Columns = new List<LeaderboardColumn>()
        {
            new LeaderboardColumn()
            {
                Name = "arcadeScore",
                SortDirection = LeaderboardSortDirection.Descending,
            }          
        }
    };

    PlayFabResult<PlayFab.LeaderboardsModels.EmptyResponse> createLbDefinitionResult = await leaderboardsAPI.CreateLeaderboardDefinitionAsync(leaderboardDefinitionRequest);
}

Ahora, expliquemos algunos elementos clave de este ejemplo:

AuthenticationContext: este parámetro controla toda la autenticación detrás de cada solicitud a nuestros servicios. Para obtener una explicación detallada, puede consultar la página siguiente: Inicio rápido de tablas de clasificación.
Name: este parámetro le ayuda a identificar la definición de la tabla de clasificación. Es importante elegir aquí algo relevante, ya que se usa para realizar otras solicitudes de recuperación de información. Además, este nombre debe ser único, por lo que se debe usar uno nuevo cada vez que se crea una tabla de clasificación.
EntityType: este parámetro especifica el tipo de entidad para el que quiere crear su tabla de clasificación. Puede obtener más información aquí: Modelo de programación de entidades.
- title_player_acount: este tipo de entidad hace referencia a los jugadores dentro de PlayFab. Para crear un jugador, puede usar el método LoginAsPlayer que se describe aquí: Inicio rápido.
- group: este tipo de entidad hace referencia a un grupo de jugadores; normalmente este concepto se aplica en juegos como “clanes”, “hermandades”, etc. Consulte más información aquí: Tablas de clasificación de grupos.
- external: este tipo de entidad sirve para agregar datos personalizados a nuestras tablas de clasificación. Cada fila no necesita estar vinculada a nada en PlayFab; son sus propios datos. Puede usar sus propios identificadores en el campo EntityId siempre que sean cadenas.
- master_player_account: este tipo de entidad hace referencia a los jugadores a través de distintos títulos. Este concepto se aplica cuando un estudio tiene varios títulos y hay jugadores que pasaron de un título a otro o que juegan a varios títulos del mismo estudio. A partir de este concepto, puede crear tablas de clasificación de jugadores de varios títulos del mismo estudio. Debe usar el identificador de cuenta de jugador maestro (también conocido como PlayFabId) para asignarlo al campo EntityId.
- character: este tipo de entidad está relacionado con juegos que tienen una serie de personajes entre los que un jugador puede elegir para empezar su aventura. Con este concepto en mente, para crear una tabla de clasificación de personajes primero debe crear un jugador y, después, puede crear un personaje asociado a ese jugador. A continuación, puede usar el CharacterId como identificador de entidad e insertar una fila con la puntuación correspondiente.
VersionConfiguration: este parámetro le permite establecer una estrategia de control de versiones para tablas de clasificación que se restablecen después de un período determinado. Este concepto se trata en profundidad aquí: Tablas de clasificación de temporada.
Columns: aquí definimos el número de columnas que va a tener nuestra tabla de clasificación. En este ejemplo, solo establecemos una columna para la puntuación. También definimos SortDirection como descendente, lo que significa que el jugador con la puntuación más alta estará en la parte superior. El número máximo de columnas permitidas por definición es 5.

Con toda esta información, ya está listo para ejecutar el ejemplo y crear su primera tabla de clasificación.

Obtención de una definición de tabla de clasificación

Antes de agregar datos a esta tabla de clasificación, queremos asegurarnos de que se creó correctamente. Para realizar esta acción, proporcionamos un ejemplo de cómo puede recuperar la definición de su tabla de clasificación.

public static async Task GetLeaderboardDefinition(PlayFabAuthenticationContext context, string leaderboardName)
{
    PlayFabProgressionInstanceAPI leaderboardsAPI = new PlayFabProgressionInstanceAPI(context);
    GetLeaderboardDefinitionRequest leaderboardDefReq = new GetLeaderboardDefinitionRequest()
    {
        Name = leaderboardName
    };

    PlayFabResult<GetLeaderboardDefinitionResponse> getleaderboardDefResult = await leaderboardsAPI.GetLeaderboardDefinitionAsync(leaderboardDefReq);
}

Para recuperar la definición de la tabla de clasificación, especifique el nombre de la tabla de clasificación que creó. Si tiene varias definiciones de tablas de clasificación, puede usar el ejemplo siguiente para obtener un conjunto de ellas.

 public static async Task ListLeaderboards(PlayFabAuthenticationContext context)
 {
     PlayFabProgressionInstanceAPI leaderboardsAPI = new PlayFabProgressionInstanceAPI(context);
     ListLeaderboardDefinitionsRequest listLbRequest = new ListLeaderboardDefinitionsRequest()  
     {
         AuthenticationContext = context,                
     };
     PlayFabResult<PlayFab.LeaderboardsModels.ListLeaderboardDefinitionsResponse> lbResponse = await leaderboardsAPI.ListLeaderboardDefinitionsAsync(listLbRequest);
    
 }

Actualización de una definición de tabla de clasificación

Si quiere actualizar la definición de su tabla de clasificación, puede hacerlo de la siguiente manera:

 public static async Task UpdateLeaderboardDefinitionAsync(PlayFabAuthenticationContext context, string leaderboardName, int sizeLimit, VersionConfiguration version)
 {
    PlayFabProgressionInstanceAPI leaderboardsAPI = new PlayFabProgressionInstanceAPI(context);
    UpdateLeaderboardDefinitionRequest updateLbDefinitionRequest = new UpdateLeaderboardDefinitionRequest()
    {
        AuthenticationContext = context,
        Name = leaderboardName,
        SizeLimit = sizeLimit,
        VersionConfiguration = version,
     };
     PlayFabResult<PlayFab.ProgressionModels.EmptyResponse> updateLbDefinitionResult = await leaderboardsAPI.UpdateLeaderboardDefinitionAsync(updateLbDefinitionRequest);
           
 }

Tenga en cuenta que Columns, EntityType y ResetInterval no se pueden modificar como parte de la actualización.

Eliminación de una definición de tabla de clasificación

Si quiere eliminar la definición de su tabla de clasificación, puede hacerlo de la siguiente manera:

public static async Task DeleteLeaderboard(PlayFabAuthenticationContext context, string leaderboardName)
{
    PlayFabProgressionInstanceAPI leaderboardsAPI = new PlayFabProgressionInstanceAPI(context);
    DeleteLeaderboardDefinitionRequest deleteLbRequest = new DeleteLeaderboardDefinitionRequest()
    {
        AuthenticationContext = context,
        Name = leaderboardName,
    };

    PlayFabResult<PlayFab.LeaderboardsModels.EmptyResponse> lbResponse = await leaderboardsAPI.DeleteLeaderboardDefinitionAsync(deleteLbRequest);
}

Adición de datos a una tabla de clasificación

Siguiendo con nuestro ejemplo del juego arcade, ahora sabemos cómo crear una definición de tabla de clasificación, recuperarla y eliminarla si es necesario. El siguiente paso es empezar a agregar datos a nuestra tabla de clasificación. Tenga en cuenta que se trata de tablas de clasificación basadas en entidades, lo que significa que las entradas son entidades. También admitimos el uso de sus propias identidades externas, lo que se trata en detalle en Cómo hacer más con las tablas de clasificación. En nuestro ejemplo concreto, usamos el tipo de entidad title_player_account, por lo que nuestra tabla de clasificación se rellena con jugadores. Sin embargo, recuerde que también hay otros tipos de entidad que puede usar. Puede consultarlos aquí: Tipos de entidad integrados disponibles. Ahora veamos cómo podemos agregar datos a nuestra tabla de clasificación.

public static async Task UpdateLeaderboardForPlayer(PlayFabAuthenticationContext context, string leaderboardName, string entityId, int score)
{
    PlayFabProgressionInstanceAPI leaderboardsAPI = new PlayFabProgressionInstanceAPI(context);
    UpdateLeaderboardEntriesRequest updateLeaderboardRequest = new UpdateLeaderboardEntriesRequest()
    {
        Entries = new List<LeaderboardEntryUpdate>()
        {
            new LeaderboardEntryUpdate()
            {
                EntityId = entityId,
                Scores = new List<string> { score.ToString()}                
            }
        },
        AuthenticationContext = context,
        LeaderboardName = leaderboardName,
    };

    PlayFabResult<PlayFab.LeaderboardsModels.EmptyResponse> updateResult = await leaderboardsAPI.UpdateLeaderboardEntriesAsync(updateLeaderboardRequest);
}

Ahora, expliquemos algunos elementos clave de este ejemplo:

Entries: este parámetro corresponde a la fila real agregada a la tabla de clasificación. Tiene un EntityId, que es una cadena que identifica la entidad dentro de la tabla de clasificación. Dado que este servicio es un componente independiente, puede usar aquí sus propios identificadores. Sin embargo, si usa otros servicios de PlayFab, este valor debe ser coherente en todos los servicios.
Scores: este parámetro corresponde a la lista de puntuaciones que puede agregar a una entidad. Recuerde que las tablas de clasificación pueden tener más de una columna. Puede consultar estos conceptos en profundidad aquí: Cómo hacer más con las tablas de clasificación
Name: este parámetro corresponde al nombre de la tabla de clasificación establecido al crear la definición de la tabla de clasificación.

Ya está listo para agregar datos a su tabla de clasificación.

Recuperación de datos de una tabla de clasificación

Hagamos un breve resumen. En este punto, creó una tabla de clasificación, comprobó todos los detalles de configuración y empezó a agregarle entidades. Ahora, imaginemos que algunos jugadores ya empezaron a usar su juego, todos con puntuaciones impresionantes. Queremos determinar quién es el mejor jugador. En el ejemplo siguiente, le mostramos cómo realizar esta acción.

public static async Task<List<EntityLeaderboardEntry>> GetLeaderboard(PlayFabAuthenticationContext context, string leaderboardName)
{
    PlayFabProgressionInstanceAPI leaderboardsAPI = new PlayFabProgressionInstanceAPI(context);
    GetEntityLeaderboardRequest getLbRequest = new GetEntityLeaderboardRequest()
    {
        LeaderboardName = leaderboardName,
        StartingPosition = 1,
        PageSize = 20,
        AuthenticationContext = context,
    };

    PlayFabResult<GetEntityLeaderboardResponse> lbResponse = await leaderboardsAPI.GetLeaderboardAsync(getLbRequest);
    
    return lbResponse.Result.Rankings;
}

Ahora, expliquemos algunos elementos clave de este ejemplo:

StartingPosition: este parámetro hace referencia a la posición desde la que quiere empezar a consultar los datos. En este caso, queremos el mejor jugador, por lo que establecemos este parámetro en 1. Este parámetro también funciona con el parámetro PageSize para consultar toda la tabla de clasificación según sea necesario.
PageSize: este parámetro especifica cuántos registros se extraen en esa solicitud.
Name: este parámetro corresponde al nombre de la tabla de clasificación establecido al crear la definición de la tabla de clasificación.

Desempate

Ahora imaginemos que algunos jugadores que usan su juego están luchando por ver quién es el mejor. Nos enfrentamos a un problema: dos jugadores tienen la misma puntuación porque derrotaron al mismo número de enemigos. Entonces, ¿quién debería ser el mejor jugador? Para responder a esa pregunta, tenemos una directiva de desempate sencilla de forma predeterminada. Elegimos al mejor jugador según la marca de tiempo en que se logró la puntuación. Quien la logró primero es el mejor jugador. Sin embargo, según el contexto del juego, esto podría no ser suficiente o preciso. Para características de desempate más complejas, consulte: Cómo hacer más con las tablas de clasificación. En nuestro ejemplo actual, la clasificación sería:

Posición	Entity Id	Puntuación	LastUpdated
1	”player 3”	103	”2024-08-27T20:24:36.738Z”
2	”player 2”	102	”2024-08-27T20:24:29.251Z”
3	”player 1”	100	”2024-08-27T19:52:26.642Z”
4	”player 4”	100	”2024-08-27T20:24:44.552Z”

En este ejemplo concreto, tanto “player 1” como “player 4” tienen la misma puntuación. La decisión de quién va primero depende de la marca de tiempo. Dado que “player 1” logró la puntuación primero, esa es la razón por la que está en la parte superior.

Eliminación de filas de una tabla de clasificación

Sus tablas de clasificación funcionan según lo previsto y tiene un montón de jugadores en su juego. Sin embargo, empieza a notar un comportamiento inusual, ya que parece que algunos jugadores hacen trampas para llegar a la parte superior de la tabla de clasificación. No va a tolerar tal comportamiento, por lo que quiere quitarlos de sus tablas de clasificación. En el ejemplo siguiente, puede ver cómo eliminar filas de su tabla de clasificación.

public static async Task DeleteLeaderboardEntries(PlayFabAuthenticationContext context, string leaderboardName, List<string> entityIds)
{
    PlayFabProgressionInstanceAPI leaderboardsAPI = new PlayFabProgressionInstanceAPI(context);
    DeleteLeaderboardEntriesRequest leaderboardsDelReq = new DeleteLeaderboardEntriesRequest() {
        Name = leaderboardName,
        EntityIds = entityIds
    };

    PlayFabResult<PlayFab.LeaderboardsModels.EmptyResponse> delLeaderboardDefResult = await leaderboardsAPI.DeleteLeaderboardEntriesAsync(leaderboardsDelReq);
}

Ahora, expliquemos algunos elementos clave de este ejemplo:

EntityIds: este parámetro es la lista de identificadores de entidad que quiere eliminar.
Name: este parámetro corresponde al nombre de la tabla de clasificación establecido al crear la definición de la tabla de clasificación.

Conclusiones

En este tutorial, aprendimos a realizar las siguientes operaciones:

Crear una tabla de clasificación.
Comprobar la configuración de una tabla de clasificación.
Actualizar la configuración de la tabla de clasificación.
Eliminar la configuración de la tabla de clasificación.
Rellenar la tabla de clasificación.
Comprender cómo funciona el desempate.
Eliminar entradas de la tabla de clasificación.

XBOX Services

PlayFab

Creación de una tabla de clasificación básica

Creación de una tabla de clasificación básica