> 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/server-browser.md).

# 服务器浏览器

使用 Edgegap 可选的入门套件 SDK，为你的 Unity 游戏添加服务器浏览器，让玩家从列表中查找并加入在线会话。

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

## 💡 功能

通过安装我们的 SDK，获取预构建的自动化功能：

{% columns %}
{% column %}

* 完整示例
* 生命周期管理
* 容量管理
  {% 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/fu-wu-qi-liu-lan-qi.md) 相关概念，以及一个正在运行的 Server Browser。

{% hint style="success" %}
**我们强烈建议导入我们的自动分配示例** ，以便在阅读本文档时跟随代码。您可以在以下位置进行： `Unity Package Manager > Edgegap SDK > Samples` .
{% endhint %}

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

### 概述

我们的 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 %}

此包包含：

* 运行时文件 - 将被编译并打包到您的客户端和服务器构建中：
  * 特定服务实用工具：
    * [#server-agent](#server-agent "mention") - 一个完整的服务器集成，可供复用/扩展。
    * [#client-agent](#client-agent "mention") - 一个完整的客户端集成，可供复用/扩展。
    * API 函数 - 端点定义、错误处理和日志自动化。
    * 过滤编译器 - 用于构建过滤查询的强类型工具。
  * 特定服务 DTO[^1] - 用于 Server Browser API 的类型化数据容器。
  * 共享实用工具 - 日志、HTTP、ping、可观察对象等……
  * 共享 DTO[^1] - 由多个 Edgegap 服务用于传递数据。
* 示例文件 - 仅在导入到您的项目时才会打包并编译：
  * [#auto-assign](#auto-assign "mention") - 带有自动分配预订的示例处理器，
  * [#custom-search](#custom-search "mention") - 带有手动实例选择的示例处理器。

### 服务器代理

**服务器生命周期和容量管理** 由服务器代理执行。

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

* `onMonitorUpdate`  回调 - 观察服务健康状态变化。
* `onInstanceUpdate`  回调 - 观察并响应实例和槽位变化。
* `onConfirmationsUpdate`  回调 - 观察并响应联邦认证。

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

从此处开始，代理的处理器应接管并调用代理函数：

* `DiscoverInstance`  用于创建初始服务器实例和槽位并启动心跳。
* `DeleteInstance`  在比赛结束后 / 以防止新玩家加入。
* `ConfirmReservation`  当玩家加入时，用于验证其身份和槽位分配。
* `UpdateSlot`  用于更新槽位容量（玩家加入/放弃时）或修改元数据。
* `UpdateInstance`  用于修改实例元数据。
* `状态`  用于验证 Server Browser 服务健康状况。

{% hint style="success" %}
确认以及槽位/实例更新默认会 **排队并批量执行** （心跳模式）以最大化可扩展性。在开发测试期间为了更快迭代，请使用贪婪模式。
{% endhint %}

{% hint style="warning" %}
**更新元数据时，必须定义所有索引。** 要取消未编入索引的键，只需省略它们。
{% endhint %}

代理会自动维持心跳，以在运行时保持服务器可被发现。如果代理连续若干次心跳都无法到达您的 server browser（可配置）：

* 少于最大值 - 实例将自动重新发现，
* 超过最大值 - 实例将自动删除。

当建立新的玩家连接时，玩家应使用您的网络代码将其预订 ID（第三方玩家 ID）发送到游戏服务器，以执行预订确认。

一旦 `onConfirmationsUpdate`  触发，处理器必须执行额外操作：

* 调用 `UpdateSlot`  以减少任何具有已确认预订的槽位的可用座位数，
* 使用特定于网络代码的方法接受或拒绝连接。

当玩家放弃游戏时，处理器应增加该槽位的可用座位数。

{% hint style="info" %}
在意外崩溃的情况下，允许玩家在放弃前有一小段时间重新连接。
{% endhint %}

### 客户端代理

**实例搜索、分页、过滤和预订** 由客户端代理执行。

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

* `onMonitorUpdate`  回调 - 观察服务健康状态变化。
* `onInstancesUpdate`  回调 - 观察并响应实例列表变化。

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

从此处开始，代理的处理器应接管并调用代理函数：

* `ReserveSeats`  用于为特定实例/槽位或自动分配创建容量预订。
* `ListInstances`  用于按特定过滤条件、排序、游标和页面大小列出实例。
* `GetNextPage`  用于使用当前参数（过滤条件等）获取更多实例。
* `RefreshList`  用于清除缓存并重新加载第一页，或使用特定游标刷新。
* `GetInstanceDetails`  用于获取特定实例的实例元数据和槽位信息。
* `状态`  用于验证 Server Browser 服务健康状况。

当建立新的玩家连接时，玩家应使用您的网络代码将其预订 ID（第三方玩家 ID）发送到游戏服务器，以执行预订确认。

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

## 🧪 示例

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

### 自动分配

使用自动分配的预订，客户端只需指定策略名称。Server browser 会自动选择匹配策略过滤条件且有足够座位的实例和槽位。

### 自定义搜索

包含完整实现，演示如何搜索实例和槽位、挂接 UI 元素，并让玩家手动选择要预订容量的位置。

## ⚙️ 自定义

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

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

⚠️ 代理 - 自行承担风险修改生命周期和容量管理，

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

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

{% hint style="warning" %}
在进行自定义之前，请务必熟悉 [Server Browser 深入概念](https://docs.edgegap.com/zh/learn/fu-wu-qi-liu-lan-qi.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>请求超时时间已限制为心跳 [{timeout}]</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><a href="https://docs.edgegap.com/zh/learn/fu-wu-qi-liu-lan-qi.md#discover-instance">实例发现</a> 已成功完成。若实例因临时情况失去连接并重新被发现，可能会触发。</td></tr><tr><td>🔴 <code>错误</code></td><td><code>发现重复</code></td><td>具有此请求 ID 的实例已被发现。</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>心跳失败，服务器无法连接到 Server Browser。</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>槽位更新已排队 [{slot}]</code></td><td>已将槽位更新排队到下一批次（心跳/贪婪）。</td></tr><tr><td>🟢 <code>更新</code> </td><td><code>槽位已更新 [{slot}]</code></td><td>槽位座位容量和/或元数据已成功更新。</td></tr><tr><td>🟡 <code>警告</code></td><td><code>代理限制了并发槽位更新</code></td><td>已阻止并发更新尝试（竞态条件）。</td></tr><tr><td>🔴 <code>错误</code></td><td><code>槽位更新失败（未找到）[{slot}]</code></td><td>此实例尚未定义该名称的槽位。</td></tr><tr><td>🔴 <code>错误</code></td><td><code>槽位更新失败（座位不足）[{slot}]</code></td><td>槽位更新尝试将可用座位数减少到零以下。</td></tr><tr><td>🔴 <code>错误</code></td><td><code>槽位更新失败，已排队重试 [{slot}]</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>已排队 [{player}]</code></td><td>已为下一批次排队确认（心跳/贪婪）。</td></tr><tr><td>🟡 <code>警告</code></td><td><code>重复 [{player}]</code></td><td>已阻止重复确认尝试（已在队列中）。</td></tr><tr><td>🟢 <code>更新</code> </td><td><code>已确认</code></td><td>已确认各个槽位的预订，其中还包括已过期和未知的玩家 ID，由处理器来处理（接受/踢出）。</td></tr><tr><td>🔴 <code>错误</code></td><td><code>失败</code></td><td>确认过程中出现意外问题。请检查服务状态。</td></tr></tbody></table>

### 客户端事件

客户端代理发出事件（动作），供父级处理器观察和消费。

{% 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>座位已预订</code></td><td>座位预订成功。</td></tr><tr><td>🔴 <code>错误</code></td><td><code>座位预订失败（未找到）</code></td><td><a data-mention href="#auto-assign">#auto-assign</a> - 未找到策略名称（已删除或未激活）。<br><a data-mention href="#custom-search">#custom-search</a> - 未找到实例或槽位。</td></tr><tr><td>🔴 <code>错误</code></td><td><code>座位预订失败（已达容量上限）</code></td><td><a data-mention href="#auto-assign">#auto-assign</a> - 策略已达到最大容量。<br><a data-mention href="#custom-search">#custom-search</a> - 槽位已达到最大容量。</td></tr><tr><td>🔴 <code>错误</code></td><td><code>座位预订失败</code></td><td>座位预订失败，可能是策略、请求 ID 或槽位 ID 无效。</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>实例未缓存，已置于前面</code></td><td>已获取当前列表之外实例的详情。</td></tr><tr><td>🔴 <code>错误</code></td><td><code>获取实例详情失败</code></td><td>获取详情失败，可能由于请求 ID 无效。</td></tr><tr><td>🟢 <code>更新</code> </td><td><code>缓存已删除</code></td><td>已清除缓存的实例列表和详情。</td></tr></tbody></table>

[^1]: 数据传输对象
