了解Edgegap的工作原理

了解Edgegap的工作原理

如何为多人体育游戏添加匹配功能

已发布

已发布

已发布

关键洞察

关键洞察

关键洞察

Edgegap 的 匹配系统 是一个完全管理的、无限可定制的匹配系统,可以最佳地将全球玩家分组——而且在开发您的多人运动游戏期间,它的使用是免费的。

它也是 唯一的 匹配系统(我们所知)具有 基于延迟的匹配规则,为您的游戏提供理想的在线多人体验,无论是引擎(Unity、Unreal 等)还是游戏服务(EOS、UGS、PlayFab、Heroic Labs Nakama、Braincloud 等)。

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

当您的游戏上线时,由于我们的匹配系统是完全管理的,您无需处理基础设施、错误、故障、可扩展性或数据库管理。我们会为您处理所有这些,几乎将您的 DevOps 工作量减少到零。

如何为您的多人体育游戏集成匹配功能

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

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

  • 在共享的托管集群上创建匹配器实例,

  • 在匹配器配置中定义规则和设置,

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

将我们的匹配器实施到您的游戏中有五个步骤:

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

  2. 现在,切勿盲目遵循在网上找到的 JSON 示例,因此强烈建议根据您的体育游戏调整上述规则。步骤 2(“探索配置”)是我们的“阅读指南”,深入探讨了各项匹配规则函数的功能(“探索配置”)。

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

  4. 步骤 4,顾名思义(“4. 测试票据 API”),主要是测试匹配器是否收到来自玩家的匹配请求(称为票据)。

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

如果您遇到故障排除难题,我们详尽的学习中心提供了额外的故障排除提示。

1. 设置免费层

注册您的免费 Edgegap 账户,然后导航至 Matchmaker 仪表板页面。

在该页面中,先点击 Create Matchmaker (创建匹配器),然后输入:

  • 匹配器的名称 – 这纯粹供您自己参考,例如 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
            }
          }
        }
      }
    }
  }
}

(温馨提醒:请务必更改应用程序 name 和 version,以匹配您的 应用程序和版本!)

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

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

2. 探索配置​

体育游戏独有规则

专门针对体育游戏,您可以定义多个 Matchmaking Profiles(匹配配置文件),以设置游戏模式特定的规则和配置:

  • 限制两名玩家之间的段位分差,适用于较休闲的游戏,

  • 在排位赛中严格限制段位分差,只允许相同段位的对手匹配,

  • 让玩家提供地图偏好,并选择适合所有人的地图,

  • 添加 Hub 选择 UI 以将对手限制在指定的 Ping 信标,

  • 将 匹配延迟 限制在最大阈值以内,以防止匹配距离较远的玩家,

  • 将 匹配延迟 限制在最大差值以内,以最大限度提高 Ping 的公平性,

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

  • 作为组加入 用于预组队大厅,或在不超过队伍规模的情况下补满队伍。

从理想条件开始,并 放宽限制 以确保快速匹配:

  • 随着时间的推移逐步放宽延迟限制,以寻找到更多玩家,

  • 逐步扩大允许的段位差距,以寻找到更多玩家,

  • 由于高段位(挑战者)可用玩家较少,因此增加各次放宽限制之间的时间间隔。

在晋级赛中创建具有更高段位的票据,以便与更强劲的对手进行匹配。

定义独立的作弊者配置文件,以确保被标记的作弊者或遭到大量管理举报的玩家不会在排位赛中对合法玩家的体验造成负面影响。

语义化版本控制

每个新版本都采用 语义化版本控制,通过解释 major.minor.patch 格式来清晰传达更改的影响:

  • major (主版本)包含不兼容的重大变更,需要进行集成审查,

  • minor (次版本)包含向后兼容的实质性改进,

  • patch (补丁版本)包含问题修复和细微改进。

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

为了确保意外的客户端崩溃或遗弃的票据不会持续滞留并占用您的匹配器资源,票据将在 ticket_expiration_period 后取消,其状态将变为 CANCELLED,然后在 ticket_removal_period 后永久删除。

我们匹配逻辑的核心是在 Matchmaking Profiles 中配置的。每个配置文件都是一个完全隔离的匹配队列,指向具有预定义所需 CPU 和内存 (RAM) 资源的 应用版本。

初始规则集中的 匹配规则 必须得到满足,玩家才能被分组在一起,每条规则由三个属性定义:

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

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

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

玩家数量规则

这是一个特殊的规则,定义了需要匹配多少玩家才能启动分配:

  • team_count 指队伍数量,1 支队伍可用于合作或混战(free-for-all)模式,

  • team_size 指每队玩家数量。

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

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

