> 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/wang-ye-you-xi/colyseus-realtime-tanks.md).

# Colyseus 实时坦克战

在 Edgegap 上托管一款 Colyseus 0.17 多人坦克游戏，每场比赛使用一台专用服务器，支持直接连接或 Edgegap 匹配器。

探索如何托管 [Colyseus](https://colyseus.io/) 使用以下示例中的技术在 Edgegap 上托管服务器： [实时坦克](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`,
* **每场对局一个服务器** ——当没有人加入、保持空闲，或达到设定回合数后，服务器会停止其自身部署，
* **直连模式** ——启动一个部署，并将其 URL 传递给 9 个客户端中的任意一个，使用 `?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 %}

## ✔️ 准备工作

开始之前，你需要：

* [实时坦克示例项目](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/zh/learn/advanced-features/edgegap-container-registry.md#getting-your-credentials) 项目名称和凭据。

☑️ 使用你的注册表项目名称、用户名和令牌，通过 Docker 登录 Edgegap 的容器注册表：

{% tabs %}
{% tab title="Bash（Linux）" %}

```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（Windows）" %}

```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/zh/learn/bian-pai/application-and-versions.md#port-mapping) `2567`，命名为 `gameport`，协议 **WS**，并启用 **TLS 升级** 启用，
* [最长持续时间](https://docs.edgegap.com/zh/learn/bian-pai/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 共享一个端口。参见 [WebSocket（WS）和安全 WebSocket（WSS）](https://docs.edgegap.com/zh/learn/bian-pai/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/zh/docs/api/zhuan-yong-fu-wu-qi.md) (`POST /v2/deployments`），在大厅准备就绪时，并将 URL 发送给玩家。 **绝不要把你的 Edgegap API 令牌放在游戏客户端或服务器镜像中。**
{% endhint %}

🙌 祝贺你在 Edgegap 上完成首次部署！

### 4. 添加匹配器（可选）

☑️ 打开 [匹配器](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/zh/learn/pi-pei-xi-tong/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" %}
**不要在游戏客户端中集成 Edgegap API 端点，因为你的 API 令牌会为你的账户提供无限访问权限。请参阅** [集成](https://docs.edgegap.com/zh/docs/api/ji-cheng.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/zh/learn/pi-pei-xi-tong/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/zh/learn/pi-pei-xi-tong.md) 以及 [部署](https://docs.edgegap.com/zh/learn/bian-pai/deployments.md) 以了解更多。

## 🚀 进一步探索

* **验证加入者** ——匹配器部署会获得 [`MM_TICKET_IDS`](https://docs.edgegap.com/zh/learn/pi-pei-xi-tong/matchmaker-in-depth.md#injected-variables)。让客户端在加入选项中传递其票据 ID，并在 `onAuth`中进行检查，这样只有匹配到的玩家才能加入。
* **发布前** ——设置 `检查` 变为 `false` 在你的匹配器配置中，列出你的真实来源，并提高最大持续时间以适应你的对局（见 [上线前](https://docs.edgegap.com/zh/learn/pi-pei-xi-tong/matchmaker-in-depth.md#before-going-live)).

## ⚠️ 已知问题

* 已在 Edgegap 上使用 Colyseus 0.17、matchmaker 3.3.2、Godot 4.5.2 和 Unity 6000.3 完整端到端测试：
  * 直连——Node Colyseus 客户端和 Godot 桌面客户端通过以下方式加入了一个部署： `wss://`，并且服务器在所有人离开后自行停止，
  * 匹配器——浏览器中的 Three.js 和 Godot 桌面客户端被匹配到同一台服务器上，然后是 Three.js 和一个 Unity Windows 构建。
* Construct 3、Defold、GameMaker、Haxe 和 PlayCanvas `服务器` 覆盖项、Godot 网页导出和 Unity WebGL 目前尚未测试。
