了解Edgegap的工作原理

對局配對

和

托管与编排

整合

Unreal Engine

Top Down Template

Unreal Engine

Top Down Template

部署至 Edgegap

已发布

2026/10/21

最近一次准确性审核

2026/10/30

俯视角模板：在 Edgegap 专属服务器上运行 Epic 的 Unreal 俯视角模板，并支持匹配

自上而下（Top Down）模板是 Unreal Engine 5 的初学者项目之一：点击即可在小型关卡中移动您的角色。Edgegap 的示例将其转换为多人游戏，其中每场对局都在其专属的专用游戏服务器上运行。

匹配和语音聊天默认都是关闭的：在您开启它们之前，该示例的运行方式与 Unreal 的模板相同，玩家使用 open <IP:port> 加入服务器。与任何 Unreal 多人游戏一样，网络同步由 Unreal 自身的复制（replication）机制处理。

开启 Edgegap 匹配器后，玩家将获得一个“寻找比赛（Find Match）”按钮：游戏会测量他们的延迟（ping），将他们与附近的玩家分在一组，并连接到专为该场对局启动的服务器。开启 EOS 语音聊天后，玩家可以在游戏服务器控制的语音房间中通话：服务器决定谁共享一个房间，因此玩家无法加入未分配给其的频道。

Edgegap 的网络覆盖 615 多个边缘云位置（了解更多）。每台服务器都会部署在最适合其玩家的可用位置，在对局空置时自行停止，并且仅在运行时计费。

克隆示例：GitHub 上的 Top Down Template 示例
完整指南：通过 Unreal Engine 集成指南将 Edgegap 添加到您自己的 Unreal 游戏中

支持平台：Windows 游戏客户端（语音功能也可针对 Mac 构建，未测试）以及 Edgegap 上的 Linux 专用服务器。最近使用基于源码构建的 Unreal Engine 5.5.4 进行了测试；其他 Edgegap Unreal 示例已确认可在 5.8 上运行。基于 Epic 的 Top Down 模板。Edgegap 的代码遵循 MIT 许可协议；其构建所基于的 Unreal Engine 内容仍遵循 Epic 的条款。

工作原理

玩家在菜单地图上选择寻找比赛（Find Match）。游戏会对 Edgegap 的信标进行 ping 测试，并发送包含这些 ping 时间的匹配票证。
匹配器将对同一信标具有相似 ping 值的 2 到 4 名玩家分为一组，然后在他们附近启动 Edgegap 部署。
每个客户端获取服务器的地址和端口，并通过 Unreal 的 ClientTravel 进行连接。
开启语音功能后，每个玩家使用设备 ID 登录 EOS，并向服务器发送一个 ID 令牌。服务器对其进行验证，从匹配器的队伍数据中选择玩家的房间，并仅向其发回该房间的语音令牌。
当最后一名玩家离开时，服务器会等待 15 秒，然后停止自身部署，从而结束计费。

该示例在模板基础上添加的内容：

路径	功能说明
`MultiplayerGame/Source/MultiplayerGame/EdgegapMatchmakerSubsystem.h/.cpp`	客户端：信标 ping 测试、匹配票证、等待服务器、连接。
`MultiplayerGame/Source/MultiplayerGame/MultiplayerGamePlayerController.cpp`	菜单地图上的寻找比赛（Find Match）/ 取消（Cancel）界面覆盖；`FindMatch` 和 `CancelMatch` 控制台命令。
`MultiplayerGame/Source/MultiplayerGame/MultiplayerGameGameMode.cpp`	服务器：当由匹配器启动的对局变空时停止部署。
`MultiplayerGame/Source/MultiplayerGame/EdgegapVoice*`	EOS 语音：设置、客户端登录和房间、复制语音组件、服务器的令牌服务。
`MultiplayerGame/Source/MultiplayerGameServer.Target.cs`	专用服务器构建目标。
`Dockerfile`, `matchmaker-config.json`	服务器镜像和匹配器配置文件。

