> 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/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에는 배포(Deployments), 매치메이킹(Matchmaking), 서버 브라우저(Server Browser)를 위한 선택적 통합 유틸리티가 포함되어 있습니다. 이 플러그인은 Unity 2021.3.0f1 이상 버전을 공식 지원합니다.

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

#### 요구 사항

<details>

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

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

</details>

#### 설치

1. Unity 프로젝트를 여세요,
2. 다음을 선택하세요 `Window > Package Management > Package Manager` ,
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로 업데이트

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

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

## 🍀 시작하기

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

{% hint style="success" %}
**Simple Example를 가져오기를 강력히 권장합니다** 이 문서를 읽는 동안 코드를 따라가며 진행할 수 있습니다. 다음에서 할 수 있습니다. `Unity Package Manager > Edgegap SDK > Samples` .
{% 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" %}
이 패키지는 두 가지를 모두 통합합니다 [서버 브라우저](/docs.edgegap.com-ko/learn/server-browser.md) 및 [매치메이킹](/docs.edgegap.com-ko/learn/matchmaking.md)이며, 함께 또는 별도로 사용할 수 있습니다. 원하는 대로 어떤 스크립트든 자신의 맞춤형 포크와 통합에 자유롭게 재사용할 수 있습니다.
{% endhint %}

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

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

### 그룹 클라이언트

**핑 자동화, 티켓 관리, 호스트 조회** 는 Group Client에서 수행됩니다.

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

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

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

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

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

새 플레이어 연결이 설정되면, 플레이어는 연결을 다음과 연관시키기 위해 netcode를 사용해 티켓 ID를 게임 서버로 보내야 합니다. [심층 살펴보기](/docs.edgegap.com-ko/learn/matchmaking/matchmaker-in-depth.md#injected-variables).

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

## 🧪 샘플

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

### 간단한 예제

핑 측정, 티켓 관리, 호스트 할당 조회를 포함한 전체 플레이어 라이프사이클 구현을 포함합니다. 서버 측에서 주입된 매치 변수를 읽는 방법을 보여줍니다.

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

### 지역 선택기

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

Region Picker 샘플을 살펴보고 매치메이킹 UI 구현에 대한 영감을 얻으세요.

### 그룹 구성

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

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

## ⚙️ 사용자 지정

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

✅ 핸들러 - UI 옵저버를 안전하게 연결하고 사소한 추가나 수정을 수행합니다,

⚠️ 에이전트 - 플레이어 라이프사이클 관리를 자기 책임하에 수정하세요,

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

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

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

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

### 이벤트 관찰

Group Client는 상위 핸들러가 관찰하고 처리할 수 있도록 이벤트(작업)를 방출합니다.

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

관찰 가능한 Monitor가 내보내는 이벤트 미리 보기 `모니터` :

<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>

관찰 가능한 Monitor가 내보내는 이벤트 미리 보기 `그룹`:

<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="/pages/9b10ade5b00c98930860db62005218f1d0bc81d1#backfill-match">/pages/9b10ade5b00c98930860db62005218f1d0bc81d1#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>

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

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

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