了解Edgegap的工作原理

了解Edgegap的工作原理

如何在MMORPG游戏中添加匹配系统

已发布

已发布

已发布

如何在MMORPG游戏中添加匹配系统

关键洞察

关键洞察

关键洞察

Edgegap 的 匹配系统 是一个完全托管、无限自定义的匹配系统,能够优化全球玩家的分组——在开发你的休闲多人游戏期间使用是免费的。

这也是我们所知道的 唯一 拥有 基于延迟的匹配规则 的匹配系统,能够为你的游戏提供理想的在线多人体验,无论使用何种引擎(Unity、Unreal 等)或游戏服务(EOS、UGS、PlayFab、Heroic Labs Nakama、Braincloud 等)。

由于我们的匹配系统基于参数,因此无需编写代码。集成非常简单,如果需要,我们的 入门指南 将在每一步中指导你。

当你的游戏上线时,由于我们的匹配系统是完全托管的,你无需处理基础设施、错误、停机、可扩展性或数据库管理。我们会为你处理所有的事情。将你的 DevOps 工作负载减少到几乎为零。

如何为您的 MMORPG 多人游戏集成匹配

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

以下示例将帮助您测试核心匹配玩家流程,即:

为您的游戏实现我们的匹配器包含五个步骤:

  1. 第一步是创建账户并使用我们的 MMORPG 游戏示例。Voilà,您(在技术上)已经完成了一半!您只需要在游戏中集成匹配器(见步骤 5)。

  2. 现在,绝不应该盲目遵循在网上找到的 JSON 示例,因此强烈建议根据您的回合制游戏调整上述规则。步骤 2(“探索配置”)是我们的“阅读指南”,深入介绍了每个匹配规则函数的功能(“探索配置”)。

  3. 步骤 3(“查看实例详情”)涵盖您专属的特定匹配器,以确保其已部署并与您的游戏设计相配合。

  4. 步骤 4,正如其名(“4. 测试票证 API”),完全是关于测试匹配器是否成功接收了来自玩家的匹配请求(称为票证 (tickets))。

  5. 步骤 5(“在游戏中集成匹配”)重点介绍如何在您的引擎项目中集成匹配器。

如果您在排查问题时遇到困难,我们深入详尽的学习中心提供了额外的排障提示。

1. 设置免费层级

注册您的免费 Edgegap 账户,并前往 Matchmaker 仪表板页面。

在那里,先点击 Create Matchmaker ,然后输入:

  • 您的匹配器的名称 —— 这纯粹供您自己参考,例如 quickstart-dev,

  • 然后,上传以下简单的 JSON 配置示例,用于您的 MMORPG 游戏:

