Tabelas de classificação de grupos

Neste tutorial, vamos aprender a usar entidades de grupo em uma tabela de classificação. Para entender esse conceito, vamos começar com o exemplo de um jogo de “RPG” focado em terraformar planetas. Como jogador, você precisa construir e desenvolver estruturas em cada planeta, coletar recursos, criar suas próprias naves e também montar defesas, porque outros jogadores podem atacar você para roubar seus itens. Um aspecto importante deste jogo é que os jogadores podem formar alianças com o objetivo de criar uma equipe e atacar outros jogadores como um grupo. Com esse contexto em mente, queremos criar uma tabela de classificação para alianças, para podermos saber qual é a aliança mais forte em todo o universo. Alguns aspectos importantes a ter em mente antes de nos aprofundarmos em como as tabelas de classificação de grupos funcionam:

Saiba mais sobre o Modelo de Programação de Entidades aqui: Modelo de Programação de Entidades.
Veja como os grupos funcionam aqui: Grupos.

Criando uma tabela de classificação

Dependendo do jogo e do tipo de cenários que você terá, é muito provável que você crie várias tabelas de classificação. Neste contexto específico, queremos mostrar dois cenários diferentes para este jogo e como usar o serviço para atender a cada um deles.

Tabelas de classificação de jogadores

Neste exemplo, temos jogadores que estão terraformando planetas e ganhando pontos de experiência ao realizar determinadas ações no jogo. Então, teremos uma tabela de classificação para acompanhar essa experiência no nível do jogador. Esse processo segue o mesmo comportamento apresentado em outros tutoriais, como Criar uma tabela de classificação básica. O aspecto importante aqui é que o parâmetro EntityType precisa ser "title_player_account", para que ela seja apenas para jogadores.

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 = "XP",
                SortDirection = LeaderboardSortDirection.Descending,
            }        
        }
    };

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

Agora vamos ao aspecto do jogo apresentado no exemplo: as alianças. Podemos criar alianças no PlayFab usando a entidade "group". Essa entidade de grupo nos permite ter uma estrutura na qual os jogadores podem entrar; ela também tem funções e outros recursos interessantes que potencializam esse tipo de cenário em jogos. Para criar a tabela de classificação, precisamos ter duas coisas claras.

O parâmetro EntityType precisa ser "group".
Essa tabela de classificação é independente. Portanto, adicionar uma pontuação para uma aliança é um processo manual separado da tabela de classificação de jogadores. Esse comportamento permite diferentes formas de relacionar as pontuações aos jogadores, ou pode ser uma nova métrica aplicável somente a grupos.

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 = "group",
        VersionConfiguration = new VersionConfiguration()
        {
            MaxQueryableVersions = 1,
            ResetInterval = ResetInterval.Manual,
        },
        Columns = new List<LeaderboardColumn>()
        {
            new LeaderboardColumn()
            {
                Name = "Group XP",
                SortDirection = LeaderboardSortDirection.Descending,
            }        
        }
    };

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

Adicionando dados à tabela de classificação

Depois de criar as duas tabelas de classificação, precisamos ver como adicionar dados a elas. Como mencionado no exemplo anterior, essas tabelas de classificação são independentes uma da outra, o que dá ao desenvolvedor o controle para aplicar lógica personalizada sobre como as pontuações funcionam para alianças (grupos).

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);
}

O código para adicionar entradas à tabela de classificação de jogadores ou à tabela de classificação de grupos é o mesmo neste cenário. Mas esse comportamento nem sempre é verdadeiro, pois poderíamos ter uma tabela de classificação com cinco colunas para jogadores e outra tabela de classificação para grupos com apenas uma coluna. Descrevemos mais sobre tabelas de classificação com várias colunas neste tutorial: Fazendo mais com tabelas de classificação. Algo a ter sempre em mente é que você precisa fornecer o EntityId correto ao serviço. Se você tiver uma tabela de classificação de jogadores, as entidades são "title_player_account"; se a tabela de classificação for composta por grupos, você precisa fornecer entidades do tipo "group.

Recuperar dados da tabela de classificação

Para obter os dados da tabela de classificação, temos todas as opções descritas em Fazendo mais com tabelas de classificação, exceto a API GetFriendLeaderboard.

Nome de exibição para tabelas de classificação de grupos

Por fim, outro detalhe que podemos fazer com as tabelas de classificação de grupos é definir o nome de exibição com o nome do grupo da entidade. Assim, se você tiver uma aliança chamada “Raiders”, esse nome de grupo será mapeado para a entidade com a propriedade DisplayName.

public static async Task<CreateGroupResponse> CreateGroup(string groupName, PlayFabAuthenticationContext context)
{
    var request = new CreateGroupRequest
    {
        GroupName = groupName,
        AuthenticationContext = context
    };
    var response = await PlayFabGroupsAPI.CreateGroupAsync(request);

    SetDisplayNameRequest displayRequest = new SetDisplayNameRequest()
    {
        AuthenticationContext = context,
        DisplayName = groupName,
        Entity = new PlayFab.ProfilesModels.EntityKey()
        {
            Id = response.Result.Group.Id,
            Type = "group",
        },
    };

    PlayFabResult<SetDisplayNameResponse> updateNameResult = await PlayFabProfilesAPI.SetDisplayNameAsync(displayRequest);

    return response.Result;
}

Neste exemplo, criamos um grupo chamando o método CreateGroupAsync. A primeira etapa dessa execução é retornar o objeto Group, que usaremos para definir o nome de exibição. Fazemos esse processo mapeando o nome do grupo para a entidade usando o objeto SetDisplayNameRequest e, em seguida, executando o método PlayFabProfilesAPI.SetDisplayNameAsync.

Conclusões

Neste tutorial, aprendemos a realizar as seguintes operações:

Criar uma tabela de classificação de grupos.
Aprender a alimentar essa tabela de classificação com dados.
Recuperar a tabela de classificação.
Alterar o displayName para que ele mostre o nome do grupo.

XBOX Services

PlayFab

Tabelas de classificação de grupos

Criando uma tabela de classificação

Tabelas de classificação de jogadores