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

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

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

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

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

• 最后，测试玩家流程并管理 玩家票证 与我们的 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. 探索配置​

独特的多人赛车游戏规则

自定义大厅（私人大厅、沙盒级别）是沙发多人游戏非常流行的选择，同时也是在进入主要游戏模式之前测试新功能的好方法。这些游戏通常对于限制的要求最少，但旨在确保玩家可以 作为小组加入。

回填 票证可以使用自定义大厅 profiles 来支持可靠邀请朋友，只要回填票证是有效的。

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

语义版本控制

随着我们发布对配对器的更新，每个新版本使用 语义版本控制 明确传达变更的影响，通过解释格式 major.minor.patch：

• major 版本包括重大变更，并需进行集成审核，

• minor 版本包括大量向后兼容的改进，

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

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

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

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

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

• 您选择的名称，例如 - match size,

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

• 最后是运算符属性，例如 team_count 或 team_size。

玩家数量规则

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

• team_count 指的是队伍的数量，1队伍可用于合作或大乱斗模式，

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

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

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

延迟规则

使用此规则为所有玩家提供最低的可能延迟。一旦客户端测量并提交其往返时间（延迟）与所有可用的信标，Gen2将只考虑在特定 difference 未使用的延迟值进行匹配，与 延迟信标进行比较。这为您提供了一种“软性”解决方案以分割您的玩家基础，允许与邻近区域匹配，特别在减少人口稀少的区域时，提高了配对速度。使用 max_latency来防止与距离很远的玩家的匹配。

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

我们的示例 beacons 规则初始配置如下： "difference": 50, "max_latency": 200：

• Alice 和 Bob 将匹配，因为北京被丢弃（>200），而其余匹配内容在 | A-B | < 50范围内：

  • Alice {Montreal: 12.3, Newark: 45.6, Dallas: 59.9, 北京: 264.4}; 和

  • Bob {Montreal: 27.3, Newark: 32.4, Dallas: 23.1, 北京: 252.2}。

• Charlie 和 Dave 不会匹配，因为 | C-D | > 50，对于达拉斯信标：

  • Alice {Montreal: 5.7 Newark: 44.2, Dallas: 59.5, 北京: 263.2}; 和

  • Bob {Montreal: 57.8, Newark: 32.0, Dallas: 24.2, 北京: 272.3}。

请注意，“延迟规则”只能在您的初始配置规则中定义一次。

3. 审核实例详情​

在我们的仪表板中审核新配对器的详细信息，待其初始化后：

状态 指示服务健康状况，可能为在线、离线或错误。

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

• 开始于 对于追踪最新更新时间可能很有用。

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

• API URL 将被游戏客户端和游戏服务器用来与 Gen2 进行通信。

• Swagger URL 是我们提供的方便的 openAPI 规范 GUI，用于探索 API 架构。

• Auth Token 是游戏客户端和游戏服务器用于身份验证的唯一密钥。

要使用 API 测试您的新配对器， 您将需要 Swagger URL、API URL 和 Auth Token。

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

4. 测试票证 API

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

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

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

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

导入您在前一步中下载的 swagger.json 文件：

• 保持 Postman Collection 被选中，

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

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

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

• 授权类型 - API 密钥,

• 密钥 - “授权”

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

• 添加到 - 头部。

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

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

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

请注意 player_ip 设置为 null- 这将自动使用添加到您的请求中的 IP 地址（请参见 服务器到服务器集成 获取替代选项），

• profile 指的是您的 配对配置文件,

• attributes 包括您的配对规则的值，在这种情况下是针对 latencies 规则，

  • 规则 player_count 是唯一不需要任何属性的票证规则。

注意: 请务必参考示例的 Swagger 的导入配置。

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

• id 是您独特的配对票证 ID，请牢记以便稍后检查您的票证，

• profile 确认选择的 配对配置文件,

• group_id 是分配给每个票证的唯一组 ID，单个玩家被视为一个组，

  • 请参见 作为小组加入 与朋友或大厅进行配对，

• player_ip 是玩家的公共 IP 地址，使用 Method 并无关，

• 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 - 虚幻引擎 Edgegap 集成工具包,

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

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

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

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

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

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

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

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

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

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

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

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

• 没有玩家加入比赛，

• 所有玩家已离开比赛，

• 比赛正确结束。

恭喜您，您已完成 Edgegap 配对器的集成！如果您想了解更多，请阅读我们 学习中心 中的所有内容。