# 심층 살펴보기 Edgegap의 코드 없는 매치메이커 개념을 심층적으로 알아보고 필요에 맞게 커스터마이즈하세요. ## ✔️ 소개 **5분 이내에 시작하고 모든 기능을 무료로 테스트하세요. 신용카드는 필요하지 않습니다.** 더 강력한 프라이빗(전용) 클러스터가 필요해지면 업그레이드하세요. Edgegap과의 기본 통합은 [배포](/docs.edgegap.com-ko/learn/orchestration/deployments.md) 플레이어가 어디에 있든 최고의 ping을 제공합니다. {% hint style="info" %} 무료 플랜은 재시작 후마다 3시간의 실행 시간을 허용합니다. 매치메이커는 제한된 리소스를 사용하는 공유 인프라에서 실행되며, 테스트에 적합합니다. **공개 출시 후에는 매치메이커가 24/7 실행되어야 합니다.** {% endhint %} 각 매치메이커에는 세 가지 핵심 개념이 있습니다: * [#hosting-cluster](#hosting-cluster "mention") - Edgegap이 완전히 관리하고 운영하는 기반 서버 인프라. * [#configuration](#configuration "mention") - 매치메이커의 작동 방식을 정의하는 규칙과 설정의 집합. * 🌐 서비스 인스턴스 **-** 클러스터에서 24/7 실행되는 라이브 매치메이킹 서비스로, 설정을 사용해 플레이어를 매칭하고 배포(서버) 할당을 생성합니다. {% hint style="success" %} [매치메이커 버전을 자주 업데이트하세요](#changelog) 을 **새 기능과 버그 수정의 이점을 누리세요.** {% endhint %} ## ▶️ 매치메이킹 시작 **빠르게 시작하세요 - 게임에 SDK 시작 샘플을 추가하세요**: 게임 통합을 커스터마이즈하고, 문제를 해결하고, 최적화하는 데 필요한 매치메이킹 프로세스를 알아보세요:

매치메이킹 시퀀스

