> 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/docs/sample-projects/web-games/colyseus-realtime-tanks.md).

# 콜라이지어스 실시간 탱크

직접 연결 또는 Edgegap 매치메이커를 사용하여, 경기마다 하나의 전용 서버를 두는 Colyseus 0.17 멀티플레이어 탱크 게임을 Edgegap에서 호스팅하세요.

호스팅하는 방법을 알아보세요 [Colyseus](https://colyseus.io/) Edgegap에서 서버를 호스팅하는 방법을, 다음의 기법을 사용하여 [Realtime Tanks](https://github.com/colyseus/realtime-tanks-demo) Colyseus 팀의 샘플입니다.

이 샘플에는 하나의 권위적 Colyseus 서버와 9개의 클라이언트가 있으며, 각각 Three.js, PlayCanvas, Construct 3, Godot, Unity, Defold, GameMaker, Haxe, MonoGame 등 서로 다른 엔진으로 만들어졌습니다. 각 매치는 자체 서버를 가지며, 플레이어들 가까이에서 시작되고, 매치가 끝나면 서버가 스스로 중지됩니다.

이 샘플은 다음을 보여줍니다:

* **Colyseus 0.17** 하나의 `linux/amd64` 포트에서 수신 대기하는 Docker 이미지 `2567`,
* **경기당 서버 1개** - 아무도 참여하지 않거나, 비어 있는 상태가 지속되거나, 정해진 라운드 수가 지나면 서버가 자체 배포를 중지합니다,
* **직접 모드** - 배포를 시작한 뒤 9개의 클라이언트 중 아무거나에 해당 URL을 전달합니다. `?server=` 또는 `--server=`,
* **Edgegap Matchmaker** (선택 사항) - 웹 및 데스크톱 빌드를 위한 Three.js, Unity 및 Godot 클라이언트에 내장되어 있습니다,
* **TLS 업그레이드를 사용하는 하나의 WebSocket 포트** - Colyseus 매치메이킹 HTTP 요청과 룸 WebSocket을 모두 전달합니다.

{% hint style="success" %}
참조 [edgegap/README.md](https://github.com/edgegap/backend-game-sample-threejs-colyseus-tanks/blob/master/edgegap/README.md) 변경된 파일의 전체 목록과 클라이언트별 설정은 샘플 저장소의
{% endhint %}

## ✔️ 준비

시작하기 전에 다음이 필요합니다:

* [Realtime Tanks 샘플 프로젝트](https://github.com/edgegap/backend-game-sample-threejs-colyseus-tanks) (Edgegap용으로 수정됨),
* [Node.js](https://nodejs.org/), 서버를 로컬에서 실행하고 배포 스크립트를 실행합니다.

<details>

<summary><a href="https://www.docker.com/products/docker-desktop/">Docker Desktop(또는 Docker CLI) 설치</a></summary>

* [공식 소스에서 Docker Desktop을 설치하세요](https://www.docker.com/products/docker-desktop/) (계정이 필요하지 않습니다).
* 설치를 완료한 후 컴퓨터를 다시 시작하세요.

</details>

로컬에서는 서버가 업스트림처럼 동작합니다. 다음 위치에서 `서버` 폴더에서 다음을 실행합니다 `npm install` 그런 다음 `npm run dev`.

## ⚡ 배포 및 연결

### 1. 서버 이미지 빌드

☑️ 시작하려면 다음이 필요합니다 [Edgegap에 무료 계정을 만드세요](https://app.edgegap.com/auth/register). 신용카드는 필요 없습니다.

☑️ 다음 항목을 찾습니다: [컨테이너 레지스트리](https://docs.edgegap.com/ko/learn/advanced-features/edgegap-container-registry.md#getting-your-credentials) 프로젝트 이름과 자격 증명.

☑️ Docker로 Edgegap의 Container Registry에 로그인하고, 레지스트리 프로젝트 이름, 사용자 이름 및 토큰을 사용하세요:

{% tabs %}
{% tab title="Bash (리눅스)" %}

```bash
project='<REGISTRY_PROJECT>';
username='robot$<REGISTRY_ORGANIZATION_ID>+client-push';
token='<REGISTRY_TOKEN>';

echo "$token" | docker login registry.edgegap.com -u "$username" --password-stdin 2>&1
```

{% endtab %}

{% tab title="PowerShell (윈도우)" %}

```powershell
$project = '<REGISTRY_PROJECT>'
$username = 'robot$<REGISTRY_ORGANIZATION_ID>+client-push'
$token = '<REGISTRY_TOKEN>'

echo "$token" | docker login registry.edgegap.com -u "$username" --password-stdin 2>&1
```

{% endtab %}
{% endtabs %}

☑️ 서버 이미지를 빌드하고 푸시합니다:

{% code collapsedlinecount="10" %}

```bash
cd server
docker build --platform linux/amd64 -t registry.edgegap.com/<project>/realtime-tanks:v1 .
docker push registry.edgegap.com/<project>/realtime-tanks:v1
```

{% endcode %}

{% hint style="danger" %}
:x: **금지 - 기존 태그를 덮어쓰거나 다음을 사용하지 마세요. `latest`  태그** - 이렇게 하면 오래된 캐시가 배포됩니다.\
:white\_check\_mark: **권장 - 버전 태그를 항상 올리고** 새 빌드를 배포하세요.
{% endhint %}

☑️ 선택 사항: 먼저 이미지를 로컬에서 테스트하세요. `ARBITRIUM_REQUEST_ID` Edgegap에서처럼 동작하게 합니다. - 삭제 URL이 설정되지 않은 경우 자체 중지 후 이를 기록하고 종료합니다:

{% code collapsedlinecount="10" %}

```bash
docker run -p 2567:2567 -e ARBITRIUM_REQUEST_ID=local -e EMPTY_TIMEOUT_S=10 realtime-tanks:v1
```

{% endcode %}

✅ 이제 다음 단계로 진행할 수 있습니다.

### 2. 앱 버전 만들기

☑️ [애플리케이션을 만들고](https://app.edgegap.com/application-management/applications/list) 이름이 `realtime-tanks`, 그리고 버전 이름 `v1` 을 다음과 함께:

* 이미지 `registry.edgegap.com/<project>/realtime-tanks`, 태그 `v1`,
* Edgegap이 이미지를 가져올 수 있도록 컨테이너 레지스트리 사용자 이름과 토큰,
* 리소스 0.25 vCPU와 512 MB 메모리,
* [포트](https://docs.edgegap.com/ko/learn/orchestration/application-and-versions.md#port-mapping) `2567`, 이름은 `gameport`, 프로토콜 **WS**, **TLS 업그레이드** 활성화됨,
* [최대 기간](https://docs.edgegap.com/ko/learn/orchestration/application-and-versions.md#safety-guardrails) 테스트용 60분.

{% hint style="warning" %}
**TLS 업그레이드** 브라우저 빌드를 포함한 모든 클라이언트가 다음에 연결할 수 있게 합니다 `wss://<id>.pr.edgegap.net:<port>`. Edgegap이 TLS를 종료하고 일반 HTTP 및 WebSocket을 포트 `2567`로 전달하므로, Colyseus 매치메이킹 HTTP 요청과 룸 WebSocket이 하나의 포트를 공유합니다. 다음을 참조하세요 [웹소켓(WS) 및 보안 웹소켓(WSS)](https://docs.edgegap.com/ko/learn/orchestration/deployments.md#websockets-ws-and-secure-websockets-wss).
{% endhint %}

선택적으로, 앱 버전에 환경 변수를 설정하세요:

* `MATCH_ROUNDS` - 이 수만큼 승리 라운드가 지나면 경기를 종료합니다(기본값 `0`, 무한 아레나),
* `FIRST_JOIN_TIMEOUT_S` - 아무도 합류하지 않은 서버가 자동 중지되기까지의 시간(초, 기본값 `120`),
* `EMPTY_TIMEOUT_S` - 모두 떠난 서버가 스스로 중지되기 전의 초(기본값 `30`).

✅ 이제 다음 단계로 진행할 수 있습니다.

### 3. 직접 연결

☑️ 샘플의 배포 스크립트를 사용해 가까운 곳에 서버를 시작하세요. Edgegap API 토큰은 로컬 머신에만 남습니다:

{% code collapsedlinecount="10" %}

```bash
cd server
EDGEGAP_API_TOKEN=<token> npm run edgegap:deploy -- realtime-tanks v1
```

{% endcode %}

스크립트가 다음을 출력합니다 `wss://<request_id>.pr.edgegap.net:<port>` 그리고 이를 각 클라이언트에 전달하는 방법입니다.

☑️ URL을 클라이언트에 전달합니다:

* **Three.js, PlayCanvas, Construct 3** - `?server=wss://...` 페이지 URL에,
* **Godot** - `--server=wss://...` (이후 `--` 에디터의 기본 실행 인수에 추가), 웹 내보내기 `?server=wss://...`,
* **Unity** - `--server=wss://...` 명령줄에서, WebGL `?server=wss://...`, 또는 `serverUrl` 필드,
* **Defold** - HTML5 `?server=wss://...`, 네이티브 `--config=tanks.server_url=wss://...` 또는 `[tanks] server_url` 의 `game.project`,
* **GameMaker** - `--server=wss://...` 명령줄에서, HTML5 `?server=wss://...`,
* **Haxe** - JS `?server=wss://...`, HashLink `--server=wss://...`,
* **MonoGame** - `--server=wss://...` 또는 `TANKS_SERVER_URL` 환경 변수.

{% hint style="danger" %}
실제 게임에서는 백엔드가 동일한 [배포 API](https://docs.edgegap.com/ko/docs/api/dedicated-servers.md) (`POST /v2/deployments`)을 호출해 로비가 준비되면 플레이어에게 URL을 보냅니다. **Edgegap API 토큰을 게임 클라이언트나 서버 이미지에 절대 넣지 마세요.**
{% endhint %}

🙌 Edgegap에서 첫 배포를 축하합니다!

### 4. 매치메이커 추가하기(선택 사항)

☑️ 다음을 엽니다 [Matchmaker](https://app.edgegap.com/matchmaker-management-v2/matchmakers/list) 대시보드 페이지에서 다음을 클릭합니다 **생성**를 클릭한 뒤, `edgegap/matchmaker-config.json` 을 샘플에서 업로드하세요.

설정에는 하나의 `캐주얼` 각 경기당 2\~8명의 플레이어를 위한 프로필입니다. 15초 후 대기 중인 사람들로, 최소 2명이 참가한 경기를 시작합니다.

☑️ 게임을 제공하는 모든 오리진을 다음에 추가합니다 `allowed_cors_origins`, 브라우저 빌드는 페이지에서 매치메이커를 호출하기 때문입니다(참조: [CORS](https://docs.edgegap.com/ko/learn/matchmaking/matchmaker-in-depth.md#cross-origin-resource-sharing-cors)). 이 구성은 다음을 허용합니다 `http://localhost:5173` (Vite), `http://localhost:8060` (Godot 웹) 및 `http://localhost:8080`.

☑️ 클릭 **만들기 및 시작**. 매치메이커가 표시되면 **온라인**, 해당 값을 복사하세요 **API URL** 및 **인증 토큰**.

{% hint style="danger" %}
**API 토큰은 계정에 무제한 접근 권한을 제공하므로 게임 클라이언트에 Edgegap API 엔드포인트를 통합하지 마세요. 다음을 참조하세요** [통합](https://docs.edgegap.com/ko/docs/api/integration.md) **안전한 클라이언트용 API 엔드포인트와 기능은 다음을 참조하세요.**
{% endhint %}

{% hint style="info" %}
매치메이킹 인증 토큰은 매치메이커 전용 범위이므로 게임 클라이언트에 포함해 배포해도 안전합니다.
{% endhint %}

☑️ 매치메이커 설정으로 클라이언트를 시작합니다:

* **Three.js** - `http://localhost:5173/?mm=<API URL>&mmToken=<Auth Token>`, 또는 `VITE_MM_URL` / `VITE_MM_TOKEN` 의 `.env.local`,
* **Unity** - `--mm=<API URL> --mm-token=<Auth Token>`, WebGL `?mm=...&mmToken=...`, 또는 *Edgegap Matchmaker* 필드에서 `GameManager`,
* **Godot** - `-- --mm=<API URL> --mm-token=<Auth Token>`, 웹 내보내기 `?mm=...&mmToken=...`.

☑️ 두 개의 클라이언트를 엽니다. 매치메이킹에는 최소 2명의 플레이어가 필요하며, 서로 다른 엔진을 사용할 수 있습니다.

각 클라이언트는 "플레이어를 찾는 중..."을 표시하고 서버가 할당되면 연결합니다.  `서버` 설정은 항상 매치메이커보다 우선합니다.

🙌 Edgegap에서 첫 번째 매치메이킹 배포를 축하합니다!

## 🔄 매치 라이프사이클

1. 클라이언트가 다음을 사용해 티켓을 생성합니다: `POST /tickets` 동안 `캐주얼` 프로필을 설정한 다음, 2초마다 다음으로 확인합니다 `GET /tickets/{id}`.
2. 매치메이커가 다음을 배포합니다: `realtime-tanks` 플레이어 가까이에서. 티켓이 다음에 도달하면 `HOST_ASSIGNED`, 클라이언트는 할당의 FQDN과 외부 포트를 읽습니다 `gameport`.
3. 클라이언트가 다음에 참여합니다: `wss://<fqdn>:<port>`. 새로 시작한 서버는 몇 초 동안 502로 응답할 수 있으므로, 클라이언트는 최대 20초 동안 다시 참가를 시도합니다(참조: [서버에 연결](https://docs.edgegap.com/ko/learn/matchmaking/matchmaker-in-depth.md#connect-to-server)).
4. 서버 호출 `ARBITRIUM_DELETE_URL` 아무도 다음 시간 내에 참여하지 않으면 자체 배포를 중지합니다 `FIRST_JOIN_TIMEOUT_S`, 모두가 다음 시간 동안 떠나면 `EMPTY_TIMEOUT_S`, 또는 다음 경우 `MATCH_ROUNDS` 라운드가 승리한 경우입니다. 앱 버전의 최대 지속 시간이 최후 방어선입니다.

매치메이커 클라이언트는 작고 의존성이 없어서 다른 클라이언트로 쉽게 이식할 수 있습니다 - 다음을 참조하세요 `web-threejs/src/Matchmaker.ts`, `unity/Assets/Scripts/EdgegapMatchmaker.cs` 및 `godot/scripts/edgegap_matchmaker.gd`.

참조 [매치메이킹](https://docs.edgegap.com/ko/learn/matchmaking.md) 및 [배포](https://docs.edgegap.com/ko/learn/orchestration/deployments.md) 자세한 내용을 알아보세요.

## 🚀 더 나아가기

* **참가자 검증** - 매치메이커 배포는 다음을 받습니다 [`MM_TICKET_IDS`](https://docs.edgegap.com/ko/learn/matchmaking/matchmaker-in-depth.md#injected-variables). 클라이언트가 참가 옵션에서 티켓 ID를 전달하게 하고, 다음에서 이를 확인합니다 `onAuth`, 따라서 매칭된 플레이어만 참여할 수 있습니다.
* **출시 전** - 다음을 설정합니다 `inspect` 다음으로 `false` 매치메이커 구성에서 실제 오리진을 나열하고, 경기 시간에 맞게 최대 지속 시간을 늘립니다(참조: [실서비스 전](https://docs.edgegap.com/ko/learn/matchmaking/matchmaker-in-depth.md#before-going-live)).

## ⚠️ 알려진 문제

* Colyseus 0.17, 매치메이커 3.3.2, Godot 4.5.2 및 Unity 6000.3으로 Edgegap에서 처음부터 끝까지 테스트되었습니다:
  * 직접 - Node Colyseus 클라이언트와 Godot 데스크톱 클라이언트가 다음을 통해 배포에 참여했습니다 `wss://`, 그리고 모두가 떠난 뒤 서버가 스스로 중지되었습니다,
  * 매치메이커 - 브라우저의 Three.js와 Godot 데스크톱 클라이언트가 하나의 서버로 매칭되었고, 그다음 Three.js와 Unity Windows 빌드가 매칭되었습니다.
* Construct 3, Defold, GameMaker, Haxe and PlayCanvas `서버` 오버라이드, Godot 웹 내보내기 및 Unity WebGL은 아직 테스트되지 않았습니다.
