> 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/pi-pei.md).

# 匹配

此 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="success" %}
此插件依据免费版条款与条件，100% 免费提供。
{% 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="" %}

```
https://github.com/edgegap/edgegap-unity-sdk.git
```

{% endcode %}

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

#### 导入示例

此包包含多个示例，旨在单独使用（不要将示例组合在一起）。

#### 已验证来源

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

#### 更新包

在 Unity Package Manager 中导航到 Edgegap SDK，然后点击 `更新` .

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

{% hint style="info" %}
某些版本可能包含破坏性变更。这将由新的主版本号标明。
{% endhint %}

#### 更新到 v3

此更新包含许多新的 [服务器浏览器](/zh/unity/fu-wu-qi-liu-lan-qi.md) 工具和示例，改进了配对错误处理等。请查看 [发布说明](/zh/docs/release-notes.md) 以获取完整列表。

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

## 🍀 开始使用

本指南假定您已具备 [匹配](/zh/learn/pi-pei.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" %}
此包整合了这两者 [服务器浏览器](/zh/learn/fu-wu-qi-liu-lan-qi.md) 和 [匹配](/zh/learn/pi-pei.md)，它们可以一起使用，也可以单独使用。您可以自由重用任何脚本，用于您自己的定制分支和集成。
{% endhint %}

此软件包包含：

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

### 组客户端

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

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

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

初始化后，该客户端将自动提供校验并连接日志观察器，最后只需调用一次监控 API 端点即可上报服务健康状况。

从这一点开始，客户端的处理器应接管并调用客户端函数：

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

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

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

## 🧪 示例

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

### 简单示例

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

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

### 区域选择器

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

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

### 组队

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

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

## ⚙️ 自定义

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

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

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

⚠️ API - 使用精选工具从零开始编写您自己的集成。

处理器可以观察如下所述由 Server 和 Client 代理发出的任何事件。

{% hint style="warning" %}
请务必熟悉 [深入了解 Matchmaking](/zh/learn/pi-pei/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>轮询 [{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="/pages/6f9da0e6c31c7a483b63af1c186100316ca2f793#backfill-match">/pages/6f9da0e6c31c7a483b63af1c186100316ca2f793#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>

[^1]: 数据传输对象

[^2]: [Internet Service Provider](https://en.wikipedia.org/wiki/Internet_service_provider)

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