如何将匹配机制整合到您的生存多人游戏中

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

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

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

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

• 最后，使用我们的 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）资源的 应用版本。

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

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

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

• 最后是运算符属性，例如 团队数量 或 团队规模。

玩家数量规则

这是一个特殊规则，定义了在分配之前需要匹配的玩家数量：

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

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

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

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

延迟规则

使用此规则为所有玩家提供尽可能低的延迟。当客户端测量并提交其往返时间（延迟）与所有可用信标时，Gen2只会考虑在特定的 差异 延迟值内的匹配，测量的是 延迟信标。这为您的玩家基础提供了一种“软”解决方案，使其能够与邻近地区匹配，特别是改善少数地区的匹配速度。使用 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 是我们提供的方便的开源API规范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 包含针对您的匹配器规则的值，在这种情况下是 延迟 规则，

  • 规则 玩家数量 是唯一不要求在玩家票据中包含任何属性的规则。

注意:请确保参考样本的 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的匹配机制整合：

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

• 与 游戏服务器，以：

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

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

对于 游戏客户端，我们建议提供票据状态更新，通过 匹配机制流程 在游戏中使用UI提供玩家最佳体验。请参见：

• Edgegap - Unity Gen2 匹配SDK，

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

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

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

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

• HTTP 404未找到  - 票据已被删除，

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

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

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

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

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

当玩家连接后， 游戏服务器和游戏客户端 开始加载场景以执行同步步骤（例如选择和加载地图/场景/等级）。我们建议一个完整的3D场景，一个类似大厅的社交UI，或带有进度条的加载屏幕，以指示初始化正在进行。

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

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

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

• 没有玩家加入比赛，

• 所有玩家都已离开比赛，

• 比赛正确结束。

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