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

# 匹配

使用 Edgegap 可选的 JavaScript SDK 为你的浏览器游戏添加匹配功能，随着多人游戏项目的发展，它可随时扩展和自定义。

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

## 💡 功能

{% columns %}
{% column %}

* 完整示例
* Promise 和异步循环
* 票证、组、队伍
  {% endcolumn %}

{% column width="33.33333333333333%" %}

* 匹配变量
* 类型定义（TypeScript）
* 补填自动化
  {% endcolumn %}

{% column width="33.33333333333333%" %}

* 浏览器、Node.js、Bun、Deno
* 零依赖
* 自动重试
  {% endcolumn %}
  {% endcolumns %}

## ✔️ 准备工作

JavaScript SDK 包含用于 Deployments 和 Matchmaking 的可选集成工具。该包官方支持所有现代浏览器、Node.js 22 及更新版本、Bun 和 Deno。

{% hint style="info" %}
**JavaScript SDK 的最新版本是 `1.1.0`**。本文档中的所有示例均已更新。
{% endhint %}

{% hint style="success" %}
该软件包在免费套餐条款与条件下提供，100% 免费。
{% endhint %}

#### 要求

<details>

<summary>在 Matchmaker 配置中允许你的游戏 Web 来源</summary>

浏览器只会从其来源被列入 `allowed_cors_origins` 的页面调用你的 Matchmaker。条目按完整来源匹配，包括协议和端口：

* `https://*.my-game.com` 匹配所有通过 HTTPS 的子域名，
* `localhost` 不匹配任何内容，本地开发服务器请完整列出，例如 `http://localhost:5173` .

</details>

<details>

<summary>为你的游戏服务器的 WebSocket 端口启用 TLS 升级</summary>

