> 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/unity-netcode-on-edgegap.md).

# Unity NGO

在 Edgegap 上托管一个 Unity Netcode for GameObjects 项目，按照 NGO Boss Room 示例，从构建到上线部署逐步进行。

了解如何使用以下技巧在 Edgegap 上托管 Unity 项目 [NGO Boss 房间示例](https://unity.com/demos/small-scale-coop-sample).

{% hint style="info" %}
此示例 **不需要任何 Unity Gaming Services（UGS）**、Multiplay 或 Relays 即可运行。
{% endhint %}

{% embed url="<https://youtu.be/8Qi-wXswjkw>" %}

## ✔️ 准备工作

开始之前，你需要：

* [Unity 6](https://unity.com/releases/unity-6) - 使用 Unity Hub 下载，
* [Unity NGO \[面向游戏对象的 Netcode\] Boss Room 示例项目](https://github.com/edgegap/netcode-game-sample-unity-ngo-bossroom) （已为 Edgegap 修改）。

## ⚡ 部署并连接

### 1. 在 Edgegap 上部署服务器

☑️ 开始前，你需要 [在 Edgegap 创建一个免费账户](https://app.edgegap.com/auth/register)。无需信用卡。

☑️ [为你的应用创建新的应用版本](https://app.edgegap.com/application-management/applications/unity-ngo-bossroom-sample/versions/create)，请选择 NGO Boss Room 示例。

☑️ [使用你的 NGO Boss Room 示例应用版本部署服务器](https://app.edgegap.com/deployment-management/deployments/list).

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

* **外部端口**，例如 `30854` （随机选择）。

☑️ 切换到“日志”选项卡并查找（CTRL+F）你的唯一一次性连接详情：

* `ARBITRIUM_PUBLIC_IP` ，例如 IPv4： `172.234.244.38` .

✅ 现在你可以继续下一步。

### 2. 从编辑器连接

☑️ 在 Unity 中打开你的新项目。

☑️ 确认你已打开场景： `Assets/Scenes/MainMenu.unity`.

☑️ 按下 ▶️ Play 按钮启动你的游戏客户端：

* 按下 **使用直接 IP 开始** 按钮，
* 选择选项卡 **JOIN WITH IP。**

☑️ 输入上一步中的连接详情。

☑️ 按下 **JOIN** 按钮以连接到你的服务器。

☑️ 使用以下方式连接第二个虚拟玩家： [Multiplayer Play Mode](https://docs-multiplayer.unity3d.com/mppm/current/about/) 或 [ParrelSync](https://github.com/VeriorPies/ParrelSync).

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

## 🎯 匹配（可选）

将玩家与 [Edgegap Matchmaker](https://docs.edgegap.com/zh/learn/pi-pei-xi-tong.md) - 它会对玩家进行分组，Edgegap 会在他们附近启动服务器，并且每个客户端都会自动连接到该服务器。默认情况下匹配功能已禁用，当直接连接正常后再启用它。

{% hint style="success" %}
匹配脚本位于 `Assets/Edgegap/` 并在运行时自行添加，因此 **Boss Room 的场景和预制体不会被修改**。请参见 [EDGEGAP.md](https://github.com/edgegap/netcode-game-sample-unity-ngo-bossroom/blob/main/EDGEGAP.md) 以获取完整的文件列表和命令行选项。
{% endhint %}

### 1. 创建匹配器

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

该配置只有一个 `休闲` 适用于 2 到 8 名玩家的配置。它会尽可能填满到 8 名玩家，并且其 [扩展](https://docs.edgegap.com/zh/learn/pi-pei-xi-tong/matchmaker-in-depth.md#rule-expansion) 在 15 秒时会允许它以更少的玩家数开始（至少 2 名）。

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

☑️ 复制你的匹配器的 **API URL** 以及 **认证令牌**.

✅ 现在你可以继续下一步。

### 2. 寻找匹配

☑️ 选择 `Assets/Edgegap/Resources/EdgegapSettings.asset` 并勾选 **使用 Edgegap 匹配器**.

☑️ 粘贴你的 **API URL** 到 **匹配器 URL** 以及 **认证令牌** 到 **Matchmaker 认证令牌**.

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

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

☑️ 重建你的客户端并启动两次。若要在一台电脑上运行两个副本，请为每个副本分配各自的配置文件： `Game.exe -AuthProfile p1` 以及 `Game.exe -AuthProfile p2`.

☑️ 点击 **寻找匹配** 在两个客户端主菜单左侧面板中。

状态会依次经过搜索、找到匹配并加入，然后两个玩家会在同一服务器上的角色选择界面出现。选择英雄并点击 **准备** 一起进入地牢。

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

{% hint style="warning" %}
在你的匹配器配置中保留一个扩展阶段。没有它时，匹配器只会在 [部分匹配](https://docs.edgegap.com/zh/learn/pi-pei-xi-tong/matchmaker-in-depth.md#partial-matches) 当票证过期时（5 分钟）。
{% endhint %}

## 🛑 服务器自停止

无论是否使用匹配，你的服务器都会自行停止部署，这样空闲服务器就不会耗费金钱：

* 当 120 秒内无人加入时，
* 最后一名玩家离开后 30 秒。

使用以下设置更改这些超时： **首位玩家超时秒数** 以及 **空服务器超时秒数** 位于 `EdgegapSettings.asset`。如果停止请求失败，服务器将直接退出。

## ✏️ 自定义服务器构建

{% hint style="success" %}
参见 [Unity](https://docs.edgegap.com/zh/unity.md) 变为 **了解如何构建和自定义服务器**.
{% endhint %}

### 作为专用服务器运行

为了让此示例作为专用服务器运行，我们进行了以下更改：

{% tabs %}
{% tab title="服务器初始化" %}
新脚本（添加到你的 `MainMenu` 场景中新建的空 `GameObject`):

<pre class="language-csharp" data-title="Assets/Scripts/EdgegapServerStarter.cs" data-line-numbers data-collapsed-line-count="10"><code class="lang-csharp">using System;
using System.Collections;
using System.Collections.Generic;
using Unity.BossRoom.ConnectionManagement;
using UnityEngine;

namespace Unity.Multiplayer.Samples.BossRoom
{
    public class EdgegapServerStarter : MonoBehaviour
    {
        // 在调用 Start 之前于第一帧更新时执行
        void Start()
        {
            if (Application.isBatchMode)
            {
                ConnectionManager connectionManager = GameObject.Find("ConnectionManager").GetComponent&#x3C;ConnectionManager>();
<strong>                string internalPortAsStr = Environment.GetEnvironmentVariable($"<a data-footnote-ref href="#user-content-fn-1">ARBITRIUM_PORT_GAMEPORT_INTERNAL</a>");
</strong>
                ushort port;
                if (internalPortAsStr == null)
                {
                    // 不在 Edgegap 上（本地运行或 docker run）：使用 EdgegapSettings.ListenPort 或 -edgegapListenPort。
                    port = EdgegapBootstrap.Settings != null ? EdgegapBootstrap.Settings.ListenPort : (ushort)9998;
                    Debug.LogWarning($"未找到 ARBITRIUM_PORT_GAMEPORT_INTERNAL，不在 Edgegap 上：正在端口 {port} 上监听。")
                }
                else if (!ushort.TryParse(internalPortAsStr, out port))
                {
                    throw new Exception($"找不到端口映射，请确保你的应用版本端口名称与 \"{portMapName}\" 匹配")
                }

                Debug.Log($"Edgegap 服务器 | 正在 0.0.0.0:{port} 上启动服务器。")
<strong>                connectionManager.StartHostIp("<a data-footnote-ref href="#user-content-fn-2">SERVER</a>", "0.0.0.0", port);
</strong>            }
        }
    }
}
</code></pre>

{% endtab %}

{% tab title="连接管理" %}
修改的文件：

<pre class="language-csharp" data-title="Assets/Scripts/ConnectionManagement/ConnectionMethod.cs" data-collapsed-line-count="10"><code class="lang-csharp"><strong>116        public override async Task SetupHostConnectionAsync()
</strong>117        {
<strong>118            <a data-footnote-ref href="#user-content-fn-3">//SetConnectionPayload(GetPlayerId(), m_PlayerName); // 主机也需要设置连接载荷，因为主机也是一个客户端</a>
</strong>119            var utp = (UnityTransport)m_ConnectionManager.NetworkManager.NetworkConfig.NetworkTransport;
120            utp.SetConnectionData(m_Ipaddress, m_Port);
121        }
</code></pre>

<pre class="language-csharp" data-title="Assets/Scripts/ConnectionManagement/ConnectionState/StartingHostState.cs" data-collapsed-line-count="10"><code class="lang-csharp"><strong>66        async void StartHost()
</strong>67        {
              ...

72                // NGO 的 StartHost 会启动一切
<strong>--                <a data-footnote-ref href="#user-content-fn-3">//if (!m_ConnectionManager.NetworkManager.StartHost())</a>
</strong><strong>73                <a data-footnote-ref href="#user-content-fn-4">if (!m_ConnectionManager.NetworkManager.StartServer())</a>
</strong>74                {
75                    StartHostFailed();
76                }

              ...
</code></pre>

<pre class="language-csharp" data-title="Assets/Scripts/Gameplay/GameplayObjects/Character/ClientCharacter.cs" data-collapsed-line-count="10"><code class="lang-csharp"><strong>112        public override void OnNetworkSpawn()
</strong>113        {
               ...

125            m_ServerCharacter.IsStealthy.OnValueChanged += OnStealthyChanged;
126            m_ServerCharacter.MovementStatus.OnValueChanged += OnMovementStatusChanged;
<strong>127            <a data-footnote-ref href="#user-content-fn-3">//OnMovementStatusChanged(MovementStatus.Normal, m_ServerCharacter.MovementStatus.Value);</a>
</strong> 
               ...
</code></pre>

{% endtab %}

{% tab title="编辑器/服务器兼容性" %}
修改文件：

<pre class="language-csharp" data-title="Assets/Scripts/ConnectionManagement/ConnectionState/HostingState.cs" data-collapsed-line-count="10"><code class="lang-csharp"><strong>148        ConnectStatus GetConnectStatus(ConnectionPayload connectionPayload)
</strong>149        {
               ...
                
<strong>155            <a data-footnote-ref href="#user-content-fn-5">//if (connectionPayload.isDebug != Debug.isDebugBuild)</a>
</strong><strong>156            //{
</strong><strong>157            //    return ConnectStatus.IncompatibleBuildType;
</strong><strong>158            //}
</strong>
               ...
</code></pre>

{% endtab %}
{% endtabs %}

[^1]: Edgegap 上的默认端口名称是 'gameport'

[^2]: 服务器的玩家名称可以是任意值

[^3]: 仅限 p2p ⇒ 将此注释掉

[^4]: 而是改为以专用服务器启动

[^5]: 编辑器兼容性 ⇒ 将此注释掉