1. [플레이어 인증](#authenticate) - 불법 복제본이 온라인 플레이를 하는 것을 방지합니다, 2. [로비 생성](#create-group) - 친구와 함께 참여하고 플레이어/매치 선호도를 공유합니다, 3. [**그룹 구성**](#group-up) **- 로비를 매치메이킹 그룹으로 등록합니다,** 4. [**매치 찾기**](#find-match) **- 준비하고 매치를 찾기 시작합니다(새 매치 또는 기존 매치),** 1. 서버 할당 및 티켓 주입 - 몇 초 후 서버가 자동으로 할당됩니다, 5. [**연결 및 인증**](#connect-to-server) **- 게임 서버에 안전하게 연결을 시도합니다,** 1. 신원 확인 - 서버가 제3자 토큰을 사용해 게임 클라이언트의 신원을 검증합니다, 2. 플레이어 수락 또는 킥 - 서버가 플레이어의 참여 허용 여부를 결정합니다. ### 인증 {% hint style="success" %} **이 토큰은 Edgegap API 접근 권한을 부여하지 않으므로 게임 클라이언트에 안전하게 포함할 수 있습니다.** {% endhint %} 개별 플레이어는 클라이언트와 서버에서 사용할 수 있는 티켓 ID로 식별할 수 있습니다. 선택적으로, [#server-to-server-api](#server-to-server-api "mention") API를 사용해 커스텀 프록시로 맞춤 인증 또는 제한을 추가하세요. ### 그룹 구성 그룹(파티)을 생성하면 플레이어가 친구들과 같은 팀과 서버에 합류할 수 있습니다. {% hint style="success" %} 그룹을 생성하고 준비 상태로 표시하면 [#find-match](#find-match "mention") 빠르게 **솔로 플레이어로서 그룹 멤버 없이**. {% endhint %}

그룹 생명주기 활동 다이어그램

#### 로비와 그룹 게임 설계에 플레이어가 제어하는 매치메이킹 선호도(예: 캐릭터 선택, 난이도, 맵 등)를 설정해야 한다면 로비 서비스를 사용하세요. 플레이어가 로비에 들어오고 나가면서 나중에 매치를 찾을 수 있도록 매치메이킹 그룹도 함께 업데이트합니다. {% hint style="success" %} **로비 서비스를 구현할 시간이 없으신가요?** Discord나 DM을 통해 그룹 ID를 공유하도록 플레이어를 안내하세요. {% endhint %}
게임 설계 - 기능 / 요구사항사전 매치 로비매치메이커 그룹
함께 플레이할 친구 초대✅✅
내 플레이어/매치 선호도 수정✅❌
다른 로비 멤버의 선호도 보기✅❌
커스텀 키-값 데이터 저장 및 관리✅❌
내가 플레이 준비가 되었음을 그룹 멤버에게 알림❌✅
매치메이킹 진행 상황 표시 및 매치 찾기❌✅
플레이어/그룹의 팀 할당 가져오기❌✅
게임 서버 연결 정보 가져오기❌✅
당사의 크로스플랫폼 매치메이커는 모든 상용 및 커스텀 로비 서비스를 지원합니다:
로비 서비스(제3자)Unreal EngineUnityPC콘솔VR/XR모바일
Epic Online Services 로비
(Epic Games)		truetruetruetruetruetrue
Steamworks 로비
(Valve Corporation)		truetruetruetruetruetrue
Nakama 그룹
(Heroic Labs)		truetruetruetruetruetrue
Playfab 로비
(Microsoft)		truetruetruetruetruetrue
brainCloud 로비
(bitHeads)		truetruetruetruetruetrue
Gamekit Friends
(Apple)		truetruefalsefalsefalsetrue
커스텀 로비
(귀사)		truetruetruetruetruetrue
로비 소유자(초대를 보내는 플레이어)는 매치메이킹 그룹도 생성해야 합니다. **공유 로비 데이터에 그룹 ID를 저장하세요**그러면 다른 로비 멤버가 제3자 로비와 연결된 매치메이킹 그룹을 쉽게 찾고 참여할 수 있습니다. 그룹에 초대된 플레이어는 그룹 ID를 사용해 **멤버십(가입)을 생성하고**또한 **안전하게 저장합니다.** [**매치메이킹 속성**](#matchmaking-rules)**.** {% hint style="warning" %} **그룹이 매치메이킹을 시작하면 더 이상 참여할 수 없습니다.** [#abandon-queue](#abandon-queue "mention") 그리고 새 그룹을 생성하세요. {% endhint %} #### Ping 최적화 만약 [#configuration](#configuration "mention") 포함한다면 [`지연 시간` 규칙](#rule-example-elo_rating) 모든 그룹 멤버가 자신의 [핑 비콘](/docs.edgegap.com-ko/learn/orchestration/ping-beacons.md) 측정값을 전송하여 **먼 지역의 플레이어가 매칭되는 것을 방지합니다** 또는 훨씬 더 높거나 낮은 ping(지연 시간)을 가진 경우를 방지합니다. {% code title="예시 게임 클라이언트 ping 측정값(밀리초)" %} ```json { "Chicago": 224.4, "Frankfurt": 23.2, "Tokyo": 167.4 } ``` {% endcode %} #### **대기열 포기** 그룹 소유자는 그룹을 삭제할 수 있으며, 그러면 모든 그룹 멤버십이 자동으로 삭제됩니다. 매치메이킹 시작 후 그룹을 삭제하면 모든 멤버십이 취소되고, 잠시 후 삭제됩니다. 그룹 멤버(소유자 제외)는 [#find-match](#find-match "mention")이전까지 언제든지 멤버십을 삭제(그룹 나가기)할 수 있습니다. 이후 멤버십을 삭제하면 전체 그룹의 매치메이킹이 취소됩니다. {% hint style="info" %} 매치메이킹이 취소되면, 멤버는 [매치메이킹에서 자동으로 제거되고](#matchmaking-profiles) 멤버십을 통해 알림을 받습니다 `status:CANCELLED` 다음 상태 폴링 응답에서. {% endhint %} 취소 후 그룹이 매치메이킹을 다시 시작하려면, 그룹 소유자가 그룹을 다시 생성하고 새 그룹 ID를 멤버들에게 공유한 뒤, 멤버들이 멤버십을 다시 생성해야 합니다. **매치가 발견되면 그룹은 삭제할 수 없고** (`409 충돌`), 그리고 [자동으로 제거됩니다](#connect-to-server). 서버는 플레이어가 연결할 시간을 어느 정도(예: 60초) 허용한 뒤 플레이어 이탈로 간주해야 합니다. 서버가 플레이어를 이탈로 표시하면 다음과 같이 할 수 있습니다: * 이탈자를 AI 캐릭터로 대체하여 즉시 매치를 시작하거나, * 또는 [백필](#backfill-match) 을 생성해 이탈자를 대체할 새 플레이어를 찾거나, * 또는 게임 설계가 가변 플레이어 수를 허용한다면 이탈자를 대체하지 않고 진행합니다. ### 매치 찾기 매치를 찾기 시작하려면 모든 멤버와 소유자가 준비 상태로 표시되어야 합니다. {% hint style="success" %} 그룹 소유자가 **즉시 매치메이킹을 시작하도록 하려면, 생성 시 멤버십을 준비 상태로 설정하세요**. 소유자가 자신을 준비 상태로 표시하면 모두가 준비되었으므로 매치메이킹이 시작됩니다. {% endhint %} {% hint style="info" %} 최상의 경험을 위해 **게임 내 UI를 사용해 플레이어에게 상태 업데이트를 제공하세요**. {% endhint %} **모든 플레이어는 정기적인 간격으로 멤버십을 폴링해야 합니다** (권장 3\~5초) 매치메이킹 시작을 감지하고, 게임 내 UI를 통해 매치메이킹 진행 상황을 전달하기 위해. 플레이어는 **멤버십과 그룹 ID를 영구적으로 저장해야 합니다**, 게임 클라이언트 충돌 시 게임을 재시작하고 매치메이킹 진행 상황을 잃지 않고 재개할 수 있게 합니다. 우리가 귀하의 [#matchmaking-rules](#matchmaking-rules "mention")를 준수하면서 같은 팀에 넣을 충분한 플레이어를 찾으면, 플레이어는 멤버십 응답에서 `status:TEAM_FOUND`. 이 단계에서 멤버십을 삭제하면 모든 그룹 멤버십이 취소되고, 같은 팀에 할당된 다른 모든 그룹은 `status:SEARCHING` . 팀은 각 그룹의 겹치는 값을 사용하여 다른 팀과 계속 매치메이킹하며(또는 `number_difference` 의 경우 평균값을 사용), 충분한 팀이 구성될 때까지 진행합니다. 멤버십은 응답에서 이를 `status:MATCH_FOUND` 로 표시하며, 이는 귀하의 [배포가 시작되고 있음을 의미합니다](https://docs.edgegap.com/docs.edgegap.com-ko/learn/matchmaking/pages/1e75126474c80b6c476cbd5e97b171fce5779d47#id-1.-start-a-deployment). **매치메이커는 매치 충원율을 최대화하는 것을 목표로 하며, 다음 조건 중 하나가 충족될 때까지 `MATCH_FOUND` 로 진행하지 않습니다:** 1. 구성된 최대 팀 크기로 충분한 팀이 매치되었거나, 2. 또는 [#rule-expansion](#rule-expansion "mention") 정의됨 AND 확장 시간이 도달했고, 구성된 최소 팀 크기로 충분한 팀이 매치되었거나, 3. 또는 구성된 티켓 만료 시간이 경과했고 구성된 최소 팀 크기로 충분한 팀이 매치되었을 때. 두 시나리오 모두 구성된 티켓 만료 이전에 성공하지 못하면 그룹과 티켓은 취소됩니다. {% hint style="info" %} 테스트 중 또는 인기 없는 지역의 플레이어로 인해 대기열 시간이 길어지나요? 더 짧은 티켓 만료 기간(예: 30초)을 설정하고, 만료 시 클라이언트 측에서 그룹(또는 티켓)을 다시 생성하세요. {% endhint %} 티켓 만료는 그룹(또는 플레이어)이 팀에 매칭될 때마다 자동으로 초기화됩니다. {% hint style="success" %} 저장 `team_id` 및 `match_id` 를 게임 백엔드에 저장하여 게임 내에서 팀 멤버 정보를 표시하세요. {% endhint %} {% hint style="info" %} 모든 플레이어는 **고유한 티켓 ID를 받으며, 이는** [#authenticate](#authenticate "mention") **게임 서버와 함께 사용할 수 있습니다.** {% endhint %} 플레이어가 매치되어 게임 서버에 할당되면 티켓은 자동으로 삭제됩니다. 이후 대기열을 포기한 플레이어는 `status:HOST_ASSIGNED` 에서 [백필](#backfill-match). 플레이어가 받으면 `status:HOST_ASSIGNED` 그들은 다음으로 진행합니다 [#connect-to-server](#connect-to-server "mention"). ### 서버에 연결 ### 백필 매치 게임 서버 초기화가 끝나면 **서버는**: * **각 새 플레이어에 대한 이탈 타이머를 시작해야 합니다.** 연결된 플레이어에게 로딩 씬/레벨로 로딩 진행 상황을 보여주는 것을 권장합니다. 완전한 3D 씬, 로비와 유사한 소셜 UI, 또는 진행 바가 있는 로딩 화면이 될 수 있습니다. * **새 플레이어 연결 또는 기존 플레이어 이탈을 시간에 따라 추적하세요**: 1. 새 플레이어는 인증과 연결을 매치메이커에 매핑하기 위해 티켓 ID를 서버에 알려야 합니다 [#injected-variables](#injected-variables "mention") 또는 `assigned_ticket` (백필된 경우). 2. 서버 수명 동안 사용되지 않은 플레이어 용량(이탈자)을 위한 새 백필을 생성하세요. 3. 만료된 백필을 갱신하세요. 이는 다음 이후 삭제됩니다 `ticket_expiration_period`. * **남아 있는 백필을 정리(삭제)하세요** 다음 시점에 [/pages/1e75126474c80b6c476cbd5e97b171fce5779d47#id-5.-deployment-stopped](https://docs.edgegap.com/docs.edgegap.com-ko/learn/matchmaking/pages/1e75126474c80b6c476cbd5e97b171fce5779d47#id-5.-deployment-stopped "mention"): * Unity - [`OnApplicationQuit`](https://docs.unity3d.com/6000.0/Documentation/ScriptReference/MonoBehaviour.OnApplicationQuit.html) 콜백 또는 커스텀 게임 종료 콜백에서, * Unreal Engine - [`OnWorldDestroyed`](https://forums.unrealengine.com/t/call-function-before-quit-game/344954/2) , [`PreExit`](https://forums.unrealengine.com/t/event-on-close/298087/2) 또는 커스텀 게임 종료 콜백에서. 유효한 서버 할당과 최소 하나의 티켓만 제공되면 어떤 프로필이든 백필에 사용할 수 있습니다. 최소 예시는 [매치메이킹](/docs.edgegap.com-ko/learn/matchmaking.md#backfill-showcase) 을(를) 참조하세요. ## ⚙️ 설정 매치메이커 API는 새 매치메이커(또는 빠른 재시작)를 생성할 때 지정한 JSON 설정에서 생성됩니다. 서로 다른 규칙과 확장을 가진 여러 개의 프로필을 지정할 수 있습니다: {% hint style="success" %} 를 참조하세요 [매치메이킹](/docs.edgegap.com-ko/learn/matchmaking.md) SDK와 상세 예제 시나리오는 {% endhint %} {% hint style="warning" %} 실행 중인 매치메이커를 편집하면 **빠른 재로드가 트리거되고**모든 티켓이 삭제되며 짧은 다운타임이 발생합니다. {% endhint %} ### 프로필(대기열) 프로필은 동일한 매치메이커 버전을 공유하는 완전히 분리된 매치메이킹 대기열을 나타냅니다. 매치메이커마다 **원하는 수의 프로필을 구성할 수 있습니다.** 플레이어 기반을 여러 프로필로 나누면 플레이어의 대기 시간이 더 길어질 수 있습니다. 각 매치메이커 프로필은 [앱 버전](/docs.edgegap.com-ko/learn/orchestration/application-and-versions.md) 을 템플릿으로 사용해 새 배포(서버)를 시작합니다. {% hint style="success" %} 일부 게임 모드는 더 많은 vCPU / RAM을 필요로 할 수 있으며, 특히 더 많은 플레이어를 지원하는 경우 그렇습니다. 각 **매치메이커에는 여러 프로필이 포함될 수 있으며**각 프로필은 조정된 리소스를 가진 앱 버전에 연결됩니다. {% endhint %} ### 규칙 모든 플레이어와 그룹은 매치메이킹 대기열에 참여하고 `초기` 규칙을 사용해 먼저 매치를 찾습니다. 경로 `.rules.initial` 의 프로필 내 각 항목은 하나의 규칙을 나타내며, 여기서: * **key** 는 규칙 이름을 원하는 대로 지정할 수 있는 문자열 값입니다. 예: `match_size` , 그리고 * **value** 는 표준 규칙셋을 따르는 규칙의 유형과 속성을 정의하는 객체입니다. {% hint style="info" %} 호스트 할당을 시작하고 배포를 시작하거나 찾으려면 모든 규칙이 동시에 충족되어야 합니다. {% endhint %} **연산자(규칙 유형)** **`player_count`** 은 할당을 시작하기 위해 몇 명의 플레이어가 매칭되어야 하는지를 정의하는 특수 규칙입니다. {% hint style="warning" %} 규칙 `player_count` **은 필수이며 한 번만 정의할 수 있습니다** 초기 설정 규칙에서. {% endhint %} 매치메이커는 항상 매치 충원율을 최대화하려고 하며, 지정된 `max_team_size` : 1. 최대 팀 크기에 도달하면 매치는 즉시 생성됩니다, 2. 그렇지 않으면 플레이어는 대기열에서 [확장](#rule-expansion) (또는 만료)가 거의 도달할 때까지 매치를 채우기 위해 기다립니다, 3. 직전에 [확장되거나](#rule-expansion) 만료되기 직전, 부분 매치가 가능하면(≥ 최소 및 < 최대 팀 크기), 이 매치는 같은 확장 단계의 모든 플레이어와 함께 생성됩니다(다른 규칙이 통과한다고 가정). {% hint style="success" %} 협동, 프리 포 올, 또는 비대칭 팀 크기 게임 모드의 경우 `"team_count": 1` . {% endhint %} 경쟁 게임을 위해 여러 개의 균형 잡힌 팀을 구성하도록 팀 수를 설정할 수 있습니다: * **그룹 속성은 평균/겹침으로 계산됩니다** 그룹의 **플레이어 속성의,** * **팀 속성은 평균/겹침으로 계산됩니다** 팀의 **그룹 속성의.** 플레이어 4명의 고정 팀 크기를 가정하면:

예시 매치 시나리오

{% hint style="info" %} **그룹은 과충원 없이 팀에 매칭되며,** 오직 팀에 전체 그룹을 수용할 충분한 용량이 있을 때만 가능합니다. {% endhint %} **`string_equality`** 는 정확히 같은 문자열 값을 가진 플레이어를 매칭합니다.
규칙 예시: selected_game_mode `selected_game_mode` 규칙은 대소문자를 구분하여 플레이어를 매칭합니다: :white\_check\_mark: Alice + Bob + Dave는 매칭될 수 있지만, :x: Alice + Erin 또는 Charlie + Frank는 절대 매칭되지 않습니다. | "Free For All" | "Capture The Flag" | "capture the flag" | | -------------- | ------------------ | ------------------ | | Alice | Erin | Frank | | Bob | Charlie | | | Dave | | |
**`number_difference`** 는 서로의 절대 수치 차이 범위 내의 플레이어를 매칭합니다.
규칙 예시: elo_rating `elo_rating` 규칙은 다음과 함께 `"max_difference": 50` 처음에는: :white\_check\_mark: Alice + Bob는 매칭될 수 있고, Bob + Charlie도 매칭될 수 있지만, :x: Alice + Bob + Charlie는 절대 매칭되지 않습니다.
**`교집합`** 하나 이상의 겹치는 문자열 값을 가진 플레이어를 대소문자를 구분하여 매칭합니다.
규칙 예시: selected_map `selected_map` 규칙은 다음과 함께 `"overlap": 1` 다음과 매칭됩니다: :white\_check\_mark: Alice + Bob + Charlie는 매칭될 수 있고, Alice + Bob + Dave도 매칭될 수 있지만, :x: Alice + Bob + Charlie + Dave는 절대 매칭되지 않습니다.
#### 규칙 확장 선택적으로, **`확장`** 은 대기열에 머문 시간 후 규칙의 속성을 수정해 제한을 완화하고 매칭 가능한 플레이어 풀을 확장합니다, **그 결과 더 빠른 매치가 가능합니다**.
예시 시나리오: 확장 [처음에는 정확히 4명으로 구성된 1개 팀이 필요합니다(그룹으로 나뉠 수 있음)](/docs.edgegap.com-ko/learn/matchmaking.md#advanced-example) 다음 조건으로: * 같은(임의의 하나) 비콘에 대해 최대 125ms 지연 시간, * 같은 비콘의 최저/최고 값 사이 지연 시간 차이가 125ms 이하, * 최저 랭크 플레이어와 최고 랭크 플레이어 사이 실력 점수 차이가 50점 이하, * 정확히 같은(대소문자 구분) 선택된 게임 모드, * 플레이어 간 최소 하나의 일치하는 맵 선택(대소문자 구분), * 최소 하나의 일치하는 [백필 그룹 크기](#backfill-match) 값이 플레이어들 사이에 존재해야 합니다. 위 예시에서 우리는 **속성을 수정하여 검색을 확장합니다** 다음 이후:
30초:
  • 4명
  • 실력 점수 범위 150
  • 최대 250ms 지연
60초:
  • 4명
  • 실력 점수 범위 200
  • 최대 250ms 지연
3분(180초):
  • 1-4명
  • 실력 점수 범위 200
  • 모든 지연 시간
{% hint style="info" %} 어떤 규칙의 속성 확장이든 **이전 값을 덮어씁니다** 해당 속성의. {% endhint %} {% hint style="success" %} [매치메이킹에서 가장 흔한 함정을 알아보세요](https://edgegap.com/blog/how-session-fill-rate-affects-your-multiplayer-hosting-costs), 그리고 [우리의 팁으로 매치 충원율을 최적화하세요](https://edgegap.com/blog/how-to-optimize-session-fill-rate-in-your-matchmaker). {% endhint %} ## 📌 주입된 변수 서버는 플레이어에 대한 세부 정보를 알아야 할 수 있습니다. 플레이어 속성, 해결된 매치 값 및 기타 값은 일반적인 값과 함께 배포에 주입됩니다 [앱 및 버전](/docs.edgegap.com-ko/learn/orchestration/application-and-versions.md#injected-variables). 서식 없는 미리보기 **🏁 고급 예시 변수:** ``` MM_MATCH_PROFILE=advanced-example MM_EXPANSION=initial MM_TICKET_IDS=["cusfn10msflc73beiik0","cusfn18msflc73beiil0"] MM_TICKET_cusfn10msflc73beiik0={"id":"cusfn10msflc73beiik0","created_at":"2025-02-21T22:17:42.3886970Z","player_ip":"174.93.233.25","group_id":"b2080c27-19c9-4fb0-8fe7-4bf1e5d285d1","team_id":"cusfn1gmsflc73beiim0","attributes":{"beacons":{"Chicago":12.3,"LosAngeles":145.6,"Tokyo":233.2},"elo_rating":1337,"selected_game_mode":"quickplay","selected_map":["DustII","Airport","BankVault"],"backfill_group_size":["new","1"]}} MM_TICKET_cusfn18msflc73beiil0={"id":"cusfn18msflc73beiil0","created_at":"2025-02-21T22:17:42.2548390Z","player_ip":"174.93.233.23","group_id":"015d4dc8-6c79-4b5c-bbc6-f309b9787c8f","team_id":"cusfn1gmsflc73beiim0","attributes":{"beacons":{"Chicago":87.3,"LosAngeles":32.4,"Tokyo":253.2},"elo_rating":1339,"selected_game_mode":"quickplay","selected_map":["Island","Airport"],"backfill_group_size":["new","1"]}} MM_GROUPS={"b2080c27-19c9-4fb0-8fe7-4bf1e5d285d1":["cusfn10msflc73beiik0"],"015d4dc8-6c79-4b5c-bbc6-f309b9787c8f":["cusfn18msflc73beiil0"]} MM_TEAMS={"cusfn1gmsflc73beiim0":["b2080c27-19c9-4fb0-8fe7-4bf1e5d285d1","015d4dc8-6c79-4b5c-bbc6-f309b9787c8f"]} MM_MATCH_ID=advanced-example_initial-2025-02-21T22:17:43.3886970Z MM_INTERSECTION={"selected_map":["Airport"],"backfill_group_size":["new","1"]} MM_EQUALITY={"selected_game_mode":"quickplay"} ``` {% hint style="info" %} 환경 변수는 **문자열화된 JSON으로 저장되며**, SDK 또는 사용자 지정 방법을 사용해 파싱하세요. {% endhint %} {% hint style="success" %} **서버는 플레이어가 티켓 ID를 서버에 보낸 후** 플레이어 연결을 그룹 및 속성에 매핑할 수 있습니다. {% endhint %} ## 🧵 플레이어 추적 플레이어가 문제를 겪는 경우 서버 로그로의 경로를 추적하는 것이 도움이 될 수 있습니다. 각 매치메이커는 **배포** **는 할당된 플레이어 티켓 ID로 태그됩니다** 그래서 쉽게 [배포](/docs.edgegap.com-ko/learn/orchestration/deployments.md#filter-deployments) 찾을 수 있고 [배포](/docs.edgegap.com-ko/learn/orchestration/deployments.md#container-logs) 문제 해결에 도움이 됩니다. {% hint style="success" %} **클라이언트 매치 기록 UI에 티켓 ID와 배포 ID를 표시하세요** 문제 해결 시 플레이어를 추적하기 위해. {% endhint %} {% hint style="info" %} 를 참조하세요 [배포](/docs.edgegap.com-ko/learn/orchestration/deployments.md#connection-quality) 배포 문제 해결에 대해 알아보려면. {% endhint %} ## 👀 분석 코드나 설정 없이 매치메이커의 부하와 성능에 대한 인사이트를 얻으세요. 🌟 [**매치메이커를 Enterprise Tier로 업그레이드**](https://app.edgegap.com/matchmaker-management-v2/matchmakers/list) **하여 매치메이킹 지표와 인사이트를 잠금 해제하세요:**
## ☁️ 호스팅 클러스터 매치메이커는 Edgegap이 24/7 편리하게 호스팅하고 관리합니다. 목표에 가장 적합한 호스팅 옵션을 선택하세요: #### 프라이빗 클러스터 티어 한 번의 클릭으로 프라이빗 클러스터로 업그레이드하세요. 출시 후에도 플레이어 다운타임 없이 프라이빗 클러스터 티어를 변경할 수 있으며, [#rolling-updates-and-ab-tests](#rolling-updates-and-ab-tests "mention"). 관리형 클러스터는 공개 출시 게임을 위해 Edgegap이 유지 관리하는 고가용성 서비스 호스팅과 24/7 라이브 지원을 제공합니다. 인스턴스의 리소스 요구 사항은 다음 요인에 따라 달라집니다: * **플레이어 수** - 플레이어가 많을수록 티켓과 API 요청이 증가합니다, * **플레이어당 요청 수** - 재시도가 빠를수록 서비스 부하가 증가하고 리소스를 소모합니다, * **설정 복잡성** - 교차 규칙과 확장은 특히 요구가 큽니다, * **평균 매치 지속 시간** - 세션이 짧을수록 플레이어가 매치메이킹에 더 자주 다시 참여합니다, * **만료 및 제거 기간** - 오래된 티켓은 시간이 지나며 쌓여 리소스를 소모합니다, * **클라이언트 재시도 폴백 로직** - 지터가 적용된 백오프로 재시도하면 트래픽 폭증을 분산하는 데 도움이 됩니다. {% hint style="warning" %} **성공을 준비하고 출시 후 최적화하여 출시일에 플레이어가 막히지 않도록 하세요.** 다음을 사용하세요. [개발자 도구](/docs.edgegap.com-ko/unity/developer-tools.md#matchmaking-sdk) 또는 **지수적 지터 백오프를 구현하여** 높은 부하에서 복구하세요. {% endhint %} ### 속도 제한 클러스터가 버스트 용량을 초과해 다운되는 것을 방지하기 위해, 우리는 내부 부하 테스트를 기반으로 초당 요청 수를 제한합니다 [매치메이킹](/docs.edgegap.com-ko/learn/matchmaking.md#advanced-example) 구성을 사용해.
API 엔드포인트무료 플랜취미 개발자 플랜스튜디오 플랜엔터프라이즈 플랜
전체 제한1002007502,000
배포 생성5103030
비콘 목록 조회102075200
그룹 생성
+ 티켓 생성
+ 그룹 티켓 생성		102075200
멤버십 읽기
+ 그룹 읽기
+ 티켓 읽기		101204501,300
백필 생성51037100
속도 제한은 **지정된 API 엔드포인트 집합에 대한 초당 결합 요청 수로 표시됩니다**. 게임 클라이언트가 응답을 받은 후 요청을 재시도하지 않으면 `429 너무 많은 요청` **배포에 플레이어가 누락될 수 있습니다** 높은 부하 때문에 할당 읽기를 중단한 플레이어로 인해. #### 부하 테스트 매치메이킹과 할당에는 CPU와 메모리 사용이 필요하므로, 각 프라이빗 매치메이커에는 호스팅 비용이 발생합니다. 각 티어와 관련된 리소스와 가격은 [가격 페이지에서 확인하세요](https://edgegap.com/resources/pricing#matchmaker). {% hint style="success" %} **항상** [**프라이빗 클러스터를 사용하여**](#private-cluster-tiers) **스트레스 테스트를 수행하세요.** 무료 매치메이커는 개발 테스트 전용으로만 엄격하게 제한됩니다. {% endhint %} 부하 테스트를 설계할 때 **현실적인 플레이어 패턴을 고려해 주세요**: | 현실적인 시나리오 | 비현실적인 트래픽 패턴 | | --------------------------------------------------- | ------------------------------------------------- | | ✅ 플레이어는 점진적으로 매치메이킹에 참여하여, 몇 시간에 걸쳐 req/s가 증가합니다. | ❌ 모든 플레이어가 조정하여 정확히 같은 초에 티켓을 생성합니다. | | ✅ 플레이어는 재시도 사이에 점점 더 긴 시간을 기다립니다(예: 1초-5초-10초-10초). | ❌ 모든 플레이어가 응답을 받자마자 즉시 재시도합니다 `429 너무 많은 요청` 응답. | | ✅ 대부분의 플레이어는 짧은 시간(10\~60초) 내에 할당을 받고 폴링을 중단합니다. | ❌ 모든 플레이어가 할당을 받은 후에도 정해진 시간 동안 계속 폴링합니다. | | ✅ 대부분의 플레이어는 새로 매치메이킹을 시작하기 전에 게임을 끝냅니다(시간이 걸림). | ❌ 모든 플레이어가 할당을 받자마자 즉시 새로 매치메이킹을 시작합니다. | | ✅ 피크 트래픽은 하루 6\~8시간 동안 유지되며, 이후 일부 시간대의 트래픽이 줄어듭니다. | ❌ 최대 트래픽은 하루 24시간 지속되며, 모든 플레이어가 밤낮으로 플레이합니다. | 매치메이커에 높은 부하가 걸리면: * CPU가 스로틀링되면 매치메이킹이 느려질 수 있고, * 매치메이커가 메모리가 부족해지면 티켓 정보를 잃지 않고 재시작하며, 클라이언트가 지수 백오프를 구현하고 폭주가 더 긴 기간에 걸쳐 분산되기를 기대합니다. ## ⏩ 롤링 업데이트 서버와 클라이언트 버전 간의 호환성을 추적하는 일은 복잡해질 수 있습니다. 안정적인 릴리스, 업데이트, 그리고 다운타임이나 호환성 문제를 방지하기 위한 팁을 따라보세요. **매치메이커 URL과 인증 토큰은 재시작 후에도 항상 동일하게 유지됩니다.** {% hint style="danger" %} **개발용과 운영용으로 별도의 매치메이커를 만드세요** 환경에서 안전하게 실험할 수 있습니다. {% endhint %} #### ⚠️ **실서비스 전** 미리 매치메이커의 여러 복사본을 만들어 두는 것을 권장합니다: `green`, `blue` 및 `orange`. 업데이트를 배포할 때 사용 중인 매치메이커를 교체할 수 있습니다 ([blue/green 전략](https://en.wikipedia.org/wiki/Blue%E2%80%93green_deployment)). **지역별 장애 동안 다운타임을 방지하기 위해 각 인스턴스에 서로 다른 리전을 선택하세요** .

Blue/Green DevOps 환경 예시

#### **🔃 클라이언트 + 서버 업데이트** **필수 조건:** 이 섹션에서는 다음을 완료했다고 가정합니다 [#before-going-live](#before-going-live "mention"). 하기 위해 **게임 클라이언트 + 서버 업데이트를 배포하려면**, 다음을 할 수 있습니다: 1. 새 서버 앱 버전 준비 `v1.2.0-rc` Edgegap에서: 1. 컨테이너 레지스트리에 새 이미지 태그를 푸시합니다 `t1.2.0`, 2. 새 앱 버전을 생성합니다 `v1.2.0-rc`, 2. 다음으로 모든 개발 테스트를 수행합니다 [새 앱 버전을 배포하여](https://app.edgegap.com/deployment-management/deployments/list) `v1.2.0-rc`: 1. 게임 엔진의 에디터를 제공된 URL + 외부 포트에 연결합니다, 3. 사용하지 않는 매치메이커 업데이트 `blue` 새 이미지 태그에 연결하도록 `t1.2.0`, 1. 새 앱 버전의 캐싱을 활성화 `v1.2.0-rc` , 이 버전에 대해 캐싱을 활성화하면 이미지도 버전 `v-blue` 에 대해 캐시되도록 보장합니다. 왜냐하면 둘 다 같은 태그를 참조하기 때문입니다, 2. 버전에서 캐싱 표시가 `v1.2.0-rc` 이 될 때까지 기다립니다 :green\_circle: green, 4. 새 게임 클라이언트 업데이트 `c2` 를 새 버전 사용하도록 `v-blue` 티켓 생성 시: 1. 게임 클라이언트에서 기본 URL과 인증 토큰을 업데이트합니다, 5. 새 게임 클라이언트에 대해 QA 테스트와 최종 검증을 수행합니다 `c2`: 1. 문제를 발견하고 해결하면, 처음부터 과정을 반복합니다, 2. 매치메이커가 중지된 후 매치메이커 DNS 변경 사항이 전 세계 ISP에 전파되도록 3\~7일을 기다립니다(빠른 재시작은 DNS 업데이트나 대기 기간이 필요하지 않음), 6. 새 게임 클라이언트 업데이트를 배포합니다 `c2` 게임 배포 플랫폼에서, 7. 새 게임 클라이언트가 `c2` 플레이어 기기에 배포될 시간을 허용합니다(일반적으로 최대 3\~7일): 1. 구버전 게임 클라이언트를 모니터링합니다 `c1` 를 사용하여 배포 [배포](/docs.edgegap.com-ko/learn/orchestration/deployments.md#analytics), 8. Edgegap 계정의 사용하지 않는 리소스를 정리합니다: 1. 이미지 태그 삭제 `t1.0.0` 를 제거하여 Container Registry 용량을 확보합니다, 2. 이미지 태그 삭제 `t1.1.0` 를 제거하여 Container Registry 용량을 확보합니다, 3. 을 끕니다 `green` 다음 업데이트 전까지 청구를 일시 중지하려면 매치메이커를 끕니다. {% hint style="success" %} **다음 업데이트에서는**, 버전 번호를 올리고 `green` 및 `blue` 가이드의 키워드를 바꾸세요. {% endhint %} #### **⚡ 서버 핫픽스** **필수 조건:** 이 섹션에서는 다음을 완료했다고 가정합니다 [#before-going-live](#before-going-live "mention"). 하기 위해 **게임 클라이언트 업데이트 없이 서버 패치를 배포하려면**, 다음을 할 수 있습니다: 1. 새 서버 앱 버전 준비 `v1.2.0-rc` Edgegap에서: 1. 컨테이너 레지스트리에 새 이미지 태그를 푸시합니다 `t1.2.0`, 2. 새 앱 버전을 생성합니다 `v1.2.0-rc`, 2. 다음으로 테스트와 검증을 수행합니다 [새 앱 버전을 배포하여](https://app.edgegap.com/deployment-management/deployments/list) `v1.2.0-rc`: 1. 게임 엔진의 에디터를 제공된 URL + 외부 포트에 연결합니다, 2. 문제를 발견하고 해결하면, 처음부터 과정을 반복합니다, 3. 새 앱 버전의 캐싱을 활성화 `v1.2.0-rc` , 이 버전에 대해 캐싱을 활성화하면 이미지도 버전 `v-green` 나중에, 동일한 태그를 참조하게 되므로 4. 버전에서 캐싱 표시가 `v1.2.0-rc` 이 될 때까지 기다립니다 :green\_circle: green, 3. 버전 업데이트 `v-green` 새 이미지 태그에 연결하도록 `t1.2.0`, 1. 새 매치는 업데이트된 태그로 자동으로 할당을 시작합니다 `t1.2.0`, 2. 구버전 게임 클라이언트를 모니터링합니다 `c1` 를 사용하여 배포 [배포](/docs.edgegap.com-ko/learn/orchestration/deployments.md#analytics), 4. Edgegap 계정의 사용하지 않는 리소스 정리: 1. 이미지 태그 삭제 `t1.1.0` Container Registry 용량을 확보합니다. ## 📗 API 클라이언트와 서버는 API를 직접 호출하거나 게임 엔진 SDK를 사용하여 호출할 수 있으며, 또한 다음을 참조하세요 [매치메이킹](/docs.edgegap.com-ko/learn/matchmaking.md). ### 서버 간 매치메이킹 흐름에 대한 향상되거나 사용자 지정된 제어를 추가하세요 - 우리의 [관리형 클러스터](/docs.edgegap.com-ko/learn/advanced-features/managed-clusters.md) 또는 어떤 클라우드 FaaS[^2] 컴퓨팅 플랫폼을 사용하여 다음 중 어떤 것이든 달성할 수 있습니다: * 치터 플래그, 스킬 등급 등 민감한 플레이어 속성을 연결합니다, * 게임 내에서 팀 및 매치 컨텍스트를 제공합니다 - 로딩 중에 팀원과 상대를 나열합니다, * 특정 예외 사례를 제한합니다 - 예: 한 번에 플레이어당 그룹 1개만 허용, * 캐싱 또는 API 레이트 리미팅을 추가합니다 - 요청 수와 매치메이커 부하를 줄입니다, * 로비-그룹 통합을 사용자 지정합니다 - 매치메이킹 전에 비대칭/역할 기반 로비를 만듭니다. {% hint style="success" %} **매개변수 포함 `player_ip` 멤버의 공용 IP 주소와 함께** 최대한 낮은 플레이어 지연 시간을 보장하고 다음의 이점을 활용하기 위해 [/pages/1e75126474c80b6c476cbd5e97b171fce5779d47#id-1.-server-score-strategy-best-practice](https://docs.edgegap.com/docs.edgegap.com-ko/learn/matchmaking/pages/1e75126474c80b6c476cbd5e97b171fce5779d47#id-1.-server-score-strategy-best-practice "mention"). {% endhint %} {% hint style="info" %} 게임 클라이언트는 [ipify.org](http://ipify.org/) 의 무료 서비스를 사용하여 공용 IP를 찾을 수 있습니다. VPN은 공용 IP 주소를 가릴 수 있습니다. {% endhint %}

서버 간 매치메이킹 활동 다이어그램

#### 교차 출처 리소스 공유(CORS) 제3자 배포 플랫폼(예: [itch.io](http://itch.io/))에서 호스팅되는 WebGL 게임의 경우, 게임 클라이언트에서 매치메이커로 요청을 보내면 [교차 출처 리소스 공유](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) 정책 위반이 발생할 수 있습니다. 최신 웹 브라우저 대부분은 백엔드 서비스(매치메이커)가 게임 클라이언트와의 통신을 이해하고 수락하는지 확인하기 위해 [사전 요청](https://developer.mozilla.org/en-US/docs/Glossary/Preflight_request) 을 보냅니다. 사전 요청 검사에 실패하면(보안상의 이유로 기본값) [여러 가능한 CORS 관련 오류 중 하나가 발생할 수 있으며](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS/Errors/CORSMissingAllowOrigin), 가장 흔한 것은 `CORS 헤더 'Access-Control-Allow-Origin' 누락` . 이 오류를 해결하려면 **`allowed_cors_origin`** 매개변수를 설정에 추가하여 다음 중 하나로 만드세요: * 정확한 클라이언트 호스팅 도메인을 화이트리스트에 추가합니다:
🍀 간단한 예시(특정 도메인 예시) 
{
  "version": "3.2.3",
  "allowed_cors_origins": [
    "https://dev.my-game-server.com",
    "https://prod.my-game-server.com"
  ],
  "profiles": {
      ...
  }
}
* 또는 와일드카드 도메인(모든 하위 도메인 포함)을 화이트리스트에 추가합니다:
🍀 간단한 예시(와일드카드 도메인 예시) 
{
  "version": "3.2.3",
  "allowed_cors_origins": ["https://*.my-game-server.com"],
  "profiles": {
      ...
  }
}
{% hint style="info" %} **도메인이 올바르게 구성되어 있다면 매치메이커 사전 요청에는 자격 증명이 필요하지 않습니다**, {% endhint %} ## 🚨 문제 해결 **여러분의 성공이 우리의 최우선입니다.** 사용자 지정 요청을 보내거나, 누락된 중요한 기능을 요청하거나, 생각을 공유하고 싶다면, [커뮤니티 Discord에 문의해 주세요](https://discord.gg/MmJf8fWjnt).
새 매치메이커를 만들려고 할 때 오류가 발생하는 이유는 무엇인가요? * 오류를 읽어보세요. 식별자, 규칙 또는 연산자를 잘못 철자했을 수 있습니다. - [JSONLint](https://jsonlint.com/) 을 사용해 JSON 형식을 검증하세요. 쉼표나 대괄호를 빠뜨렸을 수 있습니다. - [커뮤니티 Discord](https://discord.gg/MmJf8fWjnt) 를 통해 도움을 요청해 주세요. 기꺼이 도와드리겠습니다. 🙏
왜 제 매치메이커가 3시간 후에 자동으로 꺼졌나요? * 무료 티어의 매치메이커는 초기 테스트용이며 3시간 후 자동으로 꺼집니다. 테스트를 계속하려면 다음을 할 수 있습니다 [매치메이커를 재시작하세요](https://app.edgegap.com/matchmaker-management-v2/matchmakers/list). * 무제한 실행 시간을 위해 유료 티어로 업그레이드하는 것을 고려하세요.
왜 제 계정에서 두 번째 배포를 시작할 수 없나요? * 무료 티어에서는 동시에 1개의 배포만 실행할 수 있습니다. * 무제한 배포를 위해 유료 티어로 업그레이드하는 것을 고려하세요.
왜 제가 무작위 시간에 할당/배포를 받는지, 다음을 무시하고 player_count? * 이전 테스트 세션 동안 귀하 또는 다른 팀원이 할당되지 않은 티켓을 생성했을 수 있습니다. 다음을 해주세요 [매치메이커를 재시작하세요](https://app.edgegap.com/matchmaker-management-v2/matchmakers/list).
내 티켓이 다음 상태에서 멈췄습니다 SEARCHING . * 설정에 맞는 티켓을 충분히 생성했는지 확인해 주세요.
내 티켓이 다음 사이를 반복해서 전환하며 멈췄습니다 MATCH_FOUND 및 TEAM_FOUND 를 반복합니다. * 무료 티어 계정은 동시에 1개의 배포로 제한됩니다. * 업그레이드를 고려하거나 현재 배포를 중지한 후 새 배포를 시작하세요.
내 티켓이 바로 다음으로 갑니다 CANCELLED. * 티켓의 유효 기간이 만료되었습니다. 새 티켓을 만들거나 테스트 목적으로 설정에서 만료 기간을 늘리세요.
제가 받는 HTTP 404 Not Found 티켓을 확인할 때. * 티켓이 DELETE 요청에 의해 제거되었거나, 제거 기간에 도달했기 때문입니다(티켓 만료 후 시작되며, 설정에서 정의됨). 테스트 목적으로 새 티켓을 다시 만들거나 설정에서 만료/제거 기간을 늘리세요.
내 매치메이커에 오류가 표시되는데, 어떻게 해야 하나요? * 이것이 개발 또는 테스트 인스턴스라면 먼저 매치메이커를 재시작해 보세요. - 다음을 통해 모든 문제를 신고해 주세요 [커뮤니티 Discord](https://discord.gg/MmJf8fWjnt). * 이 문제가 실시간 게임에 영향을 주고 있다면, 다음을 생성하세요 [긴급 지원 요청](https://edgegap.atlassian.net/servicedesk/customer/portal/3).
## 🔖 변경 로그 설정 파일은 사용 중인 매치메이커 버전에 따라 검증됩니다. 규칙이 매치메이커 버전의 기능과 일치하는지 확인하세요. {% hint style="info" %} **매치메이커의 최신 버전은 `3.2.2`**입니다. 이 페이지의 모든 예시는 최신 상태입니다. 다음을 주의 깊게 살펴보세요 [업데이트 및 공지](/docs.edgegap.com-ko/docs/release-notes.md). 또한 다음도 참조하세요 [#rolling-updates-and-ab-tests](#rolling-updates-and-ab-tests "mention"). {% endhint %} {% hint style="warning" %} **매치메이커 버전을 업그레이드하려면 - 중지, 편집, 재시작.** 빠른 재시작은 버전 변경 사항을 적용하지 않습니다. {% endhint %} [^1]: 게임 클라이언트가 로비에 들어가 매치메이킹 그룹 ID를 가져오고 그룹에 참여합니다 [^2]: [서비스형 함수](https://www.ibm.com/think/topics/faas) [^3]: 다른 예시 보기 --- # Agent Instructions: 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/learn/matchmaking/matchmaker-in-depth.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.