延迟规则

使用此规则为所有玩家提供尽可能低的 Ping 值。一旦客户端测量并提交了针对所有可用信标的往返时间 (Ping),Gen2 将仅考虑根据 Ping 信标 测得的处于特定 Ping 值 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, 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。

确认导入,这将在左侧的集合列表中显示一个名为 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 指您的 Matchmaking Profiles,

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

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

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

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

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

  • profile 确认所选择的 Matchmaking Profiles,

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

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

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

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

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

确保在满足以下情况时,通过 注入的 DELETE_URL 妥善停止部署:

  • 没有玩家加入比赛,

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

  • 比赛正常结束。

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

如何为您的多人体育游戏集成匹配功能

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

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

  • 在共享的托管集群上创建匹配器实例,

  • 在匹配器配置中定义规则和设置,

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

将我们的匹配器实施到您的游戏中有五个步骤:

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

  2. 现在,切勿盲目遵循在网上找到的 JSON 示例,因此强烈建议根据您的体育游戏调整上述规则。步骤 2(“探索配置”)是我们的“阅读指南”,深入探讨了各项匹配规则函数的功能(“探索配置”)。

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

  4. 步骤 4,顾名思义(“4. 测试票据 API”),主要是测试匹配器是否收到来自玩家的匹配请求(称为票据)。

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

如果您遇到故障排除难题,我们详尽的学习中心提供了额外的故障排除提示。

1. 设置免费层

注册您的免费 Edgegap 账户,然后导航至 Matchmaker 仪表板页面。

在该页面中,先点击 Create Matchmaker (创建匹配器),然后输入:

  • 匹配器的名称 – 这纯粹供您自己参考,例如 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
            }
          }
        }
      }
    }
  }
}

(温馨提醒:请务必更改应用程序 name 和 version,以匹配您的 应用程序和版本!)

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

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

2. 探索配置​

体育游戏独有规则

专门针对体育游戏,您可以定义多个 Matchmaking Profiles(匹配配置文件),以设置游戏模式特定的规则和配置:

  • 限制两名玩家之间的段位分差,适用于较休闲的游戏,

  • 在排位赛中严格限制段位分差,只允许相同段位的对手匹配,

  • 让玩家提供地图偏好,并选择适合所有人的地图,

  • 添加 Hub 选择 UI 以将对手限制在指定的 Ping 信标,

  • 将 匹配延迟 限制在最大阈值以内,以防止匹配距离较远的玩家,

  • 将 匹配延迟 限制在最大差值以内,以最大限度提高 Ping 的公平性,

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

  • 作为组加入 用于预组队大厅,或在不超过队伍规模的情况下补满队伍。

从理想条件开始,并 放宽限制 以确保快速匹配:

  • 随着时间的推移逐步放宽延迟限制,以寻找到更多玩家,

  • 逐步扩大允许的段位差距,以寻找到更多玩家,

  • 由于高段位(挑战者)可用玩家较少,因此增加各次放宽限制之间的时间间隔。

在晋级赛中创建具有更高段位的票据,以便与更强劲的对手进行匹配。

定义独立的作弊者配置文件,以确保被标记的作弊者或遭到大量管理举报的玩家不会在排位赛中对合法玩家的体验造成负面影响。

语义化版本控制

每个新版本都采用 语义化版本控制,通过解释 major.minor.patch 格式来清晰传达更改的影响:

  • major (主版本)包含不兼容的重大变更,需要进行集成审查,

  • minor (次版本)包含向后兼容的实质性改进,

  • patch (补丁版本)包含问题修复和细微改进。

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

为了确保意外的客户端崩溃或遗弃的票据不会持续滞留并占用您的匹配器资源,票据将在 ticket_expiration_period 后取消,其状态将变为 CANCELLED,然后在 ticket_removal_period 后永久删除。

我们匹配逻辑的核心是在 Matchmaking Profiles 中配置的。每个配置文件都是一个完全隔离的匹配队列,指向具有预定义所需 CPU 和内存 (RAM) 资源的 应用版本。

初始规则集中的 匹配规则 必须得到满足,玩家才能被分组在一起,每条规则由三个属性定义:

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

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

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

玩家数量规则

这是一个特殊的规则,定义了需要匹配多少玩家才能启动分配:

  • team_count 指队伍数量,1 支队伍可用于合作或混战(free-for-all)模式,

  • team_size 指每队玩家数量。

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

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

延迟规则

使用此规则为所有玩家提供尽可能低的 Ping 值。一旦客户端测量并提交了针对所有可用信标的往返时间 (Ping),Gen2 将仅考虑根据 Ping 信标 测得的处于特定 Ping 值 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, 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。

