> ## Documentation Index > Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt > Use this file to discover all available pages before exploring further. # Create basic leaderboard > Create a basic PlayFab leaderboard with the C# SDK: define columns and sort direction, add player entries, query rankings, and handle score tie-breaking. # 기본 리더보드 만들기 이 튜토리얼에서는 새로운 리더보드 서비스를 사용하여 기본 리더보드를 만드는 방법을 보여드립니다. 패배할 때까지 최대한 많은 적을 물리치는 것이 목표인 아케이드 게임의 예시로 시작해 보겠습니다. 패배 시 점수가 부여됩니다. 이제 이 게임의 최고 플레이어를 결정하기 위한 리더보드를 만들어 보겠습니다. ## 리더보드 만들기 첫 번째 단계는 플레이어 순위를 매기기 위한 주요 요소를 포함하는 리더보드 정의를 만드는 것입니다. 이 아케이드 게임의 경우 점수를 위한 열 하나만 있으면 됩니다. 다음 예시는 C# SDK를 사용하여 리더보드 정의를 만드는 방법을 보여줍니다. ```C# theme={null} 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() { new LeaderboardColumn() { Name = "arcadeScore", SortDirection = LeaderboardSortDirection.Descending, } } }; PlayFabResult createLbDefinitionResult = await leaderboardsAPI.CreateLeaderboardDefinitionAsync(leaderboardDefinitionRequest); } ``` 이 예시의 주요 요소를 설명하면 다음과 같습니다. * `AuthenticationContext`: 이 매개 변수는 서비스에 대한 모든 요청 뒤의 인증을 처리합니다. 자세한 내용은 [Quickstart Leaderboard](/services/playfab/community/leaderboards/quickstart-leaderboards) 페이지를 확인하세요. * `Name`: 이 매개 변수는 리더보드 정의를 식별하는 데 도움이 됩니다. 정보를 검색하기 위한 다른 요청에도 사용되므로 관련성 있는 이름을 선택하는 것이 중요합니다. 또한 이 이름은 고유해야 하므로 리더보드를 만들 때마다 새 이름을 사용해야 합니다. * `EntityType`: 이 매개 변수는 리더보드를 만들 엔티티의 종류를 지정합니다. 자세한 내용은 [엔티티 프로그래밍 모델](/services/playfab/live-service-management/game-configuration/entities)에서 확인할 수 있습니다. * `title_player_acount`: 이 종류의 엔티티는 PlayFab의 플레이어를 의미합니다. 플레이어를 만들기 위해서는 [Quickstart](/services/playfab/community/leaderboards/quickstart-leaderboards)에 설명된 `LoginAsPlayer` 메서드를 사용할 수 있습니다. * `group`: 이 종류의 엔티티는 플레이어 그룹을 의미하며, 일반적으로 “클랜”, “길드” 같은 게임에서 사용되는 개념입니다. 자세한 정보는 [Group Leaderboards](/services/playfab/community/leaderboards/group-leaderboards)에서 확인하세요. * `external`: 이 종류의 엔티티는 리더보드에 사용자 지정 데이터를 추가하는 데 사용됩니다. 각 행이 PlayFab의 무언가에 연결될 필요가 없으며, 여러분 자체의 데이터입니다. `EntityId` 필드에 자신만의 식별자를 사용할 수 있으며, 문자열이기만 하면 됩니다. * `master_player_account`: 이 종류의 엔티티는 여러 타이틀에 걸친 플레이어를 의미합니다. 이 개념은 스튜디오가 여러 타이틀을 보유하고 있고, 한 타이틀에서 다른 타이틀로 이동했거나 동일 스튜디오의 여러 타이틀을 플레이하는 플레이어가 있을 때 적용됩니다. 이 개념을 바탕으로 동일 스튜디오의 여러 타이틀에 걸친 플레이어의 리더보드를 만들 수 있습니다. 마스터 플레이어 계정 ID(PlayFabId로도 불림)를 `EntityId`에 매핑하여 사용해야 합니다. * `character`: 이 종류의 엔티티는 플레이어가 여러 캐릭터 중 선택하여 여정을 시작하는 게임과 관련이 있습니다. 이 개념에 따라 캐릭터의 리더보드를 만들려면 먼저 플레이어를 만든 다음, 해당 플레이어와 연결된 캐릭터를 만들 수 있습니다. 그 이후에는 `CharacterId`를 엔티티 ID로 사용하고 해당 점수를 가진 행을 삽입할 수 있습니다. * `VersionConfiguration`: 이 매개 변수는 특정 기간 후에 자동으로 재설정되는 리더보드의 버전 관리 전략을 설정할 수 있게 해줍니다. 이 개념은 [Seasonal Leaderboards](/services/playfab/community/leaderboards/seasonal-leaderboards)에서 자세히 다룹니다. * `Columns`: 여기서는 리더보드에 포함될 열의 수를 정의합니다. 이 예시에서는 점수를 위한 열 하나만 설정합니다. 또한 `SortDirection`을 내림차순(descending)으로 정의하여 점수가 가장 높은 플레이어가 상단에 오도록 합니다. 정의당 허용되는 최대 열 수는 5개입니다. 이 모든 정보를 통해 이제 예시를 실행하여 첫 번째 리더보드를 만들 준비가 되었습니다. ### 리더보드 정의 가져오기 이 리더보드에 데이터를 추가하기 전에, 올바르게 생성되었는지 확인하고 싶을 것입니다. 이를 위해 리더보드 정의를 검색하는 예시를 제공합니다. ```C# theme={null} public static async Task GetLeaderboardDefinition(PlayFabAuthenticationContext context, string leaderboardName) { PlayFabProgressionInstanceAPI leaderboardsAPI = new PlayFabProgressionInstanceAPI(context); GetLeaderboardDefinitionRequest leaderboardDefReq = new GetLeaderboardDefinitionRequest() { Name = leaderboardName }; PlayFabResult getleaderboardDefResult = await leaderboardsAPI.GetLeaderboardDefinitionAsync(leaderboardDefReq); } ``` 리더보드 정의를 검색하려면 만든 리더보드의 이름을 지정합니다. 여러 개의 리더보드 정의가 있는 경우 다음 예시로 여러 개를 함께 가져올 수 있습니다. ```C# theme={null} public static async Task ListLeaderboards(PlayFabAuthenticationContext context) { PlayFabProgressionInstanceAPI leaderboardsAPI = new PlayFabProgressionInstanceAPI(context); ListLeaderboardDefinitionsRequest listLbRequest = new ListLeaderboardDefinitionsRequest() { AuthenticationContext = context, }; PlayFabResult lbResponse = await leaderboardsAPI.ListLeaderboardDefinitionsAsync(listLbRequest); } ``` ### 리더보드 정의 업데이트 리더보드 정의를 업데이트하려면 다음과 같이 하면 됩니다. ```C# theme={null} 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 updateLbDefinitionResult = await leaderboardsAPI.UpdateLeaderboardDefinitionAsync(updateLbDefinitionRequest); } ``` 업데이트의 일부로 Columns, EntityType 및 `ResetInterval`은 수정할 수 없습니다. ### 리더보드 정의 삭제 리더보드 정의를 삭제하려면 다음과 같이 하면 됩니다. ```C# theme={null} public static async Task DeleteLeaderboard(PlayFabAuthenticationContext context, string leaderboardName) { PlayFabProgressionInstanceAPI leaderboardsAPI = new PlayFabProgressionInstanceAPI(context); DeleteLeaderboardDefinitionRequest deleteLbRequest = new DeleteLeaderboardDefinitionRequest() { AuthenticationContext = context, Name = leaderboardName, }; PlayFabResult lbResponse = await leaderboardsAPI.DeleteLeaderboardDefinitionAsync(deleteLbRequest); } ``` ## 리더보드에 데이터 추가하기 아케이드 게임 예시를 계속 이어가면서, 이제 리더보드 정의를 만들고, 검색하고, 필요하면 삭제하는 방법을 알게 되었습니다. 다음 단계는 리더보드에 데이터를 추가하기 시작하는 것입니다. 이 리더보드는 엔티티 기반이므로 항목은 엔티티라는 점을 유의하세요. 또한 외부 자체 ID를 가져오는 방식도 지원하며, 이는 [Doing More With Leaderboards](/services/playfab/community/leaderboards/doing-more-with-leaderboards)에서 자세히 다룹니다. 이 예시에서는 엔티티 유형으로 title\_player\_account를 사용하고 있으므로 리더보드는 플레이어로 채워집니다. 그러나 다른 엔티티 유형도 사용할 수 있다는 점을 기억하세요. 자세한 내용은 [사용 가능한 기본 제공 엔티티 유형](/services/playfab/live-service-management/game-configuration/entities/available-built-in-entity-types)에서 확인할 수 있습니다. 이제 리더보드에 데이터를 어떻게 추가할 수 있는지 살펴보겠습니다. ```C# theme={null} 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() { new LeaderboardEntryUpdate() { EntityId = entityId, Scores = new List { score.ToString()} } }, AuthenticationContext = context, LeaderboardName = leaderboardName, }; PlayFabResult updateResult = await leaderboardsAPI.UpdateLeaderboardEntriesAsync(updateLeaderboardRequest); } ``` 이 예시의 주요 요소를 설명하면 다음과 같습니다. * `Entries`: 이 매개 변수는 리더보드에 추가되는 실제 행에 해당합니다. `EntityId`가 포함되어 있으며, 이는 리더보드 내에서 엔티티를 식별하는 문자열입니다. 이 서비스는 독립 실행형 구성 요소이므로 여기에 여러분 자체의 식별자를 사용할 수 있습니다. 다만 다른 PlayFab 서비스를 사용하고 있다면 이 값은 모든 서비스에서 일관되어야 합니다. * `Scores`: 이 매개 변수는 하나의 엔티티에 추가할 수 있는 점수 목록에 해당합니다. 리더보드는 여러 열을 가질 수 있다는 점을 기억하세요. 자세한 내용은 [Doing More With Leaderboards](/services/playfab/community/leaderboards/doing-more-with-leaderboards)에서 확인할 수 있습니다. * `Name`: 이 매개 변수는 리더보드 정의를 만들 때 설정한 리더보드 이름에 해당합니다. 이제 리더보드에 데이터를 추가할 준비가 되었습니다. ## 리더보드에서 데이터 검색 간단히 정리해 봅시다. 이 시점에서 여러분은 리더보드를 만들고, 모든 구성 세부 정보를 확인하고, 엔티티를 추가하기 시작했습니다. 이제 일부 플레이어가 이미 게임을 시작했으며 모두 인상적인 점수를 얻었다고 가정해 봅시다. 최고의 플레이어가 누구인지 알아내고 싶습니다. 다음 예시에서는 이 작업을 수행하는 방법을 보여줍니다. ```C# theme={null} public static async Task> GetLeaderboard(PlayFabAuthenticationContext context, string leaderboardName) { PlayFabProgressionInstanceAPI leaderboardsAPI = new PlayFabProgressionInstanceAPI(context); GetEntityLeaderboardRequest getLbRequest = new GetEntityLeaderboardRequest() { LeaderboardName = leaderboardName, StartingPosition = 1, PageSize = 20, AuthenticationContext = context, }; PlayFabResult lbResponse = await leaderboardsAPI.GetLeaderboardAsync(getLbRequest); return lbResponse.Result.Rankings; } ``` 이 예시의 주요 요소를 설명하면 다음과 같습니다. * `StartingPosition`: 이 매개 변수는 데이터 쿼리를 시작할 위치를 의미합니다. 여기서는 상위 플레이어를 원하므로 이 매개 변수를 1로 설정합니다. 이 매개 변수는 `PageSize` 매개 변수와 함께 작동하여 필요한 만큼 리더보드 전체를 쿼리할 수 있게 해줍니다. * `PageSize`: 이 매개 변수는 해당 요청에서 몇 개의 레코드가 가져와지는지를 지정합니다. * `Name`: 이 매개 변수는 리더보드 정의를 만들 때 설정한 리더보드 이름에 해당합니다. ### 동점 처리 이제 게임을 사용하는 일부 플레이어들이 누가 최고인지 겨루고 있다고 상상해 봅시다. 문제가 생겼습니다. 두 플레이어가 같은 수의 적을 물리쳤기 때문에 같은 점수를 갖고 있습니다. 그렇다면 누가 상위 플레이어가 되어야 할까요? 이 질문에 답하기 위해 기본적으로 간단한 동점 처리 정책이 있습니다. 점수가 달성된 타임스탬프를 기준으로 최고의 플레이어를 결정합니다. 먼저 달성한 사람이 상위 플레이어가 됩니다. 그러나 게임의 맥락에 따라 이것으로 충분하지 않거나 정확하지 않을 수 있습니다. 더 복잡한 동점 처리 기능에 대해서는 [Doing More With Leaderboards](/services/playfab/community/leaderboards/doing-more-with-leaderboards)를 참조하세요. 지금 예시의 순위는 다음과 같이 됩니다. | 순위 | Entity Id | 점수 | 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”이 먼저 점수를 달성했으므로 상위에 위치합니다. ## 리더보드 행 삭제 리더보드가 예상대로 작동하고 있고 게임에 많은 플레이어가 있습니다. 그러나 몇몇 플레이어가 리더보드 상위에 오르기 위해 부정 행위를 하는 등 이상한 행동이 눈에 띄기 시작합니다. 이러한 행동을 용납하지 않을 것이므로, 리더보드에서 이들을 제거하고 싶을 것입니다. 다음 예시에서는 리더보드에서 행을 삭제하는 방법을 확인할 수 있습니다. ```C# theme={null} public static async Task DeleteLeaderboardEntries(PlayFabAuthenticationContext context, string leaderboardName, List entityIds) { PlayFabProgressionInstanceAPI leaderboardsAPI = new PlayFabProgressionInstanceAPI(context); DeleteLeaderboardEntriesRequest leaderboardsDelReq = new DeleteLeaderboardEntriesRequest() { Name = leaderboardName, EntityIds = entityIds }; PlayFabResult delLeaderboardDefResult = await leaderboardsAPI.DeleteLeaderboardEntriesAsync(leaderboardsDelReq); } ``` 이 예시의 주요 요소를 설명하면 다음과 같습니다. * `EntityIds`: 이 매개 변수는 삭제하려는 엔티티 ID의 목록입니다. * `Name`: 이 매개 변수는 리더보드 정의를 만들 때 설정한 리더보드 이름에 해당합니다. ## 결론 이 튜토리얼에서 우리는 다음 작업을 수행하는 방법을 배웠습니다. * 리더보드 만들기. * 리더보드 구성 확인. * 리더보드 구성 업데이트. * 리더보드 구성 삭제. * 리더보드 채우기. * 동점 처리 방식 이해. * 리더보드의 항목 삭제. ## 함께 보기 * [리더보드 더 활용하기](/services/playfab/community/leaderboards/doing-more-with-leaderboards). * [제한 사항](/services/playfab/community/leaderboards/limits-leaderboards). * [할당량](/services/playfab/community/leaderboards/quota-leaderboards). * [시즌 리더보드](/services/playfab/community/leaderboards/seasonal-leaderboards). * [통계로 플레이어 순위 매기기](/services/playfab/community/leaderboards/leaderboards-linked-to-stats). * [리더보드에 상황 데이터 추가](/services/playfab/community/leaderboards/metadata-leaderboards). * [그룹 리더보드](/services/playfab/community/leaderboards/group-leaderboards). * [수동 계층](/services/playfab/community/leaderboards/manual-tiers). * [API 참조](/services/playfab/community/leaderboards/api-reference). * [리더보드와 CloudScript](/services/playfab/community/leaderboards/leaderboards-cloudscript). * [PlayStream과 함께 사용하는 리더보드](/services/playfab/community/leaderboards/leaderboards-with-playstream-and-telemetry) ## Related topics - [PlayFab 리더보드 개요](/ko/services/playfab/community/leaderboards/index.md) - [PFLeaderboardsCreateLeaderboardDefinitionRequest](/ko/services/playfab/api-references/c/pfleaderboardstypes/structs/pfleaderboardscreateleaderboarddefinitionrequest.md) - [PFLeaderboardsCreateLeaderboardDefinitionAsync](/ko/services/playfab/api-references/c/pfleaderboards/functions/pfleaderboardscreateleaderboarddefinitionasync.md) - [XStoreCreateContext](/ko/reference/system/xstore/functions/xstorecreatecontext.md) - [Quickstart on leaderboards](/ko/services/playfab/community/leaderboards/quickstart-leaderboards.md)