다음을 통해 공유

기본 순위표 만들기

  • 아티클

이 자습서에서는 새 순위표 서비스를 사용하여 기본 순위표를 만드는 방법을 보여 드립니다. 아케이드 게임의 예로 시작해 보겠습니다. 여기서 목표는 패배할 때까지 가능한 한 많은 적을 물리치는 것입니다. 이 경우 점수가 할당됩니다. 이제 이 게임이 최고의 플레이어가 누구인지 결정하는 데 도움이 되는 순위표를 만들고자 합니다.

순위표 만들기

첫 번째 단계는 순위 플레이어에 대한 기본 요소를 포함하는 순위표 정의를 만드는 것입니다. 아케이드 게임의 경우 점수에 하나의 열만 필요합니다. 다음 예제에서는 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: 이 유형의 엔터티는 플레이어가 자신의 여정을 선택하고 시작할 수 있는 일련의 문자를 포함하는 게임과 관련이 있습니다. 이 개념을 염두에 두고, 캐릭터의 순위표를 만들려면 먼저 플레이어를 만든 다음 해당 플레이어와 연결된 문자를 만들 수 있습니다. 그런 다음 를 엔터티 ID로 사용하고 CharacterId 해당 점수가 있는 행을 삽입할 수 있습니다.
  • 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);
}

순위표에 데이터 추가

아케이드 게임 예제를 계속 진행하면서 이제 순위표 정의를 만들고, 검색하고, 필요한 경우 삭제하는 방법을 알아보세요. 다음 단계는 순위표에 데이터 추가를 시작하는 것입니다.

이러한 항목은 엔터티 기반 순위표이며, 이는 항목이 엔터티임을 의미합니다. 또한 순위표로 더 많은 작업을 수행하는 데 자세히 설명된 사용자 고유의 외부 ID 가져오기를 지원합니다.

특정 예제에서는 엔터티 형식 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: 이 매개 변수는 순위표 정의를 만들 때 설정된 순위표 이름에 해당합니다.

타이 브레이킹

이제 게임을 사용하는 일부 플레이어가 누가 최고인지 확인하기 위해 싸우고 있다고 상상해 보겠습니다. 우리는 문제에 직면 : 그들은 적의 동일한 수를 물리 치기 때문에 두 선수는 같은 점수를 가지고있다. 그렇다면 누가 최고의 선수가 되어야 할까요?

이 질문에 대답하기 위해 기본적으로 간단한 타이 브레이커 정책이 있습니다. 점수가 달성되었을 때 타임스탬프를 기준으로 최고의 플레이어를 선택합니다. 누구든지 먼저 그것을 달성 최고의 선수입니다. 그러나 게임의 컨텍스트에 따라 충분하지 않거나 정확하지 않을 수 있습니다. 더 복잡한 연결 끊기 기능은 순위표로 더 많은 작업을 참조하세요.

현재 예제에서 순위는 다음과 같습니다.

Rank 엔터티 ID Score 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: 이 매개 변수는 순위표 정의를 만들 때 설정된 순위표 이름에 해당합니다.

결론

이 자습서에서는 다음 작업을 수행하는 방법을 알아보았습니다.

  • 순위표를 만듭니다.
  • 순위표의 구성을 확인합니다.
  • 순위표 구성을 삭제합니다.
  • 순위표를 채웁 수 있습니다.
  • 타이 브레이킹 작동 방식을 이해합니다.
  • 순위표에서 항목을 삭제합니다.

참고 항목