如何在你的多人格斗游戏中集成对局配对

-> 本文基于 对局配对文档。如果你遇到问题或差异，请务必参考 原始指南，因为其更新更为频繁。

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

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

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

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

将我们的对局配对器实现到你的游戏中共有 五个步骤：

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

2. 现在，你绝对不应该盲目遵循在互联网上找到的 JSON 示例，因此强烈建议根据你的游戏调整上述规则。步骤 2（“探索配置”）是我们的“如何阅读”指南，深入介绍了每个对局配对规则功能的作用（“探索配置”）。

3. 步骤 3（“查看实例详情”）涵盖了你个人特定的 对局配对器，以确保其已部署并符合你的游戏设计。

4. 步骤 4，顾名思义（“4. 测试票证 API”），完全是关于测试对局配对器是否接收到玩家的对局配对请求，这些请求被称为 票证。

5. 步骤 5（“在游戏中集成对局配对”）强调了如何将对局配对器集成到你的引擎项目中。

如果你遇到排错方面的挑战，我们的深度 学习中心 提供了额外的排错建议。

1. 设置免费层级

注册你的免费 Edgegap 账户，并导航至 对局配对器仪表板页面。

在控制面板中，首先点击 创建对局配对器，然后输入：

• 对局配对器的名称 – 这纯粹是为了你方便参考，例如 quickstart-dev，

• 然后，上传以下简单的 JSON 配置示例，作为你的格斗游戏的配置：

{
  "version": "1.0.0",
  "max_deployment_retry_count": 3,
  "ticket_expiration_period": "5m",
  "ticket_removal_period": "1m",
  "profiles": {
    "casual-example": {
      "application": {
        "name": "my-game-server=>CHANGE-THIS-NAME-HERE",
        "version": "2024.01.30-16.23.00-UTC=>CHANGE-THIS-HERE "
      },
      "rules": {
        "initial": {
          "match_size": {
            "type": "player_count",
            "attributes": {
              "team_count": 2,
              "team_size": 5
            }
          },
          "beacons": {
            "type": "latencies",
            "attributes": {
              "difference": 25,
              "max_latency": 100
            }
          },
          "league_rank": {
            "type": "number_difference",
            "attributes": {
              "max_difference": 1
            }
          },
          "selected_maps": {
            "type": "intersection",
            "attributes": {
              "overlap": 1
            }
          },
          "selected_beacons": {
            "type": "intersection",
            "attributes": {
              "overlap": 1
            }
          }
        },
        "expansions": {
          "10": {
            "beacons": {
              "difference": 40,
              "max_latency": 150
            }
          },
          "30": {
            "beacons": {
              "difference": 50
            }
          },
          "60": {
            "league_rank": {
              "max_difference": 2
            }
          },
          "180": {
            "beacons": {
              "difference": 100,
              "max_latency": 500
            }
          }
        }
      }
    },
    "competitive-example": {
      "application": {
        "name": "my-game-server",
        "version": "2024.01.30-16.23.00-UTC"
      },
      "rules": {
        "initial": {
          "match_size": {
            "type": "player_count",
            "attributes": {
              "team_count": 2,
              "team_size": 5
            }
          },
          "beacons": {
            "type": "latencies",
            "attributes": {
              "difference": 25,
              "max_latency": 100
            }
          },
          "league_rank": {
            "type": "number_difference",
            "attributes": {
              "max_difference": 0
            }
          },
          "selected_maps": {
            "type": "intersection",
            "attributes": {
              "overlap": 1
            }
          },
          "selected_beacons": {
            "type": "intersection",
            "attributes": {
              "overlap": 1
            }
          }
        },
        "expansions": {
          "30": {
            "beacons": {
              "difference": 40,
              "max_latency": 150
            }
          },
          "60": {
            "beacons": {
              "difference": 50
            }
          },
          "180": {
            "beacons": {
              "max_latency": 250
            }
          }
        }
      }
    },
    "challenger-example": {
      "application": {
        "name": "my-game-server",
        "version": "2024.01.30-16.23.00-UTC"
      },
      "rules": {
        "initial": {
          "match_size": {
            "type": "player_count",
            "attributes": {
              "team_count": 2,
              "team_size": 5
            }
          },
          "beacons": {
            "type": "latencies",
            "attributes": {
              "difference": 25,
              "max_latency": 100
            }
          },
          "league_rank": {
            "type": "number_difference",
            "attributes": {
              "max_difference": 0
            }
          },
          "selected_maps": {
            "type": "intersection",
            "attributes": {
              "overlap": 1
            }
          },
          "selected_beacons": {
            "type": "intersection",
            "attributes": {
              "overlap": 1
            }
          }
        },
        "expansions": {
          "30": {
            "beacons": {
              "difference": 40,
              "max_latency": 150
            }
          },
          "180": {
            "beacons": {
              "difference": 50
            }
          },
          "240": {
            "beacons": {
              "max_latency": 250
            }
          }
        }
      }
    }
  }
}

（友情提示，请务必修改应用 名称 和 版本 以匹配你的 应用与版本！）

如果没有出现验证错误，请点击 创建并启动 并等待该过程完成。这将启动一个新的免费集群，运行你的简单示例对局配对器。

你现在可以继续下一步了。

2. 探索配置​

独特的格斗游戏规则

专门针对 格斗游戏，你可以为特定游戏模式的规则和设置定义多个 对局配对配置文件：

• 在休闲游戏中限制两名玩家之间的段位差，

