> 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/godot/nakama-fish-game.md).

# 나카마 피시 게임

nakama-edgegap 플러그인을 통해 Nakama 매치메이커가 시작하는, Godot 4용 Heroic Labs의 Fish Game을 Edgegap 전용 서버에서 호스팅하세요.

Edgegap과 함께 Godot 프로젝트를 호스팅하는 방법 알아보기 [Nakama](https://heroiclabs.com) 매치메이킹, 다음에서 가져온 기법을 사용하여 [Fish Game](https://github.com/heroiclabs/fishgame-godot) Heroic Labs의 2\~4인용 샘플로, Godot 4로 포팅되었습니다.

원본 버전에서는 각 매치가 한 플레이어의 기기에서 실행되고 Nakama를 통해 중계되었습니다. 그 안에서 [우리 포크](https://github.com/edgegap/backend-game-sample-godot-nakama-fishgame) 플레이어 호스트 없음 - Nakama가 계정, 매치메이킹, 리더보드를 관리하고, 매칭된 플레이어 근처에서 헤드리스 Godot 서버를 시작합니다. [Nakama용 Edgegap Fleet Manager](https://github.com/edgegap/backend-nakama-edgegap-plugin).

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

* **Godot 4.7** GDScript로 작성된 게임으로, UDP 포트에서 ENet을 통해 헤드리스 전용 서버로 실행됩니다. `7777`,
* **Nakama 3.39** Go 모듈과 함께 - 매치메이커 훅이 매치마다 하나의 배포를 시작하고, 서버가 준비되었다고 보고하면 각 플레이어에게 서버 주소를 보냅니다. `준비 완료`,
* **서버 권한 매치 규칙** - 서버가 타격, 사망, 아이템 획득, 스폰, 라운드와 승자를 결정합니다,
* **플레이어 검사** - 서버는 유효한 Nakama 세션을 가지고 있고 이 서버에 매칭된 플레이어만 허용합니다,
* **서버 간 리더보드** - 서버는 승리를 권한 있는 Nakama 리더보드에 기록하며, 플레이어는 여기에 쓸 수 없습니다,
* **서버 자동 중지** - 서버는 매치가 끝나면 Nakama에 배포 중지를 요청합니다.

{% hint style="success" %}
참조 [Nakama에서 배포](https://docs.edgegap.com/ko/docs/tools-and-integrations/nakama.md) Nakama 통합 개요는 [EDGEGAP.md](https://github.com/edgegap/backend-game-sample-godot-nakama-fishgame/blob/main/EDGEGAP.md) 그리고 Edgegap 파일, 테스트, 알려진 제한 사항의 전체 목록은 샘플 저장소에서 확인하세요.
{% endhint %}

{% hint style="warning" %}
게임의 대부분의 아트와 음악은 [CC BY-NC 4.0](https://creativecommons.org/licenses/by-nc/4.0/) Heroic Labs에 의해(다음을 참조 `assets/LICENSE.txt`). 코드는 Apache 2.0입니다.
{% endhint %}

## ✔️ 준비

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

* [Fish Game 샘플 프로젝트](https://github.com/edgegap/backend-game-sample-godot-nakama-fishgame) (Edgegap용으로 수정됨),
* [Godot 4.7](https://godotengine.org/) (4.3 이상이면 동작해야 합니다),
* Edgegap API 토큰 - Nakama 전용,
* Nakama의 공개 HTTPS 주소 - Edgegap 서버가 Nakama에 다시 콜백하므로, `localhost` 작동하지 않습니다(테스트에는 터널이면 충분합니다. 2단계를 참조하세요).

<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>

## ⚡ 배포 및 연결

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

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

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

☑️ 저장소 루트에서 서버 이미지를 빌드하고 푸시하세요. `server/Dockerfile` "Linux Server" 프리셋을 `.pck` 로 내보내고 헤드리스 Godot로 실행합니다:

{% code collapsedlinecount="10" %}

```bash
docker build --platform linux/amd64 -f server/Dockerfile -t registry.edgegap.com/<project>/fishgame-godot:1.0.0 .
docker push registry.edgegap.com/<project>/fishgame-godot:1.0.0
```

{% endcode %}

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

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

* 이미지 `<project>/fishgame-godot`, 태그 `1.0.0`, 레지스트리 사용자 이름과 토큰을 사용하여,
* 0.5 vCPU와 512MB 메모리를 사용하며,
* [포트](https://docs.edgegap.com/ko/learn/orchestration/application-and-versions.md#port-mapping) `7777`, 이름은 `gameport`, 프로토콜 **UDP**,
* [최대 기간](https://docs.edgegap.com/ko/learn/orchestration/application-and-versions.md#safety-guardrails) 30분(서버도 자체적으로 중지됩니다).

서버 자체의 환경 변수는 필요 없습니다 - Fleet Manager가 모든 배포마다 Nakama의 콜백 URL을 전달합니다.

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

### 2. Nakama 실행

☑️ 복사 `nakama/.env.example` 다음으로 `nakama/.env` 에 다음을 입력하세요:

* `EDGEGAP_API_TOKEN` - Edgegap API 토큰이며, `token` 접두사를 포함합니다,
* `EDGEGAP_APPLICATION`, `INITIAL_EDGEGAP_VERSION`, `EDGEGAP_PORT_NAME` - 1단계의 애플리케이션, 버전, 포트 이름,
* `NAKAMA_ACCESS_URL` - Nakama의 공개 HTTPS 주소,
* `NAKAMA_HTTP_KEY` - 긴 무작위 문자열이며, 게임 서버는 이를 콜백 URL 안에서 받습니다.

{% hint style="danger" %}
Edgegap API 토큰은 조직 전체에 대한 접근 권한을 줍니다. 이를 `nakama/.env` 및 Nakama에만 보관하세요. **게임 클라이언트나 서버 이미지에는 절대 넣지 마세요.**
{% endhint %}

☑️ 로컬 머신에서 테스트하려면, Cloudflare quick tunnel을 시작해 Nakama에 공개 주소를 부여하세요. 출력된 `https://….trycloudflare.com` URL을 `NAKAMA_ACCESS_URL`:

{% code collapsedlinecount="10" %}

```bash
docker run -d --name fishgame-tunnel cloudflare/cloudflared:latest tunnel --no-autoupdate --url http://host.docker.internal:7350
```

{% endcode %}

☑️ Nakama와 Postgres를 시작하세요. `nakama/Dockerfile` Edgegap Fleet Manager가 포함된 Go 모듈을 Nakama에 빌드합니다:

{% code collapsedlinecount="10" %}

```bash
docker compose -p fishgame -f nakama/docker-compose.yml up -d --build
```

{% endcode %}

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

### 3. 플레이

☑️ 게임을 Nakama에 연결하세요. 상단의 기본값을 편집하거나 `autoload/Online.gd`, 또는 명령줄에서:

{% code collapsedlinecount="10" %}

```bash
godot --path . -- --nakama-host=your-tunnel.trycloudflare.com --nakama-port=443 --nakama-scheme=https
```

{% endcode %}

{% hint style="info" %}
플레이어도 Nakama에 공개 주소를 통해 연결되어야 합니다. Nakama는 각 플레이어가 로그인한 IP를 저장하고, Edgegap은 이 IP들을 사용해 [플레이어 근처에 배포합니다](https://docs.edgegap.com/ko/learn/orchestration/deployments.md#server-placement).
{% endhint %}

☑️ 게임 인스턴스 두 개를 시작하고, **온라인**, 각자 계정을 만든 다음, **매치** 를 누르세요.

"Match found! Starting a game server..." 이후 두 플레이어는 같은 Edgegap 서버의 준비 화면으로 이동합니다. 먼저 5라운드를 이기는 물고기가 매치를 승리하고 리더보드에서 +1을 얻습니다.

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

## 🔄 매치 라이프사이클

1. 플레이어는 이메일로 Nakama에 로그인한 다음 매치메이커 티켓을 제출합니다.
2. Nakama가 이들을 매칭하면, 모듈의 매치메이커 훅이 Fleet Manager에 배포 생성을 요청하고, 메타데이터에 매칭된 사용자 ID를 포함합니다.
3. 게임 서버가 부팅되어 UDP를 수신하고 `7777`, 그리고 `준비 완료` 를 자체 IP와 외부 포트와 함께 Nakama에 보냅니다. Nakama는 각 매칭된 플레이어에게 서버 주소를 알립니다.
4. 플레이어는 ENet을 통해 연결합니다. 서버는 Nakama의 `/v2/account` 로 각 플레이어의 Nakama 세션을 확인하고, 이 서버에 매칭된 플레이어만 허용합니다. 연결된 사용자 ID가 바뀌면 5초마다 Nakama에 보고합니다.
5. 매치에서 승자가 결정되면 서버는 `report_match_result` 을 Nakama의 HTTP 키를 사용해 서버 간 RPC로 호출하고, Nakama는 승리를 `fish_game_wins` 리더보드에 추가합니다. 이 RPC는 플레이어 세션을 거부하며, 각 배포는 한 번만 집계됩니다.
6. 서버가 `STOP`을 보내면, Nakama가 배포를 중지합니다. 또한 경기 도중 플레이어가 2명 미만으로 줄거나, 모두 떠나거나, 60초 내에 아무도 참가하지 않거나, 20분이 지나면 중지됩니다.

각 플레이어는 여전히 업스트림과 마찬가지로 자신의 물고기 이동을 제어합니다. 경쟁 게임을 위해서는 클라이언트 예측과 함께 이동 처리를 서버로 옮기는 것이 다음 단계입니다.

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

## ⚠️ 알려진 문제

* HTML5 내보내기는 온라인 플레이를 할 수 없습니다 - ENet은 브라우저가 사용할 수 없는 UDP를 사용합니다. 웹 빌드에는 Godot의 WebSocket 피어와 [TLS 업그레이드가 있는 WS 포트가 필요합니다](https://docs.edgegap.com/ko/learn/orchestration/deployments.md#websockets-ws-and-secure-websockets-wss).