确认导入,这将在左侧的集合列表中显示一个名为 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 指您的 Matchmaking Profiles,

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

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

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

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

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

  • profile 确认所选择的 Matchmaking Profiles,

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

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

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

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

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

确保在满足以下情况时,通过 注入的 DELETE_URL 妥善停止部署:

  • 没有玩家加入比赛,

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

  • 比赛正常结束。

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

如何为您的多人体育游戏集成匹配功能

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

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

  • 在共享的托管集群上创建匹配器实例,

  • 在匹配器配置中定义规则和设置,

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

将我们的匹配器实施到您的游戏中有五个步骤:

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

  2. 现在,切勿盲目遵循在网上找到的 JSON 示例,因此强烈建议根据您的体育游戏调整上述规则。步骤 2(“探索配置”)是我们的“阅读指南”,深入探讨了各项匹配规则函数的功能(“探索配置”)。

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

  4. 步骤 4,顾名思义(“4. 测试票据 API”),主要是测试匹配器是否收到来自玩家的匹配请求(称为票据)。

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

如果您遇到故障排除难题,我们详尽的学习中心提供了额外的故障排除提示。

1. 设置免费层

注册您的免费 Edgegap 账户,然后导航至 Matchmaker 仪表板页面。

在该页面中,先点击 Create Matchmaker (创建匹配器),然后输入:

  • 匹配器的名称 – 这纯粹供您自己参考,例如 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
            }
          }
        }
      }
    }
  }
}

(温馨提醒:请务必更改应用程序 name 和 version,以匹配您的 应用程序和版本!)

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

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

2. 探索配置​

体育游戏独有规则

专门针对体育游戏,您可以定义多个 Matchmaking Profiles(匹配配置文件),以设置游戏模式特定的规则和配置:

  • 限制两名玩家之间的段位分差,适用于较休闲的游戏,

  • 在排位赛中严格限制段位分差,只允许相同段位的对手匹配,

  • 让玩家提供地图偏好,并选择适合所有人的地图,

  • 添加 Hub 选择 UI 以将对手限制在指定的 Ping 信标,

  • 将 匹配延迟 限制在最大阈值以内,以防止匹配距离较远的玩家,

  • 将 匹配延迟 限制在最大差值以内,以最大限度提高 Ping 的公平性,

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

  • 作为组加入 用于预组队大厅,或在不超过队伍规模的情况下补满队伍。

从理想条件开始,并 放宽限制 以确保快速匹配:

  • 随着时间的推移逐步放宽延迟限制,以寻找到更多玩家,

  • 逐步扩大允许的段位差距,以寻找到更多玩家,

  • 由于高段位(挑战者)可用玩家较少,因此增加各次放宽限制之间的时间间隔。

在晋级赛中创建具有更高段位的票据,以便与更强劲的对手进行匹配。

定义独立的作弊者配置文件,以确保被标记的作弊者或遭到大量管理举报的玩家不会在排位赛中对合法玩家的体验造成负面影响。

语义化版本控制

每个新版本都采用 语义化版本控制,通过解释 major.minor.patch 格式来清晰传达更改的影响:

  • major (主版本)包含不兼容的重大变更,需要进行集成审查,

  • minor (次版本)包含向后兼容的实质性改进,

  • patch (补丁版本)包含问题修复和细微改进。

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

为了确保意外的客户端崩溃或遗弃的票据不会持续滞留并占用您的匹配器资源,票据将在 ticket_expiration_period 后取消,其状态将变为 CANCELLED,然后在 ticket_removal_period 后永久删除。

我们匹配逻辑的核心是在 Matchmaking Profiles 中配置的。每个配置文件都是一个完全隔离的匹配队列,指向具有预定义所需 CPU 和内存 (RAM) 资源的 应用版本。

初始规则集中的 匹配规则 必须得到满足,玩家才能被分组在一起,每条规则由三个属性定义:

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

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

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

玩家数量规则

这是一个特殊的规则,定义了需要匹配多少玩家才能启动分配:

  • team_count 指队伍数量,1 支队伍可用于合作或混战(free-for-all)模式,

  • team_size 指每队玩家数量。

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

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

延迟规则

使用此规则为所有玩家提供尽可能低的 Ping 值。一旦客户端测量并提交了针对所有可用信标的往返时间 (Ping),Gen2 将仅考虑根据 Ping 信标 测得的处于特定 Ping 值 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, 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。

确认导入,这将在左侧的集合列表中显示一个名为 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 指您的 Matchmaking Profiles,

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

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

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

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

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

  • profile 确认所选择的 Matchmaking Profiles,

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

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

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

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

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

