如何将匹配机制集成到您的 Unity 引擎多人游戏中

-> 本文基于 匹配文档。如果您遇到问题或差异，请确保参考 原始指南，因为这些内容更经常保持最新。

以下示例将帮助您测试 Unity 引擎多人游戏的核心 匹配 玩家流，具体如下：

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

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

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

将我们的匹配机制实施到您的游戏中需要 五个步骤：

1. 第一步是 创建一个帐户 并使用我们的简单游戏示例。 Voilà，您（技术上）已完成一半！您只需将匹配机制集成到您的游戏中（参见步骤 5）。

2. 现在，您永远不应该盲目遵循您在互联网上找到的 JSON 示例，因此强烈建议根据您的回合制游戏调整上述规则。步骤 2（“探索配置”）是我们的“如何阅读”，详细介绍了每个 匹配规则函数的作用（“探索配置”）。

3. 步骤 3（“查看实例详情”）涵盖了您的个人具体 匹配器 ，以确保其已部署并与您游戏的设计兼容。

4. 步骤 4，顾名思义（“4. 测试票据API”），完全是关于测试玩家的匹配请求是否被匹配机制接收，称为 票据。

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

如果您遇到故障排除的挑战，我们深入的 学习中心 有更多的故障排除技巧。

虚幻教程 - 添加 Edgegap 的匹配机制

如果这看起来令人生畏，我们会帮助您 - 观看逐步集成视频：

1. 设置免费层级

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

从那里，首先点击 创建匹配器 ，然后输入：

• 为您的匹配器命名 - 这纯粹是为了您自己的参考，例如 quickstart-dev,

• 然后，将以下简单示例上传为您 Unity 引擎游戏的 JSON 配置：

{
  "version": "2.1.0",
  "inspect": true,
  "max_deployment_retry_count": 3,
  "ticket_expiration_period": "5m",
  "ticket_removal_period": "1m",
  "profiles": {
    "simple-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": 2
            }
          },
          "beacons": {
            "type": "latencies",
            "attributes": {
              "difference": 50,
              "max_latency": 200
            }
          }
        },
        "expansions": {}
      }
    }
  }
}

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

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

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

2. 探索配置​

语义版本控制

随着我们对匹配器的更新，每个新版本使用 语义版本控制 来清晰地传达更改的影响，通过解释格式 major.minor.patch：

• major 版本包含重大更改，需要进行集成审核，

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

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

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

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

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

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

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

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

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

玩家数量规则

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

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

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

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

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

延迟规则

使用此规则为所有玩家提供最低可能的延迟。一旦客户端测量并提交他们的往返时间（延迟）与所有可用信标进行比较，Gen2 只会考虑在特定的 difference 延迟值范围内的匹配，测量将与 延迟信标进行比较。这提供了一种“软”的解决方案，以分割您的玩家基础，使得可以与临近区域匹配，尤其改善了人口较少区域的匹配速度。使用 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 架构。

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

要使用 API 测试您的新匹配器， 您将需要 Swagger URL、API URL 和身份验证令牌。

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

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 匹配机制集成！如果您想了解更多内容，请在我们的 学习中心 中阅读全部内容。