# 匹配

这个 SDK 是面向 Unity 用户的可选入门套件，之后可以扩展和自定义。

## 💡 功能

{% columns %}
{% column %}

* 完整示例
* Ping 自动化
* 票据、组、队伍
  {% endcolumn %}

{% column width="33.33333333333333%" %}

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

{% column width="33.33333333333333%" %}

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

## ✔️ 准备工作

## 🍀 开始使用

本指南假设你对以下内容有基本了解： [匹配](/zh/learn/pi-pei.md) 概念，并且已经运行着一个 Matchmaker。

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

### 客户端代理

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

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

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

一旦初始化完成，该代理将自动提供校验并挂接日志观察器，最后只需对监控 API 端点调用一次即可表明服务健康状态。

从这一点开始，代理的处理器应接管控制并调用代理函数：

* `信标`  以获取可用的列表 [Ping 信标](/zh/learn/bian-pai/ping-beacons.md),
* `MeasureBeaconsRoundTripTime`  以对给定的一组信标提供 ping 测量，
* `StartMatchmaking`  以创建票据并开始寻找匹配，
* `ResumeMatchmaking`  以加载先前创建的（缓存的）票据并继续搜索，
* `StopMatchmaking`  以删除票据（如果尚未匹配）并退出队列，
* `状态`  以验证 Server Browser 服务健康状态。

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

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

## 🧪 示例

通过示例快速上手，其中包括服务器端和客户端完整可运行的集成。

### 简单示例

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

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

### 区域选择器

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

查看我们的区域选择器示例，并从中获取灵感来实现你的匹配 UI。

## ⚙️ 自定义

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

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

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

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

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

{% hint style="warning" %}
在进行自定义之前，请确保熟悉 [深入理解匹配](/zh/learn/pi-pei/matchmaker-in-depth.md) 相关概念。
{% 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>轮询 [{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]: [互联网服务提供商](https://en.wikipedia.org/wiki/Internet_service_provider)

[^3]: 最典型的是中国或俄罗斯


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.edgegap.com/zh/unity/pi-pei.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.