> 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/ko/web-games/matchmaking.md).

# Matchmaking

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

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

## 💡 기능

{% columns %}
{% column %}

* 완전한 예제
* Promise와 비동기 루프
* 티켓, 그룹, 팀
  {% endcolumn %}

{% column width="33.33333333333333%" %}

* 매치 변수
* 타입 정의(TypeScript)
* 백필 자동화
  {% endcolumn %}

{% column width="33.33333333333333%" %}

* 브라우저, Node.js, Bun, Deno
* 의존성 없음
* 자동 재시도
  {% endcolumn %}
  {% endcolumns %}

## ✔️ 준비

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

{% hint style="info" %}
**JavaScript SDK의 최신 버전은 `1.1.0`**&#xC785;니다. 이 문서의 모든 예제는 최신 상태입니다.
{% endhint %}

{% hint style="success" %}
이 패키지는 Free Tier의 이용 약관에 따라 100% 무료로 제공됩니다.
{% endhint %}

#### 요구 사항

<details>

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

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

* `https://*.my-game.com` 는 HTTPS의 모든 서브도메인과 일치합니다,
* `localhost` 는 아무것과도 일치하지 않으므로 로컬 개발 서버를 전체 형식으로 나열하세요. 예: `http://localhost:5173` .

</details>

<details>

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

