如何将匹配机制集成到你的多人类 roguelike 游戏中

-> 本文基于 匹配机制文档。如果你遇到问题或不一致的情况，请确保参考 原始指南，因为它们更新得更频繁。

以下示例将帮助你测试核心 匹配机制 玩家流程，即：

• 在共享的 托管集群上创建匹配器实例，

• 在你的匹配器 配置中定义规则和设置，

• 最后，测试玩家流程并管理 玩家票据，使用我们的 API。

将我们的匹配器实现到你的游戏中有 五个步骤：

1. 第一步是 创建账号 并使用我们的 roguelike 游戏示例。 瞧，你（从技术上讲）已经完成了一半！你只需要在你的游戏中集成匹配器（见步骤 5）。

2. 现在，你绝不应该盲目遵循在网上找到的 JSON 示例，因此强烈建议将上述规则调整到你的回合制游戏中。步骤 2（“探索配置”）是我们“如何阅读”每个 匹配机制规则功能的介绍（“探索配置”）。

3. 步骤 3（“审核实例详细信息”）涵盖你的个人特定 匹配器，以确保它已部署并与游戏设计兼容。

4. 步骤 4，如其名所示（“4. 测试票据 API”），完全是关于测试玩家的匹配请求是否已被匹配器接收，称为票据。

5. 步骤 5（“在你的游戏中集成匹配机制”）强调如何在你引擎的项目中集成匹配器。

如果你遇到故障排除挑战，我们深入的 学习中心 提供额外的故障排除提示。

1. 设置免费套餐

注册你的免费 Edgegap 账号，并导航到 匹配器仪表板页面。

在此，首先点击 创建匹配器 然后输入：

• 为你的匹配器指定一个名称 - 这仅供你自己参考，例如 quickstart-dev，

• 然后，为你的 roguelike 游戏上传以下简单示例作为 JSON 配置：

{
  "version": "2.1.0",
  "inspect": true,
  "max_deployment_retry_count": 3,
  "ticket_expiration_period": "5m",
  "ticket_removal_period": "1m",
  "profiles": {
    "custom-lobby-example": {
      "application": {
        "name": "my-game-server",
        "version": "2024.01.30-16.23.00-UTC"
      },
      "rules": {
        "initial": {
          "match_size": {
            "type": "player_count",
            "attributes": {
              "team_count": 1,
              "team_size": 4
            }
          },
          "lobby_id": {
            "type": "string_equality"
          }
        },
        "expansions": {}
      }
    }
  }
}

(温馨提醒，请确保更改应用程序的 名称 和 版本 以匹配你的 应用程序和版本!)

如果没有出现验证错误，请点击 创建并开始 并等待过程完成。这将导致一个新的免费集群启动，配备你的简单示例匹配器。

你现在可以继续进行下一步。

2. 探索配置​

独特的多人 roguelike 游戏规则

自定义大厅（私有大厅、沙盒关卡）是沙发多人游戏的一个非常受欢迎的选择，同时也是在进入主要游戏模式之前测试新功能的有效方法。这些游戏通常要求尽量少的限制，但目的在于确保玩家可以 作为团队加入。

补位票据可以使用自定义大厅配置文件来支持可靠地邀请朋友，只要补位票据有效即可。

• 提示: 在你的配置中添加 custom-lobby-example 配置文件，以支持自定义大厅。

语义版本控制

当我们发布匹配机制的更新时，每个新版本都使用 语义版本控制 来清晰地传达变更的影响，格式为 major.minor.patch：

• major 版本包含破坏性更改，需进行集成审查，

• minor 版本包含大量向后兼容的改进，

• patch 版本包含错误修复和小改进。

一些 部署可能会导致错误。我们尝试通过自动重试部署 up to max_deployment_retry_count 次来解决此问题（无需客户确认）。

为确保意外的客户端崩溃或被放弃的票据不会持续存在并占用你的匹配器资源，票据将在 ticket_expiration_period 后被取消，其状态将更改为 CANCELLED ，并在 ticket_removal_period 后永久删除。

我们的匹配逻辑的核心配置在 匹配机制配置文件中。每个配置文件都是一个完全独立的匹配队列，指向具有预定义的所需 CPU 和内存 (RAM) 资源的 应用程序版本 。

