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

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

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

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

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

• 最后，使用我们的玩家票证与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来清晰传达更改的影响：

• 主要 版本包括重大更改并需要集成审查，

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

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

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

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

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

對局配對规则在初始规则集中必须达到才能将玩家分组在一起，每个规则由三个属性定义：

• 自选的名称，例如 - 对局大小，

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

• 最后是操作符属性，例如 队伍数 或 队伍大小。

玩家数量规则

这是一个定义启动分配所需匹配玩家数量的特殊规则：

• 队伍数 指队伍的数量，1 队可用于合作或自由模式，

• 队伍大小 指每队的 玩家数量。

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

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

延迟规则

使用此规则为所有玩家提供尽可能低的 ping。一旦客户端测量并提交他们对所有可用信标的往返时间（ping），Gen2 将仅考虑ping值在特定差异内的匹配，与 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 是我们提供的一个方便的 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 密钥，

• 键 - “Authorization”

• 值 - 在此插入您的 AuthToken 值，

• 添加到 - 头部。

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

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

选择选项卡 正文 以预览您的 玩家票证请求：

注意 player_ip 设置为 null–这将导致自动添加到您的请求的 IP 地址（请参见 服务器对服务器集成 了解替代方案），

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

• 属性 包括适用于您的对局配对规则的值，在这种情况下适用于 延迟 规则，

  • 规则 玩家数 是唯一一个不需要在玩家票证中指定属性的规则。

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

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

• id 是您的唯一对局配对票证 ID，请保存以便稍后查看您的票证，

• 配置文件 确认选择的对局配对配置文件，

• 群组ID 是发给每个票证的唯一群组 ID，一个独立玩家被表示为群组1，

  • 请参见 组队加入 以朋友或大厅形式进行对局配对，

• player_ip 是玩家的已解析公共IP地址，无论使用何种身份验证方法，

• 分配 设置为 null 以表示票证尚未匹配或分配给服务器，

• 创建于 提供关于票证何时为游戏 UI 使用创建的信息，

• 状态 指示票证的当前状态，所有票证均以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对局配对集成！如果您想了解更多，请在我们的学习中心中阅读所有相关信息。