如何将對局配對集成到您的多人Roguelike游戏中

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

以下示例将帮助您测试核心對局配對玩家流程：

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

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

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

将我们的配对者集成到您的游戏中有五个步骤：

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

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

3. 步骤3（“审查实例详细信息”）涵盖您的个人、特定配对者 以确保其部署并与您的游戏设计兼容。

4. 步骤4，正如其名称所示（“4. 测试票证API”），完全是关于测试玩家的對局配對请求由配对者接收到的请求，称为票证。

5. 步骤5（“在您的游戏中集成對局配對”）强调如何在您的引擎项目中集成配对者。

如果您遇到故障排除问题，我们的深入学习中心有额外的故障排除技巧。

1. 设置免费层

注册您的免费Edgegap帐户，然后导航到 配对者仪表板页面。

从那里开始，点击 创建配对者 ，然后输入：

• 为您的配对者命名——这仅供您自己参考，例如 quickstart-dev，

• 然后上传以下简单示例作为您Roguelike游戏的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": {}
      }
    }
  }
}

（友情提醒，请务必确保更改应用程序 名称 和 版本 以匹配您的 应用程序和版本！）

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

您现在可以进行下一步。

2. 探索配置​

独特的多人Roguelike游戏规则

自定义大厅（私人大厅、沙盒级别）是沙发多人游戏的一个非常受欢迎的选项，但也在竞争或合作游戏中测试新功能，然后才进入主要游戏模式。这些游戏通常需要最少的限制，但旨在确保玩家可以以组加入。

回填票证可以使用自定义大厅配置文件来支持可靠地邀请朋友，只要回填票证有效。

• 提示：将custom-lobby-example配置文件添加到您的配置中，以及其他配置文件，以支持自定义大厅。

语义版本控制

随着我們发布對局配對的更新，每个新版本都使用 语义版本控制 通过解释格式 major.minor.patch清楚地传达变更的影响：

• major 版本包括破坏性变更，需要进行集成审查，

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

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

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

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

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

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

• 您选择的名称，例如- 比赛大小，

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

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

玩家计数规则

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

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

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

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

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

延迟规则

使用此规则为所有玩家提供最低可能的ping值。一旦客户端测量并提交他们在所有可用信标上的往返时间（ping），Gen2只会考虑在Ping信标对指定的差异ping值内的比赛。这提供了一个“软”解决方案来划分您的玩家基础，使其可以与邻近地区配对，尤其是改善较少人口地区的配对速度。使用 max_latency 以防止与远距离的玩家配对。

您现在可以进行下一步。

我们上面例子的 信标 规则，最初设置差别“相差”: 50，最大延迟：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. 检查实例详情​

配对者初始化后，通过我们的仪表板检查您的新配对者的详细信息：

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

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

• 启动时间 有助于追踪最新的更新时间。

• 大小 对应我们的 定价层之一。

• API网址 将用于游戏客户端和游戏服务器与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密钥，

• 键-“授权”

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

• 添加至- 标题。

按（CTRL/CMD+S）或保存图标以保存更改。 Postman标签中的橙色圆点应消失。

在您的配对者集合中，选择票证 并 创建配对者票证，打开一个新标签。

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

注意到 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 - Unreal Engine Edgegap Integration Kit，

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

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

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

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

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

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

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

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

一旦玩家连接，游戏服务器和游戏客户端 启动加载场景以执行同步步骤（例如，选择和加载地图/场景/关卡）。我们推荐一个全方位的3D场景、一个类似大厅的社交UI或一个带有进度条的加载屏幕，以指示初始化正在进行中。

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

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

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

• 没有玩家加入比赛，

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

• 比赛正确结束。

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