# 匹配 快速上手匹配系统，并探索不同类型游戏的示例场景。 跟随此视频开始使用我们的 Matchmaker 服务： {% embed url="" %} ## ✔️ 准备工作 ### 匹配架构 本指南将重点介绍 **Matchmaking API 和 Backfill API**.
在涉及匹配时，存在四（4）个重要的数据流： 1. [Matchmaking API](/zh/learn/pi-pei/matchmaker-in-depth.md#matchmaking-api) **由游戏客户端使用，用于与 Matchmaker 通信：** 1. 用于组管理、服务器分配和监控， 2. 用于与以下组件进行 ping 测量， [Ping 信标](/zh/learn/bian-pai/ping-beacons.md). 2. [部署](/zh/learn/bian-pai/deployments.md) API 用于通过 Matchmaker 部署、扩缩和管理你的专用服务器。 3. [Netcode Transports](/zh/docs/sample-projects.md) 用于在游戏客户端和专用服务器之间通信。 4. [深入了解](/zh/learn/pi-pei/matchmaker-in-depth.md#backfill-match) **用于替换或向正在运行的服务器添加玩家。** {% hint style="info" %} 发布后， **你的匹配服务需要 24/7 运行** 以确保全球玩家都能加入服务器。 {% endhint %} ## 🍀 简单示例 从一个简单示例开始，测试基础的匹配玩家流程： * 在共享的 [深入了解](/zh/learn/pi-pei/matchmaker-in-depth.md#hosting-cluster), * 在你的匹配服务中定义规则和设置 [深入了解](/zh/learn/pi-pei/matchmaker-in-depth.md#configuration), * 使用以下功能测试玩家流程并管理票据： [深入了解](/zh/learn/pi-pei/matchmaker-in-depth.md#matchmaking-api). ### 1. 在免费层上设置 ☑️ [注册免费的 Edgegap 账户](https://app.edgegap.com/auth/register) 并打开 [Matchmaker 仪表板页面](https://app.edgegap.com/matchmaker-management-v2/matchmakers/list). ☑️ 点击 **创建 Matchmaker** 首先，然后输入： * matchmaker 名称 - 仅供你自己参考，例如 `quickstart-dev` , * 上传我们的简单示例 JSON 配置。 🍀 **简单示例（最小推荐配置）：** {% hint style="danger" %} **请确保将应用程序** **`名称`** **和** **`版本`** **更改为与你的** [应用和版本](/zh/learn/bian-pai/application-and-versions.md). {% endhint %} 
{
  "version": "3.2.2",
  "inspect": true,
  "max_deployment_retry_count": 3,
  "profiles": {
    "simple-example": {
      "ticket_expiration_period": "5m",
      "ticket_removal_period": "1m",
      "group_inactivity_removal_period": "5m",
      "application": {
        "name": "my-game-server",
        "version": "2024.01.30-16.23.00-UTC"
      },
      "rules": {
        "initial": {
          "match_size": {
            "type": "player_count",
            "attributes": {
              "team_count": 1,
              "min_team_size": 2,
              "max_team_size": 2
            }
          },
          "beacons": {
            "type": "latencies",
            "attributes": {
              "difference": 100,
              "max_latency": 200
            }
          }
        },
        "expansions": {}
      }
    }
  }
}
**故障排查和常见问题：** ☑️ 如果没有出现验证错误，请点击 **创建并启动** 并等待流程完成。这将启动一个新的免费集群，并运行你的简单示例 matchmaker。 ✅ 你现在可以继续下一步。 ### 2. 探索配置 随着我们为 Matchmaker 发布更新，每个新版本都会使用 [语义化版本控制](/zh/learn/pi-pei/matchmaker-in-depth.md#changelog) 通过解析格式来清晰传达更改影响 `major.minor.patch`: * 🔥 `主版本` 包含破坏性更改，需要进行集成审查， * 🌟 `次版本` 包含大量向后兼容的改进， * 🩹 `补丁版本` 包含错误修复和小幅改进。 [检查票据](/zh/learn/pi-pei/matchmaker-in-depth.md#matchmaking-api) 以便在开发过程中更好地理解和调试可能的匹配流程。我们建议在正式环境的 matchmaker 中禁用 inspect API。 **某些** [**部署可能会出错**](https://docs.edgegap.com/zh/learn/pages/5e7e2169ca3822647d4607dfc1d3487ebcc0836c#id-4.-deployment-error)**.** 我们会尝试通过自动重试部署最多 `max_deployment_retry_count` 次来解决此问题（无需客户端确认）。 为确保意外的客户端崩溃或放弃的票据不会长期占用你的 matchmaker 资源，未匹配的票据会在以下时间后被取消： `ticket_expiration_period` 导致其状态变为 `CANCELLED` 然后在以下时间后被永久删除： `ticket_removal_period` . {% hint style="info" %} [了解 matchmaker 如何最大化匹配填充率，并将排队时间缩短到 10 秒以内。](/zh/learn/pi-pei/matchmaker-in-depth.md#find-match) {% endhint %} 我们匹配逻辑的核心配置在 [深入了解](/zh/learn/pi-pei/matchmaker-in-depth.md#matchmaking-profiles)中。每个配置文件都是完全隔离的匹配队列，指向 [应用和版本](/zh/learn/bian-pai/application-and-versions.md#app-versions) 并预先定义所需的 CPU 和内存（RAM）资源数量。 [深入了解](/zh/learn/pi-pei/matchmaker-in-depth.md#matchmaking-rules) 初始规则集中的内容必须满足，玩家才能被分到一起，每项规则由三个属性定义： * 你自定义的名称，例如 - `匹配大小`, * 规则类型，也称为运算符，例如 - `player_count`, * 最后是运算符属性，例如 `team_count` 或 `max_team_size`. **玩家数量规则** 这是一个特殊规则，用于定义需要多少玩家匹配后才能开始分配： * `team_count` 指团队数量，1 个团队可用于合作模式或大乱斗模式， * `min_team_size` 指每个团队的最少玩家数量。 * `max_team_size` 指每个团队的最大玩家数量。 我们的简单示例演示了一个 2 人合作游戏。 {% hint style="warning" %} 玩家数量规则 **是必需的，并且只能定义一次** 在你的初始配置规则中。 {% endhint %} **延迟规则** ✅ 你现在可以继续下一步。 ### 3. 查看实例详情 ☑️ 实例初始化后，请在我们的仪表板中查看你新 matchmaker 的详情：
* **状态** 表示服务健康状态，可能为 ONLINE、OFFLINE 或 ERROR。 * **标识符** 如果你需要帮助排查问题，它能帮助 Edgegap 工作人员快速找到你的 matchmaker。 * **启动时间** 可用于追踪最近一次更新时间。 * **大小** 对应于我们的某个 [价格层级](https://edgegap.com/resources/pricing#matchmaker). * **API URL** 将由游戏客户端和游戏服务器用于与你的 matchmaker 通信。 * **Swagger URL** 是我们提供的一个便捷的 OpenAPI 规范 GUI，用于浏览 API 架构。 * **Auth Token** 是供游戏客户端和游戏服务器用于身份验证的唯一密钥令牌。 {% hint style="danger" %} **Edgegap 工作人员绝不会向你索要令牌。如果怀疑存在安全漏洞，请重新生成你的令牌。** {% endhint %} 要测试你的新 matchmaker， **你将需要 Swagger URL、API URL 和 Auth Token**. ✅ 你现在可以继续下一步。 {% hint style="info" %} 要在开发中更新你的 matchmaker 规则，请编辑配置并重新启动它。 {% endhint %} {% hint style="success" %} 参见 [深入了解](/zh/learn/pi-pei/matchmaker-in-depth.md#rolling-updates-and-ab-tests) 适用于正式游戏和零停机更新。 {% endhint %} ### 4. 测试 Tickets API {% hint style="info" %} **请等待最长 5 分钟** 在启动 matchmaker 后，以便 DNS 传播完成。 {% endhint %} ☑️ 首先， **打开你的 Swagger URL** 在 swagger GUI 中查看你的 OpenAPI 架构：
☑️ 点击 **授权** 🔒，粘贴你的 **Auth Token**，然后点击 **授权**.
☑️ 向下滚动到 **Ticket API** **- POST /tickets**，展开并点击 **Try it out**.
☑️ 预览你的请求： * 注意 `player_ip` 设置为 `null` - 这将使 Matchmaker 使用自动添加到请求中的 IP 地址（另见 [深入了解](/zh/learn/pi-pei/matchmaker-in-depth.md#server-to-server-api) 作为替代方案）， * `profile` 指的是你的 [深入了解](/zh/learn/pi-pei/matchmaker-in-depth.md#matchmaking-profiles), * `attributes` 包含你的 matchmaker 规则所需的值，在本例中是 `latencies` 规则， * rule `player_count` 这是唯一一个在玩家票据中不需要任何属性的规则。 ☑️ 点击 **Execute** 并查看你的玩家票据请求响应： * `id` 是你唯一的匹配票据 ID，请保存它以便之后查看你的票据， * `profile` 确认选择 [深入了解](/zh/learn/pi-pei/matchmaker-in-depth.md#matchmaking-profiles), * `group_id` 是分配给每个票据的唯一 [组 ID，单人玩家会被表示为 1 人组](/zh/learn/pi-pei/matchmaker-in-depth.md#group-up), * `team_id` 是在以下情况后分配给每位玩家的唯一团队 ID `TEAM_FOUND` 状态达到， * [每个团队可以包含多个组，但不能超过配置的团队大小](/zh/learn/pi-pei/matchmaker-in-depth.md#matchmaking-rules), * `player_ip` 是解析后的玩家公网 IP 地址，不论识别方式为何， * `assignment` 被设置为 `null` 以表示该票据尚未被匹配或分配到服务器， * `created_at` 提供关于玩家票据创建时间的信息，供游戏 UI 使用， * `status` 表示票据的当前状态，所有票据初始状态为 `SEARCHING` .
☑️ 再次点击以创建第二个票据， **Execute** 这样我们的两个玩家就会匹配并启动一个服务器。 ☑️ 折叠 POST /tickets 并打开 **GET /tickets/{ticketId}**，然后点击 **Try it out**. ☑️ 从上一步响应中输入票据 ID，然后点击 **Execute**.
☑️ 查看你的玩家票据更新后的分配： * 状态变为 `MATCH_FOUND` 首先，同时保持 `assignment` 设置为 `null` 以表示玩家已匹配且正在分配服务器，
☑️ 点击 **Execute** 再次检查你的票据，并查看票据更新后的分配： * 状态变为 `HOST_ASSIGNED` 其中 `assignment` 包含已分配服务器的详细信息。
故障排查与常见问题 我的票据卡在 `SEARCHING` . * 请确认你已经根据配置创建了足够多且条件重叠的票据。 *** 我的票据在 `MATCH_FOUND` 和 `TEAM_FOUND` 之间反复切换， * 免费层账户一次只能部署 1 个实例。请考虑升级，或停止当前部署后再启动新的部署。 *** 我的票据直接变成 `CANCELLED`. * 你的票据已过期。请重新创建新票据，或在配置中增加过期时长用于测试。 *** 在查看我的票据时收到 HTTP 404 Not Found。 * 你的票据已被 DELETE 请求删除，或已到达移除时长（在票据过期后开始，定义在你的配置中）。请重新创建新票据，或在配置中增加过期/移除时长用于测试。
☑️ [在我们的仪表板中查看你的新部署](https://app.edgegap.com/deployment-management/deployments/list): * 注意，每个部署都会标记所有票据 ID 和 profile，以增强可追踪性。
☑️ 尝试从你的游戏客户端连接到已分配的服务器。 {% hint style="warning" %} 如果你遇到较高延迟，你的 netcode 集成可能配置为模拟网络延迟。 **测试时禁用 VPN** 以获得更真实的条件，并收到一个 [低延迟部署](/zh/learn/bian-pai/deployments.md#server-placement). {% endhint %} ☑️ 一旦你确认能够无问题地连接到你的部署并完成测试， **停止你的部署** 以释放你账户中的容量，供下一个构建使用。 ✅ 你现在可以继续下一步。 {% hint style="info" %} 用于测试的 OpenAPI 规范可在以下地址找到 `{matchmaker-url}/swagger/v1/swagger.json`. {% endhint %} ### 5. 游戏集成 Matchmaker 与以下内容集成： * **游戏客户端**，用于 [管理组、成员、分配和票据](/zh/learn/pi-pei/matchmaker-in-depth.md#group-up), * **专用服务器**，用于 [深入了解](/zh/learn/pi-pei/matchmaker-in-depth.md#backfill-match) 在玩家离开后。 ☑️ 在 **游戏客户端**中，我们建议通过游戏内 UI 向玩家提供票据状态更新，以获得最佳玩家体验。参见： ☑️ 在 **游戏客户端**，请确保你正在处理可重试的 `429 Too Many Requests` 错误，并采用指数退避和重试，让 matchmaker 在流量突增时有时间恢复。 ☑️ 在 **游戏客户端**，请确保你正在处理不可重试的错误： * `404 Not Found` - 票据已被删除， * `500 Internal Server Error` - 临时服务中断。 ☑️ 在 **游戏服务器**，读取玩家偏好和初始服务器上下文： 1. [注入变量（Matchmaker）](/zh/learn/pi-pei/matchmaker-in-depth.md#injected-environment-variables) **用于检索初始玩家的匹配数据。** 2. [注入变量（应用版本）](/zh/learn/bian-pai/application-and-versions.md#other-parameters-optional) 用于版本参数、设置和密钥。 3. [注入变量（部署）](/zh/learn/bian-pai/deployments.md#injected-environment-variables) 用于部署信息、IP、位置等…… ☑️ 一旦玩家连接， **游戏服务器和游戏客户端** 启动加载场景——3D 场景、类似大厅的社交界面，或带进度条的加载屏幕，以表明初始化正在进行。 ☑️ 确保你的 [部署将被停止](https://docs.edgegap.com/docs/deployment#stop-a-deployment) 在比赛结束后正确地完成。 🙌 恭喜，你已完成匹配集成！想了解更多，请继续阅读。 ## 🏁 高级示例 一个完整的配置，使用了所有匹配功能，包括 [深入了解](/zh/learn/pi-pei/matchmaker-in-depth.md#matchmaking-profiles), [深入了解](/zh/learn/pi-pei/matchmaker-in-depth.md#matchmaking-rules)，以及 [深入了解](/zh/learn/pi-pei/matchmaker-in-depth.md#rule-expansion) 看起来可能如下： ## 🎾 自定义大厅 自定义大厅（私人大厅、沙盒关卡）是沙发多人游戏和在游戏正式模式上线前测试新功能的非常流行的选择。通常所需限制最少，但目标是确保玩家可以 [深入了解](/zh/learn/pi-pei/matchmaker-in-depth.md#group-up). {% hint style="info" %} 对于没有公开访问的私人大厅，请设置 `"team_size": 1` 并让组拥有者单独开始游戏。拥有者可以将组和主机分配详情分享给任意数量的成员加入。 {% endhint %} {% hint style="success" %} 添加 `custom-lobby-example` profile **到你现有的 matchmaker 中** 以支持自定义大厅。 {% endhint %} ## 🥛 补位展示 在 [#simple-example](#simple-example "mention")的基础上，这个配置展示了 [Backfill](/zh/learn/pi-pei/matchmaker-in-depth.md#backfill-match) 其中 [组](/zh/learn/pi-pei/matchmaker-in-depth.md#group-up). ## ⚔️ 竞技游戏 竞技游戏侧重于玩家之间相互竞争以取得胜利，无论是个人（大乱斗）还是团队。通过将技能水平相近的玩家或团队配对，确保公平平衡的比赛，并通过快速寻找公平对手来保持游戏节奏。 你可以 **定义多个团队，每个团队有 1 名或更多玩家**，例如：
游戏模式团队数量团队大小总玩家数
5v5 FPS2510
5v5 MOBA2510
20x3 大逃杀20360
10人自由混战11010
定义多个 [深入了解](/zh/learn/pi-pei/matchmaker-in-depth.md#matchmaking-profiles) 用于游戏模式特定的规则和设置，并在需要时 [按需扩展](/zh/learn/pi-pei/matchmaker-in-depth.md#rule-expansion). * **对于所有比赛：** * 限制 [匹配延迟](/zh/learn/pi-pei/matchmaker-in-depth.md#ping-optimization) 以防止匹配到远距离玩家， * [深入了解](/zh/learn/pi-pei/matchmaker-in-depth.md#group-up) 用于预组队伍，并防止超过团队大小， * 随着时间推移逐步放宽延迟限制，以找到更多玩家， * 通过不同的 [应用和版本](/zh/learn/bian-pai/application-and-versions.md#app-versions) 为特定配置分配更多 CPU 或内存， * **对于休闲比赛：** * 省略段位限制，以最大化匹配速度和匹配填充率， * 让玩家提供他们的地图偏好，以找到适合所有人的地图， * 指定补位组大小，以替换离开者而不超过团队大小， * 移除延迟限制，以保证在队列时间达到 3 分钟（180 秒）后匹配成功。 * **对于竞技比赛：** * 限制段位，仅允许与相近技能水平的对手对战， * 使用升段或降段段位来匹配联赛段位极端值的玩家。 * **对于前 1% 的高水平比赛（挑战者）：** * 使用数值型技能评级（ELO）来精细控制比赛中的技能分布， * 由于玩家数量较少，在放宽延迟要求前等待更久。 {% hint style="success" %} 使用多个配置文件来 **将休闲模式、竞技模式和顶级挑战者** 玩家分开，可以让你为每类玩家单独自定义规则和扩展。 {% endhint %} ## 🤝 合作游戏 合作游戏要求玩家作为团队共同朝着一个共同目标，或对抗 AI 对手。将偏好和玩法习惯相似的玩家匹配在一起。替换离开的玩家，并提升 [Ping 信标](/zh/learn/bian-pai/ping-beacons.md#connection-quality) 以提供响应迅速的玩家体验。 在团队数量为 1、最大团队大小为 4 的情况下， **每场比赛最多需要 4 名玩家**. 定义多个 [深入了解](/zh/learn/pi-pei/matchmaker-in-depth.md#matchmaking-profiles) 用于游戏模式特定的规则和设置： * 以至少 4 名玩家开始，以保持玩家在队列中并最大化匹配填充率， * 限制 [匹配延迟](/zh/learn/pi-pei/matchmaker-in-depth.md#ping-optimization) 以防止匹配到远距离玩家， * 让玩家选择特定的游戏难度，以适应每个人的技能水平， * 让玩家提供他们的地图偏好，以找到适合所有人的地图， * 限制玩家等级差异，以要求相近的游戏进度， * 指定补位组大小，以替换离开者而不超过服务器容量， * 使用审核标记将低信誉玩家和作弊者与普通玩家群体分开， * [深入了解](/zh/learn/pi-pei/matchmaker-in-depth.md#group-up) 用于预组队伍，并在不超过服务器容量的情况下填充团队， * 通过不同的 [应用和版本](/zh/learn/bian-pai/application-and-versions.md#app-versions) 用于其他配置文件。 从理想条件开始，并 [逐步放宽限制](/zh/learn/pi-pei/matchmaker-in-depth.md#rule-expansion) 以确保快速匹配： * 随着时间推移放宽延迟限制，以找到更多玩家， * 提高允许的玩家等级差异，以找到更多玩家， * 降低最小团队大小，以需要更少玩家并更快开始游戏， * 服务器可以用 AI 队友填补空位， * 或 [深入了解](/zh/learn/pi-pei/matchmaker-in-depth.md#backfill-match) 稍后再添加玩家， * 将最小团队大小设为 1，以便在排队 150 秒后单人启动游戏 ## 🎈 社交游戏 社交游戏侧重于通过协作、沟通和共享体验来建立玩家之间的联系和关系。支持大量玩家，最大化匹配填充率，并协调玩家偏好和游戏习惯。替换离开的玩家，并确保高 [Ping 信标](/zh/learn/bian-pai/ping-beacons.md#connection-quality) 以提供响应迅速的玩家体验。 在团队数量为 1（自由混战）且最大团队大小为 50 的情况下， **每场比赛最多需要 50 名玩家**. 定义 [深入了解](/zh/learn/pi-pei/matchmaker-in-depth.md#matchmaking-profiles) 用于游戏模式特定的规则和设置： * 限制 [匹配延迟](/zh/learn/pi-pei/matchmaker-in-depth.md#ping-optimization) 以防止匹配到远距离玩家， * 让玩家提供他们的游戏模式偏好，并找到适合所有人的模式， * 指定补位组大小，以替换离开者而不超过服务器容量， * 使用审核标记将低信誉玩家和作弊者与普通玩家群体分开， * [深入了解](/zh/learn/pi-pei/matchmaker-in-depth.md#group-up) 用于预设大厅，或在不超过服务器容量的情况下填充团队， * 通过不同的 [应用和版本](/zh/learn/bian-pai/application-and-versions.md#app-versions) 用于其他配置文件。 从理想条件开始，并 [逐步放宽限制](/zh/learn/pi-pei/matchmaker-in-depth.md#rule-expansion) 以确保快速匹配： * 随着时间推移放宽延迟限制，以找到更多玩家， * 逐步减少最小团队大小，以需要更少玩家并更快开始游戏， * 服务器可以用 AI 玩家填补空位， * 或 [深入了解](/zh/learn/pi-pei/matchmaker-in-depth.md#backfill-match) 稍后再添加玩家， * 将最小团队大小设为 1，以便在排队 150 秒后单人启动游戏。 [^1]: 替换为你自己的应用名称 [^2]: 替换为你自己的应用版本 --- # 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/learn/pi-pei.md?ask= ``` 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.