> 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 %} ## ✔️ 준비 ## 🍀 시작하기 이 가이드는 다음에 대한 기본 지식이 있다고 가정합니다. [매치메이킹](/docs.edgegap.com-ko/learn/matchmaking.md) 개념과 실행 중인 매치메이커. {% hint style="success" %} **문서를 읽는 동안 따라 할 수 있도록 저희의 Simple Example를 가져오시길 강력히 권장합니다.** 다음에서 가져올 수 있습니다. `Unity Package Manager > Edgegap SDK > Samples` . {% endhint %} ### 개요 이 패키지에는 다음이 포함됩니다: * 런타임 파일 - 클라이언트 및 서버 빌드와 함께 컴파일되어 번들로 포함됩니다: * 서비스별 유틸리티: * [#client-agent](#client-agent "mention") - 재사용/확장을 위한 완전한 클라이언트 통합. * API 함수 - 엔드포인트 정의, 오류 처리, 로깅 자동화. * 서비스별 DTO[^1] - 매치메이킹 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 통합을 살펴보세요. ### 그룹 클라이언트 **핑 자동화, 티켓 관리, 호스트 가져오기는** 그룹 클라이언트가 수행합니다. 인스턴스화되면 에이전트의 **상위 MonoBehaviour(핸들러)는 클라이언트를 초기화해야 하며** 다음을 제공해야 합니다: * `onMonitorUpdate` 콜백 - 서비스 상태 변경을 관찰하고, * `onAssignmentUpdate` 콜백 - 호스트 할당 변경을 관찰하고 반응합니다. 초기화되면 이 클라이언트는 자동으로 유효성 검사를 제공하고 로깅 옵저버를 연결한 뒤, 서비스 상태를 나타내기 위해 모니터링 API 엔드포인트를 단 한 번 호출합니다. 이 시점부터 클라이언트의 핸들러가 제어권을 가져가 클라이언트 함수를 호출해야 합니다: * `비콘` 사용 가능한 목록을 가져오기 위해 [Ping Beacons](/docs.edgegap.com-ko/learn/orchestration/ping-beacons.md), * `MeasureBeaconsRoundTripTime` 주어진 비콘 집합에 대한 핑 측정을 제공하기 위해, * `CreateGroup` 로비 리더가 친구를 초대할 수 있는 참가 가능한 그룹을 만들기 위해, * `JoinGroup` 3자 로비/백엔드를 통해 전송된 그룹 ID를 사용해 기존 그룹에 참가하기 위해, * `SetReady` 그룹 소유자와 멤버를 준비 완료로 표시하고 매치 검색을 시작하기 위해, * `ResumeMatchmaking` 캐시된 그룹을 불러와 클라이언트가 충돌한 경우에도 검색을 계속하기 위해, * `StopMatchmaking` 티켓을 삭제하고(매칭되지 않은 경우) 대기열을 떠나기 위해, * `상태` 서버 브라우저 서비스 상태를 확인하기 위해. 새 플레이어 연결이 수립되면, 플레이어는 연결을 다음과 연동할 수 있도록 자신의 티켓 ID를 게임 서버에 netcode를 사용해 보내야 합니다. [심층 살펴보기](/docs.edgegap.com-ko/learn/matchmaking/matchmaker-in-depth.md#injected-variables). {% hint style="success" %} 예기치 않은 충돌 시 재연결할 수 있도록 연결 세부 정보를 클라이언트 또는 게임 백엔드에 저장하세요. {% endhint %} ## 🧪 샘플 서버와 클라이언트 모두에 대한 완전한 작동 통합을 포함한 샘플로 시작하세요. ### Simple Example 핑 측정, 티켓 관리, 호스트 할당 가져오기를 포함한 전체 플레이어 생명주기 구현이 포함되어 있습니다. 서버 측에서 주입된 매치 변수를 읽는 방법을 보여줍니다. 매치메이킹 속성을 수정하여 이 예제를 쉽게 확장해 어떤 구성에도 맞출 수 있습니다. ### 지역 선택기 일부 플레이어(또는 그룹)는 다음과 같은 특수한 지역별 조건을 가집니다. ISP[^2] 차단, [국가 차원의 차단](#user-content-fn-3)[^3]또는 기타 사유가 있으며, 핑만 기준으로 하기보다 수동으로 지역을 선택하는 것을 선호할 수 있습니다. 지역 선택기 샘플을 살펴보고 매치메이킹 UI 구현에 참고하세요. ### 그룹 모으기 친구 그룹과 함께 매치메이킹 대기열에 참여하며, 검색을 시작하기 전에 모든 플레이어의 확인이 필요합니다. 최소 UI 구현으로 시작한 뒤 게임 디자인에 맞게 사용자 지정하세요. 그룹 모으기 흐름과의 UI 통합을 살펴보고 최상의 소셜 경험을 제공하세요. ## ⚙️ 사용자 지정 이 SDK는 확장 및 수정할 수 있도록 설계되었지만, 일부 수정은 위험할 수 있습니다: ✅ 핸들러 - UI 옵저버를 안전하게 연결하고 사소한 추가/수정을 수행, ⚠️ 에이전트 - 플레이어 생명주기 관리는 위험을 감수하고 수정, ⚠️ API - 선별한 유틸리티를 사용해 처음부터 직접 통합을 작성하세요. 아래 설명된 대로 핸들러는 서버 및 클라이언트 에이전트가 내보내는 모든 이벤트를 관찰할 수 있습니다. {% hint style="warning" %} 익숙해지세요 [매치메이킹 심화](/docs.edgegap.com-ko/learn/matchmaking/matchmaker-in-depth.md) 사용자 지정하기 전에 개념을. {% endhint %} ### 이벤트 관찰 그룹 클라이언트는 상위 핸들러가 관찰하고 처리할 수 있도록 이벤트(액션)를 내보냅니다. 관찰 가능한 항목에서 내보내는 이벤트 미리 보기 `모니터` :
액션 유형이벤트 메시지설명
🟢 업데이트 정상모든 시스템 정상입니다.
🟢 업데이트 비정상예기치 않은 문제.
🔴 오류모니터 가져오기에 실패잘못된 설정 또는 예기치 않은 문제.
🔴 오류비콘 가져오기에 실패예기치 않은 문제.
관찰 가능한 항목에서 내보내는 이벤트 미리 보기 `그룹`:
액션 유형이벤트 메시지설명
🟢 업데이트 생성됨그룹이 정상적으로 생성되었습니다.
🔴 오류그룹 생성 실패그룹 생성에 실패했습니다.
🟢 업데이트 참가됨그룹에 정상적으로 참가했습니다.
🔴 오류그룹 참가 실패그룹에 참가하지 못했습니다.
🟢 업데이트 재개됨그룹이 정상적으로 재개되었습니다.
🔴 오류그룹을 찾을 수 없음그룹의 멤버가 아니거나 그룹이 만료되었습니다.
🔴 오류충돌, 포기 후 재시작새 그룹을 생성/참가하기 전에 현재 그룹을 포기하세요.
🟢 업데이트 멤버 업데이트됨 [{ready}]멤버가 새 Ready 값으로 업데이트되었습니다.
🔴 오류멤버 업데이트 실패그룹이 매치 검색을 시작한 후에는 그룹 멤버를 업데이트하지 못했습니다. 준비 완료를 해제할 수 없습니다.
🔵 알림폴링 중 [{consecutive}/{maximum}]클라이언트가 그룹 상태 폴링을 시작했습니다.
🔵 알림폴링 중지됨클라이언트가 티켓 상태 폴링을 중지했습니다.
🔴 오류폴링 실패, 최대 재시도 횟수에 도달클라이언트가 연속 폴링 재시도 최대 횟수를 모두 소진했습니다. 서비스 상태를 확인하세요.
🔴 오류폴링 실패클라이언트가 폴링 중 재시도 불가능한 오류를 받았습니다. 서비스 상태를 확인하세요.
🟢 업데이트 그룹 업데이트됨 [{status}]폴링 중 그룹 상태 변경이 감지되었습니다.
🟢 업데이트 포기됨티켓이 정상적으로 삭제되었습니다.
🟢 업데이트 포기 실패(찾을 수 없음)클라이언트가 삭제할 티켓을 찾지 못했습니다. 만료되었을 수 있습니다.
🟡 경고포기 실패(이미 매칭됨)클라이언트가 매칭된 그룹을 삭제할 수 없었습니다. 포기를 비활성화하거나 /pages/9b10ade5b00c98930860db62005218f1d0bc81d1#backfill-match 플레이어를 대체하세요.
🔴 오류포기 실패그룹 또는 멤버십을 삭제하지 못했습니다.
🟢 업데이트 삭제됨그룹이 만료되었으며 로컬 참조가 삭제되었습니다.
[^1]: 데이터 전송 객체 [^2]: [인터넷 서비스 제공업체](https://en.wikipedia.org/wiki/Internet_service_provider) [^3]: 특히 중국이나 러시아 --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.edgegap.com/docs.edgegap.com-ko/unity/matchmaking.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.