> 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/photon-fusion-2-on-edgegap.md).

# Photon Fusion 2

在 Edgegap 上托管一个 Unity Photon Fusion 2 游戏，按照 Fusion 2 Asteroids 示例，从构建到上线部署逐步进行。

探索如何使用以下内容中的技术在 Edgegap 上托管 Unity 项目 [Fusion 2 Asteroids 示例](https://doc.photonengine.com/fusion/current/game-samples/fusion-asteroids).

{% embed url="<https://youtu.be/bg41HpPmE3E>" %}

## ✔️ 准备工作

在开始之前，你需要：

* [Unity 6](https://unity.com/releases/unity-6) - 使用 Unity Hub 下载，
* [Fusion 2 Asteroids 示例项目](https://github.com/edgegap/netcode-game-sample-photon-fusion2-asteroid) （已为 Edgegap 修改）。

## ⚡ 部署并连接

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

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

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

☑️ [为你的应用创建新的应用版本](https://app.edgegap.com/application-management/applications/fusion-2-asteroids-sample/versions/create)，选择 Fusion 2 Asteroids 示例。

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

☑️ 导航到 Tools / Edgegap Hosting，然后前往第 6 步。在 Edgegap 上部署服务器。

☑️ 按下 Deploy to cloud，然后 [打开你新部署的详情](https://app.edgegap.com/deployment-management/deployments/list).

☑️ 查找你的部署唯一的一次性连接信息：

* **主机 URL** 格式为 `780aa4260e83.pr.edgegap.net` .

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

### 2. 从编辑器连接

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

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

☑️ 将主机 URL（上一步的连接信息）输入为房间名。

☑️ 按下 Start Edgegap 按钮连接到你的服务器。

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

🙌 恭喜你在 Edgegap 上完成第一次部署！

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

### 在 Photon 上创建应用

{% hint style="info" %}
为了让初始演示更简单，我们使用了 Edgegap 拥有的免费版 Photon Cloud 账户。
{% endhint %}

☑️ [在 Photon 注册一个免费账户](https://dashboard.photonengine.com/).

☑️ [在 Photon 上创建应用程序](https://dashboard.photonengine.com/app/create):

* `多人游戏`,
* `Fusion` Photon SDK，
* `Fusion 2` SDK 版本。

☑️ 查找你格式为以下形式的 Application ID `85314a99-56fc-4ab3-ba26-50efca09f303` .

☑️ 在 Tools / Fusion / Fusion Hub（Alt + F）下的 Photon Settings 中输入你的 ID。

### 将 Fusion 2 项目与 Edgegap 集成

{% hint style="success" %}
请参阅 `EdgegapServerManager.cs`  用于将 Fusion 2 与 Edgegap 集成的示例脚本。
{% endhint %}

{% hint style="warning" %}
你的 `NetworkProjectConfig`  **必须使用 `Peer Mode = Single` （专用服务器）**，而不是 `Multiple` （客户端主机）！
{% endhint %}

游戏客户端将通过以下方式连接到游戏服务器： [Photon Fusion 2 ](https://doc.photonengine.com/fusion/current/manual/connection-and-matchmaking/matchmaking#creating-and-joining-a-game-session)[会话（房间） ](https://doc.photonengine.com/fusion/current/manual/connection-and-matchmaking/matchmaking#creating-and-joining-a-game-session)[功能](https://doc.photonengine.com/fusion/current/manual/connection-and-matchmaking/matchmaking#creating-and-joining-a-game-session).

你的游戏服务器在调用时需要将其 IP 地址和外部端口与会话名称一起注册， `_runnerInstance.StartGame(StartGameArgs args)`:

* 使用 `GameMode.Server`  以确保你的连接不会通过 Photon Cloud 中继（会增加延迟），
* 使用 `NetAddress.CreateFromIpPort` Fusion 中的方法，
* 提供服务器的 IP 地址：\
  `Environment.GetEnvironmentVariable("ARBITRIUM_PUBLIC_IP")`
* 提供服务器的外部端口：\
  `Environment.GetEnvironmentVariable("ARBITRIUM_PORT_GAMEPORT_EXTERNAL")`
  * 如果你使用我们的，这就是默认的端口映射名称 [用于打包服务器的 Unity 插件](https://docs.edgegap.com/zh/unity.md).

使用 Edgegap 部署主机 URL 作为会话名称：

* 在游戏服务器中，使用以下方式获取：\
  `$"{Environment.GetEnvironmentVariable(\"ARBITRIUM_REQUEST_ID\")}.pr.edgegap.net"`
* 在测试游戏客户端时，从仪表板的部署详情页面 / Host URL 获取
  * 使用我们的以下内容创建用于测试的部署： [快速入门托管插件](https://docs.edgegap.com/zh/unity/developer-tools.md#dedicated-servers-quickstart-plugin),
* 在正式游戏客户端中，从以下位置获取： [匹配 / 票证分配 / fqdn](https://docs.edgegap.com/zh/learn/pi-pei-xi-tong/matchmaker-in-depth.md#player-api):
  * 另请参阅 [开始使用 Matchmaking](https://docs.edgegap.com/zh/learn/pi-pei-xi-tong.md).

{% tabs %}
{% tab title="客户端集成" %}
{% code title="EdgegapClientManager.cs" collapsedlinecount="10" %}

```csharp
// 获取 Fusion 2 网络运行器
_runnerInstance = FindFirstObjectByType<NetworkRunner>();
_runnerInstance.ProvideInput = true;

// 从 Edgegap Matchmaker Assignment 或 Fusion 2 Sessions API 获取此值
string sessionName = "<requestId.pr.edgegap.net>";

// 查找 Fusion 2 会话（使用会话名称）
var result = await _runnerInstance.StartGame(
    new StartGameArgs() {
        GameMode = GameMode.Client,
        SessionName = sessionName,
        ObjectProvider = _runnerInstance.GetComponent<NetworkObjectPoolDefault>(),
    }
);

// Fusion 现在将根据会话名称获取服务器 IP 和端口并连接
```

{% endcode %}
{% endtab %}

{% tab title="服务器集成" %}
{% code title="EdgegapServerManager.cs" collapsedlinecount="10" %}

```csharp
// 读取 Edgegap 注入的环境变量
string requestId = Environment.GetEnvironmentVariable("ARBITRIUM_REQUEST_ID");
string listenPortStr = Environment.GetEnvironmentVariable("ARBITRIUM_PORT_GAMEPORT_INTERNAL");
string connectIP = Environment.GetEnvironmentVariable("ARBITRIUM_PUBLIC_IP");
string connectPort = Environment.GetEnvironmentVariable("ARBITRIUM_PORT_GAMEPORT_EXTERNAL");

// 获取 Fusion 2 网络运行器
_runnerInstance = FindFirstObjectByType<NetworkRunner>();
_runnerInstance.ProvideInput = true;

// 将监听端口解析为 StartGame 期望的 ushort
ushort.TryParse(listenPortStr, out ushort listenPort);

// 注册 Fusion 2 会话，供客户端稍后查找（使用会话名称）
var result = await _runnerInstance.StartGame(
    new StartGameArgs() {
        GameMode = GameMode.Server,
        SessionName = $"{requestId}.pr.edgegap.net",
        ObjectProvider = _runnerInstance.GetComponent<NetworkObjectPoolDefault>(),
        Address = NetAddress.Any(listenPort),
        CustomPublicAddress = NetAddress.CreateFromIpPort(connectIP, connectPort),
    }
);

// 加载初始场景
if (result.Ok && _runnerInstance.IsServer) {
    await _runnerInstance.LoadScene(sceneName);
}
```

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

### 🔌 直接连接

Fusion 的 `IP` 和 `端口` 设置你的服务器 **绑定** 到的地址。此套件绑定 `0.0.0.0:7777`，Fusion 会自行查找部署的公网地址，客户端则连接 **直接** - 尽管 Edgegap 会为玩家分配不同的 [外部端口](https://docs.edgegap.com/zh/learn/bian-pai/application-and-versions.md#port-mapping).

| 服务器 `IP`        | 结果                                                         |
| --------------- | ---------------------------------------------------------- |
| `0.0.0.0` （此套件） | **直接** 在 Edgegap 上。                                        |
| `127.0.0.1`     | 服务器启动了，但客户端是 **中继的** 通过 Photon，这会增加延迟。容器外部无法访问回环地址。        |
| 部署的公网 IP        | 服务器 **无法启动** (`绑定套接字失败`），因为容器不拥有该地址。客户端会收到 `GameNotFound`. |

## 🚨 故障排查

<details>

<summary><code>MethodAccessException ... CheckInvokeRpc</code> 在服务器日志中</summary>

* 你的服务器是使用 Mono 构建的。请使用 IL2CPP 重新构建。

</details>

<details>

<summary><code>未找到主机平台的工具链</code> 或 <code>未找到 Linux sysroot</code></summary>

* 缺少 Linux 工具链包。请在 Window / Package Manager / + / Add package by name 中添加 Unity 的 Linux 工具链：
  * Unity 6000.3 及更高版本： `com.unity.toolchain.win-x86_64-linux` 和 `com.unity.sdk.linux-x86_64`,
  * 较早版本： `com.unity.toolchain.win-x86_64-linux-x86_64`.

</details>

<details>

<summary>客户端收到 <code>GameNotFound</code></summary>

* 应用版本或 Photon 区域与客户端和服务器不一致。请与服务器的 `photon_region=` 日志行进行比较。

</details>

<details>

<summary>客户端收到 <code>InvalidAuthentication</code></summary>

* 你的 Fusion App ID 错误或未包含在构建中。

</details>

<details>

<summary>选项卡叠加层显示 CT Relayed</summary>

* 你的服务器绑定 `127.0.0.1`，请参阅 [直接连接](#direct-connection).

</details>