与工程师联系

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

Epic 的自上而下模板，配有专用服务器、可选的匹配系统和 EOS 语音聊天。

分步指南

运行示例

1. 开始之前

一个免费的 Edgegap 账户。测试无需信用卡。
从源码构建的 Unreal Engine 5.5，以及 Visual Studio 2022 和适用于 5.5 的 Linux 交叉编译工具链。该示例使用 RunUAT 打包其 Linux 服务器，这需要源码构建。首次构建引擎预计需要 1 到 3 小时，首次打包服务器大约需要 1 小时。Unreal Engine 指南涵盖了相关设置，以及使用 Edgegap 的 Docker Extension 的更快捷途径（该示例尚未对此进行测试）。
Docker Desktop，用于构建服务器镜像。
仅限语音聊天：Epic 开发者门户中的产品。
克隆该示例。Unreal 项目位于 MultiplayerGame 文件夹中。

2. 将游戏服务器部署在 Edgegap 上

将 Linux 专用服务器打包到仓库根目录下的 Packaged/ 中：

<UE_ROOT>/Engine/Build/BatchFiles/RunUAT.bat BuildCookRun -project=<PATH>/MultiplayerGame/MultiplayerGame.uproject -noP4 -server -noclient -serverplatform=Linux -serverconfig=Development -build -cook -stage -pak -archive -archivedirectory=<PATH>/Packaged

使用来自容器注册表页面的用户名和令牌将 Docker 登录到您的 Edgegap 注册表。然后从仓库根目录构建并推送镜像，每次构建都使用一个新标签：

docker build --platform linux/amd64 -t registry.edgegap.com/<project>/unreal-topdown:v1 .

docker push registry.edgegap.com/<project>/unreal-topdown:v1

在仪表板中，创建一个应用程序（匹配器配置文件需要 unreal-topdown）和一个版本 v1：

您的镜像和标签，以及您的注册表凭据。如果没有这些凭据，部署将失败并提示“Unable to pull image from registry”。
一个端口：名称为 gameport，7777，UDP。

Dockerfile 会直接运行服务器二进制文件，并带有 -stdout -FullStdOutLogOutput 参数，以便其日志显示在仪表板中，并在 Edgegap 结束部署时正常停止。

3. 在测试服务器上进行游戏

在仪表板中打开您的应用版本，选择部署（Deploy）并挑选一个靠近您的位置。当状态变为就绪（Ready）时，复制主机（Host）和外部端口（External Port）。

