如何将匹配系统集成到您的沙盒多人游戏中

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

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

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

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

• 最后，测试玩家流程并管理 玩家票证，配合我们的 API。

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

1. 第一步是 创建一个帐户 并使用我们的沙盒游戏示例。看看，您已经（从技术上讲）完成了一半！您只需在您的游戏中集成匹配器（请参见第5步）。

2. 现在，您永远不应盲目遵循在互联网上找到的 JSON 示例，因此强烈建议根据您的回合制游戏调整上述规则。第二步（“探索配置”）是我们的“如何阅读”，深入讲解每个 匹配规则功能（“探索配置”）。

3. 第三步（“审查实例详情”）涵盖了您个人的特定 匹配器，以确保其与您游戏的设计一起部署并正常工作。

4. 第四步，如名称所示（“4. 测试票证 API”），主要是测试玩家的匹配请求是否被匹配器接收，这些请求被称为 票证。

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": {}
      }
    }
  }
}

(温馨提示，请确保更改应用程序 name 和 version 以匹配您的 应用程序和版本!)

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

您现在可以继续下一步。

2. 探索配置​

独特的多人沙盒游戏规则

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

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

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

语义版本控制

当我们发布匹配器的更新时，每个新版本使用 语义版本控制 通过解析格式 major.minor.patch 明确定义更改的影响：

• major 版本包括重大更改，并需要进行集成审查，

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

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

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

为确保意外的客户端崩溃或被放弃的票证不会滞留并占用您的匹配器资源，票证将在 ticket_expiration_period 后被取消，状态将变为 CANCELLED 并在 ticket_removal_period 后永久删除。

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

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

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

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

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

玩家数量规则

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

• 团队数量 指的是团队的数量，一个团队可以用于合作或自由竞技模式，

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

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

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

延迟规则

使用此规则为所有玩家提供最低的延迟。一旦客户端测量并提交他们针对所有可用信标的往返时间（延迟），Gen2 将只考虑在特定 差值 内的匹配，基于对 延迟信标的测量。这为分割玩家群体提供了一种“软”解决方案，允许与邻近地区的匹配，特别是提高了人口较少地区的匹配速度。使用 max_latency 防止与远离的玩家进行匹配。

您现在可以继续下一步。

我们上面的示例 信标 规则初步设定为 "difference": 50, "max_latency": 200 ：

• 艾莉斯和鲍勃将匹配，因为北京被丢弃（>200），其余在 | A-B | < 50 之内：

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

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

• 查理和戴夫不会匹配，因为 | C-D | > 50，对于达拉斯信标：

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

  • 鲍勃 {蒙特利尔: 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 包括您的匹配器规则的值，在本例中为 延迟 规则，

  • 规则 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 匹配器集成！如果您想了解更多内容，请查看我们的 学习中心。