기술 자료

지원

Matchmaker for the Unreal Engine

Matchmaker overview

Matchmaker for the Unreal Engine

블루프린트를 사용하여 연동

Use the Matchmaker Blueprint API to add matchmaking functionality to your Unreal Engine game without writing code.
읽는 시간 2분최근 업데이트: 10일 전
다음 섹션에서는 Unreal Engine의 블루프린트를 사용하여 Matchmaker SDK와 연동하는 방법을 설명합니다. Unity Gaming Services SDK 내에서 상호 작용할 수 있는 두 가지 Matchmaker 인터페이스는 다음과 같습니다.

Matchmaker SDK 플러그인 설치

계속하기 전에 아래와 같이 모듈의 공개 종속성으로 
MatchmakerSDK
를 추가한 다음, include 문으로 클래스에 플러그인 헤더 파일을 가져옵니다. Unreal 프로젝트 빌드 파일(
YourProjectName.Build.cs
)의 모듈 종속성에 
MatchmakerServer
와 
MatchmakerClient
를 추가합니다. 
PublicDependencyModuleNames.AddRange(new string[] { "Core", "CoreUObject", "Engine", "InputCore" });PublicDependencyModuleNames.AddRange(new string[] { "MatchmakerClient", "MatchmakerServer" });PublicDependencyModuleNames.AddRange(new string[] { "Json", "JsonUtilities" });

Matchmaker 클라이언트 블루프린트 API

Matchmaker 클라이언트 시스템의 보조 시스템은 매치메이킹과 매치 찾기의 클라이언트 부분을 제어합니다. 여기에는 매치메이킹 티켓 생성, 삭제, 폴링이 포함됩니다. 
UMatchmakerClientBlueprintApi
의 정적 함수를 사용하여 다음 블루프린트를 통해 Matchmaker 클라이언트 시스템의 보조 시스템과 상호 작용합니다.

CreateTicket

CreateTicket
을 사용하려면 블루프린트에 티켓 생성 노드를 배치합니다. 티켓을 생성하려면 Players와 Options 입력 필드를 채웁니다. 다음 예제는 단일 플레이어와 대기열 이름을 전달하여 티켓을 생성하는 방법을 보여 줍니다. 또한 
TicketId
에 대한 응답을 처리하여 
FString
출력 값을 얻는 이벤트도 보여 줍니다.
플레이어 설정
CreateTicketOptions 설정
티켓 생성 호출
응답 핸들러에 대한 커스텀 이벤트를 설정하고 이벤트의 
Response
구조체 핀을 오른쪽 클릭한 다음 
Split Struct Pin
을 선택하여 
CreateTicketResponse
의 모든 개별 값에 액세스할 수 있습니다.

DeleteTicket

DeleteTicket
블루프린트를 사용하여 티켓을 삭제하는 호출을 수행하고, 삭제할 TicketId를 전달합니다. 다음은 Delete Ticket 사용 방법과 응답 처리 방법을 보여 주는 간단한 예제입니다.
매치메이킹 티켓 삭제
응답 핸들러에 대한 커스텀 이벤트를 설정하고 이벤트의 
Response
구조체 핀을 오른쪽 클릭한 다음 
Split Struct Pin
을 선택하여 
DeleteTicketResponse
의 모든 개별 값에 액세스할 수 있습니다.

GetTicketStatus

CreateTicket 블루프린트에서 가져온 
TicketId
를 사용하여 메치메이커에 매치를 폴링하려면 
GetTicketStatus
를 사용하십시오. 폴링이 완료되었거나 실패한 이후 또는 사용자가 매치메이킹을 수동으로 취소하는 경우, 
DeleteTicket
블루프린트를 사용하여 플레이어를 매치메이킹에서 제외할 수 있습니다.
매치메이킹 티켓 폴링
응답 핸들러에 대한 커스텀 이벤트를 설정하고 이벤트의 
Response
구조체 핀을 오른쪽 클릭한 다음 
Split Struct Pin
을 선택하여 
GetTicketStatusResponse]
의 모든 개별 값에 액세스할 수 있습니다. 위 이미지는 
Set Timer by Event
노드를 사용하여 매치메이킹 티켓을 폴링하는 예제를 보여 줍니다. 루핑 조건이 true일 때 이 노드는 시간 변수에 설정된 주기로 이벤트를 계속해서 트리거합니다. 이 경우, 시간이 5로 설정되어 있으므로 타이머 핸들러가 취소될 때까지 5초마다 이벤트가 발생합니다. 반환 값은 
Clear and Invalidate Timer by Handle
을 사용하여 타이머를 취소하는 데 사용할 수 있는 타이머 핸들러입니다.
이벤트별 타이머 설정
타이머 핸들은 Set Timer by Event 노드에서 Clear and Invalidate Timer by Handle 노드로 전달됩니다. Clear and Invalidate Timer by Handle을 트리거하려면 조건부 로직을 적용해야 합니다. 매치가 반환되기 전에 
GetTicketStatus
를 연속적으로 호출해야 합니다. 상태가 더 이상 InProgress로 반환되지 않으면, 폴링을 중지하고 티켓을 삭제하는 것이 좋습니다. 다음 이미지는 폴링 응답을 처리하고 Clear and Invalidate Timer를 트리거하는 방법에 대한 기본 예제를 보여 줍니다.
타이머 초기화 및 무효화

