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

> Use the Matchmaker Blueprint API to add matchmaking functionality to your Unreal Engine game without writing code.

다음 섹션에서는 [Unreal Engine의 블루프린트](https://docs.unrealengine.com/5.3/en-US/ProgrammingAndScripting/Blueprints/GettingStarted/)를 사용하여 Matchmaker SDK와 연동하는 방법을 설명합니다.

Unity Gaming Services SDK 내에서 상호 작용할 수 있는 두 가지 Matchmaker 인터페이스는 다음과 같습니다.

* [Matchmaker 클라이언트 블루프린트 API](#matchmaker-client-blueprint-api)
* [Matchmaker 서버 블루프린트 API](#matchmaker-server-blueprint-api)

### Matchmaker SDK 플러그인 설치##install-the-matchmaker-sdk-plugin

계속하기 전에 아래와 같이 모듈의 공개 종속성으로 `MatchmakerSDK`를 추가한 다음, include 문으로 클래스에 플러그인 헤더 파일을 가져옵니다.

Unreal 프로젝트 빌드 파일(`YourProjectName.Build.cs`)의 모듈 종속성에 `MatchmakerServer`와 `MatchmakerClient`를 추가합니다.

```cpp
PublicDependencyModuleNames.AddRange(new string[] { "Core", "CoreUObject", "Engine", "InputCore" });
PublicDependencyModuleNames.AddRange(new string[] { "MatchmakerClient", "MatchmakerServer" });
PublicDependencyModuleNames.AddRange(new string[] { "Json", "JsonUtilities" });

```

### Matchmaker 클라이언트 블루프린트 API##matchmaker-client-blueprint-api

Matchmaker 클라이언트 시스템의 보조 시스템은 매치메이킹과 매치 찾기의 클라이언트 부분을 제어합니다. 여기에는 매치메이킹 티켓 생성, 삭제, 폴링이 포함됩니다.

`UMatchmakerClientBlueprintApi`의 정적 함수를 사용하여 다음 블루프린트를 통해 Matchmaker 클라이언트 시스템의 보조 시스템과 상호 작용합니다.

* [CreateTicket](#createticket)
* [DeleteTicket](#deleteticket)
* [GetTicketStatus](#getticketstatus)

#### CreateTicket##createticket

`CreateTicket`을 사용하려면 블루프린트에 티켓 생성 노드를 배치합니다. 티켓을 생성하려면 **Players**와 **Options** 입력 필드를 채웁니다.

다음 예제는 단일 플레이어와 대기열 이름을 전달하여 티켓을 생성하는 방법을 보여 줍니다. 또한 `TicketId`에 대한 응답을 처리하여 `FString` 출력 값을 얻는 이벤트도 보여 줍니다.


**Frame:**
![플레이어 설정](/api/media?file=/matchmaker/media/images/unreal-sdk-set-up-player.png)


**Frame:**
![CreateTicketOptions 설정](/api/media?file=/matchmaker/media/images/unreal-sdk-createticketoptions.png)


**Frame:**
![티켓 생성 호출](/api/media?file=/matchmaker/media/images/unreal-sdk-create-ticket.png)

응답 핸들러에 대한 커스텀 이벤트를 설정하고 이벤트의 `Response` 구조체 핀을 오른쪽 클릭한 다음 `Split Struct Pin`을 선택하여 `CreateTicketResponse`의 모든 개별 값에 액세스할 수 있습니다.

#### DeleteTicket##deleteticket

`DeleteTicket` 블루프린트를 사용하여 티켓을 삭제하는 호출을 수행하고, 삭제할 TicketId를 전달합니다.

다음은 Delete Ticket 사용 방법과 응답 처리 방법을 보여 주는 간단한 예제입니다.


**Frame:**
![매치메이킹 티켓 삭제](/api/media?file=/matchmaker/media/images/unreal-sdk-deleteticket.png)

응답 핸들러에 대한 커스텀 이벤트를 설정하고 이벤트의 `Response` 구조체 핀을 오른쪽 클릭한 다음 `Split Struct Pin`을 선택하여 `DeleteTicketResponse`의 모든 개별 값에 액세스할 수 있습니다.

#### GetTicketStatus##getticketstatus

CreateTicket 블루프린트에서 가져온 `TicketId`를 사용하여 메치메이커에 매치를 폴링하려면 `GetTicketStatus`를 사용하십시오.

폴링이 완료되었거나 실패한 이후 또는 사용자가 매치메이킹을 수동으로 취소하는 경우, `DeleteTicket` 블루프린트를 사용하여 플레이어를 매치메이킹에서 제외할 수 있습니다.


**Frame:**
![매치메이킹 티켓 폴링](/api/media?file=/matchmaker/media/images/unreal-sdk-poll-matchmaking.png)

응답 핸들러에 대한 커스텀 이벤트를 설정하고 이벤트의 `Response` 구조체 핀을 오른쪽 클릭한 다음 `Split Struct Pin`을 선택하여 `GetTicketStatusResponse]`의 모든 개별 값에 액세스할 수 있습니다.

위 이미지는 `Set Timer by Event` 노드를 사용하여 매치메이킹 티켓을 폴링하는 예제를 보여 줍니다. 루핑 조건이 true일 때 이 노드는 시간 변수에 설정된 주기로 이벤트를 계속해서 트리거합니다. 이 경우, 시간이 5로 설정되어 있으므로 타이머 핸들러가 취소될 때까지 5초마다 이벤트가 발생합니다. 반환 값은 `Clear and Invalidate Timer by Handle`을 사용하여 타이머를 취소하는 데 사용할 수 있는 타이머 핸들러입니다.


**Frame:**
![이벤트별 타이머 설정](/api/media?file=/matchmaker/media/images/unreal-sdk-set-timer.png)

타이머 핸들은 Set Timer by Event 노드에서 Clear and Invalidate Timer by Handle 노드로 전달됩니다. Clear and Invalidate Timer by Handle을 트리거하려면 조건부 로직을 적용해야 합니다. 매치가 반환되기 전에 `GetTicketStatus`를 연속적으로 호출해야 합니다. 상태가 더 이상 InProgress로 반환되지 않으면, 폴링을 중지하고 티켓을 삭제하는 것이 좋습니다.

다음 이미지는 폴링 응답을 처리하고 Clear and Invalidate Timer를 트리거하는 방법에 대한 기본 예제를 보여 줍니다.


**Frame:**
![타이머 초기화 및 무효화](/api/media?file=/matchmaker/media/images/unreal-sdk-invalidate-timer.png)

### Matchmaker 서버 블루프린트 API##matchmaker-server-blueprint-api

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

`UMatchmakerServerBlueprintApi`을 사용하여 다음을 수행할 수 있습니다.

* 서버에서 Backfill을 시작하기 위해 [Backfill 티켓 생성](#createbackfillticket)
* 새 플레이어가 서버에 참여할 수 있도록 [Backfill 티켓 승인](#approvebackfillticket)
* 매치메이킹 프로세스 외부에서 플레이어가 들어오거나 나가는 경우 매치메이커에 알리기 위해 [Backfill 티켓 업데이트](#updatebackfillticket)
* 서버가 새 플레이어를 더 이상 받지 않으면 [Backfill 티켓 삭제](#deletebackfillticket)

#### CreateBackfillTicket##createbackfillticket

플레이어(또는 플레이어들)가 인원이 모두 채워진 매치에서 나간 경우 새 Backfill 티켓을 생성해야 하고, 서버는 빈 슬롯을 채워야 합니다. Create Backfill Ticket 블루프린트를 사용하여 서버의 새 Backfill 티켓을 생성합니다.


**Frame:**
![MatchProperties 설정](/api/media?file=/matchmaker/media/images/unreal-sdk-matchproperties.png)


**Frame:**
![CreatebackfillTicketOptions 설정](/api/media?file=/matchmaker/media/images/unreal-sdk-createbackfillticketoptions.png)


**Frame:**
![CreateBackfillTicket 호출](/api/media?file=/matchmaker/media/images/unreal-sdk-createbackfillticket.png)

응답 핸들러에 대한 커스텀 이벤트를 설정하고 이벤트 `Response` 구조체 핀을 오른쪽 클릭한 다음 `Split Struct Pin`을 선택하여 `CreateBackfillTicketResponse`의 모든 개별 값에 액세스할 수 있습니다.

#### ApproveBackfillTicket##approvebackfillticket

새 플레이어가 서버에 참여할 수 있도록 Approve Backfill Ticket 블루프린트를 사용하여 주기적으로 Backfill 티켓을 승인해야 합니다.

Backfill 티켓은 1초에 한 번 이하로 승인하는 것이 좋습니다. 20초 동안 승인되지 않은 티켓은 Matchmaker 서비스에서 삭제됩니다.


**Frame:**
![Backfill 티켓 승인](/api/media?file=/matchmaker/media/images/unreal-sdk-approve-backfill.png)

위 예제에서는 승인 작업이 1초마다 반복됩니다. Backfill 티켓을 삭제한 후에는 Clear and Invalidate Timer by Handle 노드를 사용해야 합니다.

응답 핸들러에 대한 커스텀 이벤트를 설정하고 이벤트 `Response` 구조체 핀을 오른쪽 클릭한 다음 `Split Struct Pin`을 선택하여 `ApproveBackfillTicketResponse`의 모든 개별 값에 액세스할 수 있습니다.

응답에서 받은 값을 캐싱하고, 이를 사용하여 `UpdateBackfillTicket`에서 `BackfillTicket`을 빌드하는 것이 좋습니다.

#### UpdateBackfillTicket##updatebackfillticket

다음 경우마다 Backfill 티켓을 업데이트해야 합니다.

* 플레이어가 서버를 나갈 때
* 매치메이킹 외부에서 플레이어가 서버에 참여할 때

여기에는 파티 초대, 직접 연결, 친구 초대 등이 포함될 수 있으나 이에 국한되지는 않습니다.

Update Backfill Ticket 블루프린트를 사용하여 서버의 현재 Backfill 티켓을 업데이트합니다.


**Frame:**
![Backfill 티켓 업데이트](/api/media?file=/matchmaker/media/images/unreal-sdk-updatebackfillticket.png)

응답 핸들러에 대한 커스텀 이벤트를 설정하고 이벤트 `Response` 구조체 핀을 오른쪽 클릭한 다음 `Split Struct Pin`을 선택하여 `UpdateBackfillTicketResponse`의 모든 개별 값에 액세스할 수 있습니다.

이 티켓은 3초에 한 번 이하로 호출해야 하며, `ApproveBackfillTicket`에서 Backfill 티켓의 변경 사항을 감지한 경우 매치메이킹 주기가 완료되었는지 확인하기 위해 호출해야 합니다.

> **Warning:**
>
> **중요**: Backfill 티켓을 너무 자주 업데이트하면 플레이어가 매치에 다시 Backfill되지 않을 수 있습니다. 자세한 내용은 [매치메이킹 로직 샘플](/matchmaker/rules-sample.md)을 참조하십시오.

먼저 `ApproveBackfillTicket`을 호출하고 `ApproveBackfillTicket`에서 반환된 `BackfillTicket`을 사용하여 필요에 따라 수정한 후 `UpdateBackfillTicket`에 전달하는 것이 좋습니다.

#### DeleteBackfillTicket##deletebackfillticket

매치가 전부 채워진 경우 Backfill 티켓을 삭제할 수 있고, 서버는 더 이상 새 플레이어를 받지 않아야 합니다. 또한 매치가 끝나면 티켓을 삭제해야 합니다.

Delete Backfill Ticket 블루프린트를 사용하여 서버에서 Backfill을 중지합니다.


**Frame:**
![Backfill 티켓 삭제](/api/media?file=/matchmaker/media/images/unreal-sdk-deletebackfillticket.png)

응답 핸들러에 대한 커스텀 이벤트를 설정하고 이벤트 `Response` 구조체 핀을 오른쪽 클릭한 다음 `Split Struct Pin`을 선택하여 `DeleteBackfillTicketResponse`의 모든 개별 값에 액세스할 수 있습니다.

### 블루프린트 유틸리티 함수##blueprint-utility-functions

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

* `MatchmakerServer`의 일부인 `MatchmakerServerBlueprintUtil`
* `MatchmakerClient`의 일부인 `MatchmakerClientBlueprintUtil`

`MatchmakerClient` 또는 `MatchmakerServer`를 추가할 때 `MatchmakerCore`가 종속성으로 포함됩니다.

#### MatchmakerClient##matchmakerclient

##### 플레이어 커스텀 데이터##player-custom-data

`MatchmakerClient` 모듈에는 다음을 포함하는 `MatchmakerClientBlueprintUtil`이 들어 있습니다.

```cpp
PlayerCustomDataAddStringData(FMatchmakerPlayer& Player, FString Key, FString Value)
```

이 블루프린트를 사용하면 플레이어의 CustomData 오브젝트에 문자열 데이터 필드를 추가할 수 있습니다.

데이터가 설정되면 true를 반환하고, 그렇지 않으면 false를 반환합니다.

```cpp
PlayerCustomDataAddNumberData(FMatchmakerPlayer& Player, FString Key, float Value)
```

이 블루프린트를 사용하면 플레이어의 CustomData 오브젝트에 숫자 데이터 필드를 추가할 수 있습니다.

데이터가 설정되면 true를 반환하고, 그렇지 않으면 false를 반환합니다.

```cpp
PlayerCustomDataRemoveData(FMatchmakerPlayer& Player, FString Key)
```

이 블루프린트를 사용하면 플레이어의 CustomData 오브젝트에서 데이터 필드를 제거할 수 있습니다.

플레이어의 CustomData에 해당 `Key`가 포함되어 있고 이를 제거한 경우 true를 반환하고, `Key`가 없으면 false를 반환합니다.

##### 속성##attributes

`MatchmakerClient` 모듈에는 다음을 포함하는 `MatchmakerClientBlueprintUtil`이 들어 있습니다.

```cpp
CreateTicketOptionsAddStringAttribute(FCreateTicketOptions& Options, FString Key, FString Value)
```

이 블루프린트를 사용하면 `CreateTicketOptions` 오브젝트에 문자열 기반의 속성을 추가할 수 있습니다. 속성이 설정되면 true를 반환하고, 그렇지 않으면 false를 반환합니다.

```cpp
CreateTicketOptionsAddNumberAttribute(FCreateTicketOptions& Options, FString Key, float Value)
```

이 블루프린트를 사용하면 `CreateTicketOptions` 오브젝트에 숫자 기반의 속성을 추가할 수 있습니다. 속성이 설정되면 true를 반환하고, 그렇지 않으면 false를 반환합니다.

```cpp
CreateTicketOptionsRemoveAttribute(FCreateTicketOptions& Options, FString Key)
```

이 블루프린트를 사용하면 `CreateTicketOptions` 오브젝트에서 속성을 제거할 수 있습니다.

`CreateTicketOptions`에 속성이 포함되어 있고 이를 제거한 경우 true를 반환하고, 속성이 없으면 false를 반환합니다.

#### MatchmakerServer##matchmakerserver

`MatchmakerServer` 모듈에는 다음 함수를 포함하는 `MatchmakerServerBlueprintUtil`이 들어 있습니다.

```cpp
CreateBackfillTicketOptionsAddStringAttribute(FCreateBackfillTicketOptions Options, FString Key, FString Value)
```

이 블루프린트를 사용하면 `CreateBackfillTicketOptions` 오브젝트에 문자열 기반의 속성을 추가할 수 있습니다. 속성이 설정되면 true를 반환하고, 그렇지 않으면 false를 반환합니다.

```cpp
CreateBackfillTicketOptionsAddNumberAttribute(FCreateBackfillTicketOptions& Options, FString Key, float Value)
```

이 블루프린트는 `CreateBackfillTicketOptions` 오브젝트에 숫자 기반의 속성을 추가하는 데 사용됩니다.

속성이 설정되면 true를 반환하고, 그렇지 않으면 false를 반환합니다.

```cpp
CreateBackfillTicketOptionsRemoveAttribute(FCreateBackfillTicketOptions Options, FString Key)
```

이 블루프린트를 사용하면 `CreateBackfillTicketOptions` 오브젝트에서 속성을 제거할 수 있습니다. `CreateBackfillTicketOptions`에 속성이 포함되어 있고 이를 제거한 경우 true를 반환하고, 속성이 존재하지 않으면 false를 반환합니다.