백필

백필(backfill)은 이미 시작된 게임에 플레이어가 참여하는 데 활용되는 플로입니다.

백필을 사용하는 이유는 다음과 같습니다.

필요한 플레이어 수가 전부 채워지지 않더라도 빠르게 매치를 시작할 수 있습니다. 이때 Matchmaker 설정의 backfill 프로퍼티가 true로 설정되어 있으면 Matchmaker가 백필을 시작합니다.
플레이어가 나가더라도 매치 내의 플레이어 수를 일정하게 유지할 수 있습니다. 이 경우, 게임 서버는 백필 티켓을 생성할 때 백필을 시작합니다.

설정에서 backfill 프로퍼티가 false로 설정되어 있더라도 Backfill 티켓이 생성되면 Backfill이 작동합니다.

백필 플로

다음 다이어그램은 백필 플로를 보여 줍니다.

백필 플로

서버가 할당되면 할당 페이로드 정보와 매치메이킹 결과를 가져옵니다. 매치메이킹 결과에는 Matchmaker가 생성한 백필 티켓 ID와 백필 티켓을 생성하는 데 필요한 중요한 정보가 담겨 있습니다.
서버는 Multiplay Hosting 토큰을 가져와서 게임 서버를 Matchmaker 서비스에 인증하는 데 사용합니다.
게임 서버는 1초마다 백필 티켓을 승인합니다. 게임 서버가 실행 중이라는 것을 Matchmaker 서비스에 알리기 위해 필요한 작업입니다.
새로 들어온 티켓이 호환되는 경우, Matchmaker 서비스가 기존 백필 티켓에 새 티켓을 추가합니다.
백필 매치에 티켓이 추가되면, 다음에 게임 서버가 백필 티켓을 승인할 때 플레이어 티켓이 서버에 할당됩니다.
매치 인원이 충족되면 게임 서버가 백필 티켓을 삭제합니다.

게임 서버는 Backfill 티켓을 최신 상태로 유지해야 합니다. 예를 들어, Matchmaker 외부에서 플레이어가 서버에 참여하거나 서버를 나가면 게임 서버는 백필 티켓을 업데이트해 Matchmaker 서비스에 이 사항을 통지해야 합니다.

플레이어가 게임을 떠나 백필을 수행해야 하는데 백필 티켓이 없는 경우에는 게임 서버가 새 백필 티켓을 생성합니다.

게임 서버에서 정기적으로 Backfill 티켓을 승인하지 않으면 Matchmaker 서비스가 자동으로 해당 티켓을 삭제합니다. 이렇게 하면 실행 중이지 않은 게임 서버의 백필 티켓이 아무 이유 없이 플레이어 티켓을 보유하는 것을 방지할 수 있습니다.

Matchmaker 서비스나 게임 서버에서 기간이 만료된 Backfill 티켓을 삭제하면 미할당 티켓이 티켓 풀로 다시 들어갑니다.

백필 티켓 생성

다음 코드 샘플은 게임 서버에서 백필 티켓을 생성하는 방법을 보여 줍니다.

Unity SDK

// Set the Match Properties. These properties can also be found in the Allocation Payload (cf Allocation Payload)

var teams = new List<Team>{
                    new Team( "Red", "9c8e302e-9cf3-4ad6-a005-b2604e6851e3", new List<string>{ "c9e6857b-a810-488f-bacc-08d18d253b0a"  } ),
                    new Team( "Blue", "e2d8f4fd-5db8-4153-bca7-72dfc9b2ac09", new List<string>{ "fe1a52cd-535a-4e34-bd24-d6db489eaa19"  } ),
                };

// Define the Players of the match with their data.
var players = new List<Unity.Services.Matchmaker.Models.Player>
{
   new (
       "c9e6857b-a810-488f-bacc-08d18d253b0a",
       new Dictionary<string, object>
       {
           { "Team", "Red" }
       }),
   new (
       "fe1a52cd-535a-4e34-bd24-d6db489eaa19",
       new Dictionary<string, object>
       {
           { "Team", "Blue" }
       })
};

