了解Edgegap的工作原理

對局配對

和

托管与编排

整合

Unreal Matchmaking

部署至 Edgegap

已发布

2025/7/24

最近一次准确性审核

2026/10/16

Unreal 對局配對：如何通过 Edgegap 为您的 Unreal Engine 多人游戏添加對局配對

本指南向你展示如何为已在 Edgegap 专属游戏服务器上运行的 Unreal Engine 多人游戏添加匹配功能：玩家选择寻找比赛（Find Match），与附近的玩家分组，并连接到 Edgegap 在他们附近启动的服务器。当所有人离开后，服务器会自动停止。

一旦你的游戏服务器容器化，Edgegap 只需通过一个简单的 API 调用即可将其按需部署到全球 615+ 个边缘云节点，并且完全按用量计费：无需租用、配置整台服务器，也无需在比赛之间保持运行。针对预留容量的持久服务器，Edgegap 提供了专用机组（Private Fleets）。Edgegap 的匹配基于此构建，并且是可选的。

你可以在 Edgegap 控制面板中使用 JSON 文件配置撮合器，无需编写后端代码。在你的游戏中，两个现成的 C++ 文件会测量 Ping 值、创建票证、等待服务器并连接，蓝图可以直接调用它们。它们使用 Unreal 自身的 ClientTravel 进行连接，因此适用于任何使用 Unreal 标准复制和专属服务器的游戏，无需更改你的游戏模式或玩家控制器。

本指南涵盖：

为你的游戏准备一个可用的 Edgegap 应用版本
将你的代码智能体连接到 Edgegap（可选）
将匹配文件添加到你的项目中
配置客户端
创建你的撮合器
选择你的匹配规则
双人玩家测试

你可以通过两种方式进行，也可以将它们结合使用：

使用代码智能体：将 Claude Code、Cursor 或其他智能体连接到 Edgegap MCP 服务器及其智能体技能。智能体负责添加文件、编辑配置、运行构建并检查撮合器。你只需负责控制面板上的操作和试玩测试。
手动操作：以下每个步骤在没有智能体的情况下也完全可行。

与工程师联系

无需信用卡。免费版包含部署真实游戏服务器所需的资源。

本指南遵循 Edgegap 的對局配對文档。请查看该文档以获取最新的配置选项和 API 变更。

在本指南结束时，玩家只需点击寻找对局，Edgegap 的配对系统便会根据玩家的延迟将他们与其他玩家进行分组，在离所有人最近的位置启动专用服务器，并且每个客户端都会自动连接到该服务器。当比赛结束且所有人离开后，服务器会自动停止，因此您只需为使用时间付费。

配对系统本身是免代码的：您可以在 Edgegap 控制面板中使用 JSON 文件对其进行配置。在游戏端，Unreal Engine 并没有像 Unity 那样拥有官方的 Edgegap 對局配對 SDK。相反，Edgegap 提供了两个开箱即用的 C++ 文件，您可以直接放入项目中。它们能为简单比赛完成 Unity SDK 所做的一切：测量 ping、创建票证、等待服务器并进行连接。您无需编写任何网络代码，并且蓝图菜单可以直接调用它们。

因为客户端是通过 Unreal 内置的 ClientTravel 进行连接的，所以这适用于任何使用 Unreal 标准复制和专用服务器的游戏，无需更改您的游戏模式或玩家控制器。

前置条件

一个 Edgegap 账号。本指南使用免费层（Free Tier）即可。
一个带有 C++ 模块的 Unreal Engine 5 项目（已在 UE 5.5 上验证；5.3+ 版本操作相同）。纯蓝图项目？先通过工具 → 新建 C++ 类添加一个。
您的游戏的 Linux 专用服务器版本，已容器化并作为应用版本发布在 Edgegap 上，游戏端口（7777，UDP）命名为 gameport。
已验证连接：您已从控制面板部署过该版本一次，并已在控制台（~）中使用 open {IP}:{port} 从客户端成功加入。