다음을 설정하세요: [App Version 포트](https://docs.edgegap.com/ko/learn/orchestration/application-and-versions.md#port-mapping) 프로토콜을 `WS` 를 사용하도록 하고 **TLS 업그레이드**, 브라우저가 보안 WebSocket(`wss://`).

</details>

#### 설치

좋아하는 패키지 관리자를 사용하여 npm에서 패키지를 설치하세요:

{% tabs %}
{% tab title="npm" %}
{% code collapsedlinecount="10" %}

```bash
npm install @edgegap/sdk
```

{% endcode %}
{% endtab %}

{% tab title="pnpm" %}
{% code collapsedlinecount="10" %}

```bash
pnpm add @edgegap/sdk
```

{% endcode %}
{% endtab %}

{% tab title="yarn" %}
{% code collapsedlinecount="10" %}

```bash
yarn add @edgegap/sdk
```

{% endcode %}
{% endtab %}

{% tab title="bun" %}
{% code collapsedlinecount="10" %}

```bash
bun add @edgegap/sdk
```

{% endcode %}
{% endtab %}

{% tab title="deno" %}
{% code collapsedlinecount="10" %}

```bash
deno add npm:@edgegap/sdk
```

{% endcode %}
{% endtab %}

{% tab title="CDN (번들러 없음)" %}
번들러 없이 HTML 게임에서 브라우저 빌드를 로드하세요. 모든 항목은 다음 아래에 노출됩니다: `Edgegap` 전역 객체로, Matchmaking은 다음 아래에 있습니다: `Edgegap.matchmaking`:

{% code collapsedlinecount="10" %}

```html
<script src="https://cdn.jsdelivr.net/npm/@edgegap/sdk@1.1.0/dist/browser/edgegap.iife.js"></script>
```

{% endcode %}

또는 ES 모듈로 가져오세요:

{% code collapsedlinecount="10" %}

```html
<script type="module">
  import { matchmaking, getConnectionUrl } from 'https://cdn.jsdelivr.net/npm/@edgegap/sdk@1.1.0/dist/browser/edgegap.js'
</script>
```

{% endcode %}
{% endtab %}
{% endtabs %}

패키지에는 두 개의 진입점이 있습니다:

* `@edgegap/sdk/matchmaking` :
  * `GroupAgent`, `ServerAgent`, `MatchEnvironment`, `MatchmakingError`, `Api` .
* `@edgegap/sdk` - 공용 유틸리티:
  * `getConnectionUrl`, `DeploymentEnvironment` .
  * `Observable`, `Logger`, 기타 HTTP 헬퍼.

#### 검증된 출처

이 패키지는 npm에 다음으로만 게시됩니다: [`@edgegap/sdk`](https://www.npmjs.com/package/@edgegap/sdk), 다음의 소스 코드에서 [GitHub](https://github.com/edgegap/sdk-js-sessions-matchmaker-server-browser). jsDelivr 및 unpkg 같은 CDN은 npm 패키지를 미러링합니다. 검증되지 않은 출처를 신뢰하지 마세요. 다음 범위 외부의 유사한 이름의 패키지는 `@edgegap` 에 속하지 않으며 Edgegap과 무관합니다!

{% hint style="success" %}
**모든 릴리스는 GitHub Actions를 통해 다음과 함께 게시됩니다:** [**npm provenance**](https://docs.npmjs.com/generating-provenance-statements), 패키지를 빌드한 커밋과 연결합니다. 설치한 패키지는 다음으로 검증하세요: `npm audit signatures` .
{% endhint %}

{% hint style="info" %}
CDN에서 로드할 때는 다음으로 정확한 버전을 고정하세요: [서브리소스 무결성](https://developer.mozilla.org/docs/Web/Security/Subresource_Integrity) 를 사용하여 수정된 버전을 거부하세요.
{% endhint %}

### 패키지 업데이트

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

{% code collapsedlinecount="10" %}

```bash
npm install @edgegap/sdk@latest
```

{% endcode %}

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

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

## 🍀 시작하기

이 가이드는 다음에 대한 기본 지식을 전제로 합니다: [Matchmaking](https://docs.edgegap.com/ko/learn/matchmaking.md) 개념과 실행 중인 Matchmaker.

{% hint style="success" %}
**다음 저장소를 클론하는 것을 강력히 권장합니다:** [**Three.js Minigames**](#three.js-minigames) **샘플** 문서를 읽으면서 코드를 따라 할 수 있습니다.
{% endhint %}

### 개요

우리 SDK는 다음을 크게 활용합니다: [Observer](https://refactoring.guru/design-patterns/observer) 프로그래밍 패턴을 사용하며, 콜백으로 변경 사항을 소비할 수 있게 해줍니다, [Promise](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise), 또는 [비동기 반복](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/for-await...of) - 게임 루프에 맞는 것을 사용하세요.

{% hint style="info" %}
이 패키지는 [Matchmaking](https://docs.edgegap.com/ko/learn/matchmaking.md) 및 [배포](https://docs.edgegap.com/ko/learn/orchestration/deployments.md) 유틸리티를 통합합니다. 자신만의 맞춤형 포크와 통합에 어떤 코드든 자유롭게 재사용할 수 있습니다.
{% endhint %}

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

* 서비스별 유틸리티:
  * [#group-agent](#group-agent "mention") - 재사용/확장 가능한 완전한 브라우저 클라이언트 통합.
  * [#server-agent](#server-agent "mention") - 재사용/확장 가능한 완전한 게임 서버 백필 통합.
  * `MatchEnvironment` - 타입이 지정된 [매치메이킹 변수](https://docs.edgegap.com/ko/learn/matchmaking/matchmaker-in-depth.md#injected-environment-variables) 게임 서버용.
  * `Api` - 엔드포인트 정의, 오류 처리 및 재시도 자동화.
* 서비스별 타입 - Matchmaking API JSON과 정확히 일치하는 요청 및 응답 타입.
* 공용 유틸리티 - 연결 URL, 배포 변수, 로깅, HTTP, observable 등...

### 그룹 에이전트

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

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

* `onMonitorUpdate` 콜백 - 서비스 상태 변경을 관찰합니다.
* `onGroupUpdate` 콜백 - 그룹 및 호스트 할당 변경을 관찰하고 대응합니다.

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

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

* `비콘` 사용 가능한 목록을 가져오려면 [비콘 핑](https://docs.edgegap.com/ko/learn/orchestration/ping-beacons.md).
* `measureBeaconsRoundTripTime` 주어진 비콘 집합에 대한 핑 측정을 제공하려면.
* `createGroup` 로비 리더가 친구를 초대할 수 있는 참여 가능한 그룹을 생성하려면.
* `joinGroup` 3rd party 로비/백엔드를 통해 전송된 그룹 ID를 사용하여 기존 그룹에 참여하려면.
* `setReady` 그룹 소유자와 멤버를 준비 완료로 표시하고 매치 검색을 시작하려면.
* `nextAssignment` 그룹이 검색을 시작한 후 호스트 할당을 기다리려면.
* `resumeMatchmaking` 페이지가 다시 로드된 경우 저장된 그룹을 불러와 검색을 계속하려면.
* `stopMatchmaking` 티켓을 삭제하고(매치되지 않은 경우) 큐를 포기하려면.
* `dispose` 모든 타이머를 지우고, 요청을 중단하고, 구독자를 제거하려면.

여기서는 세 가지 서로 다른 동시성 패턴을 보여줍니다. 원하는 것을 선택하세요:

{% tabs %}
{% tab title="Promise" %}
{% code collapsedlinecount="10" %}

```javascript
import { getConnectionUrl } from '@edgegap/sdk'
import { GroupAgent, MatchmakingError } from '@edgegap/sdk/matchmaking'

const agent = new GroupAgent({ baseUrl: '<matchmaker url>', authToken: '<matchmaker auth token>' })
agent.initialize()

const { beacons } = await agent.beacons()
const latencies = await agent.measureBeaconsRoundTripTime(beacons)

agent.createGroup({ profile: 'simple-example', attributes: { beacons: latencies }, is_ready: true }, true)

try {
  const assignment = await agent.nextAssignment()
  connect(getConnectionUrl(assignment, 'gameport'), agent.group.current.ticket_id)
} catch (error) {
  if (!(error instanceof MatchmakingError)) throw error
  showRetryButton(error.message)
}
```

{% endcode %}
{% endtab %}

{% tab title="비동기 루프" %}
{% code collapsedlinecount="10" %}

```javascript
import { getConnectionUrl, ObservableActionType } from '@edgegap/sdk'
import { GroupAgent } from '@edgegap/sdk/matchmaking'

const agent = new GroupAgent({ baseUrl: '<matchmaker url>', authToken: '<matchmaker auth token>' })
agent.initialize()

const { beacons } = await agent.beacons()
const latencies = await agent.measureBeaconsRoundTripTime(beacons)

agent.createGroup({ profile: 'simple-example', attributes: { beacons: latencies }, is_ready: true }, true)

for await (const { type, message, event, current } of agent.group) {
  if (type === ObservableActionType.Error) {
    showRetryButton(message)
    break
  }
  if (event.code !== 'updated') continue
  showStatus(current.status)
  if (current.status === 'CANCELLED') {
    showRetryButton(message)
    break
  }
  if (current.status !== 'HOST_ASSIGNED') continue
  connect(getConnectionUrl(current.assignment, 'gameport'), current.ticket_id)
  break
}
```

{% endcode %}
{% endtab %}

{% tab title="콜백" %}
{% code collapsedlinecount="10" %}

```javascript
import { getConnectionUrl, ObservableActionType } from '@edgegap/sdk'
import { GroupAgent } from '@edgegap/sdk/matchmaking'

const agent = new GroupAgent({ baseUrl: '<matchmaker url>', authToken: '<matchmaker auth token>' })
agent.initialize(
  (_monitor, _type, message) => console.log('matchmaker', message),
  (group, type, message, event) => {
    if (type === ObservableActionType.Error) return showRetryButton(message)
    if (event.code !== 'updated') return
    showStatus(group.current.status)
    if (group.current.status === 'CANCELLED') return showRetryButton(message)
    if (group.current.status === 'HOST_ASSIGNED')
      connect(getConnectionUrl(group.current.assignment, 'gameport'), group.current.ticket_id)
  },
)

const { beacons } = await agent.beacons()
const latencies = await agent.measureBeaconsRoundTripTime(beacons)

agent.createGroup({ profile: 'simple-example', attributes: { beacons: latencies }, is_ready: true }, true)
```

{% endcode %}
{% endtab %}
{% endtabs %}

`프로필` 및 `속성` 는 Matchmaker 설정의 프로필과 일치해야 합니다, `gameport` 는 App Version의 포트 이름입니다. `getConnectionUrl` 다음을 반환합니다: `wss://` WebSocket 포트용 URL.

{% hint style="warning" %}
**브라우저는 Edgegap 비콘이 응답하는 ICMP, UDP 또는 TCP 핑을 보낼 수 없으므로**, 따라서 `measureBeaconsRoundTripTime` 보고합니다 `0` 기본적으로 각 비콘에 대해 `ping` 다른 방식으로 지연 시간을 측정하려면 에이전트 옵션에 직접 만든 구현을 전달하세요.
{% endhint %}

새 플레이어 연결이 수립되면, 플레이어는 귀하의 netcode를 사용하여 자신의 티켓 ID를 게임 서버로 전송하여 연결을 다음과 연관시켜야 합니다: [매치메이킹 변수](https://docs.edgegap.com/ko/learn/matchmaking/matchmaker-in-depth.md#injected-environment-variables). 이 시점에는 게임 서버가 아직 초기화 중일 수 있으므로 **플레이어는 여러 번 연결을 재시도해야 합니다**:

{% code collapsedlinecount="10" %}

```javascript
const connect = (url, ticketId, attempts = 10) => {
  const socket = new WebSocket(url)
  let opened = false
  socket.onopen = () => {
    opened = true
    socket.send(JSON.stringify({ ticketId }))
  }
  socket.onclose = () => !opened && attempts > 1 && setTimeout(() => connect(url, ticketId, attempts - 1), 1000)
}
```

{% endcode %}

{% hint style="success" %}
예기치 않은 충돌이 발생한 경우 다시 연결할 수 있도록 클라이언트 또는 게임 백엔드에 연결 정보를 저장하세요. 다음을 참조하세요: [#resume-after-reload](#resume-after-reload "mention").
{% endhint %}

### 서버 에이전트

Server Agent는 다음을 수행합니다: **백필 생성, 티켓 할당 감지, 백필 포기 및 제거 감지. 또한 만료되었거나, 연결 유예 기간이 경과했거나, 포기된 백필을 추적하고 다시 생성하여 원하는 팀 크기에 도달하도록 합니다**.

Server Agent는 현재 연결된 플레이어를 추적하고 새 백필에 해당 티켓을 자동으로 포함하여, 백필된 플레이어가 구성된 프로필 규칙에 따라 매칭되도록 보장합니다.

인스턴스화되면 에이전트의 **핸들러(귀하의 서버 코드)가 에이전트를 초기화해야 하며** 다음을 제공해야 합니다:

* `티켓` - 이미 이 서버와 매치된 플레이어, 다음에서 [매치메이킹 변수](https://docs.edgegap.com/ko/learn/matchmaking/matchmaker-in-depth.md#injected-environment-variables).
* `onMonitorUpdate` 콜백 - 서비스 상태 변경을 관찰합니다.
* `onBackfillUpdate` 콜백 - 백필 변경을 관찰하고 대응합니다.

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

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

* `addBackfills` 할당된 플레이어와 열린 백필이 목표 팀 크기에 도달할 때까지 백필을 생성하려면.
* `playerConnected` 초기 플레이어 또는 연결되지 않은 백필 플레이어를 교체하지 않도록 하려면.
  * 플레이어의 티켓을 반환하거나 `null` 티켓이 이 서버에 할당되지 않은 경우 - 해당 연결을 거부하세요.
* `abandonPlayer` 연결된 플레이어가 서버를 떠났고 교체가 필요함을 알리려면.
* `abandonAllBackfills` 서버 백필을 즉시 중지하고 백필을 삭제하려면.
  * 이 메서드는 서버를 중지하기 전에 호출해야 합니다. 이 시점에 이미 할당된 플레이어는 서버가 종료되므로 다시 매치메이킹에 참여해야 합니다.
  * 이 호출 시점에 할당된 백필은 설정된 유예 기간 내에 계속 연결할 수 있습니다.
* `abandonBackfill` 특정 백필을 강제로 포기하려면(사용자 지정 핸들러 구현).
* `dispose` 타이머를 지우고, 요청을 중단하고, 구독자를 제거하려면.

{% code collapsedlinecount="10" %}

```javascript
import { WebSocketServer } from 'ws'
import { DeploymentEnvironment } from '@edgegap/sdk'
import { MatchEnvironment, ServerAgent } from '@edgegap/sdk/matchmaking'

const deployment = DeploymentEnvironment.fromEnv(process.env)
const match = MatchEnvironment.fromEnv(process.env)

const agent = new ServerAgent({
  baseUrl: process.env.MATCHMAKER_URL,
  authToken: process.env.MATCHMAKER_TOKEN,
  profile: match.matchProfile,
  targetTeamSize: 4,
  attributes: {
    assignment: {
      request_id: deployment.requestId,
      fqdn: deployment.fqdn,
      public_ip: deployment.publicIp,
      ports: deployment.portMapping,
      location: deployment.location,
    },
  },
})

agent.initialize(
  match.tickets,
  (_monitor, _type, message) => console.log('matchmaker', message),
  (_backfills, _type, _message, event) => {
    if (event.code === 'assigned') console.log(`ticket ${event.ticketId} is joining`)
  },
)
agent.addBackfills()

const wss = new WebSocketServer({ port: 7777 })

wss.on('connection', (socket) => {
  socket.once('message', (data) => {
    const { ticketId } = JSON.parse(data.toString())
    if (!agent.playerConnected(ticketId)) return socket.close(4001, 'unknown ticket')
    socket.once('close', () => agent.abandonPlayer(ticketId))
  })
})

process.once('SIGTERM', () => agent.abandonAllBackfills(() => process.exit(0)))
```

{% endcode %}

{% hint style="danger" %}
**서버 토큰을 환경 변수에서 불러오세요**, 예를 들어 다음을 사용하여 [App Version Variables](https://docs.edgegap.com/ko/learn/orchestration/application-and-versions.md#injected-variables). 게임 서버에서 사용하는 토큰은 절대 브라우저 번들에 포함되면 안 됩니다.
{% endhint %}

### 매치 변수

다음을 읽으세요 [매치메이킹 변수](https://docs.edgegap.com/ko/learn/matchmaking/matchmaker-in-depth.md#injected-environment-variables) 게임 서버에서 API를 호출하지 않고 연결하는 플레이어를 검증하고 팀을 할당하려면:

{% code collapsedlinecount="10" %}

```javascript
import { WebSocketServer } from 'ws'
import { MatchEnvironment } from '@edgegap/sdk/matchmaking'

const match = MatchEnvironment.fromEnv(process.env)
const wss = new WebSocketServer({ port: 7777 })

wss.on('connection', (socket) => {
  socket.once('message', (data) => {
    const { ticketId } = JSON.parse(data.toString())
    const ticket = match.tickets[ticketId]
    if (!ticket) return socket.close(4001, 'unknown ticket')
    console.log(`player joined team ${ticket.team_id} in match ${match.matchId}`)
  })
})
```

{% endcode %}

`매치` 에는 `matchProfile`, `matchId`, `티켓` (티켓 ID 기준), `그룹`, `팀`, 그리고 일치된 `동등성` 및 `교집합` 값을 포함합니다. 파싱은 절대 예외를 발생시키지 않으므로 동일한 서버를 로컬에서도 실행할 수 있습니다.

다음을 통해 참여한 플레이어는 백필 에 나열되지 않습니다 `match.tickets`, 따라서 Server Agent를 사용하는 서버는 연결하는 플레이어를 다음으로 검증합니다: `agent.playerConnected` 를 대신 사용하세요.

## 🧪 샘플

서버와 클라이언트 모두에 대한 완전한 작동 통합을 포함한 샘플로 시작하세요.

### [Three.js Minigames](#three.js-minigames)

브라우저 게임 다섯 개와 전체 플레이어 수명 주기 구현이 포함됩니다 - 그룹, 호스트 할당 검색, 연결 재시도. 매치가 종료되면 서버 측에서 주입된 매치 변수를 읽고, 2팀 프로필에서 플레이어를 팀에 할당하며, 배포를 중지하는 방법을 보여줍니다.

이 예제를 게임에 맞게 쉽게 확장하려면 새 매치메이킹 프로필과 게임 서버를 추가하세요.

### 그룹 업

친구 그룹과 함께 매치메이킹 대기열에 참여합니다. 검색을 시작하기 전에 모든 플레이어가 확인해야 합니다. 그룹 소유자는 그룹을 생성하고 로비 또는 백엔드를 통해 해당 ID를 공유합니다:

{% code collapsedlinecount="10" %}

```javascript
const attributes = { beacons: latencies }

// 그룹 소유자의 기기에서
agent.group.subscribe((group, _type, _message, event) => {
  if (event.code === 'created') shareWithFriends(group.current.group_id)
})
agent.createGroup({ profile: 'simple-example', attributes, is_ready: false }, true)

// 각 친구의 기기에서, 그룹 ID를 받으면
agent.joinGroup({ profile: 'simple-example', attributes, is_ready: false }, groupId, true)

// 모든 기기에서, 플레이어가 준비되면
agent.setReady(true)
const assignment = await agent.nextAssignment()
```

{% endcode %}

### 새로고침 후 재개

변경될 때 그룹을 저장하고, 페이지가 다시 로드되면 검색을 재개(또는 재연결)합니다:

{% code collapsedlinecount="10" %}

```javascript
agent.initialize(undefined, (group) => {
  if (group.current) localStorage.setItem('edgegap-group', JSON.stringify(group.current))
  else if (group.previous?.status !== 'HOST_ASSIGNED') localStorage.removeItem('edgegap-group')
})

const saved = JSON.parse(localStorage.getItem('edgegap-group'))
if (saved?.status === 'HOST_ASSIGNED') {
  connect(getConnectionUrl(saved.assignment, 'gameport'), saved.ticket_id)
} else if (saved) {
  agent.resumeMatchmaking(saved)
  connect(getConnectionUrl(await agent.nextAssignment(), 'gameport'), saved.ticket_id)
}
```

{% endcode %}

저장된 그룹은 다음으로 제거합니다 `localStorage.removeItem('edgegap-group')` 매치가 끝난 후, 플레이어가 완료된 매치에 다시 연결되지 않도록 합니다.

### 백필

서버 용량을 재사용하고 진행 중인 배포에 플레이어를 추가합니다. 목표 팀 규모를 설정하고 플레이어가 추가될 때까지 기다립니다. 자동 연결 유예 시간과 만료된 백필 재생성을 포함합니다. 참조 [#server-agent](#server-agent "mention").

다중 팀 또는 비대칭 팀 구성에 맞게 서버 핸들러를 사용자 지정하세요.

## ⚙️ 사용자 지정

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

✅ 핸들러 - UI 옵저버를 안전하게 연결하고 작은 추가 또는 수정을 수행합니다,

⚠️ 에이전트 - 소스 코드를 포크하여 플레이어 수명 주기 관리를 수정할 수 있으며, 그 위험은 본인 책임입니다,

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

핸들러는 아래에 설명된 대로 Server 및 Group 에이전트가 방출하는 모든 이벤트를 관찰할 수 있습니다.

{% hint style="warning" %}
다음에 익숙해지도록 하세요 [매치메이킹 심화](https://docs.edgegap.com/ko/learn/matchmaking/matchmaker-in-depth.md) 맞춤 설정을 하기 전에 개념을 익혀두세요.
{% endhint %}

{% hint style="info" %}
도움이 필요하시면 [디스코드를 통해 문의해 주세요](https://discord.gg/MmJf8fWjnt). 실시간 게임 지원은 저희의 [티켓 시스템](https://edgegap.atlassian.net/servicedesk/customer/portal/3).
{% endhint %}

### 클라이언트 이벤트

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

{% hint style="success" %}
다음에 접근하여 상태를 읽습니다 `.current` 및 `.previous` 같은 관찰 대상의  **다음을 기준으로 분기합니다 `event.code`** 이벤트 메시지는 버전 간에 변경될 수 있기 때문입니다. 🔴 `오류` 이벤트는 전체 오류 메시지도 다음에 저장합니다 `.error` .
{% endhint %}

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

<table data-full-width="true"><thead><tr><th width="125">작업 유형</th><th width="200">이벤트 코드</th><th width="300">이벤트 매개변수</th><th>설명</th></tr></thead><tbody><tr><td>🟢 <code>업데이트</code></td><td><code>정상</code></td><td>-</td><td>모든 시스템이 정상입니다.</td></tr><tr><td>🟢 <code>업데이트</code></td><td><code>비정상</code></td><td>-</td><td>예상치 못한 문제입니다.</td></tr><tr><td>🔴 <code>오류</code></td><td><code>monitor_failed</code></td><td><code>세부 정보</code></td><td>잘못된 구성 또는 예상치 못한 문제입니다.</td></tr><tr><td>🔴 <code>오류</code></td><td><code>beacons_failed</code></td><td><code>세부 정보</code></td><td>예상치 못한 문제입니다.</td></tr></tbody></table>

관찰자에서 방출되는 미리 보기 이벤트 `그룹` :

<table data-full-width="true"><thead><tr><th width="125">작업 유형</th><th width="200">이벤트 코드</th><th width="300">이벤트 매개변수</th><th>설명</th></tr></thead><tbody><tr><td>🟢 <code>업데이트</code></td><td><code>생성됨</code></td><td>-</td><td>그룹이 정상적으로 생성되었습니다.</td></tr><tr><td>🔴 <code>오류</code></td><td><code>create_failed</code></td><td><code>세부 정보</code></td><td>그룹 생성에 실패했습니다.</td></tr><tr><td>🟢 <code>업데이트</code></td><td><code>참여됨</code></td><td>-</td><td>그룹에 정상적으로 참여했습니다.</td></tr><tr><td>🔴 <code>오류</code></td><td><code>join_failed</code></td><td><code>세부 정보</code></td><td>그룹 참여에 실패했습니다.</td></tr><tr><td>🟢 <code>업데이트</code></td><td><code>재개됨</code></td><td>-</td><td>그룹이 정상적으로 재개되었습니다.</td></tr><tr><td>🔴 <code>오류</code></td><td><code>not_found</code></td><td><code>세부 정보?</code></td><td>그룹의 구성원이 아니거나, 그룹이 만료되었습니다.</td></tr><tr><td>🔴 <code>오류</code></td><td><code>충돌</code></td><td>-</td><td>새 그룹을 생성/참여하기 전에 현재 그룹을 포기하거나 다음을 전달하세요 <code>abandon: true</code>.</td></tr><tr><td>🟢 <code>업데이트</code></td><td><code>member_updated</code></td><td><code>isReady</code></td><td>구성원이 새로운 Ready 값으로 업데이트되었습니다.</td></tr><tr><td>🟡 <code>경고</code></td><td><code>member_update_failed</code></td><td>-</td><td>그룹이 매치 검색을 시작한 후에는 준비 해제를 할 수 없습니다.</td></tr><tr><td>🔴 <code>오류</code></td><td><code>update_failed</code></td><td><code>세부 정보</code></td><td>그룹 구성원 업데이트에 실패했습니다.</td></tr><tr><td>🔵 <code>로그</code></td><td><code>폴링</code></td><td><code>시도</code>, <code>maxAttempts</code></td><td>에이전트가 그룹 상태 폴링을 시작했습니다. 다음과 함께만 방출됩니다 <code>logPollingUpdates: true</code>.</td></tr><tr><td>🔵 <code>로그</code></td><td><code>polling_stopped</code></td><td>-</td><td>에이전트가 그룹 상태 폴링을 중지했습니다. 다음과 함께만 방출됩니다 <code>logPollingUpdates: true</code>.</td></tr><tr><td>🔴 <code>오류</code></td><td><code>polling_failed</code></td><td><code>reason: 'max_retries'</code>, <code>세부 정보</code></td><td>에이전트가 연속 폴링 재시도의 최대 횟수에 도달했습니다. 서비스 상태를 확인하세요.</td></tr><tr><td>🔴 <code>오류</code></td><td><code>polling_failed</code></td><td><code>reason: 'error'</code>, <code>세부 정보</code></td><td>에이전트가 폴링 중 재시도할 수 없는 오류를 받았습니다. 서비스 상태를 확인하세요.</td></tr><tr><td>🟢 <code>업데이트</code></td><td><code>업데이트됨</code></td><td><code>상태</code></td><td>폴링 중 그룹 상태 변경이 감지되었습니다.</td></tr><tr><td>🟢 <code>업데이트</code></td><td><code>포기됨</code></td><td>-</td><td>티켓이 정상적으로 삭제되었습니다.</td></tr><tr><td>🟢 <code>업데이트</code></td><td><code>abandon_failed</code></td><td><code>reason: 'not_found'</code></td><td>에이전트가 삭제할 그룹을 찾지 못했습니다. 만료되었을 수 있습니다.</td></tr><tr><td>🟡 <code>경고</code></td><td><code>abandon_failed</code></td><td><code>reason: 'match_found'</code></td><td>에이전트가 매치된 그룹을 삭제할 수 없었습니다. 포기를 비활성화하거나 <a data-mention href="https://docs.edgegap.com/ko/learn/matchmaking/matchmaker-in-depth.md#backfill-match">심층 살펴보기</a> 플레이어를 대체하세요.</td></tr><tr><td>🔴 <code>오류</code></td><td><code>abandon_failed</code></td><td><code>reason: 'error'</code>, <code>세부 정보</code></td><td>그룹 또는 멤버십 삭제에 실패했습니다.</td></tr><tr><td>🟡 <code>경고</code></td><td><code>restart_skipped</code></td><td>-</td><td>그룹이 이미 매치되었으므로, 포기 후 후속 작업이 건너뛰어졌습니다.</td></tr><tr><td>🟢 <code>업데이트</code></td><td><code>제거됨</code></td><td>-</td><td>그룹이 종료되었거나 만료되어, 로컬 참조가 삭제되었습니다.</td></tr></tbody></table>

### 서버 이벤트

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

{% hint style="info" %}
현재 할당된 티켓은 Server Agent 속성에서 읽을 수 있습니다 `assignments` 언제든지, 그리고 연결 시간은 `connectedAt` .
{% endhint %}

{% hint style="success" %}
다음에 접근하여 상태를 읽습니다 `.current` 및 `.previous` 같은 관찰 대상의  **다음을 기준으로 분기합니다 `event.code`** 이벤트 메시지는 버전 간에 변경될 수 있기 때문입니다. 🔴 `오류` 이벤트는 전체 오류 메시지도 다음에 저장합니다 `.error` .
{% endhint %}

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

<table data-full-width="true"><thead><tr><th width="125">작업 유형</th><th width="200">이벤트 코드</th><th width="300">이벤트 매개변수</th><th>설명</th></tr></thead><tbody><tr><td>🟢 <code>업데이트</code></td><td><code>정상</code></td><td>-</td><td>모든 시스템이 정상입니다.</td></tr><tr><td>🟢 <code>업데이트</code></td><td><code>비정상</code></td><td>-</td><td>예상치 못한 문제입니다.</td></tr><tr><td>🔴 <code>오류</code></td><td><code>monitor_failed</code></td><td><code>세부 정보</code></td><td>잘못된 구성 또는 예상치 못한 문제입니다.</td></tr></tbody></table>

관찰자에서 방출되는 미리 보기 이벤트 `backfills` :

<table data-full-width="true"><thead><tr><th width="125">작업 유형</th><th width="200">이벤트 코드</th><th width="300">이벤트 매개변수</th><th>설명</th></tr></thead><tbody><tr><td>🟢 <code>업데이트</code></td><td><code>생성됨</code></td><td><code>backfillId</code></td><td>백필이 정상적으로 생성되었습니다.</td></tr><tr><td>🔴 <code>오류</code></td><td><code>create_failed</code></td><td><code>세부 정보</code></td><td>백필에 예상치 못한 문제가 발생했습니다. 서비스 상태를 확인하세요.</td></tr><tr><td>🔴 <code>오류</code></td><td><code>capacity_reached</code></td><td>-</td><td>서버가 가득 찼으며, 백필이 생성되지 않았습니다.</td></tr><tr><td>🔵 <code>로그</code></td><td><code>폴링</code></td><td><code>시도</code>, <code>maxAttempts</code></td><td>에이전트가 백필 폴링을 시작했습니다. 다음과 함께만 방출됩니다 <code>logPollingUpdates: true</code>.</td></tr><tr><td>🟢 <code>업데이트</code></td><td><code>할당됨</code></td><td><code>backfillId</code>, <code>ticketId</code></td><td>백필에 티켓이 정상적으로 할당되었습니다.</td></tr><tr><td>🔵 <code>로그</code></td><td><code>polling_stopped</code></td><td>-</td><td>에이전트가 폴링을 중지했습니다. 더 이상 폴링할 백필이 없습니다.</td></tr><tr><td>🟡 <code>경고</code></td><td><code>polling_failed</code></td><td><code>backfillId</code>, <code>reason: 'not_found'</code></td><td>찾을 수 없어 참조를 제거합니다. 백필이 만료되었을 가능성이 큽니다.</td></tr><tr><td>🔴 <code>오류</code></td><td><code>polling_failed</code></td><td><code>backfillId</code>, <code>reason: 'max_retries'</code></td><td>재시도 한도를 초과하여, 모든 백필을 포기합니다.</td></tr><tr><td>🔴 <code>오류</code></td><td><code>polling_failed</code></td><td><code>backfillId</code>, <code>reason: 'error'</code>, <code>세부 정보</code></td><td>예상치 못한 문제로, 백필을 포기하고 교체합니다.</td></tr><tr><td>🔵 <code>로그</code></td><td><code>포기됨</code></td><td><code>backfillId</code></td><td>백필이 포기되어, 참조를 제거합니다.</td></tr><tr><td>🟡 <code>경고</code></td><td><code>abandon_failed</code></td><td><code>backfillId</code>, <code>reason: 'not_found'</code></td><td>백필을 찾을 수 없습니다. 만료되었거나 중복 호출일 가능성이 큽니다.</td></tr><tr><td>🟡 <code>경고</code></td><td><code>abandon_failed</code></td><td><code>backfillId</code>, <code>reason: 'error'</code>, <code>세부 정보</code></td><td>포기에 실패하여, 참조를 제거합니다.</td></tr><tr><td>🟢 <code>업데이트</code></td><td><code>제거됨</code></td><td><code>backfillId</code></td><td>백필 참조가 제거되었습니다. 중지되지 않으면 백필은 자동으로 교체됩니다.</td></tr><tr><td>🟡 <code>경고</code></td><td><code>remove_failed</code></td><td><code>backfillId</code></td><td>백필 참조를 찾을 수 없습니다. 중복 호출일 가능성이 큽니다.</td></tr></tbody></table>