var matchProperties = new MatchProperties(teams, players);


var backfillTicketProperties = new BackfillTicketProperties(matchProperties);

// Set options for matchmaking
var options = new CreateBackfillTicketOptions("queue", "127.0.0.1:8080", new Dictionary<string, object>(), backfillTicketProperties);


// Create backfill ticket
string ticketId = await MatchmakerService.Instance.CreateBackfillTicketAsync
(options);

// Print the created ticket id
Debug.Log(ticketId);

CURL

# Fetch a Multiplay token
curl --location --request POST ‘http://localhost:8086/token

# Transform match properties in a base64 format
matchProperties=$(echo '{
  "matchProperties": {
    "teams": [
      {
        "teamName": "Red Team",
        "teamId": "14f18a3e-921d-4165-90b6-ada353e186ca",
        "playerIDs": [
          "c9e6857b-a810-488f-bacc-08d18d253b0a"
        ]
      },
      {
        "teamName": "Blue Team",
        "teamId": "5aa8ae3b-d5b6-463a-9795-9bc10210dc86",
        "playerIDs": [
          "fe1a52cd-535a-4e34-bd24-d6db489eaa19"
        ]
      }
    ],
    "players": [
      {
        "id": "c9e6857b-a810-488f-bacc-08d18d253b0a",
        "customData": {
          "Team": "Red"
        }
      },
      {
        "id": "fe1a52cd-535a-4e34-bd24-d6db489eaa19",
        "customData": {
          "Team": "Blue"
        }
      }
    ],
    "region": "05083faf-3795-47b8-a0dc-c626089c5ac9",
    "backfillTicketId": "dc156067-d140-4c5e-b7d4-90ec51c8333f"
  }
}' | base64)

# Send create backfill ticket request
curl --location --request POST 'https://matchmaker.services.api.unity.com/v2/backfill' \
--header 'Authorization: Bearer <MULTIPLAY TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "poolId": "e642781a-558f-4c56-a135-c655331cdeee”, # Information retrieved from the allocation payload
  "connection": "127.0.0.1:8081",
  "properties": {
    "data":  "'+$matchProperties+'"
  }
}'

백필 티켓 승인

백필 티켓을 승인할 때, 게임 서버는 Matchmaker에 게임 서버가 아직 실행 중이며 Matchmaker로부터 새로운 티켓을 기다리고 있음을 알립니다. 유니티는 1초마다 백필 티켓을 승인할 것을 권장합니다. 일정 시간이 지나도 백필 티켓 승인을 요청하는 호출이 없으면 Matchmaker 서비스가 자동으로 해당 티켓을 삭제합니다.

다음 코드 샘플은 백필 티켓을 승인하는 방법을 보여 줍니다.

Unity SDK

// Approve a backfill ticket
// The backfill ticket retrieved as a response can then be updated to be used in the Update API
var backfillTicket = await MatchmakerService.Instance.ApproveBackfillTicketAsync("<backfill ticket id here>");

CURL

curl --location --request POST 'https://matchmaker.services.api.unity.com/v2/backfill/{BackfillTicketId}/approvals' \
--header 'Authorization: Bearer <MULTIPLAY TOKEN>' \
--header 'Content-Type: application/json'

백필 티켓 업데이트

Matchmaker 외부에서 새 플레이어가 매치에 참여하거나 기존의 플레이어가 매치에서 나가면 백필 티켓이 업데이트되어야 합니다. 백필 티켓을 업데이트하면 매치 구성이 변경되었음을 게임 서버에서 Matchmaker에 알릴 수 있습니다.

다음 코드 샘플은 기존 백필 티켓을 업데이트하는 방법을 보여 줍니다.

// Retrieve the backfill information from the approve backfill call
var backfillTicket = await MatchmakerService.Instance.ApproveBackfillTicketAsync("1459800b-d463-4197-a903-f00041fdbf6f");

