建立基本排行榜

在本教學課程中，我們將示範如何使用新的排行榜服務建立基本排行榜。讓我們從一個大型電玩遊戲的範例開始，這款遊戲的目標是在被擊敗之前盡可能擊敗最多的敵人。當您被擊敗時，就會獲得一個分數。現在，我們想要建立排行榜，協助這款遊戲判斷誰是最佳玩家。

建立排行榜

第一步是建立排行榜定義，其中包含為玩家排名的主要元素。對於我們的大型電玩遊戲，我們只需要一個分數欄。下列範例示範如何使用 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 作為實體識別碼，並插入含有對應分數的一列。
VersionConfiguration：此參數可讓您為在特定期間後自行重設的排行榜設定版本控制策略。此概念在此有深入說明：季節性排行榜。
Columns：我們在此定義排行榜將擁有的欄數。在此範例中，我們只為分數設定一個欄。我們也將 SortDirection 定義為遞減，表示分數最高的玩家將位於頂端。每個定義允許的欄數上限為 5。

有了這些資訊，您現在就可以執行範例並建立您的第一個排行榜。

取得排行榜定義

在將資料新增至此排行榜之前，我們想要確保它已正確建立。為了執行此動作，我們提供一個範例，說明如何擷取排行榜定義。

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

請注意，Columns、EntityType 和 ResetInterval 無法在更新中修改。

刪除排行榜定義

如果您想要刪除排行榜定義，可以依照下列方式進行：

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：此參數對應至您建立排行榜定義時所設定的排行榜名稱。

平手決勝

現在假設有些玩您遊戲的玩家正在一較高下，看看誰是最強的。我們遇到了一個問題：兩位玩家擊敗了相同數量的敵人，因此分數相同。那麼，誰應該是排名第一的玩家？為了回答這個問題，我們預設有一個簡單的平手決勝原則。我們會根據達成分數時的時間戳記來選擇最佳玩家。最先達成分數的人就是排名第一的玩家。不過，視遊戲的情境而定，這可能不夠充分或不夠精確。如需更複雜的平手決勝功能，請參閱：使用排行榜執行更多操作。在我們目前的範例中，排名將會是：

排名	實體識別碼	分數	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”

在這個特定範例中，“player 1” 和 “player 4” 的分數相同。由誰排在前面取決於時間戳記。由於 “player 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：此參數是您要刪除的實體識別碼清單。
Name：此參數對應至您建立排行榜定義時所設定的排行榜名稱。

結論

在本教學課程中，我們學到了如何執行下列作業：

建立排行榜。
檢查排行榜的組態。
更新排行榜組態。
刪除排行榜組態。
填入排行榜。
了解平手決勝的運作方式。
刪除排行榜中的項目。

XBOX Services

PlayFab

建立基本排行榜

建立基本排行榜

建立排行榜

取得排行榜定義

更新排行榜定義

刪除排行榜定義

將資料新增至排行榜

從排行榜擷取資料

平手決勝

刪除排行榜列

結論

另請參閱

​建立基本排行榜

​建立排行榜

​取得排行榜定義

​更新排行榜定義

​刪除排行榜定義

​將資料新增至排行榜

​從排行榜擷取資料

​平手決勝

​刪除排行榜列

​結論

​另請參閱

建立基本排行榜

建立排行榜

取得排行榜定義

更新排行榜定義

刪除排行榜定義

將資料新增至排行榜

從排行榜擷取資料

平手決勝

刪除排行榜列

結論

另請參閱