> 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/unity/matchmaking.md).

# 匹配系统

使用 Edgegap 可选的入门套件 SDK，为你的 Unity 游戏添加匹配系统；它可随你的多人项目增长而扩展和自定义。

此 SDK 是面向 Unity 用户的可选入门套件，后续可扩展和自定义。

## 💡 功能

{% columns %}
{% column %}

* 完整示例
* Ping 自动化（即将推出）
* 票据、组、队伍
  {% endcolumn %}

{% column width="33.33333333333333%" %}

* 匹配变量
* 类型定义（C#）
* 本地开发测试
  {% endcolumn %}

{% column width="33.33333333333333%" %}

* 跨平台
* 易于自定义
* 自动重试
  {% endcolumn %}
  {% endcolumns %}

## ✔️ 准备工作

Unity SDK 包含用于部署、匹配和服务器浏览器的可选集成工具。此插件官方支持 Unity 2021.3.0f1 及更高版本。

{% hint style="info" %}
**Unity SDK 的最新版本是 `3.5.6`**。本文档中的所有示例均为最新版本。
{% endhint %}

{% hint style="success" %}
此插件完全免费提供，适用免费套餐的条款与条件。
{% endhint %}

#### 要求

<details>

<summary>安装 Git 客户端（例如 <a href="https://git-scm.com/">git-scm</a>)</summary>

Unity 需要使用 Git 客户端自动下载并安装我们的 Unity 软件包。安装完成后，您无需直接使用 Git。

</details>

#### 安装

1. 打开您的 Unity 项目，
2. 选择 `Window > Package Management > Package Manager` ,
3. 点击 :heavy\_plus\_sign: 图标并选择 `Add package from git URL...` ,
4. 出现提示时，输入 SDK 的 URL：

{% code title="" collapsedlinecount="10" %}

```
https://github.com/edgegap/sdk-unity-sessions-matchmaker-server-browser.git
```

{% endcode %}

5. 点击 `Add`  并等待安装完成。

#### 导入示例

此软件包包含多个示例，旨在单独使用（请勿组合使用这些示例）。

#### 已验证的来源

这是此 SDK 唯一的官方分发渠道，请勿信任未经验证的来源！

#### 更新软件包

在 Unity Package Manager 中找到 Edgegap SDK，然后点击 `Update` .

{% hint style="warning" %}
**导入的示例不会自动更新！** 备份所有自定义属性值，删除当前场景中使用的示例脚本，然后重新导入示例。
{% endhint %}

{% hint style="info" %}
某些版本可能包含重大变更。这类版本会以新的 MAJOR 版本号标示。
{% endhint %}

#### 更新到 v3

