For the complete documentation index, see llms.txt. This page is also available as Markdown.

Matchmaking

멀티플레이어 프로젝트가 성장함에 따라 확장하고 맞춤 설정할 수 있도록 준비된 Edgegap의 선택적 JavaScript SDK로 브라우저 게임에 매치메이킹을 추가하세요.

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

💡 기능

  • 완전한 예제

  • Promise와 비동기 루프

  • 티켓, 그룹, 팀

  • 매치 변수

  • 타입 정의(TypeScript)

  • 백필 자동화

  • 브라우저, Node.js, Bun, Deno

  • 의존성 없음

  • 자동 재시도

✔️ 준비

JavaScript SDK에는 배포(Deployments) 및 매치메이킹용 선택적 통합 유틸리티가 포함되어 있습니다. 이 패키지는 공식적으로 모든 최신 브라우저, Node.js 22 이상, Bun 및 Deno를 지원합니다.

JavaScript SDK의 최신 버전은 1.1.0입니다. 이 문서의 모든 예제는 최신 상태입니다.

요구 사항

Matchmaker 설정에서 게임의 웹 오리진을 허용하세요

브라우저는 오리진이 다음에 나열된 페이지에서만 Matchmaker를 호출합니다: allowed_cors_origins 귀하의 Matchmaker 설정. 항목은 스킴과 포트를 포함한 전체 오리진과 대조됩니다:

  • https://*.my-game.com 는 HTTPS의 모든 서브도메인과 일치합니다,

  • localhost 는 아무것과도 일치하지 않으므로 로컬 개발 서버를 전체 형식으로 나열하세요. 예: http://localhost:5173 .

게임 서버의 WebSocket 포트에 대해 TLS 업그레이드를 활성화하세요

다음을 설정하세요: App Version 포트 프로토콜을 WS 를 사용하도록 하고 TLS 업그레이드, 브라우저가 보안 WebSocket(wss://).

설치

좋아하는 패키지 관리자를 사용하여 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에서 로드할 때는 다음으로 정확한 버전을 고정하세요: 서브리소스 무결성 를 사용하여 수정된 버전을 거부하세요.

패키지 업데이트

패키지 관리자를 사용하여 최신 버전으로 업데이트하세요:

CDN에서 로드할 때는 URL의 버전을 변경하고 무결성 해시를 다시 생성하세요.

일부 릴리스에는 호환성을 깨는 변경 사항이 포함될 수 있습니다. 이는 새로운 MAJOR 버전으로 표시됩니다.

🍀 시작하기

이 가이드는 다음에 대한 기본 지식을 전제로 합니다: Matchmaking 개념과 실행 중인 Matchmaker.

개요

우리 SDK는 다음을 크게 활용합니다: Observer 프로그래밍 패턴을 사용하며, 콜백으로 변경 사항을 소비할 수 있게 해줍니다, Promise, 또는 비동기 반복 - 게임 루프에 맞는 것을 사용하세요.

이 패키지는 Matchmaking 및 배포 유틸리티를 통합합니다. 자신만의 맞춤형 포크와 통합에 어떤 코드든 자유롭게 재사용할 수 있습니다.

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

  • 서비스별 유틸리티:

    • Matchmaking - 재사용/확장 가능한 완전한 브라우저 클라이언트 통합.

    • Matchmaking - 재사용/확장 가능한 완전한 게임 서버 백필 통합.

    • MatchEnvironment - 타입이 지정된 매치메이킹 변수 게임 서버용.

    • Api - 엔드포인트 정의, 오류 처리 및 재시도 자동화.

  • 서비스별 타입 - Matchmaking API JSON과 정확히 일치하는 요청 및 응답 타입.

  • 공용 유틸리티 - 연결 URL, 배포 변수, 로깅, HTTP, observable 등...

그룹 에이전트

티켓 관리, 호스트 가져오기 및 비콘 검색은 그룹 에이전트가 수행합니다.

인스턴스화되면 에이전트의 핸들러(귀하의 게임 코드)가 에이전트를 초기화해야 하며 선택적으로 다음을 제공해야 합니다:

  • onMonitorUpdate 콜백 - 서비스 상태 변경을 관찰합니다.

  • onGroupUpdate 콜백 - 그룹 및 호스트 할당 변경을 관찰하고 대응합니다.

초기화되면 이 에이전트는 자동으로 검증을 제공하고 로깅 옵저버를 연결한 뒤, 서비스 상태를 알리기 위해 모니터링 API 엔드포인트를 한 번 호출하면서 마무리합니다.

이 시점부터 에이전트의 핸들러가 제어를 넘겨받아 다음 함수를 호출하는 것으로 예상됩니다:

  • 비콘 사용 가능한 목록을 가져오려면 비콘 핑.

  • measureBeaconsRoundTripTime 주어진 비콘 집합에 대한 핑 측정을 제공하려면.

  • createGroup 로비 리더가 친구를 초대할 수 있는 참여 가능한 그룹을 생성하려면.

  • joinGroup 3rd 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: 'match_found'

에이전트가 매치된 그룹을 삭제할 수 없었습니다. 포기를 비활성화하거나 심층 살펴보기 플레이어를 대체하세요.

🔴 오류

abandon_failed

reason: 'error', 세부 정보

그룹 또는 멤버십 삭제에 실패했습니다.

🟡 경고

restart_skipped

-

그룹이 이미 매치되었으므로, 포기 후 후속 작업이 건너뛰어졌습니다.

🟢 업데이트

제거됨

-

그룹이 종료되었거나 만료되어, 로컬 참조가 삭제되었습니다.

서버 이벤트

Server Agent는 핸들러가 관찰하고 사용할 수 있도록 유형이 지정된 이벤트를 방출합니다. Server Agent는 다음에만 필요합니다 Matchmaking.

현재 할당된 티켓은 Server Agent 속성에서 읽을 수 있습니다 assignments 언제든지, 그리고 연결 시간은 connectedAt .

관찰자에서 방출되는 미리 보기 이벤트 모니터 :

작업 유형
이벤트 코드
이벤트 매개변수
설명

🟢 업데이트

정상

-

모든 시스템이 정상입니다.

🟢 업데이트

비정상

-

예상치 못한 문제입니다.

🔴 오류

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

백필 참조를 찾을 수 없습니다. 중복 호출일 가능성이 큽니다.

마지막 업데이트

도움이 되었나요?