如何将匹配系统集成到您的虚拟世界多人游戏中

-> 本文基于 匹配系统文档。如果您遇到问题或差异，请确保参考 原始指南，因为它们更新频率更高。

以下示例将帮助您测试核心 匹配系统 玩家流程，即：

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

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

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

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

1. 第一步是 创建一个账户 并使用我们的虚拟世界游戏示例。 瞧，您（技术上）已经完成一半了！您只需在游戏中集成匹配器（见第5步）。

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

3. 第3步（“查看实例详情”）涉及您个人的特定匹配器，以确保其已部署并与您游戏的设计兼容。

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

5. 第5步（“在您的游戏中集成匹配系统”）强调如何在您引擎的项目中集成匹配器。

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

1. 设置免费层

注册您的免费 Edgegap 账户，并导航至 匹配器仪表板页面。

然后，点击 创建匹配器 ，然后输入：

• 您的匹配器名称 - 这仅供您参考，例如 quickstart-dev，

• 然后，作为您的虚拟世界游戏，上传以下简单示例作为 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. 探索配置​

独特的多人虚拟世界游戏规则

自定义大厅（私人大厅、沙盒关卡）是沙发多人游戏的一个非常受欢迎的选项，但也用于测试竞技或合作游戏中的新功能，以便在它们进入主要游戏模式之前进行测试。这些游戏通常需要最少的限制，但旨在确保玩家可以 作为小组加入。

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

• 提示: 将 custom-lobby-example 配置文件添加到您的配置以外于您的其他配置文件以支持自定义大厅。

语义版本控制

随着我们向匹配系统发布更新，每个新版本使用 语义版本控制 来清楚地传达更改的影响，按格式 major.minor.patch 进行解释：

• major 版本包括破坏性更改并需要集成审查，

• minor 版本包括实质性的向后兼容改进，

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

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

为了确保意外的客户端崩溃或遗弃的票据不会停留并占用您的匹配器资源，票据将在 ticket_expiration_period 后被取消，其状态将更改为 CANCELLED ，然后在 ticket_removal_period 之后被永久删除。

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

匹配规则 在初始规则集中必须满足，以便将玩家分组在一起，分别由三个属性定义：

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

• 规则类型，也称为操作符，例如 - player_count，

• 最后是操作符属性，例如 team_count 或 team_size。

玩家数量规则

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

• team_count 指的是队伍数量，1 个队伍可用于合作或自由对战模式，

• team_size 指的是每个队伍的 玩家数量。

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

请注意，“玩家数量”规则是必需的，并且在初始配置规则中只能定义一次。

延迟规则

使用此规则为所有玩家提供最低的 ping 值。一旦客户端测量并提交其往返时间（ping）与所有可用的信标，Gen2 仅会考虑在特定的 difference ping 值内的匹配，该值是与 Ping 信标进行测量的。这呈现了一种“软”解决方案，帮助您划分玩家基础，使能力相近的区域之间的匹配更为便捷，尤其是改善了人少区域的匹配速度。使用 max_latency防止与远方玩家的匹配。

您现在可以继续到下一步。

我们上面的例子 信标 规则使用 "difference": 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 架构。

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

要使用 API 测试您的新匹配器， 您将需要 Swagger URL、API URL 和 Auth Token。

您现在可以继续到下一步。

4. 测试票据 API

首先， 打开您的 Swagger URL 以检查您的 openAPI 构架在 swagger GUI 中

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

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

打开您的 Postman 应用 并登录到您的免费账户。

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

• 保持 Postman 集合 被选择，

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

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

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

• 授权类型 - API 密钥，

• 密钥 - “授权”

• 值 - 在这里插入您的 AuthToken 值，

• 添加到 - 头部。

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

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

选择选项卡 主体 以预览您的 玩家票据请求：

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

• profile 指的是您的 匹配配置文件，

• attributes 包括匹配器规则的值，在这种情况下是针对 latencies 规则，

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

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

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

• id 是您独特的匹配票据 ID，请保存此值以便稍后检查您的票据，

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

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

  • 请参见 作为小组加入 以便与您的朋友或大厅进行匹配，

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

• assignment 设置为 null 以指示尚未匹配或分配到服务器，

• created_at 提供关于玩家票据创建时间的信息，以便在游戏 UI 中使用，

• 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 或具有进度条的加载屏幕，以指示初始化进展。

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

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

确保您的 部署将正确停止 ，使用 注入的 DELETE_URL，如果：

• 没有玩家加入比赛，

• 所有玩家已离开比赛，

• 比赛正确结束。

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