> 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/unity-netcodes/megacity-metro.md).

# Unity ECS Megacity Metro

在 Edgegap 上托管 Unity 的 Megacity Metro，这是一款支持最多 150 名玩家的 Netcode for Entities 射击游戏，配备专用服务器、匹配和补位。

探索如何使用来自以下内容的技术在 Edgegap 上托管 Unity DOTS 项目 [Megacity Metro Sample](https://github.com/Unity-Technologies/megacity-metro)，这是一款基于 Netcode for Entities 构建的移动端和桌面端射击游戏，每个服务器最多可容纳 150 名玩家。

玩家按下 **查找匹配**， [Edgegap Matchmaker](https://docs.edgegap.com/zh/learn/pi-pei-xi-tong.md) 会在他们附近启动一个专用服务器，而之后搜索的玩家会加入正在运行的服务器，并通过 [补位](https://docs.edgegap.com/zh/learn/pi-pei-xi-tong/matchmaker-in-depth.md#backfill-match)。当没有人游戏时，服务器会停止自己的部署。

此示例展示：

* **Unity 6000.1.0f1** 项目，基于 **Netcode for Entities** （DOTS）构建为 Linux 专用服务器，
* **直接连接** 从桌面客户端连接到某个部署，用于在没有匹配器的情况下进行测试，
* **Edgegap Matchmaker** 与 [Edgegap Unity SDK](https://github.com/edgegap/sdk-unity-sessions-matchmaker-server-browser) 集成 - 客户端排队并连接到分配的服务器，
* **补位**  - 正在运行的服务器会在匹配器中保留空位，因此新玩家会加入它们而不是启动新服务器，最多可达 150 名玩家，
* **服务器自停**  - 当没人加入时，或当所有人都离开后，服务器会停止自己的部署。

游戏的网络代码未作更改。若没有匹配器 URL、位于 Edgegap 部署之外且没有直接连接目标，游戏行为与上游版本相同。

{% hint style="info" %}
已在带有 Windows 桌面客户端的 Edgegap 上验证：服务器部署、直接连接，以及带补位的匹配（一个服务器上 3 名玩家）。移动端发布构建会隐藏 Connect 选项，因此手机使用 **查找匹配**.
{% endhint %}

{% hint style="success" %}
请参阅 [EDGEGAP.md](https://github.com/edgegap/netcode-game-sample-unity-dots-ecs-mobile-megacity-metro/blob/master/EDGEGAP.md) 示例仓库中的完整 Edgegap 文件和服务器设置列表。
{% endhint %}

## ✔️ 准备工作

开始之前，你需要：

* [Unity `6000.1.0f1`](https://unity.com/releases/unity-6)  - 通过 Unity Hub 下载，勾选下面的模块以及你的客户端平台模块（对测试客户端而言为 Windows Build Support (IL2CPP)），
* [Megacity Metro Sample 项目](https://github.com/edgegap/netcode-game-sample-unity-dots-ecs-mobile-megacity-metro) （为 Edgegap 修改），使用 [Git LFS](https://git-lfs.com/) 克隆（约 415 MB 的 LFS 内容）。

<details>

<summary>安装 Unity Linux 构建支持模块</summary>

* 使用 Unity Hub 选择 选项卡 **安装**，访问 **设置** 和 **添加模块** 对于您打算与 Edgegap 平台一起使用的每个 Unity 版本：

<figure><img src="https://3334189208-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FsR0dHSFv9ymoC0DO5G8J%2Fuploads%2FylRG4r8orenZrw5ijjpJ%2Fimage.png?alt=media&amp;token=fb981825-8a15-4c07-9180-0f79a6a77a91" alt=""><figcaption></figcaption></figure>

* 向下滚动以选择并安装以下 Unity 模块：
  * **Linux 构建支持（IL2CPP），**
    * **Linux 构建支持（Mono），**
    * **Linux 专用服务器构建支持**

<figure><img src="https://3334189208-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FsR0dHSFv9ymoC0DO5G8J%2Fuploads%2FuXtyqoLhBOk8CZJ4WdzA%2Fimage.png?alt=media&amp;token=19e956ed-a731-420d-b911-130c334794fc" alt=""><figcaption></figcaption></figure>

</details>

<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)。无需信用卡。

☑️ 在编辑器插件中构建，或者使用 CLI：

{% tabs %}
{% tab title="Unity Servers 快速入门插件（推荐）" %}
☑️ 选择 Tools / Edgegap / Build Linux Dedicated Server。

☑️ 完成 Edgegap 插件步骤 容器化并上传。
{% endtab %}

{% tab title="命令行界面（适用于代理）" %}
☑️ 关闭 Unity Editor 中的项目，然后从项目根目录构建 Linux 专用服务器：

{% code collapsedlinecount="10" %}

```bash
Unity -batchmode -quit -buildTarget Linux64 -standaloneBuildSubtarget Server -projectPath . -executeMethod EdgegapServerBuild.Build -logFile build.log
```

{% endcode %}

{% hint style="warning" %}
保持 `-buildTarget Linux64 -standaloneBuildSubtarget Server`，否则 Entities 内容构建会失败，并出现 `无法使用当前配置构建`.
{% endhint %}

☑️ 找到你的 [容器镜像仓库](https://docs.edgegap.com/zh/learn/advanced-features/edgegap-container-registry.md#getting-your-credentials) 项目名称和凭据，然后使用 Docker 登录：

{% 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
docker build --platform linux/amd64 -t registry.edgegap.com/<project>/megacity-metro:<tag> .
docker push registry.edgegap.com/<project>/megacity-metro:<tag>
```

{% endcode %}
{% endtab %}
{% endtabs %}

你的构建已保存到 `Builds/EdgegapServer/` （约 3.4 GB，主要是 Burst 调试信息和 IL2CPP 备份文件夹）。示例的 `.dockerignore` 排除 `*_BurstDebugInformation_DoNotShip` 和 `*_BackUpThisFolder_ButDontShipItWithYourGame`，因此你的镜像大小约为 537 MB。

{% hint style="danger" %}
:x: **不要覆盖现有标签，也不要使用 `latest`  标签** ——这会部署过时的缓存。\
:white\_check\_mark: **应该始终递增版本标签** 并部署新的构建版本。
{% endhint %}

你的服务器侦听 `0.0.0.0:7979` 上的 UDP。将额外的服务器参数传递到 `UNITY_COMMANDLINE_ARGS` 应用版本中的环境变量。

✅ 现在可以继续下一步。

### 2. 创建应用版本

☑️ [创建一个应用](https://app.edgegap.com/application-management/applications/list) 以及一个带有以下内容的版本：

* 你的 `registry.edgegap.com/<project>/megacity-metro:<tag>` 镜像，
* 你的容器注册表用户名和令牌，否则部署将无法拉取镜像，
* 资源为 1 vCPU 和 2 GB 内存（已测试，空闲服务器大约占用 18% CPU 和 323 MB），
* [端口](https://docs.edgegap.com/zh/learn/bian-pai/application-and-versions.md#port-mapping) `7979`，命名为 `gameport`，协议为 **UDP**.

✅ 现在可以继续下一步。

### 3. 直接连接

在添加匹配器之前，先验证你的服务器是否正常工作。

☑️ [从插件或仪表板部署你的应用版本](https://app.edgegap.com/deployment-management/deployments/list) 。你的服务器日志显示 `正在 Edgegap 上运行……跳过 UGS 会话`.

☑️ [打开你新部署的详情](https://app.edgegap.com/deployment-management/deployments/list) 并找到你唯一的一次性连接信息：

* **主机 URL** 格式为 `780aa4260e83.pr.edgegap.net` （或 IP），
* **外部端口** 的 `gameport` 格式为 `30854` （5 位数字，不是 `7979`).

☑️ 使用这些详细信息启动一个桌面客户端：

{% code collapsedlinecount="10" %}

```bash
<client executable> -edgegapConnect <host>:<external port>
```

{% endcode %}

你也可以设置 `EDGEGAP_CONNECT=<host>:<external port>` 在启动客户端之前。在有直接连接目标时，你的客户端会跳过 Unity Gaming Services（UGS）登录，因此不需要 UGS 项目。 **查找匹配** 连接到该目标。

☑️ 查找 `[Edgegap] 已连接玩家：1` 在你的服务器日志中，一旦你的客户端加入。

✅ 现在可以继续下一步。

### 4. 创建匹配器

☑️ 将 `application.name` 和 `application.version` 设置为你的应用和版本，在示例的 `matchmaker-config.json`.

该配置只有一个 `metro` 配置文件，包含一个 2 到 150 名玩家的队伍。两名玩家一起搜索时，大约在排队 10 秒后会获得服务器，而单人玩家会在 30 秒后获得。这样适合测试，实际比赛请提高最小值。

☑️ 打开 [匹配器](https://app.edgegap.com/matchmaker-management-v2/matchmakers/list) 页面，点击 **创建匹配器**，上传 `matchmaker-config.json`，然后点击 **创建并启动**.

☑️ 复制你的匹配器的 **API URL** 和 **认证令牌** 一旦它显示 **ONLINE**.

* **免费集群（共享）** 用于测试所有功能并探索与您的设计的协同效应，
  * 会在 3 小时后自动关闭，需要重启才能继续测试。
* **私有集群** **（专用）** 以确保为您的生产需求提供稳定的环境，
  * 选择您的区域并为实时游戏获得 24/7 支持，以便自信发布。

从仪表板重启你的匹配器会保留其 API URL 和 Auth Token。

✅ 现在可以继续下一步。

### 5. 查找匹配

☑️ 将你的 API URL 和 Auth Token 粘贴到 `Assets/Resources/EdgegapMatchmakerSettings.asset`.

{% hint style="danger" %}
**不要在游戏客户端中集成 Edgegap API 端点，因为你的 API 令牌会为你的帐户提供无限访问权限。参见** [集成](https://docs.edgegap.com/zh/docs/api/ji-cheng.md) **用于安全的面向客户端 API 端点和函数。**
{% endhint %}

{% hint style="info" %}
匹配认证令牌仅限于你的匹配器，因此可以安全地打包到游戏客户端中。
{% endhint %}

☑️ 重新构建你的服务器和客户端——客户端读取此资源以查找匹配，服务器读取它以创建补位。推送你的新服务器镜像，并将你的应用版本和 `matchmaker-config.json` 指向它。

可在启动时使用以下参数覆盖该资源 `-edgegapMatchmakerUrl`, `-edgegapMatchmakerToken` 和 `-edgegapMatchmakerProfile` （或 `EDGEGAP_MM_URL`, `EDGEGAP_MM_TOKEN`, `EDGEGAP_MM_PROFILE`).

☑️ 启动两个客户端并点击 **查找匹配** 在两者中。状态会从 `Searching...` 变为 `已找到匹配，正在启动服务器...`，然后你的客户端连接。

☑️ 启动第三个客户端并点击 **查找匹配** 当匹配正在运行时。它通过补位加入同一个服务器。

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

## 🔄 对局生命周期

1. 客户端使用 solo 票据与 `metro` profile。其 `backfill_group_size` 属性是 `["new", "1"]`  - 一个新匹配，或正在运行的服务器上的一个座位。
2. 匹配器会在玩家附近启动一个部署，或将该票据与正在运行的服务器中的补位进行匹配。
3. 客户端连接到服务器的 IP 和外部端口，然后将其票据 ID 发送到服务器。
4. 在匹配器部署中，服务器从 [`MM_*` 变量](https://docs.edgegap.com/zh/learn/pi-pei-xi-tong/matchmaker-in-depth.md#injected-variables) 读取匹配结果，并给予每位匹配到的玩家 60 秒连接时间。当座位有空时，它最多保留 3 个补位，并在玩家离开或从未到达时释放一个座位。
5. 服务器会关闭其补位，并在以下时间停止其部署： `ARBITRIUM_DELETE_URL`  - 启动后 300 秒，如果从未有玩家连接，或在最后一名玩家离开后 60 秒。

使用应用版本中的环境变量更改这些限制：

* `EDGEGAP_MAX_PLAYERS`  - 每个服务器的座位数（默认 `150`),
* `EDGEGAP_MAX_OPEN_BACKFILLS`  - 同时开放的补位数（默认 `3`),
* `EDGEGAP_FIRST_PLAYER_TIMEOUT_S`  - 在没人加入时，服务器停止自身前的秒数（默认 `300`),
* `EDGEGAP_EMPTY_TIMEOUT_S`  - 在最后一名玩家离开后，服务器停止自身前的秒数（默认 `60`).

{% hint style="warning" %}
如果部署从外部停止（仪表板、API，或达到最大持续时间），服务器会退出而不会关闭其补位。 **在它们过期之前** (`ticket_expiration_period`，30 秒）， **它们可以把一名玩家发送到已停止的服务器。** 该玩家的连接会超时，而他们下一次 **查找匹配** 就能工作。
{% endhint %}

请参阅 [匹配系统](https://docs.edgegap.com/zh/learn/pi-pei-xi-tong.md), [深入了解](https://docs.edgegap.com/zh/learn/pi-pei-xi-tong/matchmaker-in-depth.md) 和 [部署](https://docs.edgegap.com/zh/learn/bian-pai/deployments.md) 了解更多。

## ⚠️ 已知问题

* Android 和 iOS 客户端尚未测试，桌面端的窗口化试玩也尚未测试。
* 服务器会记录未知票据 ID 的连接，但仍允许它们加入（目前还没有票据验证）。
* Vivox 和 UGS 登录未受影响。Edgegap Matchmaker 和直接连接路径不会使用它们。
