매치메이킹

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

💡 기능

• 완전한 예제

• 핑 자동화

• 티켓, 그룹, 팀

• 매치 변수

• 형식 정의(C#)

• 로컬 개발 테스트

• 크로스 플랫폼

• 손쉽게 사용자 지정 가능

• 자동 재시도

✔️ 준비

🍀 시작하기

이 가이드는 다음에 대한 기본 지식이 있다고 가정합니다 매치메이킹 개념과 실행 중인 Matchmaker.

이 문서를 읽으면서 코드를 함께 따라하려면 우리의 Simple Example을 가져오는 것을 강력히 권장합니다 이 문서를 읽으면서 코드를 따라 할 수 있습니다. 다음에서 할 수 있습니다 Unity Package Manager > Edgegap SDK > Samples .

개요

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

• 런타임 파일 - 클라이언트 및 서버 빌드와 함께 컴파일되어 번들됩니다:

  • 서비스별 유틸리티:

    • 매치메이킹 - 재사용/확장할 수 있는 완전한 클라이언트 통합.

    • API 함수 - 엔드포인트 정의, 오류 처리, 로깅 자동화.

  • 서비스별 DTO - Matchmaking API용 형식 지정 데이터 컨테이너.

  • 공유 유틸리티 - 로깅, HTTP, 핑, 옵저버블 등...

  • 공유 DTO - 여러 Edgegap 서비스에서 데이터를 전달하는 데 사용됩니다.

• 샘플 파일 - 프로젝트에 가져온 경우에만 번들되고 컴파일됩니다:

  • 매치메이킹 - 다음을 위한 예제 핸들러: 최소 구성.

  • 매치메이킹 - 수동 지역 선택이 포함된 UI 통합을 살펴보세요.

그룹 클라이언트

핑 자동화, 티켓 관리, 호스트 조회 는 그룹 클라이언트가 수행합니다.

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

• onMonitorUpdate 콜백 - 서비스 상태 변화를 관찰합니다,

• onAssignmentUpdate 콜백 - 호스트 할당 변경을 관찰하고 이에 반응합니다.

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

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

• 비콘 사용 가능한 목록을 가져오기 위해 Ping Beacons,

• MeasureBeaconsRoundTripTime 지정된 비콘 집합에 대한 핑 측정을 제공하기 위해,

• CreateGroup 로비 리더가 친구를 초대할 수 있는 참여 가능한 그룹을 생성하기 위해,

• JoinGroup 서드파티 로비/백엔드를 통해 전달된 그룹 ID로 기존 그룹에 참여하기 위해,

• SetReady 그룹 소유자와 멤버를 준비 완료로 표시하고 매치 검색을 시작하기 위해,

• ResumeMatchmaking 클라이언트가 충돌한 경우 캐시된 그룹을 불러와 검색을 계속하기 위해,

• StopMatchmaking (매치되지 않은 경우) 티켓을 삭제하고 대기열을 이탈하기 위해,

• 상태 Server Browser 서비스 상태를 확인하기 위해.

새 플레이어 연결이 설정되면 플레이어는 netcode를 사용하여 티켓 ID를 게임 서버로 보내 연결을 다음과 연관시키는 것이 अपे됩니다: 심층 살펴보기.

예기치 않은 충돌 시 다시 연결할 수 있도록 연결 세부 정보를 클라이언트나 게임 백엔드에 저장하세요.

🧪 샘플

서버와 클라이언트 모두를 위한 완전하게 동작하는 통합이 포함된 샘플로 시작해 보세요.

간단한 예제

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

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

지역 선택기

일부 플레이어(또는 그룹)는 다음과 같은 특별한 지역적 조건을 가집니다( ISP 차단, 국가 단위 차단, 또는 기타) 때문에 핑만이 아니라 수동으로 지역을 선택하길 원할 수 있습니다.

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

⚙️ 사용자 지정

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

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

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

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

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

다음에 익숙해지세요 매치메이킹 심층 맞춤 설정을 하기 전에 관련 개념에 대해.

이벤트 관찰

그룹 클라이언트는 상위 핸들러가 관찰하고 처리할 수 있도록 이벤트(동작)를 내보냅니다.

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

동작 유형	이벤트 메시지	설명
🟢 업데이트	정상	모든 시스템 정상.
🟢 업데이트	비정상	예기치 않은 문제.
🔴 오류	모니터 가져오기 실패	잘못된 구성 또는 예기치 않은 문제.
🔴 오류	비콘 가져오기 실패	예기치 않은 문제.

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

동작 유형	이벤트 메시지	설명
🟢 업데이트	생성됨	그룹이 정상적으로 생성되었습니다.
🔴 오류	그룹 생성 실패	그룹 생성에 실패했습니다.
🟢 업데이트	참여됨	그룹 참여가 정상적으로 완료되었습니다.
🔴 오류	그룹 참여 실패	그룹에 참여하지 못했습니다.
🟢 업데이트	재개됨	그룹이 정상적으로 재개되었습니다.
🔴 오류	그룹을 찾을 수 없음	그룹 멤버가 아니거나 그룹이 만료되었습니다.
🔴 오류	충돌, 이탈 후 다시 시작	새 그룹을 생성/참여하기 전에 현재 그룹에서 먼저 이탈하세요.
🟢 업데이트	멤버가 업데이트됨 [{ready}]	멤버의 Ready 값이 새로 업데이트되었습니다.
🔴 오류	멤버 업데이트 실패	그룹 멤버를 업데이트하지 못했습니다.
🔵 알림	폴링 중 [{consecutive}/{maximum}]	클라이언트가 그룹 상태 폴링을 시작했습니다.
🔵 알림	폴링 중지됨	클라이언트가 티켓 상태 폴링을 중지했습니다.
🔴 오류	폴링 실패, 최대 재시도 횟수에 도달함	클라이언트가 연속 폴링 최대 재시도 횟수를 모두 소진했습니다. 서비스 상태를 확인하세요.
🔴 오류	폴링 실패	클라이언트가 폴링 중 재시도 불가능한 오류를 받았습니다. 서비스 상태를 확인하세요.
🟢 업데이트	그룹이 업데이트됨 [{status}]	폴링 중 그룹 상태 변경이 감지되었습니다.
🟢 업데이트	이탈됨	티켓이 정상적으로 삭제되었습니다.
🟢 업데이트	이탈 실패(찾을 수 없음)	클라이언트가 삭제할 티켓을 찾을 수 없습니다. 만료되었을 수 있습니다.
🟡 경고	이탈 실패(이미 매치됨)	클라이언트가 매치된 그룹을 삭제할 수 없습니다. 이탈을 비활성화하거나 심층 살펴보기 플레이어를 교체하세요.
🔴 오류	이탈 실패	그룹 또는 멤버십 삭제에 실패했습니다.
🟢 업데이트	삭제됨	그룹이 만료되어 로컬 참조가 삭제되었습니다.