匹配机制规则 在初始规则集中必须满足，玩家才能被分组，每个规则由三个属性定义：

• 你选择的名称，例如 - 匹配大小，

• 规则类型，也称为操作符，例如 - 玩家数量，

• 最后是操作符属性，例如 团队数量 或 团队大小。

玩家数量规则

这是一个特殊规则，定义需要多少玩家匹配以启动分配：

• 团队数量 指团队数量，1个团队可以用于合作或自由对战模式，

• 团队大小 指每个团队的 玩家数量。

我们的简单示例演示了一个有 2 名玩家的合作游戏。

请注意，"玩家数量" 规则是必需的，仅可在你的初始配置规则中定义一次。

延迟规则

使用此规则为所有玩家提供最低的 ping。一旦客户端测量并提交他们的往返时间（ping）与所有可用信标，Gen2 将仅考虑在特定 差异 的 ping 值内的匹配，该值与 Ping 信标测量。这为玩家基底提供了一种“软”的解决方案，能够实现与邻近地区的匹配，尤其是在人员较少的地区改善匹配速度。使用 max_latency以防止与远离的玩家匹配。

你现在可以继续进行下一步。

我们的示例 信标 规则上面的 "差异": 50, "max_latency": 200 最初：

• Alice 和 Bob 将匹配，因为北京被排除（>200），其余在 | A-B | < 50 之内：

  • Alice {蒙特利尔: 12.3, 纽瓦克: 45.6, 达拉斯: 59.9, 北京: 264.4}; 和

  • Bob {蒙特利尔: 27.3, 纽瓦克: 32.4, 达拉斯: 23.1, 北京: 252.2}。

• Charlie 和 Dave 将不会匹配，因为 | C-D | > 50，对于达拉斯信标：

  • Alice {蒙特利尔: 5.7, 纽瓦克: 44.2, 达拉斯: 59.5, 北京: 263.2}; 和

  • Bob {蒙特利尔: 57.8, 纽瓦克: 32.0, 达拉斯: 24.2, 北京: 272.3}。

请注意，"延迟规则" 只可在你的初始配置规则中定义一次。

3. 审核实例详细信息​

在仪表板上查看新匹配器的详细信息，一旦它初始化：

状态 指示服务健康状况，可能为在线、离线或错误。

• 标识符 帮助 Edgegap 员工快速找到你的匹配器，如果你需要故障排除的帮助。

• 启动于 可用于追踪最新更新时间。

• 大小 对应于我们其中一个 定价套餐。

• API URL 将由游戏客户端和游戏服务器使用与 Gen2 通信。

• Swagger URL 是一个方便的 openAPI 规范 GUI，我们提供用于探索 API 方案。

• 认证令牌 是游戏客户端和游戏服务器用于身份验证的唯一秘密令牌。

要使用 API 测试新匹配器， 你将需要 Swagger URL、API URL 和认证令牌。

你现在可以继续进行下一步。

4. 测试票据 API

首先， 打开你的 Swagger URL 以检查你的 openAPI 方案，在 swagger GUI 中

点击“匹配器”标题下的 /...swagger.json URL 以打开原始 JSON 方案：

将此页面保存为文件在你的驱动器上（CTRL/CMD+S）。

打开你的 Postman 应用程序 并登录到你的免费帐户。

从上一步导入你 swagger.json 文件：

• 保持 Postman 集合 被选择，

• 选择 查看导入设置 并改变设置 参数生成 为 示例。

确认导入，这将导致一个新的集合出现在左侧的集合列表中，标题为匹配器。

查看更多操作，打开选项卡 授权 并选择：

• 认证类型 - API 密钥，

• 密钥 - “Authorization”

• 值 - 在此处插入你的 AuthToken 值，

• 添加到 - 头。

按下 (CTRL/CMD+S) 或保存图标以 保存更改。你的 Postman 标签中的橙色点将消失。

在你的匹配器集合中，选择 票据 并 创建匹配票据 ，打开一个新选项卡。

选择选项卡 正文 以预览你的 玩家票据请求：

