> 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/threejs-minigames.md).

# Three.js 미니게임

매치메이킹이 있는 three.js 멀티플레이어: 매치가 시작될 때마다 하나의 권한 있는 Node.js 서버가 실행되는 다섯 가지 브라우저 미니게임.

매치메이킹을 사용해 three.js 멀티플레이어 게임을 만드는 방법을 알아보세요.

![매치메이커가 있는 Three.js 멀티플레이어](https://raw.githubusercontent.com/edgegap/netcode-sample-threejs-minigames/main/docs/images/banner.jpg)

이 샘플에는 장르별로 하나씩, 총 다섯 개의 작은 브라우저 게임이 포함되어 있으며, 다음을 사용해 만들었습니다 [three.js](https://threejs.org/) 및 순수 node.js WebSocket 서버. 플레이어는 **매치 찾기** 를 페이지에서 클릭하면 매치메이커가 플레이어들을 그룹으로 묶고, 근처에 전용 서버를 시작해 연결하고 플레이하게 합니다. 매치가 끝나면 서버가 스스로 중지됩니다.

이 샘플에는 5개의 미니게임이 포함되어 있습니다:

* Blaster Arena: 탑다운 자유전, 먼저 10회 처치하면 승리. 2\~8명, 총 3명이 될 때까지 봇이 채웁니다.
* Kart Rally: 레이싱, 먼저 3바퀴를 돌면 승리. 1\~8명.
* Rocket Soccer: 스포츠, 1대1 또는 2대2 팀전. 총 2\~4명.
* Light Cycles: 아케이드, 최후의 생존자 방식. 2\~6명, 총 4명이 될 때까지 봇이 채웁니다.
* Sumo Push: 파티 게임, 킹 오브 더 힐. 2\~8명, 총 4명이 될 때까지 봇이 채웁니다.

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

* **브라우저에서의 매치메이킹** 와 함께 [Edgegap JavaScript SDK](https://www.npmjs.com/package/@edgegap/sdk) (`@edgegap/sdk`): 매치 찾기, 취소, 그리고 속도 제한 시 재시도를 지원하며, 게임마다 하나의 매치메이커와 프로필이 있고 2팀 프로필도 포함됩니다.
* **권위형 서버**: 페이지는 입력만 보내고 수신한 상태를 그리므로, 플레이어가 브라우저에서 규칙을 바꿀 수 없습니다.
* **매치당 서버 하나**, TLS 업그레이드 덕분에 7만 건을 넘어섰습니다. SDK로 매치 세부 정보를 읽고, 매치가 끝나거나 모두 떠나거나 아무도 참여하지 않으면 자체 배포를 중지합니다. `wss://` TLS 업그레이드 덕분에 7만 건을 넘어섰습니다. SDK로 매치 세부 정보를 읽고, 매치가 끝나거나 모두 떠나거나 아무도 참여하지 않으면 자체 배포를 중지합니다.
* **하나의 이미지로 다섯 게임**: 게임마다 하나의 앱 버전이 있고, 서버를 선택하는 `GAME` 환경 변수가 있습니다.
* **빌드 단계 없음**: Three.js와 SDK의 브라우저 빌드는 import map을 통해 CDN에서 로드되므로, 페이지는 어디서나 호스팅할 수 있는 정적 파일입니다.

{% hint style="info" %}
다음 자료를 참고하세요 [샘플 저장소](https://github.com/edgegap/netcode-sample-threejs-minigames) 각 게임의 규칙과 서버 설계에 대한 [아키텍처 노트](https://github.com/edgegap/netcode-sample-threejs-minigames/blob/main/docs/architecture.md) 및 [자신만의 게임 추가하기](https://github.com/edgegap/netcode-sample-threejs-minigames/blob/main/docs/adding-a-game.md).
{% endhint %}

## ✔️ 준비

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

* [Three.js 미니게임 샘플](https://github.com/edgegap/netcode-sample-threejs-minigames).
* [Node.js](https://nodejs.org/) 22 이상, 서버와 페이지를 로컬에서 실행하기 위해.
* [Docker](https://docs.docker.com/get-started/get-docker/), 서버 이미지를 빌드하기 위해.

☑️ 먼저 게임을 로컬에서 실행해 보세요:

{% code collapsedlinecount="10" %}

```bash
npm install
npm run dev:all
```

{% endcode %}

이렇게 하면 다섯 개 게임 서버가 포트 `7771` 다음으로 `7775` 에서 시작되고, 페이지는 `http://localhost:8080`에서 제공됩니다. 게임을 고르고, **로컬 서버**를 클릭한 다음, 두 번째 탭을 열어 자기 자신과 대결해 보세요. `npm test` 두 명의 헤드리스 플레이어로 각 게임의 전체 매치를 플레이합니다.

## ⚡ 배포 및 연결

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

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

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

☑️ 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
docker build --platform linux/amd64 -t registry.edgegap.com/<project>/threejs-minigames:<tag> .
docker push registry.edgegap.com/<project>/threejs-minigames:<tag>
```

{% endcode %}

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

### 2. 앱 버전 생성

☑️ [애플리케이션을 만들고](https://app.edgegap.com/application-management/applications/list) 이름이 `threejs-minigames`, 그리고 게임마다 하나의 버전: `blaster-v1`, `kart-v1`, `soccer-v1`, `cycles-v1` 및 `sumo-v1`.

☑️ 각 앱 버전을 설정하세요:

* **이미지**: `registry.edgegap.com/<project>/threejs-minigames`, 태그 `<tag>`,
* **레지스트리 자격 증명**: Edgegap이 이미지를 가져올 수 있도록 컨테이너 레지스트리 사용자 이름과 토큰,
* **리소스**: 0.25 vCPU 및 512MB 메모리,
* **포트**: `7777`, 이름 `gameport`, 프로토콜 **WS**, **TLS 업그레이드** 활성화됨,
* **환경 변수**: `GAME` 다음으로 설정 `blaster`, `kart`, `soccer`, `cycles` 또는 `sumo`,
* **최대 지속 시간**: 30분, 안전장치로서: 서버가 스스로 중지합니다.

{% hint style="warning" %}
**TLS 업그레이드** 브라우저가 `https` 페이지에서 연결할 수 있게 합니다 `wss://<id>.pr.edgegap.net:<port>`. Edgegap이 TLS를 종료하고 일반 WebSocket 트래픽을 포트 `7777`로 전달합니다. 인증서가 일치하도록 IP가 아니라 FQDN으로 연결하세요.
{% endhint %}

모든 버전에서 사용할 수 있는 선택적 환경 변수:

* `WAIT_SECONDS` - 첫 번째 플레이어가 합류한 뒤 이 시간이 지나면 시작합니다. 매칭된 플레이어가 없어도 시작합니다(기본값 `15`),
* `MATCH_SECONDS` - 매치 시간 제한(게임별 기본값),
* `FIRST_JOIN_TIMEOUT_S` - 아무도 합류하지 않은 서버가 자동 중지되기까지의 시간(초, 기본값 `120`),
* `EMPTY_TIMEOUT_S` - 모두 떠난 서버가 스스로 중지되기 전의 초(기본값 `30`),
* `REQUIRE_TICKET` - `1` 은 이 매치에 속하지 않는 매치메이커 티켓의 플레이어를 거부합니다.

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

### 3. 서버 하나를 직접 테스트하기

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

{% code collapsedlinecount="10" %}

```bash
EDGEGAP_API_TOKEN=<token> node edgegap/deploy.mjs threejs-minigames sumo-v1
```

{% endcode %}

스크립트가 다음을 출력합니다 `wss://<request_id>.pr.edgegap.net:<port>`.

☑️ 다음을 엽니다 `http://localhost:8080/games/sumo/?server=wss://...` 를 두 개의 브라우저 탭에서 열고 플레이하세요. 매치가 끝나면 서버가 자체 배포를 중지합니다.

{% hint style="danger" %}
**Edgegap API 토큰을 웹페이지나 서버 이미지에 절대 넣지 마세요.** 플레이어는 자체 클라이언트 안전 토큰을 사용하는 매치메이커를 통해 서버를 받습니다.
{% endhint %}

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

### 4. 매치메이커 생성하기

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

이 구성에는 게임마다 하나의 프로필이 있으며, 각 프로필은 해당 게임의 앱 버전을 가리킵니다:

* `blaster`, `kart` 및 `sumo`: 2\~8명, `cycles`: 2\~6명. 20초 후, 혼자 대기 중인 플레이어에게 서버가 할당되고, 봇이 빈 자리를 채웁니다.
* `soccer`: `team_count: 2` 팀당 1명 또는 2명으로, 4명이 대기 중이면 2대2가 되고 그렇지 않으면 1대1이 됩니다. 각 티켓에는 `team_id`가 할당되며, 서버는 각 플레이어를 해당 팀에 배치합니다.

☑️ 브라우저 게임은 페이지에서 매치메이커를 호출하므로, 페이지를 제공하는 모든 출처를 `allowed_cors_origins`에 추가하세요. 구성은 `http://localhost:8080`.

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

{% hint style="info" %}
팀 프로필의 경우 `min_team_size: 1` 부터 시작하고 확장에 의존하지 마세요. 우리의 테스트에서는 `team_count: 2` 프로필이 `min_team_size: 2` 와 20초 확장을 사용하면 `1` 티켓 만료가 임박했을 때만 대기 중인 두 플레이어를 매칭했습니다.
{% endhint %}

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

### 5. 매치 찾기

☑️ 매치메이커의 API URL과 인증 토큰을 `client/config.js` 에 넣거나, git에서 무시되는 `client/config.local.js`에 넣거나, `?mm=<API URL>&token=<Auth Token>` 을 페이지 URL에 추가하세요.

{% hint style="success" %}
그 **매치메이커 인증 토큰은 게임 클라이언트에 넣어 배포해도 안전합니다**: 매치를 찾는 데만 사용할 수 있습니다. Edgegap API 토큰이 아닙니다.
{% endhint %}

☑️ 실행 `npm run web` 을 실행하고 같은 게임을 두 탭에서 여세요. 둘 다 20초 안에 **매치 찾기** 를 클릭하세요.

각 탭은 SDK의 `GroupAgent` 를 사용하여 다음을 수행합니다:

1. 게임 프로필에 대해 플레이어 1명의 매치메이킹 그룹을 만들고, 즉시 준비 상태로 두기,
2. 다음으로 `nextAssignment()` 이 `HOST_ASSIGNED`가 될 때까지 기다리기, 여기에는 서버 주소와 `gameport`,
3. 에 연결하기 `getConnectionUrl(assignment, "gameport")`를 사용하면 `wss://<fqdn>:<port>`가 되고, 티켓 ID를 보내 서버가 플레이어의 팀을 알 수 있게 합니다.

{% code collapsedlinecount="10" %}

```javascript
import { getConnectionUrl, matchmaking } from "@edgegap/sdk";

const agent = new matchmaking.GroupAgent({ baseUrl: "<API URL>", authToken: "<Auth Token>" });
agent.initialize();

agent.createGroup({ profile: "sumo", attributes: {}, is_ready: true }, true);
const assignment = await agent.nextAssignment();
const url = getConnectionUrl(assignment, "gameport");
const ticketId = agent.group.current.ticket_id;
```

{% endcode %}

새 배포는 `HOST_ASSIGNED`이후 몇 초 동안 연결을 거부할 수 있으므로, 클라이언트가 재시도합니다. SDK는 속도 제한(`429`) 및 실패한 요청을 스스로 재시도하고, **취소** 는 그룹을 `stopMatchmaking()`.

🙌 이제 두 플레이어가 같은 매치에 있고, 그들 근처에 배치된 서버에서 플레이합니다.

☑️ 브라우저 없이 전체 경로를 테스트하려면 E2E 테스트를 실행하세요. 각 게임에 대해 여러 개의 헤드리스 플레이어를 큐에 넣고, 같은 배포에서 만나 전체 매치를 플레이하는지 확인한 다음, 배포가 스스로 중지될 때까지 기다립니다:

{% code collapsedlinecount="10" %}

```bash
MM_URL=<API URL> MM_TOKEN=<Auth Token> npm run e2e
```

{% endcode %}

## 📦 게임 배포하기

* 페이지는 어디서나 호스팅할 수 있습니다. 빌드 단계가 없는 정적 파일입니다(`index.html`, `client/`, `games/`). 각 출처를 `allowed_cors_origins`.
* 로 설정 `inspect` 를 매치메이커 구성에서 끄세요.
* 설정 `REQUIRE_TICKET=1` 을 앱 버전에 설정해 매치메이커가 보내지 않은 플레이어를 차단하세요.
* 새 서버 빌드를 배포하려면 새 이미지 태그를 푸시하고 각 앱 버전을 그 이미지로 가리키게 하세요. 새 매치는 새 빌드를 사용하고, 실행 중인 매치는 이전 빌드를 유지합니다.
* SDK를 업그레이드하려면 `package.json` 과 각 게임 페이지의 import map에서 버전을 바꾸고, import map의 무결성 해시도 업데이트하세요.

{% hint style="info" %}
코딩 에이전트를 사용 중이신가요? `edgegap-threejs` 스킬은 [Edgegap의 에이전트 스킬](https://github.com/edgegap/llm-agent-skills) 에 이 샘플의 서버와 클라이언트를 템플릿으로 포함하고 있으며, 여러분의 브라우저 게임에 대해 에이전트를 동일한 단계로 안내합니다.
{% endhint %}