{
  "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 以匹配您的 应用程序和版本!)

如果没有出现验证错误,请点击 Create and Start 并等待过程完成。这将启动一个新的免费集群,其中包含您的“简单示例”匹配器。

您现在可以进入下一步。

2. 探索配置​

独特的多人 MMORPG 游戏规则

自定义大厅(私有大厅、沙盒关卡)是本地多人游戏非常受欢迎的选择,同时也是在竞争或合作游戏的新功能进入主要游戏模式之前对其进行测试的极佳方式。这些游戏通常需要最少的限制,但旨在确保玩家能够成组加入。

回填 (Backfill) 票证可以使用“自定义大厅”配置文件来可靠地支持邀请好友,只要回填票证有效即可。

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

语义化版本控制

随着我们向 Matchmaker 发布更新,每个新版本都使用 语义化版本控制 通过解释 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。

玩家计数规则 (Player Count Rule)

这是一条特殊规则,定义了需要匹配多少名玩家才能发起分配:

  • team_count 指队伍数量,合作模式或混战模式可使用 1 支队伍,

  • team_size 指每队玩家数量。

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

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

延迟规则 (Latencies Rule)

使用此规则为所有玩家提供尽可能低的延迟 (ping)。一旦客户端测量并提交了针对所有可用信标的往返时间 (ping),Gen2 将仅考虑 ping 值在特定 difference 以内的匹配(针对 Ping 信标进行测量)。这提供了一种拆分玩家群体的“温和”解决方案,能够与邻近地区进行匹配,尤其可以提高人口较少地区的匹配速度。使用 max_latency 防止与距离较远的玩家进行匹配。

您现在可以进入下一步。

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

  • Alice 和 Bob 将会匹配,因为北京被舍弃 (>200),其余均在 | A-B | < 50 范围内:

    • Alice {Montreal: 12.3, Newark: 45.6, Dallas: 59.9, Beijing: 264.4};以及

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

  • Charlie 和 Dave 不会匹配,因为达拉斯信标的 | C-D | > 50:

    • Alice {Montreal: 5.7 Newark: 44.2, Dallas: 59.5, Beijing: 263.2};以及

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

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

3. 查看实例详情​

在我们的仪表板初始化完成后,查看新匹配器的详细信息:

Status 表示服务健康状况,可能为 ONLINE、OFFLINE 或 ERROR。

  • Identifier 有助于 Edgegap 员工在您需要排查问题时快速找到您的匹配器。

  • Started at 有助于追踪最新的更新时间。

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

  • API URL 将由游戏客户端和游戏服务器用于与 Gen2 通信。

  • Swagger URL 是我们提供的便捷 openAPI 规范 GUI,用于浏览 API 架构模式。

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

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

您现在可以进入下一步。

4. 测试票证 API

首先,打开您的 Swagger URL 以在 swagger GUI 中检查您的 openAPI 架构模式

点击“Matchmaker”标题下方的 /...swagger.json URL 打开原始 JSON 模式:

将此页面作为文件保存到您的驱动器上 (CTRL/CMD+S)。

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

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

  • 保持选中 Postman Collection,

  • 选择 View Import Settings 并将设置 Parameter generation 更改为 Example。

确认导入,这将在左侧的 Collections 列表中出现一个名为 Matchmaker 的新集合。

View more actions,打开标签页 Authorization 并选择:

  • Auth Type - API Key,

  • Key - “Authorization”

  • Value - 在此处插入您的 AuthToken 值,

  • Add to - Header。

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

在您的 Matchmaker 集合中,选择 tickets 和 Create a matchmaking ticket,打开一个新标签页。

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

请注意 player_ip 设置为 null - 这将使用自动添加到您请求中的 IP 地址(其他替代方案请参见 服务器到服务器集成),

  • profile 指您的 匹配配置文件,

  • attributes 包含您的匹配器规则的值,在本例中为 latencies 规则,

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

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

点击 Send 并查看对玩家票证请求的响应:

  • id 是您唯一的匹配票证 ID,请保存好此 ID 以便稍后查看您的票证,

  • profile 确认所选的 匹配配置文件,

  • group_id 是发给每张票证的唯一定组 ID,单人玩家表示为 1 人组,

    • 有关与好友或大厅匹配的信息,请参见 成组加入,

  • player_ip 是玩家解析出的公网 IP 地址,无论使用何种识别方法,

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

  • created_at 提供有关何时创建玩家票证的信息,供游戏 UI 使用,

  • status 表示票证的当前状态,所有票证均以 SEARCHING 开头(详情请参见 匹配流程)。

再次点击 Send 创建第二张票证,以便我们的两名玩家进行匹配并启动服务器。

在您的 Matchmaker 集合中,选择 {ticketId} 和 Read a matchmaking ticket。

输入上一步响应中的票证 ID 并点击 Send。

查看玩家票证的更新分配:

  • 状态首先更改为 MATCH_FOUND,同时保持 assignment 设置为 null,以表示玩家已匹配且正在分配服务器,

再次点击 Send 以检查您的票证,并查看玩家票证的更新分配:

  • 状态更改为 HOST_ASSIGNED,其中 assignment 包含所分配服务器的详细信息。

 在我们的仪表板中检查您的新部署:

  • 请注意,每个部署都标有所有票证 ID 和配置文件,以增加可追溯性。

尝试从游戏客户端连接到分配的服务器。

验证能够顺利连接到您的部署并完成测试后,停止您的部署以释放账户容量供下一次构建使用。

您现在可以进入下一步。

5. 在游戏中集成匹配器​

Edgegap 的匹配集成了:

  • 与游戏客户端,用于管理玩家票证,

  • 与游戏服务器,用于:

    • 处理通过玩家票证传递的偏好设置,

    • 可选择支持 回填 以在启动后添加或更换玩家。

对于游戏客户端内部,我们建议使用游戏内 UI 在整个匹配流程中向玩家提供票证状态更新,以获得最佳玩家体验。请参阅:

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

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

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

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

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

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

  3. 读取 注入的环境变量 (Deployment) 以获取部署信息,例如 IP 地址、位置等。

玩家连接后,游戏服务器和游戏客户端启动加载场景以执行同步步骤(例如选择并加载地图/场景/关卡)。我们建议使用成熟的 3D 场景、类似大厅的社交 UI 或带有进度条的加载屏幕,以指示初始化正在进行。

一旦游戏客户端完全加载,玩家就会加载/传送至主游戏场景。

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

确保在满足以下条件时,使用 注入的 DELETE_URL 正确停止您的部署:

  • 没有玩家加入比赛,

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

  • 比赛正常结束。

恭喜,您已完成 Edgegap Matchmaker 集成!如果您想了解更多信息,请在我们的学习中心阅读所有相关内容。

如何为您的 MMORPG 多人游戏集成匹配

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

以下示例将帮助您测试核心匹配玩家流程,即:

为您的游戏实现我们的匹配器包含五个步骤:

  1. 第一步是创建账户并使用我们的 MMORPG 游戏示例。Voilà,您(在技术上)已经完成了一半!您只需要在游戏中集成匹配器(见步骤 5)。

  2. 现在,绝不应该盲目遵循在网上找到的 JSON 示例,因此强烈建议根据您的回合制游戏调整上述规则。步骤 2(“探索配置”)是我们的“阅读指南”,深入介绍了每个匹配规则函数的功能(“探索配置”)。

  3. 步骤 3(“查看实例详情”)涵盖您专属的特定匹配器,以确保其已部署并与您的游戏设计相配合。

  4. 步骤 4,正如其名(“4. 测试票证 API”),完全是关于测试匹配器是否成功接收了来自玩家的匹配请求(称为票证 (tickets))。

  5. 步骤 5(“在游戏中集成匹配”)重点介绍如何在您的引擎项目中集成匹配器。

如果您在排查问题时遇到困难,我们深入详尽的学习中心提供了额外的排障提示。

1. 设置免费层级

注册您的免费 Edgegap 账户,并前往 Matchmaker 仪表板页面。

在那里,先点击 Create Matchmaker ,然后输入:

  • 您的匹配器的名称 —— 这纯粹供您自己参考,例如 quickstart-dev,

  • 然后,上传以下简单的 JSON 配置示例,用于您的 MMORPG 游戏:

{
  "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 以匹配您的 应用程序和版本!)

如果没有出现验证错误,请点击 Create and Start 并等待过程完成。这将启动一个新的免费集群,其中包含您的“简单示例”匹配器。

您现在可以进入下一步。

2. 探索配置​

独特的多人 MMORPG 游戏规则

自定义大厅(私有大厅、沙盒关卡)是本地多人游戏非常受欢迎的选择,同时也是在竞争或合作游戏的新功能进入主要游戏模式之前对其进行测试的极佳方式。这些游戏通常需要最少的限制,但旨在确保玩家能够成组加入。

回填 (Backfill) 票证可以使用“自定义大厅”配置文件来可靠地支持邀请好友,只要回填票证有效即可。

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

语义化版本控制

随着我们向 Matchmaker 发布更新,每个新版本都使用 语义化版本控制 通过解释 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。

玩家计数规则 (Player Count Rule)

这是一条特殊规则,定义了需要匹配多少名玩家才能发起分配:

  • team_count 指队伍数量,合作模式或混战模式可使用 1 支队伍,

  • team_size 指每队玩家数量。

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

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

延迟规则 (Latencies Rule)

使用此规则为所有玩家提供尽可能低的延迟 (ping)。一旦客户端测量并提交了针对所有可用信标的往返时间 (ping),Gen2 将仅考虑 ping 值在特定 difference 以内的匹配(针对 Ping 信标进行测量)。这提供了一种拆分玩家群体的“温和”解决方案,能够与邻近地区进行匹配,尤其可以提高人口较少地区的匹配速度。使用 max_latency 防止与距离较远的玩家进行匹配。

您现在可以进入下一步。

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

  • Alice 和 Bob 将会匹配,因为北京被舍弃 (>200),其余均在 | A-B | < 50 范围内:

    • Alice {Montreal: 12.3, Newark: 45.6, Dallas: 59.9, Beijing: 264.4};以及

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

  • Charlie 和 Dave 不会匹配,因为达拉斯信标的 | C-D | > 50:

    • Alice {Montreal: 5.7 Newark: 44.2, Dallas: 59.5, Beijing: 263.2};以及

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

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

3. 查看实例详情​

在我们的仪表板初始化完成后,查看新匹配器的详细信息:

Status 表示服务健康状况,可能为 ONLINE、OFFLINE 或 ERROR。

  • Identifier 有助于 Edgegap 员工在您需要排查问题时快速找到您的匹配器。

  • Started at 有助于追踪最新的更新时间。

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

  • API URL 将由游戏客户端和游戏服务器用于与 Gen2 通信。

  • Swagger URL 是我们提供的便捷 openAPI 规范 GUI,用于浏览 API 架构模式。

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

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

您现在可以进入下一步。

4. 测试票证 API

首先,打开您的 Swagger URL 以在 swagger GUI 中检查您的 openAPI 架构模式

点击“Matchmaker”标题下方的 /...swagger.json URL 打开原始 JSON 模式:

将此页面作为文件保存到您的驱动器上 (CTRL/CMD+S)。

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

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

  • 保持选中 Postman Collection,

  • 选择 View Import Settings 并将设置 Parameter generation 更改为 Example。

确认导入,这将在左侧的 Collections 列表中出现一个名为 Matchmaker 的新集合。

View more actions,打开标签页 Authorization 并选择:

  • Auth Type - API Key,

  • Key - “Authorization”

  • Value - 在此处插入您的 AuthToken 值,

  • Add to - Header。

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

在您的 Matchmaker 集合中,选择 tickets 和 Create a matchmaking ticket,打开一个新标签页。

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

请注意 player_ip 设置为 null - 这将使用自动添加到您请求中的 IP 地址(其他替代方案请参见 服务器到服务器集成),

  • profile 指您的 匹配配置文件,

  • attributes 包含您的匹配器规则的值,在本例中为 latencies 规则,

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

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

点击 Send 并查看对玩家票证请求的响应:

  • id 是您唯一的匹配票证 ID,请保存好此 ID 以便稍后查看您的票证,

  • profile 确认所选的 匹配配置文件,

  • group_id 是发给每张票证的唯一定组 ID,单人玩家表示为 1 人组,

    • 有关与好友或大厅匹配的信息,请参见 成组加入,

  • player_ip 是玩家解析出的公网 IP 地址,无论使用何种识别方法,

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

  • created_at 提供有关何时创建玩家票证的信息,供游戏 UI 使用,

  • status 表示票证的当前状态,所有票证均以 SEARCHING 开头(详情请参见 匹配流程)。

再次点击 Send 创建第二张票证,以便我们的两名玩家进行匹配并启动服务器。

在您的 Matchmaker 集合中,选择 {ticketId} 和 Read a matchmaking ticket。

输入上一步响应中的票证 ID 并点击 Send。

查看玩家票证的更新分配:

  • 状态首先更改为 MATCH_FOUND,同时保持 assignment 设置为 null,以表示玩家已匹配且正在分配服务器,

再次点击 Send 以检查您的票证,并查看玩家票证的更新分配:

  • 状态更改为 HOST_ASSIGNED,其中 assignment 包含所分配服务器的详细信息。

 在我们的仪表板中检查您的新部署:

  • 请注意,每个部署都标有所有票证 ID 和配置文件,以增加可追溯性。

尝试从游戏客户端连接到分配的服务器。

验证能够顺利连接到您的部署并完成测试后,停止您的部署以释放账户容量供下一次构建使用。

您现在可以进入下一步。

5. 在游戏中集成匹配器​

Edgegap 的匹配集成了:

  • 与游戏客户端,用于管理玩家票证,

  • 与游戏服务器,用于:

    • 处理通过玩家票证传递的偏好设置,

    • 可选择支持 回填 以在启动后添加或更换玩家。

对于游戏客户端内部,我们建议使用游戏内 UI 在整个匹配流程中向玩家提供票证状态更新,以获得最佳玩家体验。请参阅:

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

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

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

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

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

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

  3. 读取 注入的环境变量 (Deployment) 以获取部署信息,例如 IP 地址、位置等。

玩家连接后,游戏服务器和游戏客户端启动加载场景以执行同步步骤(例如选择并加载地图/场景/关卡)。我们建议使用成熟的 3D 场景、类似大厅的社交 UI 或带有进度条的加载屏幕,以指示初始化正在进行。

一旦游戏客户端完全加载,玩家就会加载/传送至主游戏场景。

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

确保在满足以下条件时,使用 注入的 DELETE_URL 正确停止您的部署:

  • 没有玩家加入比赛,

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

  • 比赛正常结束。

恭喜,您已完成 Edgegap Matchmaker 集成!如果您想了解更多信息,请在我们的学习中心阅读所有相关内容。

如何为您的 MMORPG 多人游戏集成匹配

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

以下示例将帮助您测试核心匹配玩家流程,即:

为您的游戏实现我们的匹配器包含五个步骤:

  1. 第一步是创建账户并使用我们的 MMORPG 游戏示例。Voilà,您(在技术上)已经完成了一半!您只需要在游戏中集成匹配器(见步骤 5)。

  2. 现在,绝不应该盲目遵循在网上找到的 JSON 示例,因此强烈建议根据您的回合制游戏调整上述规则。步骤 2(“探索配置”)是我们的“阅读指南”,深入介绍了每个匹配规则函数的功能(“探索配置”)。

  3. 步骤 3(“查看实例详情”)涵盖您专属的特定匹配器,以确保其已部署并与您的游戏设计相配合。

  4. 步骤 4,正如其名(“4. 测试票证 API”),完全是关于测试匹配器是否成功接收了来自玩家的匹配请求(称为票证 (tickets))。

  5. 步骤 5(“在游戏中集成匹配”)重点介绍如何在您的引擎项目中集成匹配器。

如果您在排查问题时遇到困难,我们深入详尽的学习中心提供了额外的排障提示。

1. 设置免费层级

注册您的免费 Edgegap 账户,并前往 Matchmaker 仪表板页面。

在那里,先点击 Create Matchmaker ,然后输入:

  • 您的匹配器的名称 —— 这纯粹供您自己参考,例如 quickstart-dev,

  • 然后,上传以下简单的 JSON 配置示例,用于您的 MMORPG 游戏:

{
  "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 以匹配您的 应用程序和版本!)

如果没有出现验证错误,请点击 Create and Start 并等待过程完成。这将启动一个新的免费集群,其中包含您的“简单示例”匹配器。

您现在可以进入下一步。

2. 探索配置​

独特的多人 MMORPG 游戏规则

自定义大厅(私有大厅、沙盒关卡)是本地多人游戏非常受欢迎的选择,同时也是在竞争或合作游戏的新功能进入主要游戏模式之前对其进行测试的极佳方式。这些游戏通常需要最少的限制,但旨在确保玩家能够成组加入。

回填 (Backfill) 票证可以使用“自定义大厅”配置文件来可靠地支持邀请好友,只要回填票证有效即可。

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

语义化版本控制

随着我们向 Matchmaker 发布更新,每个新版本都使用 语义化版本控制 通过解释 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。

玩家计数规则 (Player Count Rule)

这是一条特殊规则,定义了需要匹配多少名玩家才能发起分配:

  • team_count 指队伍数量,合作模式或混战模式可使用 1 支队伍,

  • team_size 指每队玩家数量。

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

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

延迟规则 (Latencies Rule)

使用此规则为所有玩家提供尽可能低的延迟 (ping)。一旦客户端测量并提交了针对所有可用信标的往返时间 (ping),Gen2 将仅考虑 ping 值在特定 difference 以内的匹配(针对 Ping 信标进行测量)。这提供了一种拆分玩家群体的“温和”解决方案,能够与邻近地区进行匹配,尤其可以提高人口较少地区的匹配速度。使用 max_latency 防止与距离较远的玩家进行匹配。

您现在可以进入下一步。

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

  • Alice 和 Bob 将会匹配,因为北京被舍弃 (>200),其余均在 | A-B | < 50 范围内:

    • Alice {Montreal: 12.3, Newark: 45.6, Dallas: 59.9, Beijing: 264.4};以及

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

  • Charlie 和 Dave 不会匹配,因为达拉斯信标的 | C-D | > 50:

    • Alice {Montreal: 5.7 Newark: 44.2, Dallas: 59.5, Beijing: 263.2};以及

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

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

3. 查看实例详情​

在我们的仪表板初始化完成后,查看新匹配器的详细信息:

Status 表示服务健康状况,可能为 ONLINE、OFFLINE 或 ERROR。

  • Identifier 有助于 Edgegap 员工在您需要排查问题时快速找到您的匹配器。

  • Started at 有助于追踪最新的更新时间。

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

  • API URL 将由游戏客户端和游戏服务器用于与 Gen2 通信。

  • Swagger URL 是我们提供的便捷 openAPI 规范 GUI,用于浏览 API 架构模式。

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

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

您现在可以进入下一步。

4. 测试票证 API

首先,打开您的 Swagger URL 以在 swagger GUI 中检查您的 openAPI 架构模式

点击“Matchmaker”标题下方的 /...swagger.json URL 打开原始 JSON 模式:

将此页面作为文件保存到您的驱动器上 (CTRL/CMD+S)。

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

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

  • 保持选中 Postman Collection,

  • 选择 View Import Settings 并将设置 Parameter generation 更改为 Example。

确认导入,这将在左侧的 Collections 列表中出现一个名为 Matchmaker 的新集合。

View more actions,打开标签页 Authorization 并选择:

  • Auth Type - API Key,

  • Key - “Authorization”

  • Value - 在此处插入您的 AuthToken 值,

  • Add to - Header。

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

在您的 Matchmaker 集合中,选择 tickets 和 Create a matchmaking ticket,打开一个新标签页。

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

请注意 player_ip 设置为 null - 这将使用自动添加到您请求中的 IP 地址(其他替代方案请参见 服务器到服务器集成),

  • profile 指您的 匹配配置文件,

  • attributes 包含您的匹配器规则的值,在本例中为 latencies 规则,

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

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

点击 Send 并查看对玩家票证请求的响应:

  • id 是您唯一的匹配票证 ID,请保存好此 ID 以便稍后查看您的票证,

  • profile 确认所选的 匹配配置文件,

  • group_id 是发给每张票证的唯一定组 ID,单人玩家表示为 1 人组,

    • 有关与好友或大厅匹配的信息,请参见 成组加入,

  • player_ip 是玩家解析出的公网 IP 地址,无论使用何种识别方法,

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

  • created_at 提供有关何时创建玩家票证的信息,供游戏 UI 使用,

  • status 表示票证的当前状态,所有票证均以 SEARCHING 开头(详情请参见 匹配流程)。

再次点击 Send 创建第二张票证,以便我们的两名玩家进行匹配并启动服务器。

在您的 Matchmaker 集合中,选择 {ticketId} 和 Read a matchmaking ticket。

输入上一步响应中的票证 ID 并点击 Send。

查看玩家票证的更新分配:

  • 状态首先更改为 MATCH_FOUND,同时保持 assignment 设置为 null,以表示玩家已匹配且正在分配服务器,

再次点击 Send 以检查您的票证,并查看玩家票证的更新分配:

  • 状态更改为 HOST_ASSIGNED,其中 assignment 包含所分配服务器的详细信息。

 在我们的仪表板中检查您的新部署:

  • 请注意,每个部署都标有所有票证 ID 和配置文件,以增加可追溯性。

尝试从游戏客户端连接到分配的服务器。

验证能够顺利连接到您的部署并完成测试后,停止您的部署以释放账户容量供下一次构建使用。

您现在可以进入下一步。

5. 在游戏中集成匹配器​

Edgegap 的匹配集成了:

  • 与游戏客户端,用于管理玩家票证,

  • 与游戏服务器,用于:

    • 处理通过玩家票证传递的偏好设置,

    • 可选择支持 回填 以在启动后添加或更换玩家。

对于游戏客户端内部,我们建议使用游戏内 UI 在整个匹配流程中向玩家提供票证状态更新,以获得最佳玩家体验。请参阅:

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

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

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

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

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

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

  3. 读取 注入的环境变量 (Deployment) 以获取部署信息,例如 IP 地址、位置等。

玩家连接后,游戏服务器和游戏客户端启动加载场景以执行同步步骤(例如选择并加载地图/场景/关卡)。我们建议使用成熟的 3D 场景、类似大厅的社交 UI 或带有进度条的加载屏幕,以指示初始化正在进行。

一旦游戏客户端完全加载,玩家就会加载/传送至主游戏场景。

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

确保在满足以下条件时,使用 注入的 DELETE_URL 正确停止您的部署:

  • 没有玩家加入比赛,

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

  • 比赛正常结束。

恭喜,您已完成 Edgegap Matchmaker 集成!如果您想了解更多信息,请在我们的学习中心阅读所有相关内容。

如何为您的 MMORPG 多人游戏集成匹配

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

以下示例将帮助您测试核心匹配玩家流程,即:

为您的游戏实现我们的匹配器包含五个步骤:

  1. 第一步是创建账户并使用我们的 MMORPG 游戏示例。Voilà,您(在技术上)已经完成了一半!您只需要在游戏中集成匹配器(见步骤 5)。

  2. 现在,绝不应该盲目遵循在网上找到的 JSON 示例,因此强烈建议根据您的回合制游戏调整上述规则。步骤 2(“探索配置”)是我们的“阅读指南”,深入介绍了每个匹配规则函数的功能(“探索配置”)。

  3. 步骤 3(“查看实例详情”)涵盖您专属的特定匹配器,以确保其已部署并与您的游戏设计相配合。

  4. 步骤 4,正如其名(“4. 测试票证 API”),完全是关于测试匹配器是否成功接收了来自玩家的匹配请求(称为票证 (tickets))。

  5. 步骤 5(“在游戏中集成匹配”)重点介绍如何在您的引擎项目中集成匹配器。

如果您在排查问题时遇到困难,我们深入详尽的学习中心提供了额外的排障提示。

1. 设置免费层级

注册您的免费 Edgegap 账户,并前往 Matchmaker 仪表板页面。

在那里,先点击 Create Matchmaker ,然后输入:

  • 您的匹配器的名称 —— 这纯粹供您自己参考,例如 quickstart-dev,

  • 然后,上传以下简单的 JSON 配置示例,用于您的 MMORPG 游戏:

{
  "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 以匹配您的 应用程序和版本!)

如果没有出现验证错误,请点击 Create and Start 并等待过程完成。这将启动一个新的免费集群,其中包含您的“简单示例”匹配器。

您现在可以进入下一步。

2. 探索配置​

独特的多人 MMORPG 游戏规则

自定义大厅(私有大厅、沙盒关卡)是本地多人游戏非常受欢迎的选择,同时也是在竞争或合作游戏的新功能进入主要游戏模式之前对其进行测试的极佳方式。这些游戏通常需要最少的限制,但旨在确保玩家能够成组加入。

回填 (Backfill) 票证可以使用“自定义大厅”配置文件来可靠地支持邀请好友,只要回填票证有效即可。

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

语义化版本控制

随着我们向 Matchmaker 发布更新,每个新版本都使用 语义化版本控制 通过解释 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。

玩家计数规则 (Player Count Rule)

这是一条特殊规则,定义了需要匹配多少名玩家才能发起分配:

  • team_count 指队伍数量,合作模式或混战模式可使用 1 支队伍,

  • team_size 指每队玩家数量。

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

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

延迟规则 (Latencies Rule)

使用此规则为所有玩家提供尽可能低的延迟 (ping)。一旦客户端测量并提交了针对所有可用信标的往返时间 (ping),Gen2 将仅考虑 ping 值在特定 difference 以内的匹配(针对 Ping 信标进行测量)。这提供了一种拆分玩家群体的“温和”解决方案,能够与邻近地区进行匹配,尤其可以提高人口较少地区的匹配速度。使用 max_latency 防止与距离较远的玩家进行匹配。

您现在可以进入下一步。

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

  • Alice 和 Bob 将会匹配,因为北京被舍弃 (>200),其余均在 | A-B | < 50 范围内:

    • Alice {Montreal: 12.3, Newark: 45.6, Dallas: 59.9, Beijing: 264.4};以及

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

  • Charlie 和 Dave 不会匹配,因为达拉斯信标的 | C-D | > 50:

    • Alice {Montreal: 5.7 Newark: 44.2, Dallas: 59.5, Beijing: 263.2};以及

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

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

3. 查看实例详情​

在我们的仪表板初始化完成后,查看新匹配器的详细信息:

Status 表示服务健康状况,可能为 ONLINE、OFFLINE 或 ERROR。

  • Identifier 有助于 Edgegap 员工在您需要排查问题时快速找到您的匹配器。

  • Started at 有助于追踪最新的更新时间。

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

  • API URL 将由游戏客户端和游戏服务器用于与 Gen2 通信。

  • Swagger URL 是我们提供的便捷 openAPI 规范 GUI,用于浏览 API 架构模式。

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

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

您现在可以进入下一步。

4. 测试票证 API

首先,打开您的 Swagger URL 以在 swagger GUI 中检查您的 openAPI 架构模式

点击“Matchmaker”标题下方的 /...swagger.json URL 打开原始 JSON 模式:

将此页面作为文件保存到您的驱动器上 (CTRL/CMD+S)。

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

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

  • 保持选中 Postman Collection,

  • 选择 View Import Settings 并将设置 Parameter generation 更改为 Example。

确认导入,这将在左侧的 Collections 列表中出现一个名为 Matchmaker 的新集合。

View more actions,打开标签页 Authorization 并选择:

  • Auth Type - API Key,

  • Key - “Authorization”

  • Value - 在此处插入您的 AuthToken 值,

  • Add to - Header。

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

在您的 Matchmaker 集合中,选择 tickets 和 Create a matchmaking ticket,打开一个新标签页。

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

请注意 player_ip 设置为 null - 这将使用自动添加到您请求中的 IP 地址(其他替代方案请参见 服务器到服务器集成),

  • profile 指您的 匹配配置文件,

  • attributes 包含您的匹配器规则的值,在本例中为 latencies 规则,

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

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

点击 Send 并查看对玩家票证请求的响应:

  • id 是您唯一的匹配票证 ID,请保存好此 ID 以便稍后查看您的票证,

  • profile 确认所选的 匹配配置文件,

  • group_id 是发给每张票证的唯一定组 ID,单人玩家表示为 1 人组,

    • 有关与好友或大厅匹配的信息,请参见 成组加入,

  • player_ip 是玩家解析出的公网 IP 地址,无论使用何种识别方法,

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

  • created_at 提供有关何时创建玩家票证的信息,供游戏 UI 使用,

  • status 表示票证的当前状态,所有票证均以 SEARCHING 开头(详情请参见 匹配流程)。

再次点击 Send 创建第二张票证,以便我们的两名玩家进行匹配并启动服务器。

在您的 Matchmaker 集合中,选择 {ticketId} 和 Read a matchmaking ticket。

输入上一步响应中的票证 ID 并点击 Send。

查看玩家票证的更新分配:

  • 状态首先更改为 MATCH_FOUND,同时保持 assignment 设置为 null,以表示玩家已匹配且正在分配服务器,

再次点击 Send 以检查您的票证,并查看玩家票证的更新分配:

  • 状态更改为 HOST_ASSIGNED,其中 assignment 包含所分配服务器的详细信息。

 在我们的仪表板中检查您的新部署:

  • 请注意,每个部署都标有所有票证 ID 和配置文件,以增加可追溯性。

尝试从游戏客户端连接到分配的服务器。

验证能够顺利连接到您的部署并完成测试后,停止您的部署以释放账户容量供下一次构建使用。

您现在可以进入下一步。

5. 在游戏中集成匹配器​

Edgegap 的匹配集成了:

  • 与游戏客户端,用于管理玩家票证,

  • 与游戏服务器,用于:

    • 处理通过玩家票证传递的偏好设置,

    • 可选择支持 回填 以在启动后添加或更换玩家。

对于游戏客户端内部,我们建议使用游戏内 UI 在整个匹配流程中向玩家提供票证状态更新,以获得最佳玩家体验。请参阅:

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

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

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

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

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

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

  3. 读取 注入的环境变量 (Deployment) 以获取部署信息,例如 IP 地址、位置等。

玩家连接后,游戏服务器和游戏客户端启动加载场景以执行同步步骤(例如选择并加载地图/场景/关卡)。我们建议使用成熟的 3D 场景、类似大厅的社交 UI 或带有进度条的加载屏幕,以指示初始化正在进行。

一旦游戏客户端完全加载,玩家就会加载/传送至主游戏场景。

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

确保在满足以下条件时,使用 注入的 DELETE_URL 正确停止您的部署:

  • 没有玩家加入比赛,

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

  • 比赛正常结束。

恭喜,您已完成 Edgegap Matchmaker 集成!如果您想了解更多信息,请在我们的学习中心阅读所有相关内容。

书写者

Edgegap团队

Get your Game Online Easily & in Minutes

立即开始集成!

轻松在线游戏
且在几分钟内