注意 player_ip 设置为 null - 这将导致使用自动添加到你的请求中的 IP 地址（请参见 服务器到服务器集成 了解替代方案），

• profile 指的是你的 匹配机制配置文件，

• attributes 包括你的匹配器规则的值，此情况下为 延迟 规则，

  • 规则 player_count 是唯一不需要玩家票据中的任何属性的规则。

注意: 请确保参考示例的Swagger 导入配置。

点击 发送 并查看对你的玩家票据请求的响应：

• id 是你的唯一匹配票据 ID，确保保存以便稍后检查你的票据，

• profile 确认所选择的 匹配机制配置文件，

• group_id 是每个票据发放的唯一组 ID，单个玩家表示为组 1，

  • 查看 作为团队加入 以与朋友或大厅进行匹配，

• player_ip 是玩家的公用 IP 地址，无论使用何种识别方法，

• assignment 设置为 null 以指示该票据尚未匹配或分配给服务器，

• created_at 提供有关玩家票据创建时间的信息供游戏用户界面使用，

• status 指示票据的当前状态，所有票据开始时为 SEARCHING （请参见 匹配机制过程 以获取详细信息）。

通过再次点击 发送 创建第二张票据，使两名玩家匹配并启动服务器。

在你的匹配器集合中，选择 {ticketId} 并 读取匹配票据。

在之前步骤响应中输入票据 ID 并点击 发送。

查看你玩家票据的更新分配：

• 状态首先更改为 MATCH_FOUND ，同时保持 assignment 设置为 null 以指示玩家已经匹配，正在分配服务器，

再次点击 发送 以检查你的票据，并查看你玩家票据的更新分配：

• 状态更改为 HOST_ASSIGNED ， assignment 包含关于分配服务器的详细信息。

 检查你在我们仪表板中的新部署：

• 注意每个部署都标记了所有票据 ID 和配置文件，以增加可追溯性。

尝试从你的游戏客户端连接到分配的服务器。

一旦你确认可以无障碍连接到你的部署并完成测试， 停止你的部署 以释放账户中的容量以供下一个构建使用。

你现在可以继续进行下一步。

5. 在你的游戏中集成匹配器​

Edgegap 的匹配机制集成：

• 与 游戏客户端集成，以管理 玩家票据，

• 与 游戏服务器集成，以：

  • 处理玩家通过其票据传递的偏好，

  • 可选支持 补位 以在启动后添加或替换玩家。

对于 游戏客户端，我们建议在 匹配机制过程 期间向玩家提供票据状态更新，使用游戏内 UI 提供最佳玩家体验。请参阅：

• Edgegap - Unity Gen2 匹配机制 SDK，

  • 导入简单示例 并根据你的需求进行自定义，

• Betide Studio - 虚幻引擎 Edgegap 集成工具包，

  • 下载示例项目 并根据你的需求进行自定义。

在 游戏客户端中，确保你处理不可重试的错误：

• HTTP 404 未找到 - 票据已被删除，

• HTTP 500 内部服务器错误 - 临时服务中断。

在 游戏服务器中，处理玩家偏好和初始服务器上下文。无需 API 集成：

1. 读取 注入的环境变量（Gen2） 以检索初始玩家的匹配数据。

2. 读取 注入的环境变量（应用版本） 以获取特定版本的参数、设置（玩家容量）和密钥。

3. 读取 注入的环境变量（部署） 以获得有关部署的信息，如 IP 地址、位置或更多。

一旦玩家连接， 游戏服务器与游戏客户端 启动加载场景以执行同步步骤（例如选择和加载地图/场景/关卡）。我们建议使用完整的 3D 场景、类似大厅的社交 UI 或带有进度条的加载屏幕，以指示初始化正在进行。

一旦 游戏客户端 完全加载，玩家将加载/前往主游戏场景。

可选地， 游戏服务器 可以创建和管理 补位 和玩家容量（添加或替换离开的玩家）。

确保你的 部署将会被停止 适当地使用 Injected DELETE_URL，如果：

• 没有玩家加入比赛，

• 所有玩家已离开比赛，

• 比赛正确结束。

恭喜你完成了 Edgegap 匹配器集成！如果你想了解更多，请在我们的 学习中心 中阅读所有内容。