> ## 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.

# Group Leaderboards

> Rank guilds, clans, and alliances by creating PlayFab leaderboards that use the group entity type to compare team scores alongside player leaderboards.

이 튜토리얼에서는 리더보드에서 그룹 엔티티를 사용하는 방법을 배웁니다. 이 개념을 이해하기 위해 행성 테라포밍에 초점을 맞춘 “RPG” 게임 예시로 시작하겠습니다. 플레이어는 각 행성에 구조물을 건설하고 발전시키며, 자원을 모으고, 자신의 우주선을 만들고, 다른 플레이어가 물건을 훔치기 위해 공격할 수 있으므로 방어 수단도 마련해야 합니다. 이 게임의 한 가지 핵심 요소는 플레이어들이 팀을 이루어 다른 플레이어들을 그룹으로 공격하기 위해 얼라이언스를 시작할 수 있다는 것입니다.

이 컨텍스트를 바탕으로 얼라이언스에 대한 리더보드를 만들어, 전 우주에서 어느 얼라이언스가 가장 강한지 알 수 있도록 하려고 합니다.

그룹 리더보드 작동 방식을 더 자세히 알아보기 전에 유의해야 할 주요 사항이 있습니다.

* 엔티티 프로그래밍 모델에 대한 자세한 내용은 [엔티티 프로그래밍 모델](/services/playfab/live-service-management/game-configuration/entities)을 참조하세요.
* 그룹 작동 방식은 [Groups](/services/playfab/community/associations/groups/quickstart)에서 확인하세요.

## 리더보드 만들기

게임과 시나리오의 유형에 따라 여러 리더보드를 만들게 될 가능성이 높습니다. 이 컨텍스트에서는 이 게임의 두 가지 시나리오와 각각을 처리하기 위해 서비스를 어떻게 사용하는지 보여주려 합니다.

### 플레이어 리더보드

이 예시에는 행성을 테라포밍하고 게임 내 특정 행동을 통해 경험치를 얻는 플레이어들이 있습니다. 그래서 플레이어 수준에서 그 경험치를 추적하는 리더보드를 만들 것입니다. 이 프로세스는 [기본 리더보드 만들기](/services/playfab/community/leaderboards/create-basic-leaderboard) 같은 다른 튜토리얼에서 소개된 것과 동일한 동작을 따릅니다. 여기서 중요한 점은 EntityType 매개 변수가 `"title_player_account"`여야 플레이어 전용이 된다는 것입니다.

```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<LeaderboardColumn>()
        {
            new LeaderboardColumn()
            {
                Name = "XP",
                SortDirection = LeaderboardSortDirection.Descending,
            }        
        }
    };

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

### 그룹 리더보드

이제 예시에서 언급된 게임의 요소인 얼라이언스로 넘어갑시다. PlayFab에서 `"group"` 엔티티를 사용하여 얼라이언스를 만들 수 있습니다. 이 그룹 엔티티는 플레이어가 가입할 수 있는 구조를 제공하며, 역할과 이런 종류의 게임 시나리오를 강화하는 다른 흥미로운 기능도 갖추고 있습니다. 리더보드를 만들 때 두 가지를 명확히 해야 합니다.

* EntityType 매개 변수는 `"group"`이어야 합니다.
* 이 리더보드는 독립적입니다. 따라서 얼라이언스의 점수를 추가하는 작업은 플레이어 리더보드와 분리된 수동 프로세스입니다. 이 동작 덕분에 점수가 플레이어와 어떻게 연결되는지 다양한 방식이 가능하거나, 그룹에만 적용되는 새로운 지표를 사용할 수도 있습니다.

```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 = "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);
}
```

## 리더보드에 데이터 추가하기

두 리더보드를 만든 후에는 각각에 데이터를 어떻게 추가할지 확인해야 합니다. 앞서 이전 예시에서 언급했듯이 이 리더보드들은 서로 독립적이므로, 개발자가 얼라이언스(그룹)의 점수가 어떻게 작동하는지에 대한 사용자 지정 로직을 적용할 수 있습니다.

```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<LeaderboardEntryUpdate>()
        {
            new LeaderboardEntryUpdate()
            {
                EntityId = entityId,
                Scores = new List<string> { score.ToString()}                
            }
        },
        AuthenticationContext = context,
        LeaderboardName = leaderboardName,
    };

    PlayFabResult<PlayFab.LeaderboardsModels.EmptyResponse> updateResult = await leaderboardsAPI.UpdateLeaderboardEntriesAsync(updateLeaderboardRequest);
}
```

이 시나리오에서 플레이어 리더보드나 그룹 리더보드에 항목을 추가하는 코드는 동일합니다. 그러나 이 동작이 항상 그런 것은 아닌데, 예를 들어 플레이어용으로는 다섯 개의 열을 가진 리더보드를 만들고, 그룹용으로는 하나의 열만 가진 리더보드를 만들 수도 있기 때문입니다. 다중 열 리더보드에 대해서는 이 튜토리얼에서 더 자세히 다룹니다: [리더보드 더 활용하기](/services/playfab/community/leaderboards/doing-more-with-leaderboards).

항상 유의해야 할 점은 서비스에 올바른 `EntityId`를 제공해야 한다는 것입니다. 플레이어 리더보드가 있다면 엔티티는 `"title_player_account"`이며, 리더보드가 그룹으로 구성되어 있다면 `"group"`인 엔티티를 제공해야 합니다.

## 리더보드에서 데이터 검색

리더보드의 데이터를 가져오는 데는 GetFriendLeaderboard API를 제외하고 [리더보드 더 활용하기](/services/playfab/community/leaderboards/doing-more-with-leaderboards)에 설명된 모든 옵션을 사용할 수 있습니다.

## 그룹 리더보드의 표시 이름

마지막으로, 그룹 리더보드에서 할 수 있는 또 다른 세부 작업은 엔티티의 그룹 이름을 표시 이름으로 설정하는 것입니다. “Raiders”라는 얼라이언스가 있다면 이 그룹 이름은 `DisplayName` 속성을 통해 엔티티에 매핑됩니다.

```C# theme={null}
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;
}
```

이 예시에서는 `CreateGroupAsync` 메서드를 호출하여 그룹을 만듭니다. 이 실행의 첫 단계에서 Group 개체가 반환되며, 이를 표시 이름 설정에 사용합니다. `SetDisplayNameRequest` 개체로 그룹 이름을 엔티티에 매핑한 다음 `PlayFabProfilesAPI.SetDisplayNameAsync` 메서드를 실행하여 이 프로세스를 수행합니다.

## 결론

이 튜토리얼에서 우리는 다음 작업을 수행하는 방법을 배웠습니다.

* 그룹 리더보드 만들기.
* 해당 리더보드에 데이터를 공급하는 방법 학습.
* 리더보드 검색.
* 그룹 이름을 표시할 수 있도록 displayName 변경.

## 함께 보기

* [리더보드 더 활용하기](/services/playfab/community/leaderboards/doing-more-with-leaderboards).
* [기본 리더보드 만들기](/services/playfab/community/leaderboards/create-basic-leaderboard)
* [수동 계층](/services/playfab/community/leaderboards/manual-tiers).
* [제한 사항](/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)
* [API 참조](/services/playfab/community/leaderboards/api-reference)
* [리더보드와 CloudScript](/services/playfab/community/leaderboards/leaderboards-cloudscript).
* [PlayStream과 함께 사용하는 리더보드](/services/playfab/community/leaderboards/leaderboards-with-playstream-and-telemetry)