> 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/mirror-on-edgegap-websocket.md).

# Mirror WebGL

使用 Mirror 的 WebSocket 传输，在 Edgegap 游戏服务器上运行一个 Unity WebGL 多人游戏。

本指南将帮助你使用 [Mirror](https://mirror-networking.com/)的 Websocket 传输，并为 Unity 项目在 Edgegap 上创建无头服务器。

本指南将使用开源示例项目 `Tanks`，可在 Mirror 示例中的以下位置找到： `Assets/Mirror/Examples/Tanks`.

你可以找到 [该示例的最终版本](https://github.com/edgegap/netcode-game-sample-webgl-mirror-tanks) 在 GitHub 上。

### 台球示例

如果你更喜欢按照台球示例观看逐步视频教程，请在此查看：

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

{% hint style="success" %}
本视频展示了使用最新 [Unity](https://docs.edgegap.com/zh/unity.md) 构建工具的更新构建流程。
{% endhint %}

### 切换传输方式

在准备构建游戏服务器之前，我们首先需要对基础场景做一些修改。

* 打开 `MirrorTanks.unity` 位于 `Assets/Mirror/Examples/Tanks/Scenes`;
* 在 `NetworkManager` gameObject，移除 `KcpTransport` 脚本，并将其替换为 `SimpleWebTransport` 位于 `Assets/Mirror/Transports/SimpleWeb`，也请务必更新以下对象的 Transport 字段： `NetworkManager` 脚本组件中的 Transport 字段为这个新传输方式。确保 `Auto Start Server Build` 选项也已勾选。
* 根据你使用的 Mirror 版本，你可能需要更改/更新 `NetworkManagerHUD` 以使其能与 KCP 之外的其他传输方式兼容，并允许你在加入服务器前在 HUD 中输入端口值。

请记下用于网络通信的端口，称为 `[GAME PORT]`。在本例中，使用的端口是 `7778`.

### 构建游戏服务器并容器化

{% hint style="info" %}
为方便容器化和部署流程，可以使用最新版本的 [Edgegap Unity Plugin](https://github.com/edgegap/buildtool-unity-plugin) 来自动化该流程。有关如何使用此插件的更多信息，请参见 [Unity - 入门指南](https://docs.edgegap.com/zh/unity.md).

如果你愿意，也可以按照这些逐步说明操作。
{% endhint %}

当你的游戏准备就绪后，前往 `构建` 界面，在 Unity 编辑器的 `File -> Build Settings` 顶部菜单中。请根据你的 Unity 版本选择正确的预设。

* 在 2021.2 版本之前：
  * 将 `目标平台` 变为 `Linux`;
  * 将 `架构` 变为 `x86_64`;
  * 勾选 `服务器构建` 选项。
* 否则：
  * 将 `平台` 变为 `专用服务器`;
  * 将 `目标平台` 变为 `Linux`.

然后点击构建，并选择一个名为 `linux_server` 作为文件目标位置。将 `linux_server` 文件夹转移到第二个空文件夹中，该文件夹在本文档中将被称为 `[SERVER BUILD]` 文件夹移动到本文档中。添加以下 `Dockerfile` 以及 `boot.sh` 文件到 `[SERVER BUILD]` 文件夹：

#### Dockerfile

{% code collapsedlinecount="10" %}

```
FROM ubuntu:bionic
MAINTAINER <author_detail>

ARG DEBIAN_FRONTEND=noninteractive
ARG docker_version=17.06.0-ce

RUN
    apt-get update && \
    apt-get install -y libglu1 xvfb libxcursor1 ca-certificates && \\
    update-ca-certificates && \
    apt-get clean

EXPOSE 7778/TCP

COPY linux_server/  /root/linux_server/
COPY boot.sh        /boot.sh

WORKDIR /root/
ENTRYPOINT ["/bin/bash", "/boot.sh"]
```

{% endcode %}

#### boot.sh

{% code collapsedlinecount="10" %}

```
xvfb-run --auto-servernum --server-args='-screen 0 640x480x24:32' /root/linux_server/[YOUR GAME].x86_64 -batchmode -nographics
```

{% endcode %}

请务必将 `[YOUR GAME]` 占位符替换为生成文件的名称

然后，在 `[SERVER BUILD]` 文件夹中打开命令提示符；运行以下 Docker 命令来为你的构建创建镜像并将其推送到私有仓库：

{% hint style="warning" %}
对于 ARM CPU（Mac M1、M2 等）用户，请添加 `--platform linux/amd64` 选项到你的构建命令中。
{% endhint %}

#### 使用 Linux

{% code collapsedlinecount="10" %}

```bash
# 构建镜像
docker build . -t <IMAGE_NAME>:<IMAGE_TAG>

# 登录，系统会提示输入密码
docker login -u '<REGISTRY_USERNAME>' <REGISTRY_URL>

# 为你的镜像添加另一个与注册表对应的标签
docker image tag <IMAGE_NAME>:<IMAGE_TAG> <REGISTRY_URL>/<PROJECT_NAME>/<IMAGE_NAME>:<IMAGE_TAG>

# 推送镜像
docker push <REGISTRY_URL>/<PROJECT_NAME>/<IMAGE_NAME>:<IMAGE_TAG>
```

{% endcode %}

#### 使用 cmd

{% code collapsedlinecount="10" %}

```bash
# 构建镜像
docker build . -t <IMAGE_NAME>:<IMAGE_TAG>

# 登录，系统会提示输入密码
docker login -u <REGISTRY_USERNAME> <REGISTRY_URL>

# 为你的镜像添加另一个与注册表对应的标签
docker image tag <IMAGE_NAME>:<IMAGE_TAG> <REGISTRY_URL>/<PROJECT_NAME>/<IMAGE_NAME>:<IMAGE_TAG>

# 推送镜像
docker push <REGISTRY_URL>/<PROJECT_NAME>/<IMAGE_NAME>:<IMAGE_TAG>
```

{% endcode %}

#### 使用 PowerShell

{% code collapsedlinecount="10" %}

```bash
# 构建镜像
docker build . -t <IMAGE_NAME>:<IMAGE_TAG>

# 登录，系统会提示输入密码
docker login -u '<REGISTRY_USERNAME>' <REGISTRY_URL>

# 为你的镜像添加另一个与注册表对应的标签
docker image tag <IMAGE_NAME>:<IMAGE_TAG> <REGISTRY_URL>/<PROJECT_NAME>/<IMAGE_NAME>:<IMAGE_TAG>

# 推送镜像
docker push <REGISTRY_URL>/<PROJECT_NAME>/<IMAGE_NAME>:<IMAGE_TAG>
```

{% endcode %}

### 将服务器部署到 Edgegap

登录 Edgegap 仪表板后，前往 `应用与游戏` 页面。点击 `创建新的` 按钮以打开应用表单。以下是各字段及其正确填写方式：

* 应用名称：可以是你想使用的任何显著名称，以便在其他应用中轻松识别你的应用。
* 镜像：可以是你想使用的任何特定镜像，以便在其他应用中轻松识别你的应用。
* 版本名称：你可能希望使用版本名称来描述你正在部署的版本范围。示例可以是“demo”、“production”、“v1”、“v2”
* 容器：
  * 注册表：“\[URL]”，其中 \[URL] 是你可以在容器仓库页面上显示的凭据中的值。
  * 镜像仓库：“\[PROJECT]/\[YOUR GAME]”，其中 \[PROJECT] 和 \[YOUR GAME] 是你之前在推送 docker 镜像时使用的值。
  * 标签：“\[TAG]”，其中 \[TAG] 是你之前在推送 docker 镜像时使用的值。
  * 勾选“使用私有仓库”
  * 私有注册表用户名：“\[USERNAME]”，其中 \[USERNAME] 是你凭据中的值。
  * 私有注册表令牌：“\[TOKEN]”，其中 \[TOKEN] 是你凭据中的值。
  * 要求：保持不变。
  * 端口：点击 `+ 添加端口` 链接以添加新端口，并添加以下条目：
    * `7778` - WS - 启用 TLS 升级（Beta）

{% hint style="warning" %}
如果你使用 WSS 选项，务必启用 `TLS 升级` 选项。否则，你会在 Edgegap 仪表板的容器日志中遇到类似如下的错误。

{% code collapsedlinecount="10" %}

```cmd
客户端发来的前几个字节不是用于握手的 'GET'，而是 16-03-01
```

{% endcode %}
{% endhint %}

<figure><img src="https://3334189208-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FsR0dHSFv9ymoC0DO5G8J%2Fuploads%2Fgit-blob-4996c904d603b04628fdd82091b1d3a5768aac40%2Fserver-port.png?alt=media" alt=""><figcaption></figcaption></figure>

创建应用后，你可以点击 `部署` 按钮以继续部署你的游戏服务器。一旦你的部署最新状态变为 `就绪`，你就可以使用游戏客户端版本连接到服务器。请记下 `托管` URL，并在部署的端口映射选项卡中查看 `外部端口` 其公开可用的地址。

### 测试客户端

#### 在编辑器中

回到 Unity 编辑器中的坦克场景，选择 `NetworkManager` gameObject，并更改以下设置：

* 在 `网络管理器` 组件：
  * 将 `网络地址` 为服务器部署的 `托管` URL；
  * 取消勾选 `Auto Start Server Build` 选项。
* 在 `Simple Web Transport` 组件：
  * 将 `端口` 值为 Edgegap 部署的 `外部端口` 例如： `32821`;
  * 请确保 `客户端使用 WSS` 选项已启用。

<figure><img src="https://3334189208-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FsR0dHSFv9ymoC0DO5G8J%2Fuploads%2Fgit-blob-8fe3a5d63fc65f33f18d8e0c39a5d2d5a5b97e6c%2Fnetwork-manager-client-settings-1.png?alt=media" alt=""><figcaption></figcaption></figure>

<figure><img src="https://3334189208-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FsR0dHSFv9ymoC0DO5G8J%2Fuploads%2Fgit-blob-8a7da870b869174fc4117dc6e6e44edb8e62b906%2Fnetwork-manager-client-settings-2.png?alt=media" alt=""><figcaption></figcaption></figure>

完成后，点击 `Play` 在编辑器中，然后点击 `Client` 按钮；你将连接到服务器，并在短暂等待后开始游戏。

#### 在 Itch.io 上

要将你的游戏客户端发布到 Itch，你需要制作客户端构建；你需要安装 `WebGL 构建支持` 模块，适配你所使用的 Unity 版本。完成后，返回到 `构建` 界面，在 Unity 编辑器的 `File -> Build Settings`，并选择以下选项：

* 将 `平台` 变为 `WebGL`;
* 打开 `Player 设置`。在 `Player -> 发布设置`中，将 `压缩格式` 变为 `Gzip` 并确保 `解压回退` 选项已选中。保存这些设置，然后关闭窗口。

<figure><img src="https://3334189208-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FsR0dHSFv9ymoC0DO5G8J%2Fuploads%2Fgit-blob-04b0077a769072f95884b660b71bc3e93655f6a6%2Fclient-build.png?alt=media" alt=""><figcaption></figcaption></figure>

然后点击构建，并选择一个名为 `构建` 作为文件目标位置。将 `构建` 文件夹转移到第二个空文件夹中，该文件夹在本文档中将被称为 `[CLIENT BUILD]` 文件夹。

游戏构建完成后，将此 `构建` 文件夹中的文件压缩为一个 zip 压缩包，并确保它们位于压缩包根目录中。然后你只需将该 zip 压缩包上传到你的 Itch 项目，并确保选择让文件在浏览器中运行的选项。启动游戏后，只需确保 HUD 中的网络地址和端口值设置正确，然后点击 `Client` 按钮开始游戏。

#### 在 Edgegap 上托管客户端

甚至可以在 Edgegap 上托管你的游戏客户端！为此，请添加以下 `Dockerfile` 以及 `nginx.conf` 文件到 `[CLIENT BUILD]` 文件夹：

**Dockerfile**

{% code collapsedlinecount="10" %}

```
FROM nginx:alpine
MAINTAINER <author_detail>

COPY build/ /usr/share/nginx/html
copy nginx.conf /etc/nginx/
```

{% endcode %}

**nginx.conf**

{% code collapsedlinecount="10" %}

```
user  nginx;
worker_processes  auto;

error_log  /var/log/nginx/error.log notice;
pid        /var/run/nginx.pid;


events {
worker_connections  1024;
}


http {
include       /etc/nginx/mime.types;
default_type  application/octet-stream;

log_format  main  '$remote_addr - $remote_user [$time_local] "$request" '
'$status $body_bytes_sent "$http_referer" '
'"$http_user_agent" "$http_x_forwarded_for"';

access_log  /var/log/nginx/access.log  main;

sendfile        on;
#tcp_nopush     on;

keepalive_timeout  65;

#gzip  on;

include /etc/nginx/conf.d/*.conf;

server {
# 在 http 服务器配置中添加以下配置
# ...

    # 磁盘上的 Brotli 预压缩数据文件应以启用压缩的方式提供：
    location ~ .+\.(data|symbols\.json)\.br$ {
        # 因为该文件已在磁盘上预先压缩，所以请禁用其按需压缩。
        # 否则 nginx 会尝试进行双重压缩。
        gzip off;
        add_header Content-Encoding br;
        default_type application/octet-stream;
    }

    # 磁盘上的 Brotli 预压缩 JavaScript 代码文件：
    location ~ .+\.js\.br$ {
        gzip off; # 不要对已压缩文件尝试动态 gzip 压缩
        add_header Content-Encoding br;
        default_type application/javascript;
    }

    # 磁盘上的 Brotli 预压缩 WebAssembly 文件：
    location ~ .+\.wasm\.br$ {
        gzip off; # 不要对已压缩文件尝试动态 gzip 压缩
        add_header Content-Encoding br;
        # 通过为以下内容指定正确的 MIME 类型来启用流式 WebAssembly 编译
        # Wasm 文件。
        default_type application/wasm;
    }

    # 磁盘上的 gzip 预压缩数据文件应以启用压缩的方式提供：
    location ~ .+\.(data|symbols\.json)\.gz$ {
        gzip off; # 不要对已压缩文件尝试动态 gzip 压缩
        add_header Content-Encoding gzip;
        default_type application/octet-stream;
    }

    # 磁盘上的 gzip 预压缩 JavaScript 代码文件：
    location ~ .+\.js\.gz$ {
        gzip off; # 不要对已压缩文件尝试动态 gzip 压缩
        add_header Content-Encoding gzip;
        default_type application/javascript;
    }

    # 磁盘上的 gzip 预压缩 WebAssembly 文件：
    location ~ .+\.wasm\.gz$ {
        gzip off; # 不要对已压缩文件尝试动态 gzip 压缩
        add_header Content-Encoding gzip;
        # 通过为以下内容指定正确的 MIME 类型来启用流式 WebAssembly 编译
        # Wasm 文件。
        default_type application/wasm;
    }
}
}
```

{% endcode %}

继续使用 [之前相同的 Docker 命令](#bootsh) 来构建并将你的游戏客户端镜像推送到私有仓库，但请在打开于以下位置的命令窗口中执行： `[CLIENT BUILD]` 文件夹。请务必使用与服务器不同的镜像名称。

然后，在 Edgegap 仪表板上为你的客户端创建一个新应用，并使用以下设置：

* 应用名称：可以是你想使用的任何显著名称，以便在其他应用中轻松识别你的应用。
* 镜像：可以是你想使用的任何特定镜像，以便在其他应用中轻松识别你的应用。
* 版本名称：你可能希望使用版本名称来描述你正在部署的版本范围。示例可以是“demo”、“production”、“v1”、“v2”
* 容器：
  * 注册表：“\[URL]”，其中 \[URL] 是你可以在容器仓库页面上显示的凭据中的值。
  * 镜像仓库：“\[PROJECT]/\[YOUR GAME]”，其中 \[PROJECT] 和 \[YOUR GAME] 是你之前在推送 docker 镜像时使用的值。
  * 标签：“\[TAG]”，其中 \[TAG] 是你之前在推送 docker 镜像时使用的值。
  * 勾选“使用私有仓库”
  * 私有注册表用户名：“\[USERNAME]”，其中 \[USERNAME] 是你凭据中的值。
  * 私有注册表令牌：“\[TOKEN]”，其中 \[TOKEN] 是你凭据中的值。
  * 要求：保持不变。
  * 端口：点击 `+ 添加端口` 链接以添加新端口，并添加以下条目：
    * `80` - HTTPS

<figure><img src="https://3334189208-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FsR0dHSFv9ymoC0DO5G8J%2Fuploads%2Fgit-blob-f88e313ed093082a221680f4b59b241afe7cbf70%2Fclient-port.png?alt=media" alt=""><figcaption></figcaption></figure>

创建应用后，你可以点击 `部署` 按钮继续部署你的游戏客户端。在服务器和客户端部署都设置为 `就绪`后，打开游戏客户端的 `托管` URL，在指定的 `外部端口` 中在浏览器里打开，在游戏 HUD 中设置正确的值后，你就可以游玩了！

<figure><img src="https://3334189208-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FsR0dHSFv9ymoC0DO5G8J%2Fuploads%2Fgit-blob-b140451a9c9404cba2498e715c6c83abb656e655%2Fonline-client.png?alt=media" alt=""><figcaption></figcaption></figure>

### Edgegap 配对器（可选）

该示例还可以将玩家与 [Edgegap Matchmaker](https://docs.edgegap.com/zh/learn/pi-pei-xi-tong.md)。它默认处于禁用状态，上述步骤无需它也能工作。开箱即用时，Edgegap SDK 包未安装，配对脚本会编译为空存根，而 `EdgegapMatchmaking` 对象在 `MirrorTanks` 场景中处于非活动状态。

启用后，玩家点击 `寻找匹配` 而不是输入服务器地址。配对器会将他们分组，Edgegap 会在他们附近启动部署，每个客户端都会自动连接到它。

配对脚本位于 `Assets/EdgegapMatchmaking`:

* `TanksMatchmakingClient` - 创建一个票据并轮询，直到分配到服务器，然后将 Mirror 连接到 `wss://{fqdn}:{external port}`，在服务器启动期间重试，并绘制一个小型 `寻找匹配` / `取消` 面板，
* `TanksMatchmakingServer` - 仅在专用服务器上运行，并在 2 分钟内无人加入，或在最后一名玩家离开 30 秒后停止其自身的部署，
* `Edgegap.Tanks.Matchmaking.asmdef` - 使用 `versionDefines` 来定义 `EDGEGAP_SDK` 当 `com.edgegap.unity-sdk` `3.5.5` 或更新版本已安装（`3.5.5` 是第一个可编译为 WebGL 的 SDK 版本），
* `matchmaker-config.json` - 仓库根目录中的一个示例配对器配置。

要启用它：

1. 安装 [Edgegap Unity SDK](https://docs.edgegap.com/zh/unity/matchmaking.md)。在 Package Manager 中，选择 `从 git URL 添加包` 并输入 `https://github.com/edgegap/sdk-unity-sessions-matchmaker-server-browser.git`.
2. 打开 `MirrorTanks` 场景，选择 `EdgegapMatchmaking` gameObject，并勾选其名称旁边的复选框。
3. 按上述方式构建并上传服务器，并将 `7778` 端口、协议 `WS` 以及 `TLS 升级` 启用。请在第 2 步之后再构建，以便服务器包含 `TanksMatchmakingServer` ，并在比赛结束时停止其部署。
4. 在以下位置创建一个配对器： [控制面板](https://app.edgegap.com/matchmaker-management-v2/matchmakers/list) 来自 `matchmaker-config.json`。将 `application.name` 以及 `application.version` 设置为你的应用版本，并将 `allowed_cors_origins` 设置为提供你的 WebGL 构建的源。浏览器会直接调用配对器，因此 [来自任何其他源的请求都会被阻止](https://docs.edgegap.com/zh/learn/pi-pei-xi-tong/matchmaker-in-depth.md#cross-origin-resource-sharing-cors).
5. 粘贴你的配对器的 `API URL` 到 `Base URL` 在 `TanksMatchmakingClient`，以及它的 `认证令牌` 到 `认证令牌`.
6. 构建 WebGL，将其托管在允许的源上，在两个浏览器窗口中打开它，并点击 `寻找匹配` 各自的按钮。

{% hint style="info" %}
Auth Token 归你的配对器所有，并随客户端构建一起发布，但不会授予你对 Edgegap 账户的访问权限。 **切勿将你的 Edgegap API 令牌放入客户端。**
{% endhint %}

使用示例配置文件时，2 到 4 名玩家会被配对在一起。在队列中等待 30 秒后，单个玩家将单独获得一个服务器。

{% hint style="info" %}
浏览器无法 ping [延迟信标](https://docs.edgegap.com/zh/learn/bian-pai/ping-beacons.md)，因此示例配置文件没有 `延迟` 规则，配对器会根据玩家的公网 IP 地址来放置服务器。
{% endhint %}

要再次禁用配对器，请停用 `EdgegapMatchmaking`。若要完全移除它，也请移除 SDK 包。

{% hint style="info" %}
如果你需要有关 Mirror 集成和 websocket 的更多信息，请参阅 Mirror 的 [WebSockets Transport 文档](https://mirror-networking.gitbook.io/docs/manual/transports/websockets-transport).
{% endhint %}