将你的 [App Version 端口](https://docs.edgegap.com/zh/learn/bian-pai/application-and-versions.md#port-mapping) 协议设置为 `WS` 并启用 **TLS Upgrade**，这样浏览器就可以使用安全的 WebSocket（`wss://`).

</details>

#### 安装

使用你喜欢的包管理器从 npm 安装该包：

{% tabs %}
{% tab title="npm" %}
{% code collapsedlinecount="10" %}

```bash
npm install @edgegap/sdk
```

{% endcode %}
{% endtab %}

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

```bash
pnpm add @edgegap/sdk
```

{% endcode %}
{% endtab %}

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

```bash
yarn add @edgegap/sdk
```

{% endcode %}
{% endtab %}

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

```bash
bun add @edgegap/sdk
```

{% endcode %}
{% endtab %}

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

```bash
deno add npm:@edgegap/sdk
```

{% endcode %}
{% endtab %}

{% tab title="CDN（无需打包器）" %}
在没有打包器的 HTML 游戏中加载浏览器构建。所有内容都通过以下全局对象暴露： `Edgegap` 全局对象，Matchmaking 位于 `Edgegap.matchmaking`:

{% code collapsedlinecount="10" %}

```html
<script src="https://cdn.jsdelivr.net/npm/@edgegap/sdk@1.1.0/dist/browser/edgegap.iife.js"></script>
```

{% endcode %}

或者将其作为 ES 模块导入：

{% code collapsedlinecount="10" %}

```html
<script type="module">
  import { matchmaking, getConnectionUrl } from 'https://cdn.jsdelivr.net/npm/@edgegap/sdk@1.1.0/dist/browser/edgegap.js'
</script>
```

{% endcode %}
{% endtab %}
{% endtabs %}

该包有两个入口点：

* `@edgegap/sdk/matchmaking` :
  * `GroupAgent`, `ServerAgent`, `MatchEnvironment`, `MatchmakingError`, `Api` .
* `@edgegap/sdk` - 共享工具：
  * `getConnectionUrl`, `DeploymentEnvironment` .
  * `Observable`, `Logger`，以及其他 HTTP 辅助函数。

#### 已验证来源

此包仅在 npm 上以 [`@edgegap/sdk`](https://www.npmjs.com/package/@edgegap/sdk)形式发布，源代码位于 [GitHub](https://github.com/edgegap/sdk-js-sessions-matchmaker-server-browser)。像 jsDelivr 和 unpkg 这样的 CDN 会镜像 npm 包。不要信任未经验证的来源，位于 `@edgegap` 作用域之外、名称相似的包与 Edgegap 无关！

{% hint style="success" %}
**每个版本都由 GitHub Actions 使用** [**npm provenance**](https://docs.npmjs.com/generating-provenance-statements)发布，并将包与构建它的提交关联起来。请使用 `npm audit signatures` .
{% endhint %}

{% hint style="info" %}
来验证你安装的包。 [从 CDN 加载时，请使用](https://developer.mozilla.org/docs/Web/Security/Subresource_Integrity) 子资源完整性
{% endhint %}

### 更新包

使用你的包管理器更新到最新版本：

{% code collapsedlinecount="10" %}

```bash
npm install @edgegap/sdk@latest
```

{% endcode %}

从 CDN 加载时，请更改 URL 中的版本并重新生成你的完整性哈希。

{% hint style="info" %}
某些版本可能包含破坏性更改。这会通过新的 MAJOR 版本来标识。
{% endhint %}

## 🍀 快速开始

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

{% hint style="success" %}
**我们强烈建议你克隆我们的** [**Three.js Minigames**](#three.js-minigames) **示例** ，以便在阅读本文档时跟着代码一起操作。
{% endhint %}

### 概述

我们的 SDK 大量使用 [观察者](https://refactoring.guru/design-patterns/observer) 编程模式，并允许你通过回调、 [Promise](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)，或者 [异步迭代](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/for-await...of) 来消费变更——取决于哪种方式更适合你的游戏循环。

{% hint style="info" %}
该包集成了 [Matchmaking](https://docs.edgegap.com/zh/learn/pi-pei-xi-tong.md) 和 [Deployments](https://docs.edgegap.com/zh/learn/bian-pai/deployments.md) 工具。你可以自由复用任何代码，用于你自己的定制分支和集成。
{% endhint %}

该包包含：

* 服务专用工具：
  * [#group-agent](#group-agent "mention") - 可完整复用/扩展的浏览器客户端集成。
  * [#server-agent](#server-agent "mention") - 可完整复用/扩展的游戏服务器补填集成。
  * `MatchEnvironment` - 类型化的 [Matchmaking 变量](https://docs.edgegap.com/zh/learn/pi-pei-xi-tong/matchmaker-in-depth.md#injected-environment-variables) ，供你的游戏服务器使用。
  * `Api` - 端点定义、错误处理和重试自动化。
* 服务专用类型 - 与 Matchmaking API JSON 完全匹配的请求和响应类型。
* 共享工具 - 连接 URL、部署变量、日志、HTTP、可观察对象等……

### 组代理

**票证管理、主机获取和信标发现** 由 Group Agent 处理。

实例化后，代理的 **处理器（你的游戏代码）必须初始化代理** 并可选地提供：

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

初始化后，此代理会自动提供校验并连接日志观察器，最后只需一次调用监控 API 端点以表示服务健康状态。

期望代理的处理器从此处接管并调用代理函数：

* `beacons` 以获取可用 [Ping 信标](https://docs.edgegap.com/zh/learn/bian-pai/ping-beacons.md).
* `measureBeaconsRoundTripTime` 以对给定的一组信标提供 ping 测量。
* `createGroup` 用于由大厅房主创建一个可加入的组，好友可以被邀请加入。
* `joinGroup` 用于通过第三方大厅/后端发送的组 ID 加入现有组。
* `setReady` 用于将组所有者和成员标记为就绪，并开始搜索匹配。
* `nextAssignment` 用于在组开始搜索后等待主机分配。
* `resumeMatchmaking` 用于加载已保存的组，并在页面重新加载时继续搜索。
* `stopMatchmaking` 用于删除票证（如果尚未匹配）并离开队列。
* `dispose` 用于清除所有计时器、中止请求并移除订阅者。

这里演示了三种不同的并发模式，选择你喜欢的即可：

{% tabs %}
{% tab title="Promise" %}
{% code collapsedlinecount="10" %}

```javascript
import { getConnectionUrl } from '@edgegap/sdk'
import { GroupAgent, MatchmakingError } from '@edgegap/sdk/matchmaking'

const agent = new GroupAgent({ baseUrl: '<matchmaker url>', authToken: '<matchmaker auth token>' })
agent.initialize()

const { beacons } = await agent.beacons()
const latencies = await agent.measureBeaconsRoundTripTime(beacons)

agent.createGroup({ profile: 'simple-example', attributes: { beacons: latencies }, is_ready: true }, true)

try {
  const assignment = await agent.nextAssignment()
  connect(getConnectionUrl(assignment, 'gameport'), agent.group.current.ticket_id)
} catch (error) {
  if (!(error instanceof MatchmakingError)) throw error
  showRetryButton(error.message)
}
```

{% endcode %}
{% endtab %}

{% tab title="异步循环" %}
{% code collapsedlinecount="10" %}

```javascript
import { getConnectionUrl, ObservableActionType } from '@edgegap/sdk'
import { GroupAgent } from '@edgegap/sdk/matchmaking'

const agent = new GroupAgent({ baseUrl: '<matchmaker url>', authToken: '<matchmaker auth token>' })
agent.initialize()

const { beacons } = await agent.beacons()
const latencies = await agent.measureBeaconsRoundTripTime(beacons)

agent.createGroup({ profile: 'simple-example', attributes: { beacons: latencies }, is_ready: true }, true)

for await (const { type, message, event, current } of agent.group) {
  if (type === ObservableActionType.Error) {
    showRetryButton(message)
    break
  }
  if (event.code !== 'updated') continue
  showStatus(current.status)
  if (current.status === 'CANCELLED') {
    showRetryButton(message)
    break
  }
  if (current.status !== 'HOST_ASSIGNED') continue
  connect(getConnectionUrl(current.assignment, 'gameport'), current.ticket_id)
  break
}
```

{% endcode %}
{% endtab %}

{% tab title="回调" %}
{% code collapsedlinecount="10" %}

```javascript
import { getConnectionUrl, ObservableActionType } from '@edgegap/sdk'
import { GroupAgent } from '@edgegap/sdk/matchmaking'

const agent = new GroupAgent({ baseUrl: '<matchmaker url>', authToken: '<matchmaker auth token>' })
agent.initialize(
  (_monitor, _type, message) => console.log('matchmaker', message),
  (group, type, message, event) => {
    if (type === ObservableActionType.Error) return showRetryButton(message)
    if (event.code !== 'updated') return
    showStatus(group.current.status)
    if (group.current.status === 'CANCELLED') return showRetryButton(message)
    if (group.current.status === 'HOST_ASSIGNED')
      connect(getConnectionUrl(group.current.assignment, 'gameport'), group.current.ticket_id)
  },
)

const { beacons } = await agent.beacons()
const latencies = await agent.measureBeaconsRoundTripTime(beacons)

agent.createGroup({ profile: 'simple-example', attributes: { beacons: latencies }, is_ready: true }, true)
```

{% endcode %}
{% endtab %}
{% endtabs %}

`profile` 和 `attributes` 必须与 Matchmaker 配置中的一个 profile 匹配， `gameport` 是你 App Version 中的端口名称。 `getConnectionUrl` 返回一个 `wss://` 用于 WebSocket 端口的 URL。

{% hint style="warning" %}
**浏览器无法发送 Edgegap 信标所响应的 ICMP、UDP 或 TCP ping，**&#x56E0;此 `measureBeaconsRoundTripTime` 默认会为每个信标报告 `0` 。你可以在代理选项中传入自己的 `ping` 实现，以用其他方式测量延迟。
{% endhint %}

当建立新的玩家连接时，玩家应使用你的网络代码将其票证 ID 发送到游戏服务器，以将连接与 [Matchmaking 变量](https://docs.edgegap.com/zh/learn/pi-pei-xi-tong/matchmaker-in-depth.md#injected-environment-variables)关联。此时你的游戏服务器可能仍在初始化，因此 **玩家必须多次重试连接**:

{% code collapsedlinecount="10" %}

```javascript
const connect = (url, ticketId, attempts = 10) => {
  const socket = new WebSocket(url)
  let opened = false
  socket.onopen = () => {
    opened = true
    socket.send(JSON.stringify({ ticketId }))
  }
  socket.onclose = () => !opened && attempts > 1 && setTimeout(() => connect(url, ticketId, attempts - 1), 1000)
}
```

{% endcode %}

{% hint style="success" %}
将连接详情保存在客户端或游戏后端中，以便在意外崩溃时重新连接。参见 [#resume-after-reload](#resume-after-reload "mention").
{% endhint %}

### Server Agent

Server Agent 执行 **补填创建、票证分配检测、补填放弃和移除检测。它还会跟踪并重新创建已过期、连接宽限期已结束或被放弃的补填——以达到期望的队伍规模**.

Server Agent 会跟踪当前已连接的玩家，并自动将他们的票证包含在新的补填中，以确保被补填的玩家会根据所配置的 profile 规则进行匹配。

实例化后，代理的 **处理器（你的服务器代码）必须初始化代理** 并提供：

* `tickets` - 已匹配到此服务器的玩家，来自 [Matchmaking 变量](https://docs.edgegap.com/zh/learn/pi-pei-xi-tong/matchmaker-in-depth.md#injected-environment-variables).
* `onMonitorUpdate` 回调 - 观察服务健康状态变化。
* `onBackfillUpdate` 回调 - 观察并响应补填变化。

初始化后，此代理会自动提供校验并连接日志观察器，最后只需一次调用监控 API 端点以表示服务健康状态。

期望服务器处理器从此处接管并调用代理函数：

* `addBackfills` 用于创建补填，直到已分配玩家和开放补填达到目标队伍规模。
* `playerConnected` 用于防止替换那些从未连接的初始玩家或补填玩家。
  * 返回该玩家的票证，或者 `null` 如果该票证未分配到此服务器——拒绝此类连接。
* `abandonPlayer` 用于表示某个已连接玩家离开了服务器并需要被替换。
* `abandonAllBackfills` 用于立即停止服务器补填并删除补填。
  * 在停止服务器之前应调用此方法。此时已分配的玩家需要重新加入匹配，因为服务器正在关闭。
  * 在此调用时已分配的补填仍可在配置的宽限期内连接。
* `abandonBackfill` 用于强制放弃特定补填（自定义处理器实现）。
* `dispose` 用于清除计时器、中止请求并移除订阅者。

{% code collapsedlinecount="10" %}

```javascript
import { WebSocketServer } from 'ws'
import { DeploymentEnvironment } from '@edgegap/sdk'
import { MatchEnvironment, ServerAgent } from '@edgegap/sdk/matchmaking'

const deployment = DeploymentEnvironment.fromEnv(process.env)
const match = MatchEnvironment.fromEnv(process.env)

const agent = new ServerAgent({
  baseUrl: process.env.MATCHMAKER_URL,
  authToken: process.env.MATCHMAKER_TOKEN,
  profile: match.matchProfile,
  targetTeamSize: 4,
  attributes: {
    assignment: {
      request_id: deployment.requestId,
      fqdn: deployment.fqdn,
      public_ip: deployment.publicIp,
      ports: deployment.portMapping,
      location: deployment.location,
    },
  },
})

agent.initialize(
  match.tickets,
  (_monitor, _type, message) => console.log('matchmaker', message),
  (_backfills, _type, _message, event) => {
    if (event.code === 'assigned') console.log(`ticket ${event.ticketId} is joining`)
  },
)
agent.addBackfills()

const wss = new WebSocketServer({ port: 7777 })

wss.on('connection', (socket) => {
  socket.once('message', (data) => {
    const { ticketId } = JSON.parse(data.toString())
    if (!agent.playerConnected(ticketId)) return socket.close(4001, 'unknown ticket')
    socket.once('close', () => agent.abandonPlayer(ticketId))
  })
})

process.once('SIGTERM', () => agent.abandonAllBackfills(() => process.exit(0)))
```

{% endcode %}

{% hint style="danger" %}
**从环境变量中加载服务器令牌**，例如使用 [App Version Variables](https://docs.edgegap.com/zh/learn/bian-pai/application-and-versions.md#injected-variables)。游戏服务器使用的令牌绝不应包含在浏览器包中。
{% endhint %}

### 匹配变量

阅读 [Matchmaking 变量](https://docs.edgegap.com/zh/learn/pi-pei-xi-tong/matchmaker-in-depth.md#injected-environment-variables) ，在你的游戏服务器中无需调用任何 API 即可验证连接的玩家并分配队伍：

{% code collapsedlinecount="10" %}

```javascript
import { WebSocketServer } from 'ws'
import { MatchEnvironment } from '@edgegap/sdk/matchmaking'

const match = MatchEnvironment.fromEnv(process.env)
const wss = new WebSocketServer({ port: 7777 })

wss.on('connection', (socket) => {
  socket.once('message', (data) => {
    const { ticketId } = JSON.parse(data.toString())
    const ticket = match.tickets[ticketId]
    if (!ticket) return socket.close(4001, 'unknown ticket')
    console.log(`player joined team ${ticket.team_id} in match ${match.matchId}`)
  })
})
```

{% endcode %}

`match` 包含 `matchProfile`, `matchId`, `tickets` （按票证 ID）， `组`, `队伍`以及匹配到的 `相等性` 和 `交集` 值。解析从不抛出异常，因此相同服务器也可在本地运行。

通过 补填 加入的玩家不会列在 `match.tickets`中，因此使用 Server Agent 的服务器会通过 `agent.playerConnected` 来验证连接的玩家。

## 🧪 示例

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

### [Three.js Minigames](#three.js-minigames)

包含五个浏览器游戏，完整实现玩家生命周期——组、主机分配获取以及连接重试。演示如何在服务器端读取注入的匹配变量，从 2 人队伍配置中将玩家分配到队伍，并在匹配结束时停止部署。

添加新的匹配配置和游戏服务器，即可轻松扩展此示例以适配你的游戏。

### 组队

与一组好友一起加入匹配队列，要求所有玩家在开始搜索前确认。群组创建者创建群组，并通过你的大厅或后端共享其 ID：

{% code collapsedlinecount="10" %}

```javascript
const attributes = { beacons: latencies }

// 在群组创建者的设备上
agent.group.subscribe((group, _type, _message, event) => {
  if (event.code === 'created') shareWithFriends(group.current.group_id)
})
agent.createGroup({ profile: 'simple-example', attributes, is_ready: false }, true)

// 在每个好友的设备上，一旦他们收到群组 ID
agent.joinGroup({ profile: 'simple-example', attributes, is_ready: false }, groupId, true)

// 在每台设备上，当玩家准备好时
agent.setReady(true)
const assignment = await agent.nextAssignment()
```

{% endcode %}

### 重新加载后恢复

当群组发生变化时保存它，并在页面再次加载时恢复搜索（或重新连接）：

{% code collapsedlinecount="10" %}

```javascript
agent.initialize(undefined, (group) => {
  if (group.current) localStorage.setItem('edgegap-group', JSON.stringify(group.current))
  else if (group.previous?.status !== 'HOST_ASSIGNED') localStorage.removeItem('edgegap-group')
})

const saved = JSON.parse(localStorage.getItem('edgegap-group'))
if (saved?.status === 'HOST_ASSIGNED') {
  connect(getConnectionUrl(saved.assignment, 'gameport'), saved.ticket_id)
} else if (saved) {
  agent.resumeMatchmaking(saved)
  connect(getConnectionUrl(await agent.nextAssignment(), 'gameport'), saved.ticket_id)
}
```

{% endcode %}

使用以下命令移除已保存的群组 `localStorage.removeItem('edgegap-group')` 在对局结束后，这样玩家就不会重新连接到已结束的对局。

### 补位

重复利用服务器容量并向正在进行的部署中添加玩家。设置目标队伍人数并等待玩家加入。包括自动连接宽限期和重新创建已过期的补位，参见 [#server-agent](#server-agent "mention").

为多队伍或不对称队伍编排自定义你的服务器处理器。

## ⚙️ 自定义

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

✅ Handler - 安全地连接 UI 观察者并进行少量添加或修改，

⚠️ Agent - 分叉源代码并修改玩家生命周期管理，风险自负，

⚠️ API - 从头编写你自己的集成，使用 `Api` 以及精选的实用工具。

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

{% 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 %}

### 客户端事件

Group Agent 会发出带类型的事件，供处理器观察和消费。

{% hint style="success" %}
通过访问 `.current` 和 `.previous` 任意可观察对象的，并且 **根据 `event.code`** 因为事件消息可能会在不同版本之间发生变化。🔴 `错误` 事件还会将完整错误信息存储在 `.error` .
{% endhint %}

预览由 observable 发出的事件 `监控` :

<table data-full-width="true"><thead><tr><th width="125">操作类型</th><th width="200">事件代码</th><th width="300">事件参数</th><th>描述</th></tr></thead><tbody><tr><td>🟢 <code>更新</code></td><td><code>正常</code></td><td>-</td><td>所有系统正常。</td></tr><tr><td>🟢 <code>更新</code></td><td><code>异常</code></td><td>-</td><td>意外问题。</td></tr><tr><td>🔴 <code>错误</code></td><td><code>monitor_failed</code></td><td><code>detail</code></td><td>配置错误或意外问题。</td></tr><tr><td>🔴 <code>错误</code></td><td><code>beacons_failed</code></td><td><code>detail</code></td><td>意外问题。</td></tr></tbody></table>

预览由 observable 发出的事件 `群组` :

<table data-full-width="true"><thead><tr><th width="125">操作类型</th><th width="200">事件代码</th><th width="300">事件参数</th><th>描述</th></tr></thead><tbody><tr><td>🟢 <code>更新</code></td><td><code>已创建</code></td><td>-</td><td>群组创建成功。</td></tr><tr><td>🔴 <code>错误</code></td><td><code>create_failed</code></td><td><code>detail</code></td><td>创建群组失败。</td></tr><tr><td>🟢 <code>更新</code></td><td><code>已加入</code></td><td>-</td><td>群组加入成功。</td></tr><tr><td>🔴 <code>错误</code></td><td><code>join_failed</code></td><td><code>detail</code></td><td>加入群组失败。</td></tr><tr><td>🟢 <code>更新</code></td><td><code>已恢复</code></td><td>-</td><td>群组恢复成功。</td></tr><tr><td>🔴 <code>错误</code></td><td><code>not_found</code></td><td><code>detail?</code></td><td>不是群组成员，或者群组已过期。</td></tr><tr><td>🔴 <code>错误</code></td><td><code>冲突</code></td><td>-</td><td>请先放弃当前群组，再尝试创建/加入新群组，或者传入 <code>abandon: true</code>.</td></tr><tr><td>🟢 <code>更新</code></td><td><code>member_updated</code></td><td><code>isReady</code></td><td>成员已使用新的 Ready 值更新。</td></tr><tr><td>🟡 <code>警告</code></td><td><code>member_update_failed</code></td><td>-</td><td>群组开始搜索匹配后，无法取消准备。</td></tr><tr><td>🔴 <code>错误</code></td><td><code>update_failed</code></td><td><code>detail</code></td><td>更新群组成员失败。</td></tr><tr><td>🔵 <code>日志</code></td><td><code>轮询</code></td><td><code>尝试</code>, <code>maxAttempts</code></td><td>代理已开始轮询群组状态。仅在以下情况下发出 <code>logPollingUpdates: true</code>.</td></tr><tr><td>🔵 <code>日志</code></td><td><code>polling_stopped</code></td><td>-</td><td>代理已停止轮询群组状态。仅在以下情况下发出 <code>logPollingUpdates: true</code>.</td></tr><tr><td>🔴 <code>错误</code></td><td><code>polling_failed</code></td><td><code>reason: 'max_retries'</code>, <code>detail</code></td><td>代理已用尽连续轮询重试次数上限。请检查服务状态。</td></tr><tr><td>🔴 <code>错误</code></td><td><code>polling_failed</code></td><td><code>reason: 'error'</code>, <code>detail</code></td><td>代理在轮询时收到了不可重试的错误。请检查服务状态。</td></tr><tr><td>🟢 <code>更新</code></td><td><code>已更新</code></td><td><code>状态</code></td><td>在轮询过程中检测到群组状态变化。</td></tr><tr><td>🟢 <code>更新</code></td><td><code>已放弃</code></td><td>-</td><td>票据删除成功。</td></tr><tr><td>🟢 <code>更新</code></td><td><code>abandon_failed</code></td><td><code>reason: 'not_found'</code></td><td>代理找不到要删除的群组，可能已过期。</td></tr><tr><td>🟡 <code>警告</code></td><td><code>abandon_failed</code></td><td><code>reason: 'match_found'</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>abandon_failed</code></td><td><code>reason: 'error'</code>, <code>detail</code></td><td>删除群组或成员关系失败。</td></tr><tr><td>🟡 <code>警告</code></td><td><code>restart_skipped</code></td><td>-</td><td>群组已经匹配，放弃后的后续操作已跳过。</td></tr><tr><td>🟢 <code>更新</code></td><td><code>已移除</code></td><td>-</td><td>群组已结束或已过期，本地引用已删除。</td></tr></tbody></table>

### 服务器事件

Server Agent 会发出带类型的事件，供处理器观察和消费。Server Agent 仅用于 [#backfill](#backfill "mention").

{% hint style="info" %}
当前已分配的票据可随时从 Server Agent 属性中读取 `assignments` ，以及来自 `connectedAt` .
{% endhint %}

{% hint style="success" %}
通过访问 `.current` 和 `.previous` 任意可观察对象的，并且 **根据 `event.code`** 因为事件消息可能会在不同版本之间发生变化。🔴 `错误` 事件还会将完整错误信息存储在 `.error` .
{% endhint %}

预览由 observable 发出的事件 `监控` :

<table data-full-width="true"><thead><tr><th width="125">操作类型</th><th width="200">事件代码</th><th width="300">事件参数</th><th>描述</th></tr></thead><tbody><tr><td>🟢 <code>更新</code></td><td><code>正常</code></td><td>-</td><td>所有系统正常。</td></tr><tr><td>🟢 <code>更新</code></td><td><code>异常</code></td><td>-</td><td>意外问题。</td></tr><tr><td>🔴 <code>错误</code></td><td><code>monitor_failed</code></td><td><code>detail</code></td><td>配置错误或意外问题。</td></tr></tbody></table>

预览由 observable 发出的事件 `backfills` :

<table data-full-width="true"><thead><tr><th width="125">操作类型</th><th width="200">事件代码</th><th width="300">事件参数</th><th>描述</th></tr></thead><tbody><tr><td>🟢 <code>更新</code></td><td><code>已创建</code></td><td><code>backfillId</code></td><td>补位创建成功。</td></tr><tr><td>🔴 <code>错误</code></td><td><code>create_failed</code></td><td><code>detail</code></td><td>补位出现意外问题。请检查服务状态。</td></tr><tr><td>🔴 <code>错误</code></td><td><code>capacity_reached</code></td><td>-</td><td>服务器已满，未创建补位。</td></tr><tr><td>🔵 <code>日志</code></td><td><code>轮询</code></td><td><code>尝试</code>, <code>maxAttempts</code></td><td>代理已开始轮询补位。仅在以下情况下发出 <code>logPollingUpdates: true</code>.</td></tr><tr><td>🟢 <code>更新</code></td><td><code>已分配</code></td><td><code>backfillId</code>, <code>ticketId</code></td><td>已将票据分配给补位，成功。</td></tr><tr><td>🔵 <code>日志</code></td><td><code>polling_stopped</code></td><td>-</td><td>代理已停止轮询，已没有可轮询的补位。</td></tr><tr><td>🟡 <code>警告</code></td><td><code>polling_failed</code></td><td><code>backfillId</code>, <code>reason: 'not_found'</code></td><td>未找到，正在移除引用。补位很可能已过期。</td></tr><tr><td>🔴 <code>错误</code></td><td><code>polling_failed</code></td><td><code>backfillId</code>, <code>reason: 'max_retries'</code></td><td>重试耗尽，正在放弃所有补位。</td></tr><tr><td>🔴 <code>错误</code></td><td><code>polling_failed</code></td><td><code>backfillId</code>, <code>reason: 'error'</code>, <code>detail</code></td><td>出现意外问题，正在放弃并替换补位。</td></tr><tr><td>🔵 <code>日志</code></td><td><code>已放弃</code></td><td><code>backfillId</code></td><td>补位已放弃，正在移除引用。</td></tr><tr><td>🟡 <code>警告</code></td><td><code>abandon_failed</code></td><td><code>backfillId</code>, <code>reason: 'not_found'</code></td><td>未找到补位，可能已过期或为重复调用。</td></tr><tr><td>🟡 <code>警告</code></td><td><code>abandon_failed</code></td><td><code>backfillId</code>, <code>reason: 'error'</code>, <code>detail</code></td><td>放弃失败，正在移除引用。</td></tr><tr><td>🟢 <code>更新</code></td><td><code>已移除</code></td><td><code>backfillId</code></td><td>补位引用已移除。如果未停止，补位将自动替换。</td></tr><tr><td>🟡 <code>警告</code></td><td><code>remove_failed</code></td><td><code>backfillId</code></td><td>未找到补位引用，可能为重复调用。</td></tr></tbody></table>