• 在排位赛中限制段位差，仅允许相同段位的对手进行对决，

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

• 添加 大厅选择 UI 来限制对手只能使用特定的 Ping 信号塔，

• 限制 对局配对延迟 在最高阈值内，以防止与距离遥远的玩家进行配对，

• 限制 对局配对延迟 在最大差值内，以最大化 Ping 值的公平性，

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

• 为预先创建的游戏大厅或为了在不超过队伍大小的情况下填满队伍，而使用 作为组队加入。

先从理想条件开始，然后 放宽限制 以确保快速配对：

• 随着时间推移，慢慢放宽延迟限制以找到更多玩家，

• 慢慢增加允许的段位差距以找到更多玩家，

• 增加最高段位（挑战者）在每次放宽限制之间的等待时间，因为可用玩家较少。

在晋级赛中，创建拥有更高段位的票证，以匹配更强劲的对手。

定义 独立的作弊者配置文件 以确保被标记的作弊者或收到大量举报的玩家不会在排位赛中对守法玩家的游戏体验产生负面影响。

语义化版本控制

每个新版本都使用 语义化版本控制，通过解释 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 名玩家参与的合作游戏。

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

延迟规则

使用此规则为所有玩家提供尽可能低的 Ping 值。一旦客户端测量并提交了他们对所有可用信号塔的往返时间 (Ping)，Gen2 将仅考虑在特定 Ping 值 difference（差值）范围内的对局，该差值是针对 Ping 信号塔 测量的。这为分割你的玩家群体提供了一个“温和”的解决方案，允许与邻近区域进行配对，特别是能提高人口较少区域的配对速度。使用 max_latency（最大延迟）来防止与距离遥远的玩家进行配对。

你现在可以继续下一步了。

我们上面的示例 beacons 规则最初设置为 "difference": 50, "max_latency": 200：

• 爱丽丝 (Alice) 和鲍勃 (Bob) 将会匹配成功，因为北京被排除（>200），其余的在 | A-B | < 50 范围内：

  • 爱丽丝 {蒙特利尔: 12.3, 纽瓦克: 45.6, 达拉斯: 59.9, 北京: 264.4}；以及

  • 鲍勃 {蒙特利尔: 27.3, 纽瓦克: 32.4, 达拉斯: 23.1, 北京: 252.2}。

• 查理 (Charlie) 和戴夫 (Dave) 将不会匹配，因为对于达拉斯信号塔，| C-D | > 50：

  • 爱丽丝 {蒙特利尔: 5.7, 纽瓦克: 44.2, 达拉斯: 59.5, 北京: 263.2}；以及

  • 鲍勃 {蒙特利尔: 57.8, 纽瓦克: 32.0, 达拉斯: 24.2, 北京: 272.3}。

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

3. 查看实例详情​

在你的新对局配对器初始化后，在我们的控制面板中查看其详细信息：

状态 指示服务健康状况，可能是 ONLINE（在线）、OFFLINE（离线）或 ERROR（错误）。

• 标识符 可在你需要排错帮助时，协助 Edgegap 工作人员快速找到你的对局配对器。

• 启动于 对于追踪最新的更新时间非常有用。

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

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

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

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

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

你现在可以继续下一步了。

4. 测试票证 API

首先，打开你的 Swagger URL，在 Swagger GUI 中检查你的 OpenAPI 架构

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

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

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

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

• 保持勾选 Postman 集合，

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

确认导入，这将在左侧的“集合”列表中生成一个名为“Matchmaker”的新集合。

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

• 授权类型 - API 密钥，

• 密钥 - “Authorization”

• 值 - 在此处插入你的 验证令牌 (AuthToken) 的值，

• 添加到 - 请求头 (Header)。

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

在你的对局配对器 (Matchmaker) 集合中，选择 tickets（票证）和 创建对局配对票证，这将打开一个新的标签页。

选择标签页 正文 (Body) 来预览你的 玩家票证请求：

注意 player_ip 被设置为 null——这将导致自动使用添加到你请求中的 IP 地址（其他选择请参见 服务器到服务器集成），

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

• attributes 包括你的对局配对器规则的值，在这种情况下是针对 latencies（延迟）规则，

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

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

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

• id 是你的唯一对局配对票证 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 的对局配对集成包括：

• 与 游戏客户端 集成，以管理 玩家票证，

• 与 游戏服务器 集成，以：

  • 处理通过其票证传递的玩家偏好，

  • （可选）支持 回填 (Backfill) 以在游戏开始后添加或替换玩家。

在 游戏客户端 中，我们建议在整个 对局配对流程 中使用游戏内 UI 向玩家提供票证状态更新，以获得最佳的玩家体验。参见：

• Edgegap - Unity Gen2 对局配对 SDK，

  • 导入简单示例 并根据你的需求进行自定义，

• Betide Studio - Unreal Engine Edgegap 集成套件，

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

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

• HTTP 404 Not Found - 票证已被删除，

• HTTP 500 Internal Server Error - 临时服务中断。

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

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

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

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

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

一旦 游戏客户端 完全加载，玩家将加载/转移到主游戏场景中。

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

如果发生以下情况，请确保使用 注入的 DELETE_URL 妥善 停止你的部署：

• 没有玩家加入对局，

• 所有玩家都已离开对局，

• 对局正常结束。

恭喜，你已完成了 Edgegap 对局配对器的集成！如果你想了解更多，欢迎在我们的 学习中心 阅读所有相关内容。