블루프린트를 사용하여 연동
Use the Matchmaker Blueprint API to add matchmaking functionality to your Unreal Engine game without writing code.
읽는 시간 2분최근 업데이트: 7달 전
다음 섹션에서는 Unreal Engine의 블루프린트를 사용하여 Matchmaker SDK와 연동하는 방법을 설명합니다.
Unity Gaming Services SDK 내에서 상호 작용할 수 있는 두 가지 Matchmaker 인터페이스는 다음과 같습니다.
Matchmaker SDK 플러그인 설치
계속하기 전에 아래와 같이 모듈의 공개 종속성으로 를 추가한 다음, include 문으로 클래스에 플러그인 헤더 파일을 가져옵니다.
MatchmakerSDKUnreal 프로젝트 빌드 파일()의 모듈 종속성에 와 를 추가합니다.
YourProjectName.Build.csMatchmakerServerMatchmakerClientPublicDependencyModuleNames.AddRange(new string[] { "Core", "CoreUObject", "Engine", "InputCore" });PublicDependencyModuleNames.AddRange(new string[] { "MatchmakerClient", "MatchmakerServer" });PublicDependencyModuleNames.AddRange(new string[] { "Json", "JsonUtilities" });
Matchmaker 클라이언트 블루프린트 API
Matchmaker 클라이언트 시스템의 보조 시스템은 매치메이킹과 매치 찾기의 클라이언트 부분을 제어합니다. 여기에는 매치메이킹 티켓 생성, 삭제, 폴링이 포함됩니다.
UMatchmakerClientBlueprintApiCreateTicket
CreateTicket다음 예제는 단일 플레이어와 대기열 이름을 전달하여 티켓을 생성하는 방법을 보여 줍니다. 또한 에 대한 응답을 처리하여 출력 값을 얻는 이벤트도 보여 줍니다.
TicketIdFString
응답 핸들러에 대한 커스텀 이벤트를 설정하고 이벤트의 구조체 핀을 오른쪽 클릭한 다음 을 선택하여 의 모든 개별 값에 액세스할 수 있습니다.
ResponseSplit Struct PinCreateTicketResponseDeleteTicket
DeleteTicket다음은 Delete Ticket 사용 방법과 응답 처리 방법을 보여 주는 간단한 예제입니다.
응답 핸들러에 대한 커스텀 이벤트를 설정하고 이벤트의 구조체 핀을 오른쪽 클릭한 다음 을 선택하여 의 모든 개별 값에 액세스할 수 있습니다.
ResponseSplit Struct PinDeleteTicketResponseGetTicketStatus
CreateTicket 블루프린트에서 가져온 를 사용하여 메치메이커에 매치를 폴링하려면 를 사용하십시오.
TicketIdGetTicketStatus폴링이 완료되었거나 실패한 이후 또는 사용자가 매치메이킹을 수동으로 취소하는 경우, 블루프린트를 사용하여 플레이어를 매치메이킹에서 제외할 수 있습니다.
DeleteTicket
응답 핸들러에 대한 커스텀 이벤트를 설정하고 이벤트의 구조체 핀을 오른쪽 클릭한 다음 을 선택하여 의 모든 개별 값에 액세스할 수 있습니다.
ResponseSplit Struct PinGetTicketStatusResponse]위 이미지는 노드를 사용하여 매치메이킹 티켓을 폴링하는 예제를 보여 줍니다. 루핑 조건이 true일 때 이 노드는 시간 변수에 설정된 주기로 이벤트를 계속해서 트리거합니다. 이 경우, 시간이 5로 설정되어 있으므로 타이머 핸들러가 취소될 때까지 5초마다 이벤트가 발생합니다. 반환 값은 을 사용하여 타이머를 취소하는 데 사용할 수 있는 타이머 핸들러입니다.
Set Timer by EventClear and Invalidate Timer by Handle
타이머 핸들은 Set Timer by Event 노드에서 Clear and Invalidate Timer by Handle 노드로 전달됩니다. Clear and Invalidate Timer by Handle을 트리거하려면 조건부 로직을 적용해야 합니다. 매치가 반환되기 전에 를 연속적으로 호출해야 합니다. 상태가 더 이상 InProgress로 반환되지 않으면, 폴링을 중지하고 티켓을 삭제하는 것이 좋습니다.
GetTicketStatus다음 이미지는 폴링 응답을 처리하고 Clear and Invalidate Timer를 트리거하는 방법에 대한 기본 예제를 보여 줍니다.
Matchmaker 서버 블루프린트 API
Matchmaker 서버 시스템의 보조 시스템은 매치메이킹의 서버 부분을 제어합니다. 여기에는 Backfill 티켓 생성, 승인, 삭제, 업데이트가 포함됩니다.
UMatchmakerServerBlueprintApi- 서버에서 Backfill을 시작하기 위해 Backfill 티켓 생성
- 새 플레이어가 서버에 참여할 수 있도록 Backfill 티켓 승인
- 매치메이킹 프로세스 외부에서 플레이어가 들어오거나 나가는 경우 매치메이커에 알리기 위해 Backfill 티켓 업데이트
- 서버가 새 플레이어를 더 이상 받지 않으면 Backfill 티켓 삭제
CreateBackfillTicket
플레이어(또는 플레이어들)가 인원이 모두 채워진 매치에서 나간 경우 새 Backfill 티켓을 생성해야 하고, 서버는 빈 슬롯을 채워야 합니다. Create Backfill Ticket 블루프린트를 사용하여 서버의 새 Backfill 티켓을 생성합니다.
응답 핸들러에 대한 커스텀 이벤트를 설정하고 이벤트 구조체 핀을 오른쪽 클릭한 다음 을 선택하여 의 모든 개별 값에 액세스할 수 있습니다.
ResponseSplit Struct PinCreateBackfillTicketResponseApproveBackfillTicket
새 플레이어가 서버에 참여할 수 있도록 Approve Backfill Ticket 블루프린트를 사용하여 주기적으로 Backfill 티켓을 승인해야 합니다.
Backfill 티켓은 1초에 한 번 이하로 승인하는 것이 좋습니다. 20초 동안 승인되지 않은 티켓은 Matchmaker 서비스에서 삭제됩니다.
위 예제에서는 승인 작업이 1초마다 반복됩니다. Backfill 티켓을 삭제한 후에는 Clear and Invalidate Timer by Handle 노드를 사용해야 합니다.
응답 핸들러에 대한 커스텀 이벤트를 설정하고 이벤트 구조체 핀을 오른쪽 클릭한 다음 을 선택하여 의 모든 개별 값에 액세스할 수 있습니다.
ResponseSplit Struct PinApproveBackfillTicketResponse응답에서 받은 값을 캐싱하고, 이를 사용하여 에서 을 빌드하는 것이 좋습니다.
UpdateBackfillTicketBackfillTicketUpdateBackfillTicket
다음 경우마다 Backfill 티켓을 업데이트해야 합니다.
- 플레이어가 서버를 나갈 때
- 매치메이킹 외부에서 플레이어가 서버에 참여할 때
여기에는 파티 초대, 직접 연결, 친구 초대 등이 포함될 수 있으나 이에 국한되지는 않습니다.
Update Backfill Ticket 블루프린트를 사용하여 서버의 현재 Backfill 티켓을 업데이트합니다.
응답 핸들러에 대한 커스텀 이벤트를 설정하고 이벤트 구조체 핀을 오른쪽 클릭한 다음 을 선택하여 의 모든 개별 값에 액세스할 수 있습니다.
ResponseSplit Struct PinUpdateBackfillTicketResponse이 티켓은 3초에 한 번 이하로 호출해야 하며, 에서 Backfill 티켓의 변경 사항을 감지한 경우 매치메이킹 주기가 완료되었는지 확인하기 위해 호출해야 합니다.
ApproveBackfillTicket경고
중요: Backfill 티켓을 너무 자주 업데이트하면 플레이어가 매치에 다시 Backfill되지 않을 수 있습니다. 자세한 내용은 매치메이킹 로직 샘플을 참조하십시오.
먼저 을 호출하고 에서 반환된 을 사용하여 필요에 따라 수정한 후 에 전달하는 것이 좋습니다.
ApproveBackfillTicketApproveBackfillTicketBackfillTicketUpdateBackfillTicketDeleteBackfillTicket
매치가 전부 채워진 경우 Backfill 티켓을 삭제할 수 있고, 서버는 더 이상 새 플레이어를 받지 않아야 합니다. 또한 매치가 끝나면 티켓을 삭제해야 합니다.
Delete Backfill Ticket 블루프린트를 사용하여 서버에서 Backfill을 중지합니다.
응답 핸들러에 대한 커스텀 이벤트를 설정하고 이벤트 구조체 핀을 오른쪽 클릭한 다음 을 선택하여 의 모든 개별 값에 액세스할 수 있습니다.
ResponseSplit Struct PinDeleteBackfillTicketResponse블루프린트 유틸리티 함수
블루프린트의 제한으로 인해 JSON 데이터 유형(예: 와 )은 기본적으로 호환되지 않으며 직접 조작을 지원하지 않습니다. SDK는 API의 일부로 JSON 데이터를 관리할 수 있도록 다음과 같은 유틸리티 함수를 제공합니다.
FJsonObjectFJsonValue- 의 일부인
MatchmakerServerMatchmakerServerBlueprintUtil - 의 일부인
MatchmakerClientMatchmakerClientBlueprintUtil
MatchmakerClientMatchmakerServerMatchmakerCoreMatchmakerClient
플레이어 커스텀 데이터
MatchmakerClientMatchmakerClientBlueprintUtilPlayerCustomDataAddStringData(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에 해당 가 포함되어 있고 이를 제거한 경우 true를 반환하고, 가 없으면 false를 반환합니다.
KeyKey속성
MatchmakerClientMatchmakerClientBlueprintUtilCreateTicketOptionsAddStringAttribute(FCreateTicketOptions& Options, FString Key, FString Value)
이 블루프린트를 사용하면 오브젝트에 문자열 기반의 속성을 추가할 수 있습니다. 속성이 설정되면 true를 반환하고, 그렇지 않으면 false를 반환합니다.
CreateTicketOptionsCreateTicketOptionsAddNumberAttribute(FCreateTicketOptions& Options, FString Key, float Value)
이 블루프린트를 사용하면 오브젝트에 숫자 기반의 속성을 추가할 수 있습니다. 속성이 설정되면 true를 반환하고, 그렇지 않으면 false를 반환합니다.
CreateTicketOptionsCreateTicketOptionsRemoveAttribute(FCreateTicketOptions& Options, FString Key)
이 블루프린트를 사용하면 오브젝트에서 속성을 제거할 수 있습니다.
CreateTicketOptionsCreateTicketOptionsMatchmakerServer
MatchmakerServerMatchmakerServerBlueprintUtilCreateBackfillTicketOptionsAddStringAttribute(FCreateBackfillTicketOptions Options, FString Key, FString Value)
이 블루프린트를 사용하면 오브젝트에 문자열 기반의 속성을 추가할 수 있습니다. 속성이 설정되면 true를 반환하고, 그렇지 않으면 false를 반환합니다.
CreateBackfillTicketOptionsCreateBackfillTicketOptionsAddNumberAttribute(FCreateBackfillTicketOptions& Options, FString Key, float Value)
이 블루프린트는 오브젝트에 숫자 기반의 속성을 추가하는 데 사용됩니다.
CreateBackfillTicketOptions속성이 설정되면 true를 반환하고, 그렇지 않으면 false를 반환합니다.
CreateBackfillTicketOptionsRemoveAttribute(FCreateBackfillTicketOptions Options, FString Key)
이 블루프린트를 사용하면 오브젝트에서 속성을 제거할 수 있습니다. 에 속성이 포함되어 있고 이를 제거한 경우 true를 반환하고, 속성이 존재하지 않으면 false를 반환합니다.
CreateBackfillTicketOptionsCreateBackfillTicketOptions