Matchmaker 서버 블루프린트 API

Matchmaker 서버 시스템의 보조 시스템은 매치메이킹의 서버 부분을 제어합니다. 여기에는 Backfill 티켓 생성, 승인, 삭제, 업데이트가 포함됩니다. 
UMatchmakerServerBlueprintApi
을 사용하여 다음을 수행할 수 있습니다.

CreateBackfillTicket

플레이어(또는 플레이어들)가 인원이 모두 채워진 매치에서 나간 경우 새 Backfill 티켓을 생성해야 하고, 서버는 빈 슬롯을 채워야 합니다. Create Backfill Ticket 블루프린트를 사용하여 서버의 새 Backfill 티켓을 생성합니다.
MatchProperties 설정
CreatebackfillTicketOptions 설정
CreateBackfillTicket 호출
응답 핸들러에 대한 커스텀 이벤트를 설정하고 이벤트 
Response
구조체 핀을 오른쪽 클릭한 다음 
Split Struct Pin
을 선택하여 
CreateBackfillTicketResponse
의 모든 개별 값에 액세스할 수 있습니다.

ApproveBackfillTicket

새 플레이어가 서버에 참여할 수 있도록 Approve Backfill Ticket 블루프린트를 사용하여 주기적으로 Backfill 티켓을 승인해야 합니다. Backfill 티켓은 1초에 한 번 이하로 승인하는 것이 좋습니다. 20초 동안 승인되지 않은 티켓은 Matchmaker 서비스에서 삭제됩니다.
Backfill 티켓 승인
위 예제에서는 승인 작업이 1초마다 반복됩니다. Backfill 티켓을 삭제한 후에는 Clear and Invalidate Timer by Handle 노드를 사용해야 합니다. 응답 핸들러에 대한 커스텀 이벤트를 설정하고 이벤트 
Response
구조체 핀을 오른쪽 클릭한 다음 
Split Struct Pin
을 선택하여 
ApproveBackfillTicketResponse
의 모든 개별 값에 액세스할 수 있습니다. 응답에서 받은 값을 캐싱하고, 이를 사용하여 
UpdateBackfillTicket
에서 
BackfillTicket
을 빌드하는 것이 좋습니다.

UpdateBackfillTicket

다음 경우마다 Backfill 티켓을 업데이트해야 합니다.
  • 플레이어가 서버를 나갈 때
  • 매치메이킹 외부에서 플레이어가 서버에 참여할 때
여기에는 파티 초대, 직접 연결, 친구 초대 등이 포함될 수 있으나 이에 국한되지는 않습니다. Update Backfill Ticket 블루프린트를 사용하여 서버의 현재 Backfill 티켓을 업데이트합니다.
Backfill 티켓 업데이트
응답 핸들러에 대한 커스텀 이벤트를 설정하고 이벤트 
Response
구조체 핀을 오른쪽 클릭한 다음 
Split Struct Pin
을 선택하여 
UpdateBackfillTicketResponse
의 모든 개별 값에 액세스할 수 있습니다. 이 티켓은 3초에 한 번 이하로 호출해야 하며, 
ApproveBackfillTicket
에서 Backfill 티켓의 변경 사항을 감지한 경우 매치메이킹 주기가 완료되었는지 확인하기 위해 호출해야 합니다. 먼저 
ApproveBackfillTicket
을 호출하고 
ApproveBackfillTicket
에서 반환된 
BackfillTicket
을 사용하여 필요에 따라 수정한 후 
UpdateBackfillTicket
에 전달하는 것이 좋습니다.

DeleteBackfillTicket

매치가 전부 채워진 경우 Backfill 티켓을 삭제할 수 있고, 서버는 더 이상 새 플레이어를 받지 않아야 합니다. 또한 매치가 끝나면 티켓을 삭제해야 합니다. Delete Backfill Ticket 블루프린트를 사용하여 서버에서 Backfill을 중지합니다.
Backfill 티켓 삭제
응답 핸들러에 대한 커스텀 이벤트를 설정하고 이벤트 
Response
구조체 핀을 오른쪽 클릭한 다음 
Split Struct Pin
을 선택하여 
DeleteBackfillTicketResponse
의 모든 개별 값에 액세스할 수 있습니다.