运行游戏，使用 ` 键打开控制台并输入：

open <host>:<external port>

每次部署时外部端口都会更改。以相同的方式运行第二个客户端，两名玩家就可以在同一关卡中走动了。

手动部署的服务器绝不会自动停止：完成后请在控制台中将其停止。免费套餐一次只能运行一个部署，因此遗忘的测试服务器会阻塞玩家匹配。

4. 添加 EOS 语音聊天（可选）

游戏服务器充当 EOS Voice 的受信任服务器。它通过 HTTPS 调用 EOS Voice Web API，因为 EOS SDK 在 Linux 上不支持语音。玩家使用设备 ID 登录，因此不需要 Epic 账户。

在 Epic 开发者门户中，打开您的产品，然后进入产品设置（Product Settings）。记下产品 ID、沙盒 ID 和部署 ID。在客户端（Clients）选项卡上，添加两个客户端策略，并为每个策略各添加一个客户端：
游戏客户端：类型为 GameClient，勾选需要用户（User required），无 Voice 权限。
受信任服务器：自定义策略，取消勾选需要用户（User required），包含 Voice 操作 createRoomToken、kick 和 mute。该客户端可以为任何房间创建令牌：切勿将其放入游戏构建版本中。
将产品、沙盒和部署 ID 以及游戏客户端的 ID 和密钥放入 MultiplayerGame/Config/UserEngine.ini 的 [EOSVoiceChat] 部分。Git 会忽略该文件。
在 MultiplayerGame/Config/UserGame.ini 中开启语音：在 [/Script/MultiplayerGame.EdgegapVoiceSettings] 下设置 bEnabled=True。
在新的应用版本中，添加包含受信任服务器凭据的环境变量 EOS_VOICE_CLIENT_ID 和 EOS_VOICE_CLIENT_SECRET（标记为隐藏），以及 EOS_VOICE_DEPLOYMENT_ID。设置后，无需重新构建镜像即可在服务器中开启语音。
重新打包客户端并运行游戏。在控制台中输入 VoiceMute 即可静音或取消静音您的麦克风。

在手动部署的服务器上，整场比赛共用一个房间。使用匹配系统（步骤 6）时，队友共用一个房间。

若要在单台电脑上测试两个客户端，请为第二个客户端添加 -EOSVoiceNewDeviceId，并在第一个客户端记录 Voice: logged into EOS 后再启动它。要在没有麦克风的情况下测试音频，请使用以下参数启动客户端：

-ExecCmds="EOSVoiceChat.FakeAudioInputEnabled 1"

随后另一个客户端将记录 Voice: <id> started talking in room <room>。

5. 将其添加到你自己的 Unreal 游戏中

该示例是一个可运行的参考：您的编码智能体（coding agent）可以直接复制其经过测试的文件，而无需从头编写。这些更改使 Unreal 游戏能够在 Edgegap 上运行：

专用服务器（Dedicated Server）构建。一个 Server 目标（Source/MultiplayerGameServer.Target.cs）、一个服务器默认地图（Config/DefaultEngine.ini 中的 ServerMap）以及待烘焙地图列表中的该地图（Config/DefaultGame.ini）。
客户端上的“寻找比赛”（Find Match）。EdgegapMatchmakerSubsystem ping 信标、创建票证、等待服务器并进行连接。其设置位于 DefaultGame.ini 的 [/Script/MultiplayerGame.EdgegapMatchmakerSubsystem] 部分中。
可自动停止的服务器。当匹配系统启动服务器后，一旦比赛中无人，它就会停止其部署（MultiplayerGameGameMode.cpp）。
由服务器决定的语音房间。四个 EdgegapVoice* 类、MultiplayerGame.Build.cs 中仅适用于 Windows 和 Mac 客户端的 EOS 模块，以及 .uproject 中仅限 Win64 和 Mac 的 EOSVoiceChat 插件，以使 Linux 服务器不会加载 EOS SDK。
服务器镜像。Dockerfile 将 Packaged/LinuxServer 复制到一个作为非 root 用户运行的小型 Ubuntu 镜像中。

在该示例中，“寻找比赛”覆盖层和自动停止功能位于玩家控制器（player controller）和游戏模式（game mode）中。在您自己的游戏中，您无需编辑这两者：Edgegap 智能体技能以即插即用子系统的形式提供了相同的逻辑。

配合您的智能体使用：

“加载 edgegap-unreal 技能，然后加载 edgegap-eos-voice。以 github.com/edgegap/game-sample-unreal-engine-topdown 为参考，让我的 Unreal 项目支持专用服务器，添加带有‘寻找比赛’按钮和服务器自动停止功能的 Edgegap 匹配系统，并添加每个匹配队伍一个房间的 EOS 语音聊天。在我向你提供我的匹配系统 URL 和 EOS ID 之前，保持匹配和语音功能禁用，并检查编辑器与 Server 目标是否能正常编译。”

如需了解每个步骤的手动详细操作，请参阅 Unreal Engine 集成指南。

6. 开启“查找匹配”

在仪表板中，打开 Matchmaker 并选择 Create Matchmaker。上传示例的 matchmaker-config.json，并将 application.name 和 application.version 更改为您的应用程序和版本，然后点击 Create and Start。
当其状态变为 ONLINE 时，复制其 API URL 和 Auth Token。
在 MultiplayerGame/Config/UserGame.ini 中，添加 [/Script/MultiplayerGame.EdgegapMatchmakerSubsystem] 部分，并包含 bEnabled=True、MatchmakerUrl="<API URL>" 和 AuthToken="<Auth Token>"。请将 URL 保留在引号中：若不加引号，Unreal 会在 // 处将其截断。
启动两个客户端，并在 10 秒内在两者中均选择 Find Match。它们将加入同一个服务器。

casual 配置文件匹配 2 到 4 名玩家，这些玩家连接到公共信标的 ping 值需低于 150 毫秒，且相互之间的差距在 100 毫秒以内。10 秒后，它还会接受单个玩家以及高达 250 毫秒的 ping 值，以便您可以单独进行测试。没有匹配成功的票证将在 20 秒后取消：请再次选择 Find Match。

Auth Token 仅允许客户端创建和读取票证，因此随游戏一起发布是安全的。切勿将您的 Edgegap API 令牌放入游戏中。

对于无人值守测试，命令行中的 -FindMatch 会在启动时排队。客户端的启动速度各不相同，因此在进行语音测试时，请改为使用相同的 -FindMatchAt=<unix time> 启动两者：每个客户端都会在该时刻开始排队。

当您发布新的服务器版本时，请将 application.version 指向新版本，否则比赛将继续部署旧版本。有关在您自己的游戏中实现匹配的信息，请参阅 Unreal 匹配。

已知限制

引擎从源码构建。 该示例的打包步骤需要 Unreal 5.5 的源码构建版本。Edgegap 的 Docker 扩展通过启动器安装构建 Unreal 服务器；它应该适用于此示例，但尚未经过测试。
语音在 Windows 和 Mac 客户端上运行。 引擎的 EOSVoiceChat 插件没有 Linux 客户端。Mac 构建版本应该可以运行，尚未经过测试。
每场比赛一个队伍。 casual 配置文件只有一个队伍，因此每个匹配的玩家共享一个语音房间。对于两个队伍，在配置文件中添加 team_count: 2：服务器随后会为每个队伍分配自己的房间（代码已编写但未测试）。服务器根据玩家的 IP 确定其队伍，因此同一 IP 背后的玩家会保留在比赛房间中。
设备 ID 登录。 玩家会获得一个与其 PC 绑定的 EOS 身份，无需平台账户。对于正式发行的游戏，请使用平台登录（Steam、主机）并关联账户。
基础菜单。 “寻找比赛”（Find Match）覆盖层是一个简单的 Slate 控件。如需制作自己的菜单，请调用 FindMatch 并从 UMG 侦听子系统的状态。
服务器上没有票据检查。 服务器不会检查连接的玩家是否持有本场比赛的匹配器票据，因此任何获取服务器地址的人都可以加入，并在开启语音的情况下获取该房间的语音令牌。

测试了什么

于 2026 年 10 月在 Edgegap 上进行了端到端测试（撮合测试于 10 月 14 日通过），使用从源码构建的 Unreal Engine 5.5.4、Windows 客户端以及 Edgegap 上的 Linux 服务器：

匹配：两个客户端根据延迟匹配到同一个 Edgegap 部署上；在两者都离开后，服务器停止了自己的部署。
语音，本地：一台 PC 上的两个客户端（-EOSVoiceNewDeviceId，虚拟音频输入）连接本地专用服务器：两者使用不同的 EOS 身份加入了房间。
语音，在 Edgegap 上：两个客户端匹配到同一个部署中，在同一个队伍房间内，可以互相听到声音。当其中一个退出时，服务器将其从房间中移除（204）。

需要查找的日志行（LogEdgegapVoice）：在服务器上，为 Voice: trusted voice server ready，然后每个玩家显示 Voice: <id> gets room <room>，当玩家离开时显示 Voice: removed <id>。在每个客户端上，显示 Voice: logged into EOS as <id> 和 Voice: joined room <room>。

尚未测试：3 或 4 名玩家的比赛、两个队伍在不同房间、Mac 客户端以及使用 Docker Extension 构建示例。