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

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

以下示例将帮助您测试核心对局配对玩家流程，包括：

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

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

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

实施对局配对器到您的游戏中有五个步骤：

1. 第一步是创建一个账户并使用我们的合作游戏示例。Voilà，您（技术上）已经完成一半！您只需将对局配对器集成到您的游戏中（参见步骤5）。

2. 现在，您绝不应盲目跟随您在互联网上找到的JSON示例，因此强烈建议根据上述规则适应您的回合制游戏。步骤2（“探索配置”）是我们的“如何阅读”，其中深入探讨每个对局配对规则功能（“探索配置”）。

3. 第3步（“审查实例详情”）涵盖了您个人的特定对局配对器，以确保它已部署并与您的游戏设计协同工作。

4. 正如名称所示，步骤4（“4. 测试票据API”）完全是关于测试来自玩家的对局配对请求是否被称为票据的对局配对器接收到。

5. 第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": {
    "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. 探索配置​

独特的多人合作游戏规则

专门针对合作游戏，您可以定义多个 对局配对档案 用于具体游戏模式的规则和设置：

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

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

• 限制玩家等级差异以使玩家处于相似的游戏进度水平，

• 组队加入 用于预制的大厅或不超过团队规模的组队，

• 允许更高的延迟以更快的速度进行匹配并提供更精细的玩家偏好，

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

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

• 随时间放宽延迟限制以寻找更多玩家，

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

  • 还可以选择让服务器用AI队友填补空位，

• 逐渐增加允许的玩家等级差异以寻找更多玩家，

• 如果没有找到队友，则单独启动游戏并使用 补位 稍后添加玩家。

语义版本化

随着我们发布对局配对的更新，每个新版本都使用 语义版本化 以清楚地传达更改的影响，解释格式 major.minor.patch：

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

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

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

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

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

我们的对局配对逻辑核心在 对局配对档案中配置。每个档案是一个完全隔离的对局配对队列，指向 应用版本 具有预定义的所需CPU和内存（RAM）资源。

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

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

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

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

玩家计数规则

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

• 团队数量 指的是团队的数量，1个团队可用于合作模式或所有人对所有模式，

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

我们的简单示例展示了一款由2名玩家组成的合作游戏。

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

延迟规则

使用此规则为所有玩家提供最低可能的延迟。当客户端测量并提交其所有可用信标的往返时间（ping）时，Gen2仅会考虑在特定的 差异 内的匹配，针对 ping信标测量。这呈现了一种“软”解决方案，用于分割您的玩家群体，启用与邻近地区的匹配，尤其改善人口较少地区的匹配速度。使用 最大延迟可防止与远离的玩家进行匹配。

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

我们的示例 信标 规则上面提供 "差异": 50, "最大延迟": 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是我们提供用于探索API架构的便捷openAPI规范界面。

• 授权令牌是一个用来进行身份验证的唯一秘密令牌，由游戏客户端和游戏服务器使用。

要使用API测试您的新对局配对器，您将需要Swagger URL、API URL和授权令牌。

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

4. 测试票据API

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

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

将此页面保存为文件到您的驱动器上（CTRL/CMD+S）。

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

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

• 保持 Postman Collection 选中，

• 选择 查看导入设置 并更改设置 参数生成 为 示例。

确认导入，这将导致新集合出现在左侧的集合列表中，标题为对局配对。

查看更多操作，打开标签 授权 并选择：

• 授权类型 - API密钥，

• 密钥 - “授权”

• 值 - 在此处插入您的 授权令牌 值，

• 添加到 - 头部。

按下（CTRL/CMD+S）或保存图标以保存更改。您Postman选项卡中的橙色点应该消失。

在您的对局配对集合中，选择 票据 和 创建对局配对票据，会打开一个新标签。

选择标签 正文以预览您的 玩家票据请求：

注意 player_ip 设置为 null - 这将自动使用添加到您请求中的IP地址（有关替代方法，请参阅 服务器到服务器集成），

• 档案 指的是您的 对局配对档案，

• 属性 包括对局配对规则的值，在此情况下为 latencies 规则，

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

注意：确保参考示例的Swagger的导入配置。

点击 发送 并查看您的玩家票据请求的响应：

• id 是您独特的对局配对票据ID，请保存以便稍后查看您的票据，

• 档案 确认选择的 对局配对档案，

• group_id 是每个票据生成的唯一组ID，单个玩家被视为1人的组，

  • 参见 组队加入 以与您的朋友或大厅进行对局配对，

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

• assignment 设置为 null 以指示票据尚未匹配或分配到服务器，

• created_at 提供关于何时为玩家票据创建的信息，以便游戏界面使用，

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