시작하기
주의: DSA(디지털서비스법)는 유니티가 DSA에 따라 고객의 최종 사용자에게 영향을 미치는 조치를 취할 경우 최종 사용자에게 알릴 것을 요구합니다. 이 요구 사항을 준수하기 위해, Unity Authentication 서비스를 이용하는 UGS(Unity Gaming Services) 제품을 사용할 경우, 알림 API를 연동해야 합니다.
DSA에 대한 자세한 내용은 디지털서비스법 - 규정 준수 업데이트를 참조하십시오.
게임이 DSA를 준수하도록 하려면 DSA 알림을 참조하십시오.
이 가이드에서는 Matchmaker SDK를 설치하고, Matchmaker를 활성화하고, 첫 매치메이킹 티켓을 만든 다음 Multiplay Hosting 할당을 생성하는 데 필요한 여러 단계를 살펴봅니다.
필수 조건
Multiplay를 시작하려면 다음을 수행해야 합니다.
호스팅 구성
먼저 Multiplay Hosting 또는 Unity에서 제공하는 클라이언트 호스팅 솔루션을 초기화한 다음 Matchmaker를 활성화해야 합니다. Multiplay Hosting 시작하기, Relay 시작하기, 배포 권한 빠른 시작을 참조하십시오.
Matchmaker SDK 설치
다음 단계를 따라 Unity용 최신 Matchmaker 패키지를 설치합니다.
- Unity 에디터에서 Window > Package Manager로 이동합니다.
- Package Manager에서 다음 패키지를 검색합니다.
- Unity 6 이상:
com.unity.services.multiplayer - Unity 2022 LTS 이하:
com.unity.services.matchmaker
- Unity 6 이상:
- 패키지를 선택한 후 Install을 선택합니다.
자세한 내용은 패키지 관리자 기술 자료를 참조하십시오.
Matchmaker 설정
Unity Cloud Dashboard를 통해 Matchmaker를 설정하고 관리할 수 있습니다.
- cloud.unity.com으로 이동합니다.
- 사이드바에서 Products 탭을 선택합니다.
- Gaming Services > Multiplayer에서 Matchmaker로 이동한 다음 Launch를 선택합니다.
Matchmaker를 처음 실행하면, 사이드바의 Shortcuts 섹션에 Matchmaker가 추가되고 Overview 페이지가 열립니다.
대기열과 풀 생성
- Create a Queue를 선택합니다. 첫 번째 대기열의 이름을 입력하고 매치메이킹 티켓의 최대 플레이어 수를 설정합니다. Create를 클릭합니다.
- Create a Pool을 선택합니다. 풀의 이름을 입력합니다. 이전 단계에서 생성한 대기열을 선택합니다. 티켓의 타임아웃 값을 설정합니다. Next를 클릭합니다.
- 호스팅 유형을 선택합니다.
- Multiplay Hosting을 사용하는 경우 먼저 드롭다운 메뉴에서 Multiplay Hosting을 선택한 다음 Multiplay Hosting이 구성될 때 생성된 Fleet과 Build Configuration을 선택합니다.
- Unity에서 제공하는 클라이언트 호스팅 솔루션을 사용하는 경우 드롭다운 메뉴에서 Client Hosting을 선택합니다.
- Next를 클릭합니다.
해당 대기열과 풀에 티켓을 전달할 때 생성되는 매치를 정의하는 데 사용되는 규칙을 정의합니다. JSON을 선택하고 다음 코드 블록을 복사해 붙여 넣습니다.
{
"Name": "Test",
"MatchDefinition": {
"Teams": [
{
"Name": "Main team",
"TeamCount": {
"Min": 1,
"Max": 1
},
"PlayerCount": {
"Min": 1,
"Max": 5
}
}
],
"MatchRules": []
},
"BackfillEnabled": false
}위 코드는 최소 플레이어 수가 1명이고 최대 플레이어 수가 5명인 팀 1개로 구성된 매치를 생성합니다.
- Logic Builder를 클릭하고 드롭다운에서 지역을 선택해 Default QoS Region을 설정합니다.
- 페이지 하단의 Create를 클릭합니다.
Matchmaker 설정이 완료되었습니다. 생성된 대기열과 풀은 Matchmaker 섹션 아래의 메뉴에서 Queues를 클릭하여 확인할 수 있습니다.
매치메이킹 티켓 생성
Matchmaker를 설정했으니 이제 티켓을 생성하고 전달해 Multiplay Hosting 할당을 요청할 수 있습니다.
Unity SDK
var players = new List<Unity.Services.Matchmaker.Models.Player>
{
new ("Player1", new Dictionary<string, object>())
};
// Set options for matchmaking
var options = new CreateTicketOptions(
"Default", // The name of the queue defined in the previous step,
new Dictionary<string, object>());
// Create ticket
var ticketResponse = await MatchmakerService.Instance.CreateTicketAsync(players, options);
// Print the created ticket id
Debug.Log(ticketResponse.Id);CURL
# Fetch anonymous token
curl -X POST -H "ProjectId: <projectId>" https://player-auth.services.api.unity.com/v1/authentication/anonymous
# Call the create ticket endpoint
curl -X POST -H "Authorization: Bearer <TOKEN>" \
-H 'Content-Type: application/json' \
--data-raw '{
"queueName": "Default",
"attributes": {},
"players": [{
"id": "Player 1",
"customData": {}
}]
}' \
'https://matchmaker.services.api.unity.com/v2/tickets'REST API
https://services.docs.unity.com/matchmaker/v2/index.html#tag/Tickets/operation/createTicket
티켓 상태 폴링
티켓이 생성되면 클라이언트는 티켓을 생성했을 때 반환된 티켓 ID를 사용해 티켓 상태를 폴링합니다.
티켓이 매치에 할당되고 서버가 할당되면 Matchmaker가 티켓 상태 응답에 서버 정보를 추가합니다.
Unity SDK
MultiplayAssignment assignment = null;
bool gotAssignment = false;
do
{
//Rate limit delay
await Task.Delay(TimeSpan.FromSeconds(1f));
// Poll ticket
var ticketStatus = await MatchmakerService.Instance.GetTicketAsync("<ticket id here>");
if (ticketStatus == null)
{
continue;
}
//Convert to platform assignment data (IOneOf conversion)
if (ticketStatus.Type == typeof(MultiplayAssignment))
{
assignment = ticketStatus.Value as MultiplayAssignment;
}
switch (assignment?.Status)
{
case MultiplayAssignment.StatusOptions.Found:
gotAssignment = true;
break;
case MultiplayAssignment.StatusOptions.InProgress:
//...
break;
case MultiplayAssignment.StatusOptions.Failed:
gotAssignment = true;
Debug.LogError("Failed to get ticket status. Error: " + assignment.Message);
break;
case MultiplayAssignment.StatusOptions.Timeout:
gotAssignment = true;
Debug.LogError("Failed to get ticket status. Ticket timed out.");
break;
default:
throw new InvalidOperationException();
}
} while (!gotAssignment);CURL
# Call the poll ticket status endpoint with same anonymous token as for the creation
curl -X GET -H "Authorization: Bearer <TOKEN>" \
--header 'Content-Type: application/json' \
'https://matchmaker.services.api.unity.com/v2/tickets/status?id=<TICKETID>'REST API
https://services.docs.unity.com/matchmaker/v2/index.html#tag/Tickets/operation/getTicketStatus
매치메이킹 결과
서버가 할당되면 페이로드 할당을 사용해 성사된 매치의 매치메이킹 결과를 서버 측에서 가져올 수 있습니다.
매치메이킹 결과는 매치에 참여할 것으로 예상되는 플레이어들의 정보, 해당 플레이어 데이터, 팀 간의 플레이어 분포에 대한 정보를 서버에 제공합니다.
이 코드는 Multiplay Hosting을 통해 할당된 서버에서만 작동합니다.
Unity SDK
var payloadAllocation = await MultiplayService.Instance.GetPayloadAllocationFromJsonAs<MatchmakingResults>();Note: server.json 파일을 사용해 서버의 할당 UUID를 가져오십시오.
매치메이킹 결과에 액세스하려면 Multiplay Hosting SDK를 설치해야 합니다.
CURL
curl -X GET http://localhost:8086/payload/<allocation_uuid>