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

# Nakama Fish Game

在 Edgegap 专用服务器上托管 Heroic Labs 的 Godot 4 Fish Game，由 Nakama 匹配器通过 nakama-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 负责账号、配对和排行榜，并通过 [适用于 Nakama 的 Edgegap Fleet Manager](https://github.com/edgegap/backend-nakama-edgegap-plugin).

此示例展示：

* **Godot 4.7** 使用 GDScript 编写的游戏，以无头专用服务器方式通过 ENet 运行，使用 UDP 端口 `7777`,
* **Nakama 3.39** 配合 Go 模块 - 配对器钩子会为每场对局启动一个部署，并在服务器报告后将服务器地址发送给每位玩家 `READY`,
* **服务器权威的对局规则** - 由服务器决定命中、死亡、拾取、生成、回合和获胜者，
* **玩家检查** - 服务器只接纳具有有效 Nakama 会话且已被匹配到此服务器的玩家，
* **服务器到服务器排行榜** - 服务器会将胜利记录到权威的 Nakama 排行榜中，玩家无法写入，
* **服务器自停** - 对局结束后，服务器会请求 Nakama 停止其部署。

{% hint style="success" %}
参见 [从 Nakama 部署](https://docs.edgegap.com/zh/docs/tools-and-integrations/cong-nakama-bu-shu.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/zh/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 和 512 MB 内存，
* [端口](https://docs.edgegap.com/zh/learn/bian-pai/application-and-versions.md#port-mapping) `7777`，命名为 `gameport`，协议 **UDP**,
* [最长持续时间](https://docs.edgegap.com/zh/learn/bian-pai/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/zh/learn/bian-pai/deployments.md#server-placement).
{% endhint %}

☑️ 启动两个游戏实例，选择 **在线**，在每个实例中创建一个账户，然后按下 **匹配** 在两个客户端中都按下。

在“找到匹配！正在启动游戏服务器...”之后，两位玩家都会进入同一个 Edgegap 服务器的准备界面。第一个先赢得 5 回合的鱼将赢得对局，并在排行榜上获得 +1。

祝贺你在 Edgegap 上完成了第一个匹配部署！

## 🔄 比赛生命周期

1. 玩家使用电子邮件登录 Nakama，然后提交配对票据。
2. 当 Nakama 为他们匹配成功后，该模块的配对器钩子会请求 Fleet Manager 创建一个部署，并在其元数据中包含已匹配的用户 ID。
3. 游戏服务器启动，监听 UDP `7777`，并发送 `READY` 到 Nakama，包含其自身 IP 和外部端口。Nakama 会向每位匹配到的玩家通知服务器地址。
4. 玩家通过 ENet 连接。服务器使用 Nakama 的 `/v2/account` 检查每位玩家的 Nakama 会话，并且只接受与其匹配的玩家。每当已连接用户 ID 发生变化时，它都会每 5 秒向 Nakama 报告一次。
5. 当对局获胜后，服务器调用 `report_match_result` 通过 Nakama 的 HTTP key 进行服务器到服务器的 RPC，Nakama 会将胜利计入 `fish_game_wins` 排行榜。该 RPC 会拒绝玩家会话，并且每个部署只计数一次。
6. 服务器发送 `STOP`，然后 Nakama 停止该部署。若对局中少于 2 名玩家、所有人离开、60 秒内无人加入，或 20 分钟后，它也会停止。

与上游版本一样，每位玩家仍然拥有自己鱼的移动控制。对于竞技游戏来说，将移动逻辑迁移到服务器并使用客户端预测是下一步。

参见 [从 Nakama 部署](https://docs.edgegap.com/zh/docs/tools-and-integrations/cong-nakama-bu-shu.md), [匹配系统](https://docs.edgegap.com/zh/learn/pi-pei-xi-tong.md) 以及 [部署](https://docs.edgegap.com/zh/learn/bian-pai/deployments.md) 以了解更多。

## ⚠️ 已知问题

* HTML5 导出无法进行在线游玩 - ENet 使用 UDP，而浏览器无法使用它。网页构建需要 Godot 的 WebSocket peer，以及一个 [带 TLS Upgrade 的 WS 端口](https://docs.edgegap.com/zh/learn/bian-pai/deployments.md#websockets-ws-and-secure-websockets-wss).
