> For the complete documentation index, see [llms.txt](https://docs.edgegap.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.edgegap.com/ko/unity/matchmaking.md).

# 매치메이킹

이 SDK는 Unity 사용자를 위한 선택적 스타터 키트로, 나중에 확장하고 사용자 지정할 수 있습니다.

## 💡 기능

{% columns %}
{% column %}

* 완전한 예제
* 핑 자동화
* 티켓, 그룹, 팀
  {% endcolumn %}

{% column width="33.33333333333333%" %}

* 매치 변수
* 타입 정의(C#)
* 로컬 개발 테스트
  {% endcolumn %}

{% column width="33.33333333333333%" %}

* 크로스 플랫폼
* 사용자 지정하기 쉬움
* 자동 재시도
  {% endcolumn %}
  {% endcolumns %}

## ✔️ 준비

Unity SDK에는 배포, 매치메이킹, 서버 브라우저를 위한 선택적 통합 유틸리티가 포함되어 있습니다. 이 플러그인은 Unity 2021.3.0f1 이상 버전을 공식 지원합니다.

{% hint style="info" %}
**Unity SDK의 최신 버전은 `3.5.4`**. 이 문서의 모든 예제는 최신 상태입니다.
{% endhint %}

{% hint style="success" %}
이 플러그인은 Free Tier의 이용 약관에 따라 100% 무료로 제공됩니다.
{% endhint %}

#### 요구 사항

<details>

<summary>Git 클라이언트를 설치하세요(예: <a href="https://git-scm.com/">git-scm</a>)</summary>

Unity가 당사의 Unity 패키지를 자동으로 다운로드하고 설치하려면 Git 클라이언트가 필요합니다. 한 번 설치하면 git을 직접 사용할 필요가 없습니다.

</details>

#### 설치

1. Unity 프로젝트를 여세요,
2. 선택 `창 > 패키지 관리 > 패키지 관리자` ,
3. 다음을 클릭하세요 :heavy\_plus\_sign: 아이콘을 클릭한 다음 `git URL에서 패키지 추가...` ,
4. 프롬프트가 표시되면 SDK의 URL을 입력하세요:

{% code title="" %}

```
https://github.com/edgegap/edgegap-unity-sdk.git
```

{% endcode %}

5. 클릭하세요 `추가`  그리고 설치가 완료될 때까지 기다리세요.

#### 샘플 가져오기

이 패키지에는 여러 샘플이 포함되어 있으며, 각각 개별적으로 사용하도록 되어 있습니다(샘플을 함께 결합하지 마세요).

#### 검증된 출처

이것이 이 SDK의 유일한 공식 배포 채널입니다. 검증되지 않은 출처는 신뢰하지 마세요!

#### 패키지 업데이트

Unity Package Manager에서 Edgegap SDK로 이동한 다음 클릭하세요 `업데이트` .

{% hint style="warning" %}
**가져온 샘플은 자동으로 업데이트되지 않습니다!** 사용자 지정 속성 값은 백업하고, 현재 씬에서 사용 중인 샘플 스크립트를 삭제한 다음 샘플을 다시 가져오세요.
{% endhint %}

{% hint style="info" %}
일부 릴리스에는 호환성을 깨는 변경 사항이 포함될 수 있습니다. 이는 새로운 MAJOR 버전으로 표시됩니다.
{% endhint %}

#### v3로 업데이트

이번 업데이트에는 많은 새로운 [서버 브라우저](/ko/unity/server-browser.md) 유틸리티와 예제가 포함되어 있으며, 매치메이킹 오류 처리가 개선되는 등 다양한 개선 사항이 있습니다. 자세한 내용은 [릴리스 노트](/ko/docs/release-notes.md) 전체 목록을 확인하세요.

{% hint style="warning" %}
Unity SDK v3 업데이트에는 몇 가지 호환성을 깨는 변경 사항이 포함되어 있습니다. 통합을 신중하게 다시 테스트해 주세요.
{% endhint %}

## 🍀 시작하기

이 가이드는 다음에 대한 기본 지식이 있다고 가정합니다 [매치메이킹](/ko/learn/matchmaking.md) 개념과 실행 중인 Matchmaker.

{% hint style="success" %}
**Simple Example을 가져오시기를 강력히 권장합니다** 이 문서를 읽으면서 코드를 함께 따라가 보세요. 방법은 `Unity Package Manager > Edgegap SDK > 샘플` .
{% endhint %}

{% embed url="<https://youtu.be/LupYTyzgz6g>" %}

### 개요

우리 SDK는 이를 적극적으로 활용합니다 [의존성 주입](https://learn.microsoft.com/en-us/dotnet/core/extensions/dependency-injection/overview#the-concept) 및 [옵저버](https://learn.microsoft.com/en-us/dotnet/standard/events/observer-design-pattern) 프로그래밍 패턴.

{% hint style="info" %}
이 패키지는 두 가지를 모두 통합합니다 [서버 브라우저](/ko/learn/server-browser.md) 및 [매치메이킹](/ko/learn/matchmaking.md)이며, 함께 또는 별도로 사용할 수 있습니다. 원하는 대로 어떤 스크립트든 자신의 맞춤형 포크와 통합에 자유롭게 재사용할 수 있습니다.
{% endhint %}

이 패키지에는 다음이 포함됩니다:

* 런타임 파일 - 클라이언트 및 서버 빌드와 함께 컴파일되고 번들로 포함됩니다:
  * 서비스별 유틸리티:
    * [#client-agent](#client-agent "mention") - 재사용/확장할 수 있는 완전한 클라이언트 통합.
    * API 함수 - 엔드포인트 정의, 오류 처리, 로깅 자동화.
  * 서비스별 DTO[^1] - 매치메이킹 API를 위한 타입이 지정된 데이터 컨테이너.
  * 공용 유틸리티 - 로깅, HTTP, 핑, 옵저버블 등...
  * 공용 DTO[^1] - 여러 Edgegap 서비스에서 데이터를 주고받는 데 사용됩니다.
* 샘플 파일 - 프로젝트에 가져온 경우에만 번들로 포함되고 컴파일됩니다:
  * [#simple-example](#simple-example "mention") - 다음을 위한 예제 핸들러: [최소 구성](/ko/learn/matchmaking.md#simple-example).
  * [#region-picker](#region-picker "mention") - 수동 지역 선택을 통한 UI 통합을 살펴보세요.

### 그룹 클라이언트

**핑 자동화, 티켓 관리, 호스트 검색** 은 그룹 클라이언트에서 수행합니다.

인스턴스화되면 에이전트의 **상위 MonoBehaviour(핸들러)가 클라이언트를 초기화해야 합니다** 그리고 다음을 제공해야 합니다:

* `onMonitorUpdate`  콜백 - 서비스 상태 변경을 관찰합니다.
* `onAssignmentUpdate`  콜백 - 호스트 할당 변경을 관찰하고 대응합니다.

초기화되면 이 클라이언트는 자동으로 유효성 검사를 제공하고 로깅 옵저버를 연결한 뒤, 서비스 상태를 알리기 위해 모니터링 API 엔드포인트를 한 번 호출합니다.

이 시점부터는 클라이언트의 핸들러가 제어권을 가져가 클라이언트 함수를 호출해야 합니다:

* `비콘`  사용 가능한 목록을 가져오기 위해 [핑 비컨](/ko/learn/orchestration/ping-beacons.md).
* `MeasureBeaconsRoundTripTime`  지정된 비콘 집합에 대한 핑 측정을 제공합니다.
* `CreateGroup`  로비 리더가 친구를 초대할 수 있는 참여 가능한 그룹을 생성합니다.
* `JoinGroup`  서드파티 로비/백엔드를 통해 전송된 그룹 ID를 사용해 기존 그룹에 참여합니다.
* `SetReady`  그룹 소유자와 멤버를 준비 완료로 표시하고 매치 검색을 시작합니다.
* `ResumeMatchmaking`  클라이언트가 충돌한 경우 캐시된 그룹을 불러와 검색을 계속합니다.
* `StopMatchmaking`  티켓을 삭제하고(매치되지 않은 경우) 대기열을 포기합니다.
* `상태`  Matchmaker 서비스 상태를 확인합니다.

새 플레이어 연결이 수립되면 플레이어는 netcode를 사용하여 티켓 ID를 게임 서버로 보내 연결을 다음과 연관시켜야 합니다 [심층 살펴보기](/ko/learn/matchmaking/matchmaker-in-depth.md#injected-variables).

{% hint style="success" %}
예기치 않은 충돌이 발생한 경우 다시 연결할 수 있도록 연결 세부 정보를 클라이언트 또는 게임 백엔드에 저장하세요.
{% endhint %}

## 서버 에이전트

서버 에이전트는 다음을 수행합니다 **백필 생성, 티켓 할당 감지, 백필 포기 및 제거 감지를 수행합니다. 또한 만료되었거나 연결 유예 시간이 경과했거나 포기된 백필을 추적하고 다시 생성하여 원하는 팀 규모에 도달하도록 합니다**.

서버 에이전트는 현재 연결된 플레이어를 추적하고, 백필로 들어온 플레이어가 구성된 프로필의 규칙에 따라 매치되도록 새 백필에 해당 플레이어의 티켓을 자동으로 포함합니다.

인스턴스화되면 에이전트의 **상위 MonoBehaviour(핸들러)가 클라이언트를 초기화해야 합니다** 그리고 다음을 제공해야 합니다:

* `onMonitorUpdate`  콜백 - 서비스 상태 변경을 관찰합니다.
* `onBackfillUpdate` 콜백 - 백필 변경을 관찰하고 대응합니다.

초기화되면 이 클라이언트는 자동으로 유효성 검사를 제공하고 로깅 옵저버를 연결한 뒤, 서비스 상태를 알리기 위해 모니터링 API 엔드포인트를 한 번 호출합니다.

이 시점부터는 서버 핸들러가 제어권을 가져가 클라이언트 함수를 호출해야 합니다:

* `플레이어 연결됨`  처음 배정되었거나 백필된 플레이어 중 연결되지 않은 플레이어를 교체하지 않도록 합니다.
* `플레이어 포기`  연결된 플레이어가 서버를 떠나 교체가 필요함을 알립니다.
* `모든 백필 포기`  서버의 백필을 즉시 중지하고 백필을 삭제합니다.
  * 이 메서드는 서버를 중지하기 전에 호출해야 합니다. 이 시점에 이미 할당된 플레이어는 서버가 종료되므로 매치메이킹에 다시 참여해야 합니다.
  * 이 호출 시점에 할당된 백필은 구성된 유예 시간 내에 여전히 연결할 수 있습니다.
* `백필 포기`  특정 백필을 강제로 포기합니다(사용자 지정 핸들러 구현).
* `상태`  matchmaker 서비스 상태를 확인합니다.

## 🧪 샘플

서버와 클라이언트 모두에 대한 완전한 동작 통합이 포함된 샘플로 시작하세요.

### 간단한 예제

핑 측정, 티켓 관리, 호스트 할당 검색을 포함한 전체 플레이어 생명주기 구현이 포함되어 있습니다. 서버 측에서 주입된 매치 변수를 읽는 방법을 보여줍니다.

매치메이킹 속성을 수정하여 이 예제를 어떤 구성에도 쉽게 맞출 수 있습니다.

### 지역 선택기

일부 플레이어(또는 그룹)는 다음과 같은 특별한 지역별 조건이 있습니다( ISP[^2] 차단, [국가 차원의 차단](#user-content-fn-3)[^3], 또는 기타) 때문에 핑만으로 결정하기보다 지역을 수동으로 선택하는 것을 선호할 수 있습니다.

지역 선택기 샘플을 살펴보고 매치메이킹 UI 구현에 대한 영감을 얻으세요.

### 그룹으로 참여

친구 그룹과 함께 매치메이킹 대기열에 참여하며, 검색을 시작하기 전에 모든 플레이어의 확인이 필요합니다. 최소한의 UI 구현으로 시작한 다음 게임 디자인에 맞게 사용자 지정하세요.

그룹 참여 흐름과 UI 통합을 살펴보고 최상의 소셜 경험을 제공하세요.

### 백필

서버 용량을 재사용하고 진행 중인 배포에 플레이어를 추가합니다. 목표 팀 크기를 설정하고 플레이어가 추가되기를 기다립니다. 자동 연결 유예 시간과 만료된 백필 재생성을 포함합니다.

다중 팀 또는 비대칭 팀 구성을 위해 예제 서버 핸들러를 사용자 지정하세요.

## ⚙️ 사용자 지정

이 SDK는 확장 및 수정하도록 설계되었지만, 일부 수정은 위험할 수 있습니다:

✅ 핸들러 - UI 옵저버를 안전하게 연결하고 작은 추가 또는 수정을 수행합니다,

⚠️ 에이전트 - 플레이어 생명주기 관리는 본인의 책임하에 수정하세요,

⚠️ API - 선별한 유틸리티를 사용해 처음부터 직접 통합을 작성하세요.

핸들러는 아래에 설명된 대로 서버 및 클라이언트 에이전트가 발생시키는 모든 이벤트를 관찰할 수 있습니다.

{% hint style="warning" %}
다음에 익숙해지세요 [매치메이킹 심층](/ko/learn/matchmaking/matchmaker-in-depth.md) 개념을 사용자 지정하기 전에.
{% endhint %}

{% hint style="info" %}
도움이 필요하시면 [디스코드를 통해 문의해 주세요](https://discord.gg/MmJf8fWjnt). 실시간 게임 지원은 저희의 [티켓 시스템](https://edgegap.atlassian.net/servicedesk/customer/portal/3).
{% endhint %}

### 클라이언트 이벤트

그룹 클라이언트는 상위 핸들러가 관찰하고 사용할 수 있도록 이벤트(동작)를 발생시킵니다.

{% hint style="success" %}
액세스하여 이벤트 페이로드를 읽습니다  `.Current` 모든 관찰 가능한 것의 상태. 🔴 `오류` 이벤트에는 주요 이벤트 메시지 뒤에 줄바꿈 문자로 구분된 전체 오류 메시지가 포함됩니다.
{% endhint %}

옵저버블이 발생시키는 이벤트 미리보기 `모니터` :

<table data-full-width="true"><thead><tr><th width="125">작업 유형</th><th width="450">이벤트 메시지</th><th>설명</th></tr></thead><tbody><tr><td>🟢 <code>업데이트</code> </td><td><code>정상</code></td><td>모든 시스템 정상입니다.</td></tr><tr><td>🟢 <code>업데이트</code> </td><td><code>비정상</code></td><td>예기치 않은 문제입니다.</td></tr><tr><td>🔴 <code>오류</code></td><td><code>모니터 가져오기 실패</code></td><td>잘못된 구성 또는 예기치 않은 문제입니다.</td></tr><tr><td>🔴 <code>오류</code></td><td><code>비콘 가져오기 실패</code></td><td>예기치 않은 문제입니다.</td></tr></tbody></table>

옵저버블이 발생시키는 이벤트 미리보기 `그룹`:

<table data-full-width="true"><thead><tr><th width="125">작업 유형</th><th width="450">이벤트 메시지</th><th>설명</th></tr></thead><tbody><tr><td>🟢 <code>업데이트</code> </td><td><code>생성됨</code></td><td>그룹이 정상적으로 생성되었습니다.</td></tr><tr><td>🔴 <code>오류</code></td><td><code>그룹 생성 실패</code></td><td>그룹 생성에 실패했습니다.</td></tr><tr><td>🟢 <code>업데이트</code> </td><td><code>참여됨</code></td><td>그룹 참여가 정상적으로 완료되었습니다.</td></tr><tr><td>🔴 <code>오류</code></td><td><code>그룹 참여 실패</code></td><td>그룹 참여에 실패했습니다.</td></tr><tr><td>🟢 <code>업데이트</code> </td><td><code>재개됨</code></td><td>그룹이 정상적으로 재개되었습니다.</td></tr><tr><td>🔴 <code>오류</code></td><td><code>그룹을 찾을 수 없음</code></td><td>그룹의 멤버가 아니거나 그룹이 만료되었습니다.</td></tr><tr><td>🔴 <code>오류</code></td><td><code>충돌, 포기 후 다시 시작</code></td><td>새 그룹을 생성/참여하려면 먼저 현재 그룹을 포기하세요.</td></tr><tr><td>🟢 <code>업데이트</code> </td><td><code>멤버 업데이트됨 [{ready}]</code></td><td>멤버가 새 Ready 값으로 업데이트되었습니다.</td></tr><tr><td>🔴 <code>오류</code></td><td><code>멤버 업데이트 실패</code></td><td>그룹 멤버를 업데이트하지 못했습니다. 그룹이 매치 검색을 시작한 후에는 준비 해제를 할 수 없습니다.</td></tr><tr><td>🔵 <code>알림</code></td><td><code>폴링 [{consecutive}/{maximum}]</code></td><td>클라이언트가 그룹 상태 폴링을 시작했습니다.</td></tr><tr><td>🔵 <code>알림</code></td><td><code>폴링 중지됨</code></td><td>클라이언트가 티켓 상태 폴링을 중지했습니다.</td></tr><tr><td>🔴 <code>오류</code></td><td><code>폴링 실패, 최대 재시도 횟수에 도달함</code></td><td>클라이언트가 연속 폴링 재시도 최대 횟수를 모두 소진했습니다. 서비스 상태를 확인하세요.</td></tr><tr><td>🔴 <code>오류</code></td><td><code>폴링 실패</code></td><td>클라이언트가 폴링 중 재시도할 수 없는 오류를 받았습니다. 서비스 상태를 확인하세요.</td></tr><tr><td>🟢 <code>업데이트</code> </td><td><code>그룹 업데이트됨 [{status}]</code></td><td>폴링 중 그룹 상태 변경이 감지되었습니다.</td></tr><tr><td>🟢 <code>업데이트</code> </td><td><code>포기됨</code></td><td>티켓이 정상적으로 삭제되었습니다.</td></tr><tr><td>🟢 <code>업데이트</code> </td><td><code>포기 실패(찾을 수 없음)</code></td><td>클라이언트가 삭제할 티켓을 찾지 못했습니다. 만료되었을 수 있습니다.</td></tr><tr><td>🟡 <code>경고</code></td><td><code>포기 실패(이미 매치됨)</code></td><td>클라이언트가 매치된 그룹을 삭제할 수 없습니다. 포기를 비활성화하거나 <a data-mention href="/ko/learn/matchmaking/matchmaker-in-depth.md#backfill-match">심층 살펴보기</a> 플레이어를 교체하세요.</td></tr><tr><td>🔴 <code>오류</code></td><td><code>포기 실패</code></td><td>그룹 또는 멤버십 삭제에 실패했습니다.</td></tr><tr><td>🟢 <code>업데이트</code> </td><td><code>제거됨</code></td><td>그룹이 만료되어 로컬 참조가 삭제되었습니다.</td></tr></tbody></table>

### 서버 이벤트

서버 에이전트는 상위 핸들러가 관찰하고 사용할 수 있도록 이벤트(동작)를 발생시킵니다. 서버 에이전트가 이러한 이벤트를 발생시키는 것은 다음에서만 초기화됩니다. [#backfill](#backfill "mention") 샘플.

{% hint style="info" %}
현재 할당된 티켓은 서버 에이전트 속성에서 읽을 수 있습니다 `할당`  언제든지.
{% endhint %}

{% hint style="success" %}
액세스하여 이벤트 페이로드를 읽습니다  `.Current` 모든 관찰 가능한 것의 상태. 🔴 `오류` 이벤트에는 주요 이벤트 메시지 뒤에 줄바꿈 문자로 구분된 전체 오류 메시지가 포함됩니다.
{% endhint %}

옵저버블이 발생시키는 이벤트 미리보기 `모니터` :

<table data-full-width="true"><thead><tr><th width="125">작업 유형</th><th width="450">이벤트 메시지</th><th>설명</th></tr></thead><tbody><tr><td>🟢 <code>업데이트</code> </td><td><code>정상</code></td><td>모든 시스템 정상입니다.</td></tr><tr><td>🟢 <code>업데이트</code> </td><td><code>비정상</code></td><td>예기치 않은 문제입니다.</td></tr><tr><td>🔴 <code>오류</code></td><td><code>모니터 가져오기 실패</code></td><td>잘못된 구성 또는 예기치 않은 문제입니다.</td></tr></tbody></table>

옵저버블이 발생시키는 이벤트 미리보기 `백필`:

<table data-full-width="true"><thead><tr><th width="125">작업 유형</th><th width="450">이벤트 메시지</th><th>설명</th></tr></thead><tbody><tr><td>🟢 <code>업데이트</code> </td><td><code>생성됨 [{backfill}]</code></td><td>백필이 정상적으로 생성되었습니다.</td></tr><tr><td>🔴 <code>오류</code></td><td><code>생성 실패</code></td><td>백필에 예기치 않은 문제가 발생했습니다. 서비스 상태를 확인하세요.</td></tr><tr><td>🔵 <code>알림</code></td><td><code>폴링 [{consecutive}/{maximum}]</code></td><td>폴링 실패, 자동으로 재시도합니다.</td></tr><tr><td>🟢 <code>업데이트</code> </td><td><code>할당됨 [{backfill}]</code></td><td>티켓이 백필에 정상적으로 할당되었습니다.</td></tr><tr><td>🔵 <code>알림</code></td><td><code>폴링 중지됨</code></td><td>핸들러의 요청으로 폴링이 중지되었습니다.</td></tr><tr><td>🔵 <code>알림</code></td><td><code>폴링 실패(찾을 수 없음) [{backfill}]</code></td><td>찾을 수 없어 참조를 제거합니다. 백필이 만료되었을 가능성이 큽니다.</td></tr><tr><td>🔴 <code>오류</code></td><td><code>폴링 실패(최대 재시도 횟수에 도달) [{backfill}]</code></td><td>재시도를 모두 소진하여 백필을 포기합니다.</td></tr><tr><td>🔴 <code>오류</code></td><td><code>폴링 실패 [{backfill}]</code></td><td>예기치 않은 문제로 참조를 제거합니다.</td></tr><tr><td>🔵 <code>알림</code></td><td><code>포기됨 [{backfill}]</code></td><td>백필이 포기되어 참조를 제거합니다.</td></tr><tr><td>🟡 <code>경고</code></td><td><code>포기 실패 [{backfill}]</code></td><td>포기에 실패하여 참조를 제거합니다.</td></tr><tr><td>🟢 <code>업데이트</code> </td><td><code>제거됨 [{backfill}]</code></td><td>백필 참조가 제거되었습니다. 중지하지 않으면 백필은 자동으로 대체됩니다.</td></tr><tr><td>🟡 <code>경고</code></td><td><code>제거 실패 [{backfill}]</code></td><td>백필 참조를 찾을 수 없습니다. 중복 호출일 가능성이 높습니다.</td></tr></tbody></table>

[^1]: 데이터 전송 객체

[^2]: [인터넷 서비스 제공업체](https://en.wikipedia.org/wiki/Internet_service_provider)

[^3]: 특히 중국이나 러시아에서