如何将对局配对集成到您的 PvE 多人游戏中

-> 本文基于對局配對文档。如果您遇到问题或差异，请务必参考原始指南，因为它们通常会更频繁地更新。

以下示例将帮助您测试核心matchmaking 玩家流程，即:

• 在共享的Hosting Cluster上创建匹配器实例,

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

• 最后，使用我们的Player Tickets和API测试玩家流程并进行管理。

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

1. 第一步是创建一个帐户并使用我们的 PvE 游戏示例。Voilà，您（技术上）完成了一半！ 您只需在游戏中集成匹配器（见第5步）。

2. 现在，您不应盲目地遵循在互联网上找到的 JSON 示例，因此强烈建议将上述规则调整为您回合制游戏。步骤 2（“探索配置”）是我们的“如何阅读”，深入了解每个對局配對规则functions（“探索配置”）的作用。

3. 步骤 3（“审查实例详情”）涵盖您的个人具体匹配器以确保它已部署并可与您的游戏设计配合使用。

4. 步骤 4，如名称所示（“4. 测试票券 API”），专注于测试您来自玩家的配对请求是否被称为票券的匹配器收到。

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

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

1. 设置免费套餐

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

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

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

• 然后，上传以下简单示例作为您 PvE 游戏的 JSON 配置:

{
  "version": "2.1.0",
  "inspect": true,
  "max_deployment_retry_count": 3,
  "ticket_expiration_period": "5m",
  "ticket_removal_period": "1m",
  "profiles": {
    "cooperative-example": {
      "application": {
        "name": "my-game-server=>CHANG-THIS-HERE",
        "version": "2024.01.30-16.23.00-UTC=>CHANG-THIS-HERE"
      },
      "rules": {
        "initial": {
          "match_size": {
            "type": "player_count",
            "attributes": {
              "team_count": 1,
              "team_size": 4
            }
          },
          "beacons": {
            "type": "latencies",
            "attributes": {
              "difference": 60,
              "max_latency": 60
            }
          },
          "selected_map": {
            "type": "intersection",
            "attributes": {
              "overlap": 1
            }
          },
          "selected_difficulty": {
            "type": "string_equality"
          },
          "player_level": {
            "type": "number_difference",
            "attributes": {
              "max_difference": 10
            }
          }
        },
        "expansions": {
          "5": {
            "beacons": {
              "difference": 80,
              "max_latency": 80
            }
          },
          "10": {
            "player_level": {
              "max_difference": 20
            }
          },
          "20": {
            "match_size": {
              "team_count": 1,
              "team_size": 3
            },
            "beacons": {
              "difference": 100,
              "max_latency": 100
            }
          },
          "30": {
            "match_size": {
              "team_count": 1,
              "team_size": 2
            },
            "beacons": {
              "max_latency": 200
            }
          },
          "60": {
            "match_size": {
              "team_count": 1,
              "team_size": 1
            }
          }
        }
      }
    }
  }
}

（温馨提醒，请确保更改应用程序 name和 version 以匹配您的 应用程序和版本！）

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

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

2. 探索配置​

独特的多人 PvE 游戏规则

特别适合 PvE 游戏，您可以定义多个 對局配對配置文件 以针对特定游戏模式的规则和设置：

• 让玩家提供他们的地图偏好，并选择适合所有人的地图，

• 让玩家选择特定的游戏难度以适合每个人的技能水平，

• 限制玩家级别差异，使玩家具有相似的游戏进度程度，

• 以小组加入 以预先组建的大厅或填充团队以不超过团队规模，

• 允许更高的延迟以更快的比赛速度来享受更好的玩家偏好，

• 在允许更多玩家时使用不同的 🏷️ 应用版本 分配更多的 CPU 或内存。

从理想条件开始，并 扩展限制 以确保快速匹配：

• 随着时间的推移降低延迟限制以找到更多玩家，

• 慢慢减少团队规模以减少所需玩家并更快开始游戏，

  • 或者，您可以让服务器填补空位与 AI 队友搭配，

• 慢慢增加允许的玩家级别差异以找到更多玩家，

• 如果找不到队友，请单独启动游戏，并使用 Backfill 稍后添加玩家。

语义版本控制

随着我们向對局配對发布更新，每个新版本使用 语义版本控制 来清晰传达变更的影响，解释格式 major.minor.patch:

• major 版本包括重大的变化，并需要进行集成审查，

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

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

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

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

我們的對局配對邏輯的核心配置在 對局配對配置文件中。每个配置文件是一个完全隔离的配对队列，指向 应用版本 并具有预定义的所需 CPU 和内存（RAM）资源量。

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

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

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

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

玩家计数规则

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

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

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

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

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

延迟规则

使用此规则为所有玩家提供最低可能的延迟。一旦客户端测量并提交它们对所有可用信标的往返时间（ping），Gen2 将仅考虑在特定 difference ping 值之内的匹配，并测量对 Ping 信标。这提供了一个“软”的解决方案来拆分您的玩家基础，启用与邻近地区的匹配，尤其提高了人口较少地区的匹配速度。使用 max_latency防止与远距离的玩家匹配。

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

我们的示例 beacons 规则与 "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. 审查实例详情​

在我们的仪表板中审查您的新匹配器的详细信息一旦它初始化：

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

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

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

• 大小 对应于我们的某一个 定价层级。

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

• Swagger URL 是我们提供的一个方便的 openAPI 规范 GUI，用于浏览 API 架构。

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

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

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

4. 测试票券 API

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

点击“/...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，保留此 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 的对局配对集成:

  • 与 游戏客户端，以管理 玩家票券，

  • 与 游戏服务器，以：

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

    • 可选支持 Backfill 以在启动后添加或更换玩家。

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

  • Edgegap - Unity Gen2 对局配对 SDK，

    • 导入简单示例，并根据需要自定义，

  • Betide Studio - Unreal Engine Edgegap 集成工具包，

    • 下载示例项目并根据需要定制。

  在游戏客户端中，确保您处理非重试错误：

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

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

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

  1. 读取注入环境变量 (Gen2)以获取初始玩家的对局配对数据。

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

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

  一旦玩家连接，游戏服务器和游戏客户端启动加载场景，以执行同步步骤（如选择和加载地图/场景/等级）。我们建议使用全功能 3D 场景、大厅式的社交界面，或带进度条的加载画面，以指示初始化进展。

  一旦游戏客户端完全加载，玩家则可加载/转至主游戏场景。

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

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

  • 没有玩家加入比赛，

  • 所有玩家离开比赛，

  • 比赛正常结束。

  恭喜您，您已完成 Edgegap 对局配对的集成！如果您想了解更多，请在我们的学习中心中阅读。