群組排行榜

在本教學課程中，我們將學習如何在排行榜上使用群組實體。為了理解這個概念，我們將從一款專注於行星地球化的「RPG」遊戲範例開始。身為玩家，您需要在每顆行星上建造和發展建築，收集資源、建立自己的太空船，還要設置防禦，因為其他玩家可能會攻擊您以竊取您的物品。這款遊戲的一個關鍵面向是，玩家可以組成聯盟，目標是建立團隊並以群組方式攻擊其他玩家。基於這樣的背景，我們想要為聯盟建立一個排行榜，以便知道整個宇宙中哪個聯盟最強大。在深入了解群組排行榜的運作方式之前，請先記住以下幾個重點：

在此深入了解實體程式設計模型：實體程式設計模型。
在此查看群組的運作方式：群組。

建立排行榜

根據遊戲以及您將面對的情境類型，您很可能會建立多個排行榜。在這個特定情境中，我們想要展示此遊戲的兩種不同情境，以及如何使用此服務來處理每一種情境。

玩家排行榜

在此範例中，玩家正在為行星進行地球化，並藉由在遊戲中執行特定動作來獲得經驗值。因此，我們將建立一個排行榜，在玩家層級追蹤該經驗值。此流程與其他教學課程（例如建立基本排行榜）中介紹的行為相同。這裡的關鍵在於 EntityType 參數必須是 "title_player_account"，因此它只會用於玩家。

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

現在讓我們來看看範例中提到的遊戲面向：聯盟。我們可以使用 "group" 實體在 PlayFab 中建立聯盟。這個群組實體讓我們擁有可供玩家加入的結構，它也具備角色和其他有趣的功能，能夠支援遊戲中的這類情境。建立排行榜時，我們需要清楚兩件事。

EntityType 參數必須是 "group"。
這個排行榜是獨立的。因此，為聯盟新增分數是與玩家排行榜分開的手動流程。此行為允許以不同方式將分數與玩家建立關聯，或者它也可以是僅適用於群組的新指標。

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

將資料新增至排行榜

建立兩個排行榜之後，我們需要了解如何將資料新增至其中。如先前範例所述，這些排行榜彼此獨立，這讓開發人員能夠控制並套用自訂邏輯，決定聯盟 (群組) 的分數運作方式。

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

在此情境中，將項目新增至玩家排行榜或群組排行榜的程式碼是相同的。但此行為並非總是如此，因為我們可能有一個玩家排行榜具有五個欄，但另一個群組排行榜只有一個欄。我們會在此教學課程中進一步說明多欄排行榜：使用排行榜執行更多操作。請務必記住，您必須將正確的 EntityId 提供給服務。如果您有玩家排行榜，實體就是 "title_player_account"；如果排行榜由群組組成，則您需要提供 "group 實體。

從排行榜擷取資料

現在，若要取得排行榜的資料，除了 GetFriendLeaderboard API 之外，我們可以使用此處所述的所有選項：使用排行榜執行更多操作。