不要在您尚未成功连接过的服务器上添加配对功能。如果之后出现问题，您就能确定是对局配对层的问题，而不是服务器本身的问题。

分步指南

详细集成步骤

1. 开始之前

一个免费的 Edgegap 账户。验证您的电子邮件。测试无需信用卡。
一个包含 C++ 模块的 Unreal Engine 5 项目（已在 UE 5.5 和 5.8 上验证；5.3 或更高版本同样适用）。纯蓝图项目？请先通过工具 → 新建 C++ 类 → 无添加一个。
您的游戏服务器的一个可用 Edgegap 应用版本：一个 Linux 专用服务器，已容器化，端口为 7777，UDP，命名为 gameport。匹配会为每场比赛部署所请求的版本，因此需要一个功能完备的容器化游戏服务器来实现端到端工作。如果您还没有，请参阅我们的指南：Unreal Engine。
一个经过测试的连接：您曾从控制面板部署过该版本一次，并通过客户端控制台使用 open <IP>:<port> 成功加入。切勿在尚未成功加入的服务器上添加匹配：如果稍后出现问题，您就能确定是匹配层的原因。
对于代理路径：一个 Edgegap API 令牌，来自控制面板 → 用户设置 → 令牌。它是组织级别的，因此请像对待密码一样对待它：切勿将其放入您的项目、游戏客户端或聊天中。

2. 将您的代码代理连接到 Edgegap

如果您全部手动操作，请跳过此步骤。

Edgegap MCP 服务器允许您的智能体在您的账户上创建应用和版本、部署服务器、读取日志并生成匹配系统配置。edgegap-unreal 智能体技能可为其提供匹配和服务器关闭文件、相关配置以及已知注意事项。

Claude Code：安装 Edgegap 插件。它会同时添加 MCP 服务器和技能，并在安装期间提示输入您的 API 令牌（存储在系统的凭据管理器中）：

/plugin marketplace add edgegap/llm-agent-skills，然后运行 /plugin install edgegap@edgegap。重启会话。

仅需要 MCP 服务器而不需要插件？请改为在您自己的终端中运行以下命令：claude mcp add --transport http edgegap https://mcp.edgegap.dev/mcp -H "Authorization: token YOUR_EDGEGAP_API_TOKEN" --scope user。切勿两者都配置，否则会出现两个 edgegap 服务器。

Cursor、VS Code 以及其他支持发送请求头的客户端：添加 https://mcp.edgegap.dev/mcp 并附带请求头 Authorization: token YOUR_EDGEGAP_API_TOKEN，然后通过 npx skills add edgegap/llm-agent-skills --skill "*" 安装技能。

Claude Desktop：自定义连接器无法发送请求头，因此请改为使用本地服务器（需要 Node 18+）：{ "mcpServers": { "edgegap": { "command": "npx", "args": ["-y", "@edgegap/mcp"] } } }。首次使用时会要求输入令牌。

检查是否正常运行：

“列出我的 Edgegap 应用。”

您的应用及其版本应显示在列表中。

3. 将匹配文件添加到您的项目中

Edgegap 在其开源智能体技能代码库中发布了两个即插即用文件：

EdgegapMatchmakerSubsystem（游戏客户端）：测量到 Edgegap 信标的延迟（ping），创建匹配票证，等待服务器分配，然后进行连接。它包含一个基础的寻找比赛/取消覆盖层界面。
EdgegapServerSubsystem（专用服务器）：当服务器由匹配系统启动后，一旦比赛中无人，它将停止该部署。

使用您的智能体，首先进行审查（只读）：

“查看我的 Unreal 项目，并告诉我目前玩家是如何连接的：C++ 模块名称、是否存在 Server 目标、服务器默认地图，以及是否有任何地方使用了 open、ClientTravel、会话或 OnlineSubsystem。不要修改任何文件。”

