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

-> 本文基于對局配對文档。如果您遇到问题或差异，请确保参阅原始指南，因为它们更常被更新。

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

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

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

• 最后，使用我们的玩家票据和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": {
    "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）资源量的 应用版本。

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

• 您选择的名称，例如 - 组合大小，

• 规则类型，也称为运算符，例如 - player_count，

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

玩家数量规则

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

• team_count 指的是团队数量，1个团队可用于合作或全员对战模式，

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

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

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

延迟规则

使用此规则为所有玩家提供最低的可能的延迟。一旦客户端测量并提交他们对所有可用信标的往返时间（ping），Gen2将仅在指定的 difference ping值内考虑匹配，根据 延迟信标测量。此方法为划分您的玩家群体提供“软”解决方案，使得与邻近地区的匹配，特别是为人口较少的地区提高匹配速度。使用 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 是我们提供的OpenAPI规范GUI，用于探索API架构。

• 认证令牌是游戏客户端和游戏服务器用于认证的独特秘密令牌。

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

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

4. 测试票据API

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

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

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

打开您的Postman应用程序，登录您的免费帐户。

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

• 保持Postman集合为选中状态，

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

确认导入，这将在左侧集合列表中显示一个名为对局配对的新集合。

查看更多操作，打开授权选项卡并选择：

• 认证类型 - API密钥，

• 密钥 - “认证”

• 值 - 在这里插入您的 认证令牌，

• 添加到 - Header。

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

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

选择Body选项卡以预览您的 玩家票据请求：

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

• profile 指的是您的 对局配对配置文件，

• 属性 包括对局配对规则的值，在此案例中用于 延迟规则，

  • 规则 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. 阅读 注入的环境变量 (应用版本) 以获取版本特定的参数、设置（玩家容量）和秘密。

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

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

当游戏客户端 完全加载后，玩家会加载/移动到主要的游戏场景。

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

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

• 没有玩家加入比赛，

• 所有玩家已离开比赛，

• 比赛正常结束。

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