Matchmaking
멀티플레이어 프로젝트가 성장함에 따라 확장하고 맞춤 설정할 수 있도록 준비된 Edgegap의 선택적 JavaScript SDK로 브라우저 게임에 매치메이킹을 추가하세요.
이 SDK는 JavaScript 및 TypeScript 사용자를 위한 선택적 스타터 키트로, 나중에 확장하고 사용자 지정할 수 있습니다.
💡 기능
완전한 예제
Promise와 비동기 루프
티켓, 그룹, 팀
매치 변수
타입 정의(TypeScript)
백필 자동화
브라우저, Node.js, Bun, Deno
의존성 없음
자동 재시도
✔️ 준비
JavaScript SDK에는 배포(Deployments) 및 매치메이킹용 선택적 통합 유틸리티가 포함되어 있습니다. 이 패키지는 공식적으로 모든 최신 브라우저, Node.js 22 이상, Bun 및 Deno를 지원합니다.
요구 사항
설치
좋아하는 패키지 관리자를 사용하여 npm에서 패키지를 설치하세요:
번들러 없이 HTML 게임에서 브라우저 빌드를 로드하세요. 모든 항목은 다음 아래에 노출됩니다: Edgegap 전역 객체로, Matchmaking은 다음 아래에 있습니다: Edgegap.matchmaking:
또는 ES 모듈로 가져오세요:
패키지에는 두 개의 진입점이 있습니다:
@edgegap/sdk/matchmaking:GroupAgent,ServerAgent,MatchEnvironment,MatchmakingError,Api.
@edgegap/sdk- 공용 유틸리티:getConnectionUrl,DeploymentEnvironment.Observable,Logger, 기타 HTTP 헬퍼.
검증된 출처
이 패키지는 npm에 다음으로만 게시됩니다: @edgegap/sdk, 다음의 소스 코드에서 GitHub. jsDelivr 및 unpkg 같은 CDN은 npm 패키지를 미러링합니다. 검증되지 않은 출처를 신뢰하지 마세요. 다음 범위 외부의 유사한 이름의 패키지는 @edgegap 에 속하지 않으며 Edgegap과 무관합니다!
패키지 업데이트
패키지 관리자를 사용하여 최신 버전으로 업데이트하세요:
CDN에서 로드할 때는 URL의 버전을 변경하고 무결성 해시를 다시 생성하세요.
🍀 시작하기
이 가이드는 다음에 대한 기본 지식을 전제로 합니다: Matchmaking 개념과 실행 중인 Matchmaker.
개요
우리 SDK는 다음을 크게 활용합니다: Observer 프로그래밍 패턴을 사용하며, 콜백으로 변경 사항을 소비할 수 있게 해줍니다, Promise, 또는 비동기 반복 - 게임 루프에 맞는 것을 사용하세요.
이 패키지에는 다음이 포함됩니다:
서비스별 유틸리티:
Matchmaking - 재사용/확장 가능한 완전한 브라우저 클라이언트 통합.
Matchmaking - 재사용/확장 가능한 완전한 게임 서버 백필 통합.
MatchEnvironment- 타입이 지정된 매치메이킹 변수 게임 서버용.Api- 엔드포인트 정의, 오류 처리 및 재시도 자동화.
서비스별 타입 - Matchmaking API JSON과 정확히 일치하는 요청 및 응답 타입.
공용 유틸리티 - 연결 URL, 배포 변수, 로깅, HTTP, observable 등...
그룹 에이전트
티켓 관리, 호스트 가져오기 및 비콘 검색은 그룹 에이전트가 수행합니다.
인스턴스화되면 에이전트의 핸들러(귀하의 게임 코드)가 에이전트를 초기화해야 하며 선택적으로 다음을 제공해야 합니다:
onMonitorUpdate콜백 - 서비스 상태 변경을 관찰합니다.onGroupUpdate콜백 - 그룹 및 호스트 할당 변경을 관찰하고 대응합니다.
초기화되면 이 에이전트는 자동으로 검증을 제공하고 로깅 옵저버를 연결한 뒤, 서비스 상태를 알리기 위해 모니터링 API 엔드포인트를 한 번 호출하면서 마무리합니다.
이 시점부터 에이전트의 핸들러가 제어를 넘겨받아 다음 함수를 호출하는 것으로 예상됩니다:
비콘사용 가능한 목록을 가져오려면 비콘 핑.measureBeaconsRoundTripTime주어진 비콘 집합에 대한 핑 측정을 제공하려면.createGroup로비 리더가 친구를 초대할 수 있는 참여 가능한 그룹을 생성하려면.joinGroup3rd party 로비/백엔드를 통해 전송된 그룹 ID를 사용하여 기존 그룹에 참여하려면.setReady그룹 소유자와 멤버를 준비 완료로 표시하고 매치 검색을 시작하려면.nextAssignment그룹이 검색을 시작한 후 호스트 할당을 기다리려면.resumeMatchmaking페이지가 다시 로드된 경우 저장된 그룹을 불러와 검색을 계속하려면.stopMatchmaking티켓을 삭제하고(매치되지 않은 경우) 큐를 포기하려면.dispose모든 타이머를 지우고, 요청을 중단하고, 구독자를 제거하려면.
여기서는 세 가지 서로 다른 동시성 패턴을 보여줍니다. 원하는 것을 선택하세요:
프로필 및 속성 는 Matchmaker 설정의 프로필과 일치해야 합니다, gameport 는 App Version의 포트 이름입니다. getConnectionUrl 다음을 반환합니다: wss:// WebSocket 포트용 URL.
새 플레이어 연결이 수립되면, 플레이어는 귀하의 netcode를 사용하여 자신의 티켓 ID를 게임 서버로 전송하여 연결을 다음과 연관시켜야 합니다: 매치메이킹 변수. 이 시점에는 게임 서버가 아직 초기화 중일 수 있으므로 플레이어는 여러 번 연결을 재시도해야 합니다:
서버 에이전트
Server Agent는 다음을 수행합니다: 백필 생성, 티켓 할당 감지, 백필 포기 및 제거 감지. 또한 만료되었거나, 연결 유예 기간이 경과했거나, 포기된 백필을 추적하고 다시 생성하여 원하는 팀 크기에 도달하도록 합니다.
Server Agent는 현재 연결된 플레이어를 추적하고 새 백필에 해당 티켓을 자동으로 포함하여, 백필된 플레이어가 구성된 프로필 규칙에 따라 매칭되도록 보장합니다.
인스턴스화되면 에이전트의 핸들러(귀하의 서버 코드)가 에이전트를 초기화해야 하며 다음을 제공해야 합니다:
티켓- 이미 이 서버와 매치된 플레이어, 다음에서 매치메이킹 변수.onMonitorUpdate콜백 - 서비스 상태 변경을 관찰합니다.onBackfillUpdate콜백 - 백필 변경을 관찰하고 대응합니다.
초기화되면 이 에이전트는 자동으로 검증을 제공하고 로깅 옵저버를 연결한 뒤, 서비스 상태를 알리기 위해 모니터링 API 엔드포인트를 한 번 호출하면서 마무리합니다.
이 시점부터 서버 핸들러가 제어를 넘겨받아 다음 함수를 호출하는 것으로 예상됩니다:
addBackfills할당된 플레이어와 열린 백필이 목표 팀 크기에 도달할 때까지 백필을 생성하려면.playerConnected초기 플레이어 또는 연결되지 않은 백필 플레이어를 교체하지 않도록 하려면.플레이어의 티켓을 반환하거나
null티켓이 이 서버에 할당되지 않은 경우 - 해당 연결을 거부하세요.
abandonPlayer연결된 플레이어가 서버를 떠났고 교체가 필요함을 알리려면.abandonAllBackfills서버 백필을 즉시 중지하고 백필을 삭제하려면.이 메서드는 서버를 중지하기 전에 호출해야 합니다. 이 시점에 이미 할당된 플레이어는 서버가 종료되므로 다시 매치메이킹에 참여해야 합니다.
이 호출 시점에 할당된 백필은 설정된 유예 기간 내에 계속 연결할 수 있습니다.
abandonBackfill특정 백필을 강제로 포기하려면(사용자 지정 핸들러 구현).dispose타이머를 지우고, 요청을 중단하고, 구독자를 제거하려면.
매치 변수
다음을 읽으세요 매치메이킹 변수 게임 서버에서 API를 호출하지 않고 연결하는 플레이어를 검증하고 팀을 할당하려면:
매치 에는 matchProfile, matchId, 티켓 (티켓 ID 기준), 그룹, 팀, 그리고 일치된 동등성 및 교집합 값을 포함합니다. 파싱은 절대 예외를 발생시키지 않으므로 동일한 서버를 로컬에서도 실행할 수 있습니다.
다음을 통해 참여한 플레이어는 백필 에 나열되지 않습니다 match.tickets, 따라서 Server Agent를 사용하는 서버는 연결하는 플레이어를 다음으로 검증합니다: agent.playerConnected 를 대신 사용하세요.
🧪 샘플
서버와 클라이언트 모두에 대한 완전한 작동 통합을 포함한 샘플로 시작하세요.
Three.js Minigames
브라우저 게임 다섯 개와 전체 플레이어 수명 주기 구현이 포함됩니다 - 그룹, 호스트 할당 검색, 연결 재시도. 매치가 종료되면 서버 측에서 주입된 매치 변수를 읽고, 2팀 프로필에서 플레이어를 팀에 할당하며, 배포를 중지하는 방법을 보여줍니다.
이 예제를 게임에 맞게 쉽게 확장하려면 새 매치메이킹 프로필과 게임 서버를 추가하세요.
그룹 업
친구 그룹과 함께 매치메이킹 대기열에 참여합니다. 검색을 시작하기 전에 모든 플레이어가 확인해야 합니다. 그룹 소유자는 그룹을 생성하고 로비 또는 백엔드를 통해 해당 ID를 공유합니다:
새로고침 후 재개
변경될 때 그룹을 저장하고, 페이지가 다시 로드되면 검색을 재개(또는 재연결)합니다:
저장된 그룹은 다음으로 제거합니다 localStorage.removeItem('edgegap-group') 매치가 끝난 후, 플레이어가 완료된 매치에 다시 연결되지 않도록 합니다.
백필
서버 용량을 재사용하고 진행 중인 배포에 플레이어를 추가합니다. 목표 팀 규모를 설정하고 플레이어가 추가될 때까지 기다립니다. 자동 연결 유예 시간과 만료된 백필 재생성을 포함합니다. 참조 Matchmaking.
다중 팀 또는 비대칭 팀 구성에 맞게 서버 핸들러를 사용자 지정하세요.
⚙️ 사용자 지정
이 SDK는 확장 및 수정할 수 있도록 설계되었지만, 일부 수정은 위험할 수 있습니다:
✅ 핸들러 - UI 옵저버를 안전하게 연결하고 작은 추가 또는 수정을 수행합니다,
⚠️ 에이전트 - 소스 코드를 포크하여 플레이어 수명 주기 관리를 수정할 수 있으며, 그 위험은 본인 책임입니다,
⚠️ API - 다음을 사용해 처음부터 직접 통합을 작성하세요 Api 및 선별한 유틸리티.
핸들러는 아래에 설명된 대로 Server 및 Group 에이전트가 방출하는 모든 이벤트를 관찰할 수 있습니다.
클라이언트 이벤트
Group Agent는 핸들러가 관찰하고 사용할 수 있도록 유형이 지정된 이벤트를 방출합니다.
관찰자에서 방출되는 미리 보기 이벤트 모니터 :
🟢 업데이트
정상
-
모든 시스템이 정상입니다.
🟢 업데이트
비정상
-
예상치 못한 문제입니다.
🔴 오류
monitor_failed
세부 정보
잘못된 구성 또는 예상치 못한 문제입니다.
🔴 오류
beacons_failed
세부 정보
예상치 못한 문제입니다.
관찰자에서 방출되는 미리 보기 이벤트 그룹 :
🟢 업데이트
생성됨
-
그룹이 정상적으로 생성되었습니다.
🔴 오류
create_failed
세부 정보
그룹 생성에 실패했습니다.
🟢 업데이트
참여됨
-
그룹에 정상적으로 참여했습니다.
🔴 오류
join_failed
세부 정보
그룹 참여에 실패했습니다.
🟢 업데이트
재개됨
-
그룹이 정상적으로 재개되었습니다.
🔴 오류
not_found
세부 정보?
그룹의 구성원이 아니거나, 그룹이 만료되었습니다.
🔴 오류
충돌
-
새 그룹을 생성/참여하기 전에 현재 그룹을 포기하거나 다음을 전달하세요 abandon: true.
🟢 업데이트
member_updated
isReady
구성원이 새로운 Ready 값으로 업데이트되었습니다.
🟡 경고
member_update_failed
-
그룹이 매치 검색을 시작한 후에는 준비 해제를 할 수 없습니다.
🔴 오류
update_failed
세부 정보
그룹 구성원 업데이트에 실패했습니다.
🔵 로그
폴링
시도, maxAttempts
에이전트가 그룹 상태 폴링을 시작했습니다. 다음과 함께만 방출됩니다 logPollingUpdates: true.
🔵 로그
polling_stopped
-
에이전트가 그룹 상태 폴링을 중지했습니다. 다음과 함께만 방출됩니다 logPollingUpdates: true.
🔴 오류
polling_failed
reason: 'max_retries', 세부 정보
에이전트가 연속 폴링 재시도의 최대 횟수에 도달했습니다. 서비스 상태를 확인하세요.
🔴 오류
polling_failed
reason: 'error', 세부 정보
에이전트가 폴링 중 재시도할 수 없는 오류를 받았습니다. 서비스 상태를 확인하세요.
🟢 업데이트
업데이트됨
상태
폴링 중 그룹 상태 변경이 감지되었습니다.
🟢 업데이트
포기됨
-
티켓이 정상적으로 삭제되었습니다.
🟢 업데이트
abandon_failed
reason: 'not_found'
에이전트가 삭제할 그룹을 찾지 못했습니다. 만료되었을 수 있습니다.
🔴 오류
abandon_failed
reason: 'error', 세부 정보
그룹 또는 멤버십 삭제에 실패했습니다.
🟡 경고
restart_skipped
-
그룹이 이미 매치되었으므로, 포기 후 후속 작업이 건너뛰어졌습니다.
🟢 업데이트
제거됨
-
그룹이 종료되었거나 만료되어, 로컬 참조가 삭제되었습니다.
서버 이벤트
Server Agent는 핸들러가 관찰하고 사용할 수 있도록 유형이 지정된 이벤트를 방출합니다. Server Agent는 다음에만 필요합니다 Matchmaking.
관찰자에서 방출되는 미리 보기 이벤트 모니터 :
🟢 업데이트
정상
-
모든 시스템이 정상입니다.
🟢 업데이트
비정상
-
예상치 못한 문제입니다.
🔴 오류
monitor_failed
세부 정보
잘못된 구성 또는 예상치 못한 문제입니다.
관찰자에서 방출되는 미리 보기 이벤트 backfills :
🟢 업데이트
생성됨
backfillId
백필이 정상적으로 생성되었습니다.
🔴 오류
create_failed
세부 정보
백필에 예상치 못한 문제가 발생했습니다. 서비스 상태를 확인하세요.
🔴 오류
capacity_reached
-
서버가 가득 찼으며, 백필이 생성되지 않았습니다.
🔵 로그
폴링
시도, maxAttempts
에이전트가 백필 폴링을 시작했습니다. 다음과 함께만 방출됩니다 logPollingUpdates: true.
🟢 업데이트
할당됨
backfillId, ticketId
백필에 티켓이 정상적으로 할당되었습니다.
🔵 로그
polling_stopped
-
에이전트가 폴링을 중지했습니다. 더 이상 폴링할 백필이 없습니다.
🟡 경고
polling_failed
backfillId, reason: 'not_found'
찾을 수 없어 참조를 제거합니다. 백필이 만료되었을 가능성이 큽니다.
🔴 오류
polling_failed
backfillId, reason: 'max_retries'
재시도 한도를 초과하여, 모든 백필을 포기합니다.
🔴 오류
polling_failed
backfillId, reason: 'error', 세부 정보
예상치 못한 문제로, 백필을 포기하고 교체합니다.
🔵 로그
포기됨
backfillId
백필이 포기되어, 참조를 제거합니다.
🟡 경고
abandon_failed
backfillId, reason: 'not_found'
백필을 찾을 수 없습니다. 만료되었거나 중복 호출일 가능성이 큽니다.
🟡 경고
abandon_failed
backfillId, reason: 'error', 세부 정보
포기에 실패하여, 참조를 제거합니다.
🟢 업데이트
제거됨
backfillId
백필 참조가 제거되었습니다. 중지되지 않으면 백필은 자동으로 교체됩니다.
🟡 경고
remove_failed
backfillId
백필 참조를 찾을 수 없습니다. 중복 호출일 가능성이 큽니다.
마지막 업데이트
도움이 되었나요?

