如何将對局配對整合到您的 Unity Engine 多人游戏中

-> 本文基于 對局配對文档。如果您遇到问题或发现不一致之处，请务必参考 原始指南，因为它们的更新频率更高。

以下示例将帮助您测试 Unity Engine 多人游戏的核​​心對局配對 玩家流程，即：

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

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

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

只需五个步骤即可在您的游戏中实现我们的配对器：

1. 第一步是创建一个账户并使用我们简单的游戏示例。瞧，您（在技术上）已经完成了一半！您只需要在游戏中整合配对器（参见步骤 5）。

2. 现在，您绝对不要盲目遵循在互联网上找到的 JSON 示例，因此强烈建议将上述规则调整为您自己的回合制游戏。步骤 2（“探索配置”）是我们的“阅读指南”，深入介绍了每项對局配對规则功能的作用（“探索配置”）。

3. 步骤 3（“查看实例详情”）涵盖了您个人特定的配对器，以确保其已部署并可与您的游戏设计配合使用。

4. 步骤 4，正如其名（“4. 测试票证 API”），完全是关于测试您的配对器是否接收到玩家的對局配對请求，即所谓的票证。

5. 步骤 5（“在您的游戏中整合對局配對”）重点介绍了如何将配对器整合到您的引擎项目中。

如果您遇到排错方面的挑战，我们深入的学习中心提供了额外的排错技巧。

Unreal 教程 - 添加 Edgegap 的對局配對

如果这看起来令人望而生畏，不用担心 - 请观看分步整合视频：

1. 设置免费层级

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

在该页面上，首先点击 Create Matchmaker ，然后输入：

• 您的配对器的名称 – 纯粹供您自己参考，例如 quickstart-dev，

• 然后，上传以下简单的 JSON 配置示例，适用于您的 Unity Engine 游戏：

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

（友情提示：请务必修改 application name 和 version 以匹配您的 Application 和 Versions！）

如果没有出现验证错误，点击 Create and Start 并等待过程完成。这将启动一个新的免费集群，并运行您的简单示例配对器。

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

2. 探索配置​

语义化版本控制

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

• major 版本包含不兼容的重大更改，需要重新评估整合情况，

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

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

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

为确保意外的客户端崩溃或遗弃的票证不会持续占用您的配对器资源，票证将在 ticket_expiration_period 后被取消，使其状态更改为 CANCELLED，然后在 ticket_removal_period 后被永久删除。

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

初始规则集中的 對局配對规则 必须满足才能将玩家分组在一起，每项规则由三个属性定义：

• 您选择的名称，例如 - match size，

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

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

玩家数量规则

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

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

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

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

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

延迟规则

使用此规则为所有玩家提供尽可能低的 Ping 值。一旦客户端测量并提交了针对所有可用信标的往返时间 (Ping)，Gen2 将只考虑在特定 difference Ping 值范围内的匹配，该值是针对 Ping Beacons 测量的。这为细分您的玩家群提供了一种“温和”的解决方案，能够与相邻区域进行匹配，尤其可以提高人口较少区域的匹配速度。使用 max_latency 来防止与地理位置过远的玩家进行匹配。

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

我们上面带有 "difference": 50, "max_latency": 200 的示例 beacons 规则最初：

• Alice 和 Bob 将会匹配，因为北京被丢弃（>200），其余部分在 | A-B | < 50 范围内：

  • Alice {Montreal: 12.3, Newark: 45.6, Dallas: 59.9, Beijing: 264.4}；以及

  • Bob {Montreal: 27.3, Newark: 32.4, Dallas: 23.1, Beijing: 252.2}。

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

  • Alice {Montreal: 5.7 Newark: 44.2, Dallas: 59.5, Beijing: 263.2}；以及

  • Bob {Montreal: 57.8, Newark: 32.0, Dallas: 24.2, Beijing: 272.3}。

请注意，“延迟规则”在您的初始配置规则中只能定义一次。

3. 查看实例详情​

在您的新配对器初始化后，在我们的仪表板中查看其详细信息：

Status 指示服务健康状况，可能是 ONLINE、OFFLINE 或 ERROR。