此次更新包含许多新的 [服务器浏览器](https://docs.edgegap.com/zh/unity/server-browser.md) 工具和示例，改进了匹配错误处理等。请参阅 [发行说明](https://docs.edgegap.com/zh/docs/release-notes.md) 查看完整列表。

{% hint style="warning" %}
Unity SDK v3 更新包含一些重大变更。请仔细重新测试您的集成。
{% endhint %}

<details>

<summary>Unity SDK v3 重大变更——范围、影响和解决方法</summary>

在命名空间 `Edgegap.Matchmaking`:

* 合并的方法 `Client._Abandon -> Client.StopMatchmaking` .
  * 影响较小——主要涉及自定义客户端处理程序的实现。
  * 解决方法——将 `_Abandon` 调用替换为 `StopMatchmaking` 方法。
* 合并的事件侦听器 `onTicketUpdate -> onAssignmentUpdate`.
  * 影响较小——大多数实现都无需使用此侦听器。
  * 解决方法——查找并替换为 [新事件](https://docs.edgegap.com/unity/matchmaking#client-events) 在……之下 `onAssignmentUpdate` 监听器。
* 已解耦 `Ping` , `SafeHttpRequest` ，以及 `Observable` 。已移至命名空间 `Edgegap` .
  * 影响较低 - 功能保持不变，只是移至另一个命名空间。
  * 解决方案 - 根据需要更新导入语句或命名空间引用。
* 由于与控制台的兼容性较差且增加了引导使用的阻力，已移除缓存功能。
  * 影响较低 - 崩溃的玩家可能会创建重复工单，而不是从缓存恢复。
  * 解决方案 - 使用以下内容实现自定义缓存： `onAssignmentUpdate` 事件监听器。
* 已重命名程序集 `com.edgegap.unity-matchmaking-sdk -> com.edgegap.unity-sdk` .
  * 影响较低 - 仅影响引用此 SDK 的高度定制化构建流水线。
  * 解决方案 - 在自定义工具中更新 SDK 程序集名称引用。

</details>

## 🍀 快速开始

本指南默认你已具备以下基础知识： [匹配系统](https://docs.edgegap.com/zh/learn/pi-pei-xi-tong.md) 相关概念以及一个正在运行的 Matchmaker。

{% hint style="success" %}
**我们强烈建议导入我们的 Simple Example** 以便在阅读本文档时跟着代码一起学习。你可以在以下位置进行导入： `Unity Package Manager > Edgegap SDK > Samples` .
{% endhint %}

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

### 概述

我们的 SDK 大量使用 [依赖注入](https://learn.microsoft.com/en-us/dotnet/core/extensions/dependency-injection/overview#the-concept) 和 [观察者](https://learn.microsoft.com/en-us/dotnet/standard/events/observer-design-pattern) 编程模式。

{% hint style="info" %}
此包整合了这两者 [服务器浏览器](https://docs.edgegap.com/zh/learn/fu-wu-qi-liu-lan-qi.md) 和 [匹配系统](https://docs.edgegap.com/zh/learn/pi-pei-xi-tong.md)，它们可以一起使用，也可以单独使用。您可以自由重用任何脚本，用于您自己的定制分支和集成。
{% endhint %}

此软件包包括：

* 运行时文件 - 将会在你的客户端和服务器构建中编译并打包：
  * 服务专用工具：
    * [#client-agent](#client-agent "mention") - 一个完整的客户端集成，可复用/扩展。
    * API 函数 - 端点定义、错误处理和日志自动化。
  * 服务专用 DTO[^1] - 用于 Matchmaking API 的类型化数据容器。
  * 共享工具 - 日志、HTTP、ping、可观察对象等...
  * 共享 DTO[^1] - 供多个 Edgegap 服务用于传递数据。
* 示例文件 - 仅在导入到你的项目中时才会打包并编译：
  * [#simple-example](#simple-example "mention") - 某个示例处理器，用于 [最小配置](https://docs.edgegap.com/zh/learn/pi-pei-xi-tong.md#simple-example).
  * [#region-picker](#region-picker "mention") - 探索带有手动区域选择的 UI 集成。

### 组客户端

**Ping 自动化、票据管理和主机获取** 由组客户端执行。

实例化后，代理的 **父级 MonoBehaviour（处理器）必须初始化客户端** 并提供：

* `onMonitorUpdate`  回调 - 观察服务健康状态变化。
* `onAssignmentUpdate`  回调 - 观察并响应主机分配变化。

初始化后，该客户端将自动提供校验并挂接日志观察器，最终通过一次对监控 API 端点的调用来指示服务健康状况。

从此处开始，预期由客户端处理器接管并调用客户端函数：

* `信标`  以获取可用列表 [Ping 信标](https://docs.edgegap.com/zh/learn/bian-pai/ping-beacons.md).
* `MeasureBeaconsRoundTripTime`  以针对给定的一组信标提供 ping 测量。
* `CreateGroup`  供大厅房主创建一个可加入的组，好友可被邀请加入。
* `JoinGroup`  使用通过第三方大厅/后端发送的组 ID 加入现有组。
* `SetReady`  将组所有者和成员标记为已准备好，并开始搜索匹配。
* `ResumeMatchmaking`  在客户端崩溃时加载缓存的组并继续搜索。
* `StopMatchmaking`  删除票据（如果尚未匹配）并退出队列。
* `Status`  用于验证 Matchmaker 服务健康状况。

当建立新的玩家连接时，玩家应使用你的网络代码向游戏服务器发送其票据 ID，以将连接与 [深入了解](https://docs.edgegap.com/zh/learn/pi-pei-xi-tong/matchmaker-in-depth.md#injected-variables).

{% hint style="success" %}
将连接详情保存在客户端或游戏后端，以便在意外崩溃时重新连接。
{% endhint %}

## 服务器代理

服务器代理执行 **回填创建、检测票据分配、检测回填放弃和移除。它还会跟踪并重新创建已过期、已超出连接宽限期或已被放弃的回填 - 以达到所需队伍人数**.

服务器代理会跟踪当前已连接的玩家，并自动将他们的票据包含到新的回填中，以确保回填玩家将按所配置配置文件的规则进行匹配。

实例化后，代理的 **父级 MonoBehaviour（处理器）必须初始化客户端** 并提供：

* `onMonitorUpdate`  回调 - 观察服务健康状态变化。
* `onBackfillUpdate` 回调 - 观察并响应回填变化。

初始化后，该客户端将自动提供校验并挂接日志观察器，最终通过一次对监控 API 端点的调用来指示服务健康状况。

从此处开始，预期由服务器处理器接管并调用客户端函数：

* `PlayerConnected`  用于防止替换那些从未连接过的初始或回填玩家。
* `AbandonPlayer`  用于表示已连接玩家离开服务器并需要被替换。
* `AbandonAllBackfills`  立即停止服务器回填并删除回填。
  * 应在停止服务器之前调用此方法。此时已被分配的玩家需要重新加入匹配，因为服务器正在关闭。
  * 在调用此方法时已分配的回填仍可在配置的宽限期内连接。
* `AbandonBackfill`  强制放弃特定回填（自定义处理器实现）。
* `Status`  用于验证匹配器服务健康状况。

## 🧪 示例

通过示例开始，其中包含服务器和客户端的完整可运行集成。

### 简单示例

包含完整的玩家生命周期实现，涵盖 ping 测量、票据管理和主机分配获取。演示如何在服务器端读取注入的匹配变量。

修改匹配属性，可轻松扩展此示例以适配任何配置。

### 区域选择器

某些玩家（或组）存在特殊的本地化条件（例如 ISP[^2] 封锁， 全国范围的封锁[^3]，或其他情况），因此可能更倾向于手动选择区域，而不是仅根据 ping 来决定。

查看我们的 Region Picker 示例，并从中汲取灵感来实现你的匹配 UI。

### 组队

与好友组队加入匹配队列，要求所有玩家在开始搜索前确认。先从最小化 UI 实现开始，然后根据你的游戏设计进行自定义。

探索与组队流程的 UI 集成，提供尽可能好的社交体验。

### 回填

复用服务器容量并将玩家加入正在进行的部署。设置目标队伍人数并等待玩家加入。包含自动连接宽限期和对过期回填的重新创建。

自定义示例服务器处理器，以适配多队伍或非对称队伍配置。

## ⚙️ 自定义

此 SDK 旨在被扩展和修改，不过某些修改可能存在风险：

✅ 处理器 - 可安全挂接 UI 观察器并进行少量添加或修改，

⚠️ 代理 - 修改玩家生命周期管理需自行承担风险，

⚠️ API - 使用挑选出的工具从头编写你自己的集成。

处理器可观察如下所述由服务器和客户端代理发出的任何事件。

{% hint style="warning" %}
请务必熟悉 [深入匹配](https://docs.edgegap.com/zh/learn/pi-pei-xi-tong/matchmaker-in-depth.md) 概念后再进行自定义。
{% endhint %}

{% hint style="info" %}
如果你需要帮助， [请通过 Discord 联系我们](https://discord.gg/MmJf8fWjnt)。关于实时游戏支持，请查看我们的 [工单系统](https://edgegap.atlassian.net/servicedesk/customer/portal/3).
{% endhint %}

### 客户端事件

组客户端会发出事件（动作），供父级处理器观察和使用。

{% hint style="success" %}
通过访问读取事件载荷  `.Current` 任何可观察对象的状态。🔴 `错误` 事件在主事件消息之后包含由换行符分隔的完整错误消息。
{% endhint %}

预览由可观察对象发出的事件 `监控` :

<table data-full-width="true"><thead><tr><th width="125">动作类型</th><th width="450">事件消息</th><th>描述</th></tr></thead><tbody><tr><td>🟢 <code>更新</code> </td><td><code>健康</code></td><td>所有系统正常。</td></tr><tr><td>🟢 <code>更新</code> </td><td><code>不健康</code></td><td>意外问题。</td></tr><tr><td>🔴 <code>错误</code></td><td><code>获取监控失败</code></td><td>配置错误或意外问题。</td></tr><tr><td>🔴 <code>错误</code></td><td><code>获取信标失败</code></td><td>意外问题。</td></tr></tbody></table>

预览由可观察对象发出的事件 `组`:

<table data-full-width="true"><thead><tr><th width="125">动作类型</th><th width="450">事件消息</th><th>描述</th></tr></thead><tbody><tr><td>🟢 <code>更新</code> </td><td><code>已创建</code></td><td>组创建成功。</td></tr><tr><td>🔴 <code>错误</code></td><td><code>组创建失败</code></td><td>创建组失败。</td></tr><tr><td>🟢 <code>更新</code> </td><td><code>已加入</code></td><td>组加入成功。</td></tr><tr><td>🔴 <code>错误</code></td><td><code>组加入失败</code></td><td>加入组失败。</td></tr><tr><td>🟢 <code>更新</code> </td><td><code>已恢复</code></td><td>组恢复成功。</td></tr><tr><td>🔴 <code>错误</code></td><td><code>未找到组</code></td><td>不是组成员，或组已过期。</td></tr><tr><td>🔴 <code>错误</code></td><td><code>冲突，放弃并重新开始</code></td><td>在尝试创建/加入新组之前，请先放弃当前组。</td></tr><tr><td>🟢 <code>更新</code> </td><td><code>成员已更新 [{ready}]</code></td><td>成员已使用新的 Ready 值更新。</td></tr><tr><td>🟡 <code>警告</code></td><td><code>成员更新失败</code></td><td>更新组成员失败。组开始搜索匹配后无法取消准备。</td></tr><tr><td>🔴 <code>错误</code></td><td><code>组更新失败</code></td><td>使用新的 Ready 值更新失败。</td></tr><tr><td>🔵 <code>通知</code></td><td><code>轮询 [{consecutive}/{maximum}]</code></td><td>客户端已开始轮询组状态。</td></tr><tr><td>🔵 <code>通知</code></td><td><code>轮询已停止</code></td><td>客户端已停止轮询票据状态。</td></tr><tr><td>🔴 <code>错误</code></td><td><code>轮询失败，已达到最大重试次数</code></td><td>客户端已用尽连续轮询的最大重试次数。请检查服务状态。</td></tr><tr><td>🔴 <code>错误</code></td><td><code>轮询失败</code></td><td>客户端在轮询时收到了不可重试的错误。请检查服务状态。</td></tr><tr><td>🟢 <code>更新</code> </td><td><code>组已更新 [{status}]</code></td><td>在轮询期间检测到组状态变化。</td></tr><tr><td>🟢 <code>更新</code> </td><td><code>已放弃</code></td><td>票据删除成功。</td></tr><tr><td>🟢 <code>更新</code> </td><td><code>放弃失败（未找到）</code></td><td>客户端无法找到要删除的票据，可能已过期。</td></tr><tr><td>🟡 <code>警告</code></td><td><code>放弃失败（已找到匹配）</code></td><td>客户端无法删除已匹配的组。请禁用放弃或 <a data-mention href="https://docs.edgegap.com/zh/learn/pi-pei-xi-tong/matchmaker-in-depth.md#backfill-match">深入了解</a> 以替换该玩家。</td></tr><tr><td>🔴 <code>错误</code></td><td><code>放弃失败</code></td><td>删除组或成员资格失败。</td></tr><tr><td>🟢 <code>更新</code> </td><td><code>已移除</code></td><td>组已过期，本地引用已删除。</td></tr></tbody></table>

### 服务器事件

服务器代理会发出事件（动作），供父级处理器观察和使用。发出这些事件的服务器代理仅在以下 [#backfill](#backfill "mention") 示例中初始化。

{% hint style="info" %}
当前已分配的票据可从服务器代理属性中读取 `分配`  可随时读取。
{% endhint %}

{% hint style="success" %}
通过访问读取事件载荷  `.Current` 任何可观察对象的状态。🔴 `错误` 事件在主事件消息之后包含由换行符分隔的完整错误消息。
{% endhint %}

预览由可观察对象发出的事件 `监控` :

<table data-full-width="true"><thead><tr><th width="125">动作类型</th><th width="450">事件消息</th><th>描述</th></tr></thead><tbody><tr><td>🟢 <code>更新</code> </td><td><code>健康</code></td><td>所有系统正常。</td></tr><tr><td>🟢 <code>更新</code> </td><td><code>不健康</code></td><td>意外问题。</td></tr><tr><td>🔴 <code>错误</code></td><td><code>获取监控失败</code></td><td>配置错误或意外问题。</td></tr></tbody></table>

预览由可观察对象发出的事件 `回填`:

<table data-full-width="true"><thead><tr><th width="125">动作类型</th><th width="450">事件消息</th><th>描述</th></tr></thead><tbody><tr><td>🟢 <code>更新</code> </td><td><code>已创建 [{backfill}]</code></td><td>回填创建成功。</td></tr><tr><td>🔴 <code>错误</code></td><td><code>创建失败</code></td><td>回填出现意外问题。请检查服务状态。</td></tr><tr><td>🔴 <code>错误</code></td><td><code>当前已达到最大容量</code></td><td>无法在目标队伍人数之外添加回填。</td></tr><tr><td>🔵 <code>通知</code></td><td><code>轮询 [{consecutive}/{maximum}]</code></td><td>轮询失败，正在自动重试。</td></tr><tr><td>🟢 <code>更新</code> </td><td><code>已分配 [{backfill}]</code></td><td>票据分配到回填成功。</td></tr><tr><td>🔵 <code>通知</code></td><td><code>轮询已停止</code></td><td>轮询已按处理器请求停止。</td></tr><tr><td>🔵 <code>通知</code></td><td><code>轮询失败（未找到）[{backfill}]</code></td><td>未找到，正在移除引用。回填很可能已过期。</td></tr><tr><td>🔴 <code>错误</code></td><td><code>轮询失败（已达到最大重试次数）[{backfill}]</code></td><td>已用尽重试次数，正在放弃回填。</td></tr><tr><td>🔴 <code>错误</code></td><td><code>轮询失败 [{backfill}]</code></td><td>意外问题，正在移除引用。</td></tr><tr><td>🔵 <code>通知</code></td><td><code>已放弃 [{backfill}]</code></td><td>回填已放弃，正在移除引用。</td></tr><tr><td>🔵 <code>通知</code></td><td><code>放弃失败（未找到）[{backfill}]</code></td><td>服务器无法找到要删除的回填，可能已过期。</td></tr><tr><td>🟡 <code>警告</code></td><td><code>放弃失败 [{backfill}]</code></td><td>放弃失败，正在移除引用。</td></tr><tr><td>🟢 <code>更新</code> </td><td><code>已移除 [{backfill}]</code></td><td>回填引用已移除。若未停止，回填将自动被替换。</td></tr><tr><td>🟡 <code>警告</code></td><td><code>移除失败（未找到）[{backfill}]</code></td><td>未找到回填引用，可能是重复调用。</td></tr></tbody></table>

[^1]: 数据传输对象

[^2]: [互联网服务提供商](https://en.wikipedia.org/wiki/Internet_service_provider)

[^3]: 尤其是中国或俄罗斯
