> 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-simple-fps.md).

# Photon Fusion 2 简易 FPS

在 Edgegap 专用服务器上托管 Photon 的简易 FPS 示例（Photon Fusion 2），每场比赛部署一台服务器，使用 Edgegap Simple FPS 套件。

了解如何使用以下内容中的技术，在 Edgegap 上托管 Unity 项目： [Simple FPS 多人游戏示例](https://assetstore.unity.com/packages/templates/tutorials/simple-fps-multiplayer-photon-fusion-272941)。玩家通过示例的 **派对** 菜单，输入部署地址和 Photon 区域后加入服务器。

{% hint style="info" %}
我们的 [Edgegap Simple FPS 工具包](https://github.com/edgegap/netcode-game-sample-photon-fusion2-simple-fps) 是一组你复制到 Simple FPS 项目中的文件。它 **不会更改或包含任何受 Photon 许可证约束的代码**，因此你可以在你自己的许可证下，从 Unity 资产商店获取 Simple FPS。
{% endhint %}

本示例展示：

* **作为专用服务器的 Simple FPS** - 每场比赛一个部署， [尽量靠近玩家部署](https://docs.edgegap.com/zh/learn/bian-pai/deployments.md#server-placement).
* **派对菜单加入** - 加入卡片使用你的部署 FQDN 和 Photon 区域代码， **创建游戏** 保持不变。
* **直接连接** - 服务器绑定 `0.0.0.0` 到端口 `7777`，因此客户端直接连接。
* **同一个项目同时用于客户端和服务器** - 服务器和客户端构建共享同一场景列表。
* **服务器自停止** - 当服务器进程自行退出时，启动脚本会停止该部署。

{% hint style="success" %}
请参见 [Photon Fusion 2](https://docs.edgegap.com/zh/docs/sample-projects/unity-netcodes/photon-fusion-2-on-edgegap.md) ，了解 **Edgegap 上 Photon Fusion 2 的通用指南**。请查看该工具包的 [README](https://github.com/edgegap/netcode-game-sample-photon-fusion2-simple-fps) ，了解完整文件列表和测试结果。
{% endhint %}

## ✔️ 准备工作

在开始之前，你需要：

* [Simple FPS Multiplayer（Photon Fusion）](https://assetstore.unity.com/packages/templates/tutorials/simple-fps-multiplayer-photon-fusion-272941) - 下载并导入到一个新的 Unity 项目中。
  * 此示例自带其项目设置。
* [Edgegap Simple FPS 工具包](https://github.com/edgegap/netcode-game-sample-photon-fusion2-simple-fps),
* Unity 6000.3，以及下面这些 Linux 构建模块，和 **Windows Build Support（IL2CPP）** 用于客户端（需要 Visual Studio 的 C++ 工作负载），
* Photon Fusion App ID - 在你的 [Photon 仪表板](https://dashboard.photonengine.com).

{% hint style="info" %}
中找到它。打开你的项目，并按照 [Unity](https://docs.edgegap.com/zh/unity.md) 准备步骤
{% endhint %}

安装服务器构建工具。此工具包已在 Windows 上使用 Simple FPS 2.1.1、Fusion 2.1.1（构建 2177）和 Unity 6000.3.11f1 测试过。

{% hint style="warning" %}
你的服务器 **必须使用 IL2CPP** （这是示例的默认设置）。Mono 服务器会在运行时不可恢复地失败。
{% endhint %}

☑️ 要在 Windows 上构建 Linux IL2CPP，请在 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`.

## ⚡ 部署并连接

### 1. 将工具包添加到你的项目中

☑️ 复制 `Assets/EdgegapSimpleFPS`, `edgegap/`, `scripts/`, `.dockerignore` 和 `.gitattributes` 从工具包到你的项目根目录，与 `Assets/`.

☑️ 在 Tools / Fusion / Realtime Settings 中粘贴你的 Fusion App ID。

{% hint style="info" %}
客户端和服务器 **必须使用相同的 App ID、App Version 和 Photon 区域**，否则它们无法找到彼此。
{% endhint %}

{% hint style="warning" %}
资产商店包还包含一个 `PhotonAppSettings` 资源文件，位于 `Assets/AssetStoreTools/Resources/` 其中使用了发布者的 App ID。 **也把你的 App ID 放在那里，或者删除那份副本。**
{% endhint %}

☑️ 将 **Peer Mode** 设置为 `Single` ，在 Tools / Fusion / Network Project Config 中。

☑️ 运行 Tools / Edgegap Simple FPS / Check Project，并修复报告的任何问题。

☑️ 运行 Tools / Edgegap Simple FPS / Set Up Project。它只会更改场景和构建设置，并且可以安全地再次运行：

* 死亡竞赛： `FusionBootstrap` 变为 `EdgegapFusionBootstrap` （保留其设置），并且 Start Mode 变为 **用户界面**,
* 启动：派对菜单的 `FusionMenuUIParty` 变为 `EdgegapPartyMenu` （为此会解包菜单预制体实例），
* 加入卡片的代码字段最多可接受 30 个字符（字母、数字和点），并在旁边新增一个 **区域** 字段，
* 构建配置设为 Startup (0)，然后是 Deathmatch (1)。

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

### 2. 构建并上传服务器

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

☑️ 使用 Edgegap 插件或从终端构建并上传你的服务器：

{% tabs %}
{% tab title="Edgegap 插件（推荐）" %}
☑️ 打开 Tools / Edgegap Server Hosting。在第 **3. 将服务器容器化**步，点击 **Path To Dockerfile** 并选择 `edgegap/Dockerfile`。将 **Relative Build Path** 保持为 `Builds/EdgegapServer`，然后进行容器化并上传。

☑️ 保持端口 `7777` / UDP 不变，当插件创建你的应用版本时。
{% endtab %}

{% tab title="终端（适用于 Agents）" %}
☑️ 找到你的 [容器注册表](https://docs.edgegap.com/zh/learn/advanced-features/edgegap-container-registry.md#getting-your-credentials) 项目名称和凭据，然后使用以下命令登录： `docker login registry.edgegap.com`.

☑️ 构建你的服务器，然后打包并推送镜像（Windows 上可使用 Git Bash）：

{% code collapsedlinecount="10" %}

```bash
scripts/build.sh server
scripts/package.sh registry.edgegap.com/<your-registry-project>/simplefps <new-tag>
```

{% endcode %}

`package.sh` 会打印它推送的新标签。

☑️ [创建一个应用](https://app.edgegap.com/application-management/applications/list) 以及你的镜像版本。你也可以使用该工具包的 `examples/app-version.json` 配合 `POST /v1/app/{app}/version`.
{% endtab %}
{% endtabs %}

第一次 IL2CPP 服务器构建大约需要 13 分钟。

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

你也可以在编辑器中通过 Tools / Edgegap Simple FPS / Build Linux Server 构建，它会把相同输出构建到 `Builds/EdgegapServer`。请参见 [Unity](https://docs.edgegap.com/zh/unity.md) 以了解更多关于构建 Unity 服务器的信息。

{% hint style="warning" %}
如果你使用 Edgegap Unity 插件打包服务器，请设置其 **Path To Dockerfile** 设置为 `edgegap/Dockerfile`.
{% endhint %}

☑️ [创建一个应用](https://app.edgegap.com/application-management/applications/list) 以及一个版本，使用：

* 你的镜像和标签，
* 你的容器注册表用户名和令牌，
* 初始资源为 1 vCPU 和 2 GB，
* [端口](https://docs.edgegap.com/zh/learn/bian-pai/application-and-versions.md#port-mapping) `7777`，协议 **UDP**，并关闭端口检查。

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

### 3. 本地测试

☑️ 构建一个本地镜像，并使用 Edgegap 会注入的变量运行它：

{% code collapsedlinecount="10" %}

```bash
scripts/package.sh
scripts/run-local.sh
```

{% endcode %}

☑️ 查找日志行 `[edgegap-simplefps] server started: session=f68e011bfb01.pr.edgegap.net photon_region=<code>` ，然后使用该会话和区域从客户端加入，如下一步所示。

{% hint style="info" %}
本地客户端连接 **中继**，因为同一台机器上的客户端无法直接到达 Docker Desktop 的 NAT 地址。在 Edgegap 上，相同的镜像会连接 **直接**.
{% endhint %}

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

### 4. 部署并连接

☑️ 从插件启动一个部署， [仪表板](https://app.edgegap.com/deployment-management/deployments/list)，或者 `POST /v2/deployments`。将你玩家的公网 IP 传递给 [以便靠近他们部署](https://docs.edgegap.com/zh/learn/bian-pai/deployments.md#server-placement).

☑️ 找到 `server started: session=<fqdn> photon_region=<code>` 在你的部署日志中。

☑️ 使用以下方式构建客户端 `scripts/build.sh client` （或你通常的 Windows 构建方式），启动它并在主菜单中点击 **派对菜单** 。

☑️ 在加入卡片上，在代码字段中输入你的部署 FQDN（例如 `f68e011bfb01.pr.edgegap.net`），并在 `区域代码（例如`cae **区域** ）字段中输入，随后点击 **加入**.

{% hint style="info" %}
如果你的客户端无法连接，最可能是你的区域与服务器日志不匹配。
{% endhint %}

🙌 祝贺你在 Edgegap 上完成了第一次部署！

## 🔄 对局生命周期

1. 服务器构建会跳过 Startup 菜单并加载 Deathmatch。
2. `EdgegapFusionBootstrap` 在 `ARBITRIUM_PORT_GAMEPORT_INTERNAL` (`7777` 上启动 Fusion 服务器（默认），绑定到 `0.0.0.0`，并以部署 FQDN 命名会话， `<ARBITRIUM_REQUEST_ID>.pr.edgegap.net`.
3. 服务器会记录会话名称和 Photon 区域，玩家将其输入到派对菜单的加入卡片中，并直接连接到该部署。
4. 当服务器进程自行退出时， `edgegap/start-server.sh` 会调用 `ARBITRIUM_DELETE_URL` 来停止该部署。

{% hint style="info" %}
启动脚本从不打印环境，因此 **你的删除令牌不会出现在日志中**.
{% endhint %}

请参见 [部署](https://docs.edgegap.com/zh/learn/bian-pai/deployments.md) 以了解更多。

## ⚙️ 环境变量

| 变量                                               | 由以下设置    | 作用                                                            |
| ------------------------------------------------ | -------- | ------------------------------------------------------------- |
| `ARBITRIUM_REQUEST_ID`                           | Edgegap  | 会话名称变为 `<request id>.pr.edgegap.net`，即部署的 FQDN。               |
| `ARBITRIUM_PORT_GAMEPORT_INTERNAL`               | Edgegap  | 服务器绑定的 UDP 端口（`7777` 默认值）。它绑定 `0.0.0.0`，因此客户端直接连接。            |
| `PHOTON_REGION`                                  | 你（版本或部署） | 固定的 Photon 区域，例如 `us`。当未设置时，服务器会使用其运行位置 ping 最好的区域。此覆盖目前尚未测试。 |
| `ARBITRIUM_DELETE_URL`, `ARBITRIUM_DELETE_TOKEN` | Edgegap  | 当服务器进程自行退出时，启动脚本会使用它们来停止该部署。                                  |

请参见 [注入的变量](https://docs.edgegap.com/zh/learn/bian-pai/deployments.md#injected-environment-variables) 以了解更多。

## 🔌 直接连接

Simple FPS 的  `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`. |

## 🎬 服务器场景

Fusion 通过以下方式告诉客户端要加载哪个场景： **构建索引**。仅使用 Deathmatch 构建的服务器会将 Deathmatch 放在索引 0，而客户端会将 Startup 放在索引 0。随后客户端永远找不到游戏对象，并在 `NullReferenceException` 中抛出异常 `Player.FixedUpdateNetwork` 每个 tick 都会如此。这就是为什么两个构建都使用 Startup (0) 和 Deathmatch (1)，并且服务器会跳过 Startup。

出于同样的原因，服务器会将 Deathmatch 标记为 **加载时激活**，就像示例自身的主机一样。没有它，客户端会加载 Deathmatch，但仍保持 Startup 处于激活状态，并出现同样的异常。

## ⚠️ 已知问题

* 完成一场比赛直到结束，以及服务器是否会在比赛后退出，尚未测试——请参见该工具包的 [README](https://github.com/edgegap/netcode-game-sample-photon-fusion2-simple-fps).
* `PHOTON_REGION` 覆盖目前尚未测试。

## 🚨 故障排除

<details>

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

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

</details>

<details>

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

* 缺少 Linux 工具链包，请参见 [准备工作](#preparation).

</details>

<details>

<summary>客户端获得 <code>GameNotFound</code></summary>

* 客户端和服务器之间的 App Version 或 Photon 区域不同。请与服务器的 `photon_region=` 日志行进行比较。

</details>

<details>

<summary>客户端获得 <code>InvalidAuthentication</code></summary>

* 你的 Fusion App ID 在构建中错误或缺失。

</details>

<details>

<summary>Tab 覆盖显示 CT Relayed</summary>

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

</details>