然后：

“使用 edgegap-unreal 技能为此项目添加 Edgegap 匹配功能。放入 matchmaker 和 server 子系统，在 DefaultGame.ini 中添加配置部分并禁用匹配，同时确认编辑器目标仍然可以编译。创建完成后，我会提供 matchmaker URL 和令牌。”

手动操作：

将 assets/unreal/Source/ 中的四个文件（每个子系统的 .h 和 .cpp）复制到 Source/<YourModule>/ 中。
在 Source/<YourModule>/<YourModule>.Build.cs 中，将 "HTTP", "Json", "Sockets", "Slate", "SlateCore" 添加到 PublicDependencyModuleNames。
重新生成项目文件并构建编辑器目标。

这两个子系统默认都是关闭的：添加这些文件不会产生任何改动，直到您在第 5 步中开启匹配功能。它们负责处理信标 ping、票证、重试、玩家在搜索过程中退出时取消票证、选择正确的端口、ClientTravel 调用以及服务器关闭。初次测试时您无需编写任何代码。

更倾向于使用蓝图？由 Betide Studios 在 Fab 上发布的 Edgegap Integration Kit 支持 Edgegap 匹配，并附带现成的蓝图示例。

4. 配置客户端

所有设置均位于 Config/DefaultGame.ini 中以您的模块命名的节下：[/Script/<YourModule>.EdgegapMatchmakerSubsystem]。添加以下行：

bEnabled=False：在步骤 5 之前保持关闭状态。
MatchmakerUrl="YOUR_MATCHMAKER_URL" 和 AuthToken="YOUR_MATCHMAKER_AUTH_TOKEN"：来自步骤 5 中的撮合器页面。请将 URL 保留在引号内，否则 Unreal 会在 // 处将其截断，导致请求失败并提示“Couldn't resolve host name”。
Profile=simple-example：撮合器配置中的配置文件名称。
PortName=gameport：应用程序版本上的端口名称。
bSendBeaconLatencies=True：仅当配置文件包含延迟规则时使用（简单示例包含此规则）。撮合器会拒绝包含意外值的票据，因此请确保此项与您的配置保持同步。
bShowDefaultUI=True：在菜单地图上显示基本的“寻找比赛”浮层。一旦您自己的菜单调用了“寻找比赛”，请将其设置为 False。

此外，还需添加一个空的 [/Script/<YourModule>.EdgegapServerSubsystem] 节。如果 5 分钟内没有人加入，或者在最后一名玩家离开 15 秒后，服务器将自行停止（NoPlayerTimeoutSeconds、EmptyServerGraceSeconds）。这仅适用于撮合器启动的服务器，因此您的手动测试部署不受影响。

Auth Token 可以安全地随游戏客户端一同发布：它只能创建和读取票据，无法访问您的 Edgegap 账户。在公开仓库中，请在 DefaultGame.ini 中保留占位符，并将真实值放入 Config/UserGame.ini 中，后者会覆盖前者、被 Git 忽略，且仍会被打包到构建版本中。

5. 创建您的撮合器

在仪表板中，打开 Matchmaker，选择创建 Matchmaker，为其命名，然后选择 Simple Example 模板（它包含的内容）。
将 application.name 和 application.version 设置为与仪表板中显示的应用程序和版本完全一致的名称及版本。如果版本不存在，配置将被拒绝。
选择创建并启动，然后等待其就绪。新 matchmaker 的地址可能需要长达 5 分钟的时间才能响应。
将 API URL 和 Auth Token 复制到 DefaultGame.ini 中，并设置 bEnabled=True。

在启动游戏前检查 URL 和令牌：curl -H "Authorization: <auth token>" <api url>/locations/beacons。如果返回信标的 JSON 列表，则表示它们正常工作。

与您的代理配合使用： “这是我的 matchmaker API URL 和 Auth Token。请检查它们是否有响应，将它们填入 Edgegap matchmaker 设置中，并开启匹配功能。”