블루프린트 유틸리티 함수

블루프린트의 제한으로 인해 JSON 데이터 유형(예: 
FJsonObject
와 
FJsonValue
)은 기본적으로 호환되지 않으며 직접 조작을 지원하지 않습니다. SDK는 API의 일부로 JSON 데이터를 관리할 수 있도록 다음과 같은 유틸리티 함수를 제공합니다. 
  • MatchmakerServer
    의 일부인 
    MatchmakerServerBlueprintUtil
  • MatchmakerClient
    의 일부인 
    MatchmakerClientBlueprintUtil
MatchmakerClient
또는 
MatchmakerServer
를 추가할 때 
MatchmakerCore
가 종속성으로 포함됩니다.

MatchmakerClient

플레이어 커스텀 데이터
MatchmakerClient
모듈에는 다음을 포함하는 
MatchmakerClientBlueprintUtil
이 들어 있습니다. 
PlayerCustomDataAddStringData(FMatchmakerPlayer& Player, FString Key, FString Value)
이 블루프린트를 사용하면 플레이어의 CustomData 오브젝트에 문자열 데이터 필드를 추가할 수 있습니다. 데이터가 설정되면 true를 반환하고, 그렇지 않으면 false를 반환합니다. 
PlayerCustomDataAddNumberData(FMatchmakerPlayer& Player, FString Key, float Value)
이 블루프린트를 사용하면 플레이어의 CustomData 오브젝트에 숫자 데이터 필드를 추가할 수 있습니다. 데이터가 설정되면 true를 반환하고, 그렇지 않으면 false를 반환합니다. 
PlayerCustomDataRemoveData(FMatchmakerPlayer& Player, FString Key)
이 블루프린트를 사용하면 플레이어의 CustomData 오브젝트에서 데이터 필드를 제거할 수 있습니다. 플레이어의 CustomData에 해당 
Key
가 포함되어 있고 이를 제거한 경우 true를 반환하고, 
Key
가 없으면 false를 반환합니다.
속성
MatchmakerClient
모듈에는 다음을 포함하는 
MatchmakerClientBlueprintUtil
이 들어 있습니다. 
CreateTicketOptionsAddStringAttribute(FCreateTicketOptions& Options, FString Key, FString Value)
이 블루프린트를 사용하면 
CreateTicketOptions
오브젝트에 문자열 기반의 속성을 추가할 수 있습니다. 속성이 설정되면 true를 반환하고, 그렇지 않으면 false를 반환합니다. 
CreateTicketOptionsAddNumberAttribute(FCreateTicketOptions& Options, FString Key, float Value)
이 블루프린트를 사용하면 
CreateTicketOptions
오브젝트에 숫자 기반의 속성을 추가할 수 있습니다. 속성이 설정되면 true를 반환하고, 그렇지 않으면 false를 반환합니다. 
CreateTicketOptionsRemoveAttribute(FCreateTicketOptions& Options, FString Key)
이 블루프린트를 사용하면 
CreateTicketOptions
오브젝트에서 속성을 제거할 수 있습니다. 
CreateTicketOptions
에 속성이 포함되어 있고 이를 제거한 경우 true를 반환하고, 속성이 없으면 false를 반환합니다.

MatchmakerServer

MatchmakerServer
모듈에는 다음 함수를 포함하는 
MatchmakerServerBlueprintUtil
이 들어 있습니다. 
CreateBackfillTicketOptionsAddStringAttribute(FCreateBackfillTicketOptions Options, FString Key, FString Value)
이 블루프린트를 사용하면 
CreateBackfillTicketOptions
오브젝트에 문자열 기반의 속성을 추가할 수 있습니다. 속성이 설정되면 true를 반환하고, 그렇지 않으면 false를 반환합니다. 
CreateBackfillTicketOptionsAddNumberAttribute(FCreateBackfillTicketOptions& Options, FString Key, float Value)
이 블루프린트는 
CreateBackfillTicketOptions
오브젝트에 숫자 기반의 속성을 추가하는 데 사용됩니다. 속성이 설정되면 true를 반환하고, 그렇지 않으면 false를 반환합니다. 
CreateBackfillTicketOptionsRemoveAttribute(FCreateBackfillTicketOptions Options, FString Key)
이 블루프린트를 사용하면 
CreateBackfillTicketOptions
오브젝트에서 속성을 제거할 수 있습니다. 
CreateBackfillTicketOptions
에 속성이 포함되어 있고 이를 제거한 경우 true를 반환하고, 속성이 존재하지 않으면 false를 반환합니다.