• Identifier 可帮助 Edgegap 工作人员在您需要排错帮助时快速找到您的配对器。

• Started at 可用于追踪最新的更新时间。

• Size 对应于我们的一个 价格层级。

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

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

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

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

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

4. 测试票证 API

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

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

将此页面作为文件保存到您的驱动器中 (CTRL/CMD+S)。

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

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

• 保持勾选 Postman Collection，

• 选择 View Import Settings 并将设置 Parameter generation 更改为 Example。

确认导入，这将在左侧的“Collections”列表中显示一个名为 Matchmaker 的新集合。

查看更多操作，打开标签页 Authorization 并选择：

• Auth Type - API Key，

• Key - “Authorization”

• Value - 在此处插入您的 AuthToken 值，

• Add to - Header。

按下 (CTRL/CMD+S) 或保存图标以 保存更改。您 Postman 标签页中的橙色圆点应该会消失。

在您的 Matchmaker 集合中，选择 tickets 和 Create a matchmaking ticket，打开一个新标签页。

选择标签页 Body 以预览您的 玩家票证请求：

请注意 player_ip 设置为 null- 这将导致使用自动添加到您的请求中的 IP 地址（其他选择请参见 服务器对服务器整合），

• profile 指向您的 對局配對配置文件，

• attributes 包含您的配对器规则的值，在此例中用于 latencies 规则，

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

注意：请务必参考示例的 Swagger 导入配置。 

点击 Send 并查看对您的玩家票证请求的响应：

• id 是您唯一的對局配對票证 ID，请保存此 ID 以便稍后检查您的票证，

• profile 确认了 對局配對配置文件 的选择，

• group_id 是向每张票证发放的唯一组 ID，单人玩家表示为 1 人的组，

  • 关于与您的朋友或大厅进行對局配對，请参见 作为组加入，

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

• assignment 设置为 null ，表示票证尚未匹配或分配到服务器，

• created_at 提供了关于玩家票证何时创建的信息，供游戏 UI 使用，

• status 指示票证的当前状态，所有票证均从 SEARCHING 开始（详情请参见 對局配對流程）。

再次点击 Send 来创建第二张票证，这样我们的两名玩家就会匹配并启动一台服务器。

在您的 Matchmaker 集合中，选择 {ticketId} 并选择 Read a matchmaking ticket。

输入上一步响应中的票证 ID，然后点击 Send。

查看您玩家票证的更新分配情况：

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

再次点击 Send 以检查您的票证，并查看您玩家票证的更新分配情况：

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

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

• 请注意，每次部署都会标有所有票证 ID 和配置文件，以提高可追溯性。

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

一旦您验证能够毫无问题地连接到您的部署并完成测试，请 停止您的部署 以释放您账户中的容量，供下一个构建使用。

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

5. 在您的游戏中整合配对器​

Edgegap 的對局配對整合：

• 与 游戏客户端 整合，以管理 玩家票证，

• 与 游戏服务器 整合，以：

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

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

对于 游戏客户端，我们建议在整个 對局配對流程 中，通过游戏内 UI 向玩家提供票证状态更新，以获得最佳的玩家体验。参见：

• Edgegap - Unity Gen2 Matchmaking SDK，

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

• Betide Studio - Unreal Engine Edgegap Integration Kit，

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

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

• HTTP 404 Not Found - 票证已被删除，

• HTTP 500 Internal Server Error - 暂时性服务中断。

在 游戏服务器 中，处理玩家偏好和初始服务器上下文。不需要 API 整合：

1. 阅读 注入的环境变量 (Gen2) 以检索初始玩家的對局配對数据。

2. 阅读 注入的环境变量 (App 版本) 以获取特定版本的参数、设置（玩家容量）和机密。

3. 阅读 注入的环境变量 (部署) 以获取部署信息，例如 IP 地址、位置等。

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

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

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

如果发生以下情况，请确保使用 注入的 DELETE_URL 妥善 停止您的部署：

• 没有玩家加入对局，

• 所有玩家都已离开对局，

• 对局正常结束。

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