6. 选择您的匹配规则

首先使用简单示例运行第 7 步测试，然后根据您的游戏定制规则。简单示例包含两项规则：

比赛规模：恰好 2 名玩家组成一支队伍，因此撮合程序会等待 2 张票据才启动服务器。
延迟：仅当玩家到同一个 Edgegap 位置的延迟差在 100 毫秒以内时才会分组，且忽略高于 200 毫秒的位置。

单人测试？添加扩展规则，以便单个玩家在 10 秒后即可获得服务器："expansions": { "10": { "match_size": { "min_team_size": 1 } } }。停止撮合程序，编辑配置，然后重新启动。在正式发布前请将其移除。

然后添加队伍规模、技术或段位、游戏模式、地图以及随着玩家等待时间增加而放宽规则的扩展。类型示例（竞技、合作、社交、候补补位）请参阅撮合文档。除比赛规模外，每条规则都需要在每位玩家的票据中包含对应的值：添加规则时请告知您的代理，它也会同步更新客户端。

撮合程序部署会以 JSON 字符串形式接收 MM_MATCH_ID、MM_MATCH_PROFILE、MM_TICKET_IDS、MM_TEAMS、MM_GROUPS 以及针对每位玩家的 MM_TICKET_<id>。使用 FPlatformMisc::GetEnvironmentVariable 读取它们以分配队伍或检查加入的玩家。

发布新的服务器版本时，请更新 application.version（停止、编辑、启动），否则比赛将继续部署旧版本。

7. 双人测试

请确保没有测试部署仍在运行：免费层每次仅运行一个部署，遗留的部署会阻塞匹配。
并排启动两个客户端：UnrealEditor.exe "<path>\<Project>.uproject" -game -windowed -ResX=960 -ResY=540 -WinX=0 -log，第二个客户端使用 -WinX=970。
在两个客户端中均选择Find Match。状态会从测量延迟变为搜索中、找到匹配，然后是正在连接。几秒钟内，两个客户端都会加载到同一个服务器中，控制面板会显示带有两个票据 ID 标记的部署。
关闭两个客户端。大约一分钟后，部署会自动停止。

您也可以从控制台使用 Edgegap.FindMatch 和 Edgegap.CancelMatch 排队，或者在命令行中添加 -FindMatch。如果票据分配到了服务器但客户端无法连接，问题出在服务器端，而不是匹配器：请手动部署该版本并再次测试 open <IP>:<port>。在免费层上，匹配器在每次启动 3 小时后停止：请从控制面板重新启动它。

后续步骤

构建您自己的菜单。FindMatch、CancelMatch、GetState 和 GetStatusText 可在 Edgegap Matchmaker Subsystem（Get Game Instance Subsystem）上通过蓝图调用，并且每次更新 UMG 控件时都会触发 OnStatusChanged。然后设置 bShowDefaultUI=False。

文件工作原理。客户端获取 Edgegap 的信标并对每个信标进行 TCP 握手计时（三次取最佳值，并行进行，1 秒超时），将 Ping 值发送到按城市键入的票据中，每 2 秒轮询一次直至分配完成，然后转移到服务器的 IP 以及 PortName 中指定的端口，如同 open <IP>:<port>。取消或退出会删除该票据。在服务器上，子系统识别匹配器的 MM_MATCH_ID，监控登录，并在比赛为空时调用 Edgegap 注入的 ARBITRIUM_DELETE_URL。身份验证令牌原样放在 Authorization 请求头中，无需“Bearer”前缀。

准备上线？让您的智能体运行 edgegap-launch 技能的检查清单，并在发布前选择生产环境匹配器。正在使用 Epic Online Services？请参阅 Epic Online Services。

遇到问题？让您的智能体加载 edgegap-troubleshoot，或在 Edgegap Discord 上向我们的团队和其他工作室咨询。