确保在满足以下情况时,通过 注入的 DELETE_URL 妥善停止部署:

  • 没有玩家加入比赛,

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

  • 比赛正常结束。

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

如何为您的多人体育游戏集成匹配功能

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

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

  • 在共享的托管集群上创建匹配器实例,

  • 在匹配器配置中定义规则和设置,

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

将我们的匹配器实施到您的游戏中有五个步骤:

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

  2. 现在,切勿盲目遵循在网上找到的 JSON 示例,因此强烈建议根据您的体育游戏调整上述规则。步骤 2(“探索配置”)是我们的“阅读指南”,深入探讨了各项匹配规则函数的功能(“探索配置”)。

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

  4. 步骤 4,顾名思义(“4. 测试票据 API”),主要是测试匹配器是否收到来自玩家的匹配请求(称为票据)。

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

如果您遇到故障排除难题,我们详尽的学习中心提供了额外的故障排除提示。

1. 设置免费层

注册您的免费 Edgegap 账户,然后导航至 Matchmaker 仪表板页面。

在该页面中,先点击 Create Matchmaker (创建匹配器),然后输入:

  • 匹配器的名称 – 这纯粹供您自己参考,例如 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
            }
          }
        }
      }
    }
  }
}

(温馨提醒:请务必更改应用程序 name 和 version,以匹配您的 应用程序和版本!)

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

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

2. 探索配置​

体育游戏独有规则

专门针对体育游戏,您可以定义多个 Matchmaking Profiles(匹配配置文件),以设置游戏模式特定的规则和配置:

  • 限制两名玩家之间的段位分差,适用于较休闲的游戏,

  • 在排位赛中严格限制段位分差,只允许相同段位的对手匹配,

  • 让玩家提供地图偏好,并选择适合所有人的地图,

  • 添加 Hub 选择 UI 以将对手限制在指定的 Ping 信标,

  • 将 匹配延迟 限制在最大阈值以内,以防止匹配距离较远的玩家,

  • 将 匹配延迟 限制在最大差值以内,以最大限度提高 Ping 的公平性,

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

  • 作为组加入 用于预组队大厅,或在不超过队伍规模的情况下补满队伍。

从理想条件开始,并 放宽限制 以确保快速匹配:

  • 随着时间的推移逐步放宽延迟限制,以寻找到更多玩家,

  • 逐步扩大允许的段位差距,以寻找到更多玩家,

  • 由于高段位(挑战者)可用玩家较少,因此增加各次放宽限制之间的时间间隔。

在晋级赛中创建具有更高段位的票据,以便与更强劲的对手进行匹配。

定义独立的作弊者配置文件,以确保被标记的作弊者或遭到大量管理举报的玩家不会在排位赛中对合法玩家的体验造成负面影响。

语义化版本控制

每个新版本都采用 语义化版本控制,通过解释 major.minor.patch 格式来清晰传达更改的影响:

  • major (主版本)包含不兼容的重大变更,需要进行集成审查,

  • minor (次版本)包含向后兼容的实质性改进,

  • patch (补丁版本)包含问题修复和细微改进。

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

为了确保意外的客户端崩溃或遗弃的票据不会持续滞留并占用您的匹配器资源,票据将在 ticket_expiration_period 后取消,其状态将变为 CANCELLED,然后在 ticket_removal_period 后永久删除。

我们匹配逻辑的核心是在 Matchmaking Profiles 中配置的。每个配置文件都是一个完全隔离的匹配队列,指向具有预定义所需 CPU 和内存 (RAM) 资源的 应用版本。

初始规则集中的 匹配规则 必须得到满足,玩家才能被分组在一起,每条规则由三个属性定义:

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

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

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

玩家数量规则

这是一个特殊的规则,定义了需要匹配多少玩家才能启动分配:

  • team_count 指队伍数量,1 支队伍可用于合作或混战(free-for-all)模式,

  • team_size 指每队玩家数量。

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

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

延迟规则

使用此规则为所有玩家提供尽可能低的 Ping 值。一旦客户端测量并提交了针对所有可用信标的往返时间 (Ping),Gen2 将仅考虑根据 Ping 信标 测得的处于特定 Ping 值 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, 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。

确认导入,这将在左侧的集合列表中显示一个名为 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 指您的 Matchmaking Profiles,

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

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

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

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

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

  • profile 确认所选择的 Matchmaking Profiles,

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

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

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

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

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

确保在满足以下情况时,通过 注入的 DELETE_URL 妥善停止部署:

  • 没有玩家加入比赛,

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

  • 比赛正常结束。

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

书写者

Edgegap团队

Get your Game Online Easily & in Minutes

立即开始集成!

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