// Add a new player to the backfill ticket

var newPlayer = new Player(
   "6ebbc1f9-1c42-479c-b80d-9b6f6aa281f3",
   new Dictionary<string, object>
   {
       { "Team", "Red" }
   });
backfillTicket.Properties.MatchProperties.Players.Add(newPlayer);
backfillTicket.Properties.MatchProperties.Teams[0].PlayerIds.Add(newPlayer.Id);

// remove a player from the backfill ticket
var playerIdToRemove = "fe1a52cd-535a-4e34-bd24-d6db489eaa19";
var playerToRemove = backfillTicket.Properties.MatchProperties.Players.FirstOrDefault(p => p.Id.Equals(playerIdToRemove));
backfillTicket.Properties.MatchProperties.Players.Remove(playerToRemove);
backfillTicket.Properties.MatchProperties.Teams[0].PlayerIds.Remove(playerIdToRemove);


await MatchmakerService.Instance.UpdateBackfillTicketAsync(backfillTicket.Id, backfillTicket);

CURL

# Fetch a Multiplay token
curl --location --request POST ‘http://localhost:8086/token

# Transform match properties in a base64 format
matchProperties=$(echo '{
  "matchProperties": {
    "teams": [
      {
        "teamName": "Red Team",
        "teamId": "14f18a3e-921d-4165-90b6-ada353e186ca",
        "playerIDs": [
          "6ebbc1f9-1c42-479c-b80d-9b6f6aa281f3",
        ]
      },
      {
        "teamName": "Blue Team",
        "teamId": "5aa8ae3b-d5b6-463a-9795-9bc10210dc86",
        "playerIDs": [
          "fe1a52cd-535a-4e34-bd24-d6db489eaa19"
        ]
      }
    ],
    "players": [
      {
        "id": "6ebbc1f9-1c42-479c-b80d-9b6f6aa281f3",
        "customData": {
          "Team": "Red"
        }
      },
      {
        "id": "fe1a52cd-535a-4e34-bd24-d6db489eaa19",
        "customData": {
          "Team": "Blue"
        }
      }
    ],
    "region": "05083faf-3795-47b8-a0dc-c626089c5ac9",
    "backfillTicketId": "dc156067-d140-4c5e-b7d4-90ec51c8333f"
  }
}' | base64)

# Send update backfill ticket request
curl --location --request PUT 'https://matchmaker.services.api.unity.com/v2/backfill/{BackfillTicketId}' \
--header 'Authorization: Bearer <MULTIPLAY TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "poolId": "e642781a-558f-4c56-a135-c655331cdeee”, # Information retrieved from the allocation payload
  "connection": "127.0.0.1:8081",
  "properties": {
    "data":  "'+$matchProperties+'"
  }
}'

게임 서버에서 Backfill 티켓을 업데이트하면 모든 미할당 티켓이 티켓 풀로 들어갑니다.

백필 티켓 삭제

다음과 같은 경우에 백필 티켓을 삭제해야 합니다.

서버에 새 티켓이 필요하지 않은 경우
서버를 중지하는 경우

다음 코드 샘플은 백필 티켓을 삭제하는 방법을 보여 줍니다.

Unity SDK

await MatchmakerService.Instance.DeleteBackfillTicketAsync
("1459800b-d463-4197-a903-f00041fdbf6f");

CURL

curl --location --request DELETE 'https://matchmaker.services.api.unity.com/v2/backfill/{BackfillTicketId}' \
--header 'Authorization: Bearer <MULTIPLAY TOKEN>' \
--header 'Content-Type: application/json'

백필

백필 플로#

백필 티켓 생성#

백필 티켓 승인#

백필 티켓 업데이트#

백필 티켓 삭제#

백필 플로

백필 티켓 생성

백필 티켓 승인

백필 티켓 업데이트

백필 티켓 삭제