创建基本排行榜

项目
11/05/2024

本教程介绍如何使用新的排行榜服务创建基本排行榜。让我们从街机游戏的示例开始，其中的目标是击败尽可能多的敌人，直到你被击败。发生这种情况时，系统会为你分配分数。现在，我们希望创建一个排行榜，以帮助此游戏确定谁是最佳玩家。

创建排行榜

第一步是创建一个排行榜定义，其中包含用于排名玩家的main元素。对于我们的街机游戏，我们只需要一列的分数。以下示例演示如何使用 C# SDK 创建排行榜定义。

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

现在，让我们解释一下此示例的一些关键元素：

AuthenticationContext：此参数处理对服务的每个请求背后的所有身份验证。有关详细说明，可以检查以下页面：快速入门排行榜。
Name：此参数可帮助你识别排行榜定义。请务必在此处选择相关内容，因为它用于发出其他请求来检索信息。此外，此名称必须是唯一的，因此每次创建排行榜时，都应使用一个新名称。
EntityType：此参数指定要为其创建排行榜的实体的类型。可在此处了解详细信息：实体编程模型。
- title_player_acount：此类型的实体是指 PlayFab 中的玩家。若要创建玩家，可以使用此处所述的方法 LoginAsPlayer ：快速入门。
- group：这种类型的实体是指一组玩家，此概念通常适用于“部落”、“公会”等游戏。有关详细信息，请参阅：组排行榜。
- external：这种类型的实体用于将自定义数据添加到排行榜。每一行不需要绑定到 PlayFab 上的任何内容，它是你自己的数据。可以在字段中使用自己的标识符， EntityId 只要它们是字符串。
- master_player_account：这种类型的实体是指跨游戏的玩家。当一个工作室有多个游戏，并且你拥有从一个游戏到另一个游戏，或者他们正在从同一个工作室玩多个游戏的玩家时，此概念适用。基于此概念，可以从同一工作室跨多个游戏创建玩家排行榜。你需要使用：主玩家帐户 ID 也指 PlayFabId 以将其映射到 EntityId。
- character：这种类型的实体与具有一系列角色的游戏相关，玩家可以从这些角色中选择并开始其旅程。考虑到这一概念，若要创建字符排行榜，需要先创建一个玩家，然后才能创建与该玩家关联的角色。之后，可以使用 CharacterId 作为实体 ID，并插入具有相应分数的行。
VersionConfiguration：此参数允许你为排行榜设置版本控制策略，这些排行榜在特定时间段后自行重置。此处深入介绍了此概念：季节性排行榜。
Columns：在这里，我们定义排行榜将具有的列数。在此示例中，我们只为分数设置了一列。我们还将定义为 SortDirection 降序，这意味着得分最高的玩家将位于榜首。

有了所有这些信息，就可以运行示例并创建第一个排行榜了。

获取排行榜定义

在向此排行榜添加数据之前，我们希望确保数据已正确创建。为此，我们提供了一个示例，说明如何检索排行榜定义。

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

若要检索排行榜定义，请指定创建的排行榜的名称。如果有多个排行榜定义，可以使用下一个示例来获取一组排行榜定义。


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

删除排行榜定义

如果要删除排行榜定义以添加更多列或修复某些错误，可按如下所示操作：


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

将数据添加到排行榜

继续我们的街机游戏示例，我们现在知道如何创建排行榜定义，检索它，并在必要时将其删除。下一步是开始将数据添加到排行榜。

请记住，这些是基于实体的排行榜，这意味着条目是实体。我们还支持引入自己的外部标识，在排行榜中详细讨论了这一点。

在我们的特定示例中，我们使用实体类型title_player_account，因此排行榜上充满了玩家。但请记住，也可以使用其他实体类型。可在此处检查它们：可用的内置实体类型。

现在，让我们深入了解如何将数据添加到排行榜。

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

现在，让我们解释一下此示例的一些关键元素：

Entries：此参数对应于添加到排行榜的实际行。它有一个 EntityId，它是一个字符串，用于标识排行榜中的实体。由于此服务是独立组件，因此可在此处使用自己的标识符。但是，如果你使用的是其他 PlayFab 服务，则此值应在所有服务中保持一致。
Scores：此参数对应于可添加到一个实体的分数列表。请记住，排行榜可以有多个列。可在此处深入检查以下概念：使用排行榜执行更多操作
Name：此参数对应于创建排行榜定义时设置的排行榜名称。

现在可以将数据添加到排行榜。

从排行榜检索数据

让我们快速回顾一下。此时，你创建了一个排行榜，检查了所有配置详细信息，并开始向其添加实体。现在，让我们假设一些玩家已经开始使用你的游戏，所有游戏都有令人印象深刻的分数。我们想确定谁是最好的球员。在以下示例中，我们将演示如何执行此操作。

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

现在，让我们解释一下此示例的一些关键元素：

StartingPosition：此参数引用要从中开始查询数据的位置。在本例中，我们需要顶级玩家，因此将此参数设置为 1。此参数还与参数一起使用， PageSize 以便根据需要查询整个排行榜。
PageSize：此参数指定在该请求中拉取的记录数。
Name：此参数对应于创建排行榜定义时设置的排行榜名称。

断线

现在，假设一些使用你的游戏的玩家正在奋力查看谁是最好的。我们面临着一个问题：两名球员的分数相同，因为他们击败了同样数量的敌人。那么，谁应该成为顶级球员呢？

为了回答这个问题，我们默认有一个简单的断线策略。我们根据得分达到时的时间戳选择最佳球员。谁先做到了，就是顶级球员。但是，根据游戏的上下文，这可能不够或不准确。有关更复杂的分线功能，请参阅：使用排行榜执行更多操作。

在当前示例中，排名为：

排名	实体 ID	得分	LastUpdated
1	“玩家 3”	103	“2024-08-27T20：24：36.738Z”
2	“玩家 2”	102	“2024-08-27T20：24：29.251Z”
3	“玩家 1”	100	“2024-08-27T19：52：26.642Z”
4	“玩家 4”	100	“2024-08-27T20：24：44.552Z”

在此特定示例中，“玩家 1”和“玩家 4”的分数相同。谁首先决定取决于时间戳。由于“球员1”先得了比分，这成了为什么在积分榜上名列前茅的原因。

删除排行榜行

排行榜按预期工作，并且游戏中有一群玩家。但是，你开始注意到一些不寻常的行为，因为似乎有些玩家欺骗了排行榜的顶部。你不会容忍此类行为，因此希望将其从排行榜中删除。在下一个示例中，可以看到如何从排行榜中删除行。


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

现在，让我们解释一下此示例的一些关键元素：

EntityIds：此参数是要删除的实体 ID 的列表。
Name：此参数对应于创建排行榜定义时设置的排行榜名称。

结论

在本教程中，我们学习了如何执行以下操作：

创建排行榜。
检查排行榜的配置。
删除排行榜配置。
填充排行榜。
了解断线的工作原理。
删除排行榜中的条目。

通过

创建基本排行榜

创建排行榜

获取排行榜定义

删除排行榜定义

将数据添加到排行榜

从排行榜检索数据

断线

删除排行榜行

结论

另请参阅

反馈

其他资源