了解Edgegap的工作原理

了解Edgegap的工作原理

對局配對

對局配對

和

和

托管与编排

托管与编排

整合

/

LightNet Relay

/

LightNet Relay

部署至 Edgegap

已发布

已发布

已发布

最近一次准确性审核

最近一次准确性审核

最近一次准确性审核

LightNet Relay for Unity: How to run an extensible relay on a dedicated server, with room codes and optional game logic

LightNet Relay for Unity: How to run an extensible relay on a dedicated server, with room codes and optional game logic

This guide shows you how to run LightNet, an open-source relay you run on a dedicated server on Edgegap and can extend with your own game logic, so players of your host-client Unity game host a match and join it with a room code. The sample works with Mirror, Fish-Networking, PurrNet and Netcode for GameObjects, with one setting to pick the netcode.

Think of it as peer-to-peer, elevated. Out of the box, the relay forwards traffic and the host's game owns the match. Add game logic and it becomes a multi-room dedicated server with relay-like resource efficiency, on the same code and deployment. What changes from day one is where the traffic goes. Every player connects out to your relay, in a location you choose, so nobody opens a port, no player sees another player's IP address, and no shared relay network decides your route.

Once your relay is containerized, Edgegap deploys it from a simple API call, on Edge Cloud for tests or on Private Fleets for a relay that stays up. One relay serves many rooms at once.

This guide covers:

  1. What you need before you start

  2. Connecting your coding agent to Edgegap (optional)

  3. Picking your netcode in the sample

  4. Containerizing the relay and creating an app version

  5. Deploying the relay and connecting players

  6. Grouping players with room codes

  7. Testing with two players

You can do it two ways, and mix them:

  • With a coding agent: Connected to the Edgegap MCP server and its agent skills, your agent can build and push the relay image, create the app version, deploy it, read its logs and stop it.

  • By hand: Every step below also works without an agent.

Here, we use Edgegap's LightNet relay sample: the relay, plus Mirror's Tanks game playing through it on all four netcodes.

与工程师联系

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

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

Which setup fits your game?

An extensible relay is one of six ways to put players in the same match. They differ in who owns the match and where it runs:

Setup

Who owns the match

Best for

Peer-to-peer

A player's device

Local or LAN-style play

Shared relay service (Steam, Epic Online Services, Unity Relay)

The host player

A quick fix for connections that fail

Extensible relay (this guide), on a dedicated server

The host player

Co-op and private rooms among players who trust each other, with your own relay and route; add game logic to grow it into a multi-room game server

Multi-room game server

The server

Latency-tolerant games such as RTS, card and turn-based games, with many matches in one central process

Small dedicated server

The server

Matches where fairness matters, each on a fractional vCPU server deployed nearest to its players

Full dedicated server

The server

Full simulations, large matches and anti-cheat

What an extensible relay gives you:

  • Players' IP addresses stay hidden: Everyone connects out to the relay, so players never connect to each other directly. That closes the door on attacks on a player's connection, such as flooding the host, that peer-to-peer leaves open.

  • No port forwarding, no NAT issues: Including on mobile networks, where direct peer-to-peer connections often fail.

  • Your route, your locations: Deploy the relay where your players are. On free relay services, studios have reported "absolutely no control over how those players are routed" (Live Service Game Summit talk, September 2024).

  • No shared network: A routing change or outage on another relay network doesn't reach your game.

  • No rewrite: Your host-client netcode stays as it is, with no relay vendor SDK in your game.

  • Extend it: You own the relay code, so you can add your own logic: room passwords or player checks, rate limits, kick and ban, room data, telemetry, hooks to your lobby. Shared relay services like Steam's and Epic's don't let you add code.

  • Grow it into a game server: Add game logic and it becomes a multi-room dedicated server with relay-like resource efficiency, on the same code and deployment.

What it can't do:

  • Stop cheating out of the box: Whoever holds the match state can change it, and as shipped, the host's game holds it. A cheater ruins the match for everyone, casual or ranked. Server authority stops that: add game logic so the relay holds the match, which means rebuilding your game's rules on the server since the relay only sees raw netcode traffic, or move to a small dedicated server per match. A multi-room server runs in one location, so run one per region: players far from it get worse latency and fairness than players close to it.

  • Keep the match going when the host leaves: The relay closes the room and disconnects the other players.

  • Match players or scale on its own: The sample has no matchmaking and no scaling: players share room codes, and you choose where to deploy relays.

  • Encrypt traffic or check who joins, as shipped: The sample's transports are plain TCP and UDP, and anyone with the relay address and a valid room code can join until you add your own player checks.

  • Serve browser games: For web games, see Browser Games, Colyseus or Manus AI.

Where it fits:

分步指南

详细集成步骤

1. Before you start

  • A free Edgegap account. Verify your email. No credit card is needed to test.
  • Unity 6000.0.54f1 (Unity 6), the version the sample uses. PurrNet needs Unity 2022.3 or newer.
  • Docker to build the relay image. Other containerization tools aren't covered here. The .NET 8 SDK is only needed to build the relay outside Docker.
  • For the agent path: an Edgegap API token, from Dashboard → User Settings → Tokens. It is organization-wide, so treat it like a password: never put it in your project, your game client or a chat.

Git: Unity needs a Git client (2.14.0 or newer) on your PATH to install packages from a Git URL, such as PurrNet in this sample. macOS usually has one already (Xcode Command Line Tools); on Windows, install Git.

Clone the sample: git clone https://github.com/edgegap/server-sample-lightnet-relay.git

2. Connect your coding agent to Edgegap

Skip this step if you're doing everything by hand.

The Edgegap MCP server lets your agent work on your account: push images, create app versions, deploy, read logs and stop deployments. The skills hold the tested workflow.

Claude Code: install the Edgegap plugin. It adds both the MCP server and the skills, and asks for your API token during install (stored in your system's credential store):

/plugin marketplace add edgegap/llm-agent-skills, then /plugin install edgegap@edgegap. Restart the session.

Only want the MCP server, without the plugin? Run this in your own terminal instead: claude mcp add --transport http edgegap https://mcp.edgegap.dev/mcp -H "Authorization: token YOUR_EDGEGAP_API_TOKEN" --scope user. Don't do both, or you'll have two edgegap servers.

Cursor, VS Code and other clients that send headers: add https://mcp.edgegap.dev/mcp with the header Authorization: token YOUR_EDGEGAP_API_TOKEN, and install the skills with npx skills add edgegap/llm-agent-skills --skill "*".

Claude Desktop: custom connectors can't send the header, so use the local server instead (Node 18+): { "mcpServers": { "edgegap": { "command": "npx", "args": ["-y", "@edgegap/mcp"] } } }. It asks for the token on first use.

Check it works:

List my Edgegap apps.

An empty list is fine. Your agent may also point out that a dedicated server would give your game server authority: that's expected, since a relay leaves the host in charge of the match.

3. Pick your netcode in the sample

Open the tanks/ folder in Unity Hub. The netcode is one field, netcode, in tanks/Assets/Tanks/Resources/TanksSettings.asset: Mirror, FishNet, PurrNet or NGO. The same asset holds the relay address and port. Other ways to switch:

  • In the editor: Tanks > Netcode > Mirror / FishNet / PurrNet / NGO sets the asset and opens that netcode's scene.
  • In the game: the netcode buttons at the top of the HUD, before hosting or joining.
  • From the command line: -netcode FishNet.

Host and players must use the same netcode. One build contains all four.

NetcodeVersion in the sampleRelay transport
Mirror66.0.9MirrorRelayTransport
Fish-Networking4.7.4FishNetRelayTransport
PurrNet1.24.1PurrNetRelayTransport
Netcode for GameObjects1.13.0NgoRelayTransport

Each transport wraps RelayPeer, the netcode-agnostic relay client in the sample's LightNet package. Reliable messages go over TCP and unreliable ones over UDP, up to 16 KB reliable and 1,177 bytes unreliable per message.

Your own game? Copy the LightNet/ package and the transport for your netcode into your project, and set it as your Network Manager's transport. Your game keeps hosting the match as it does today.

"In my Unity project using {netcode}, add the LightNet package from Edgegap's server-sample-lightnet-relay repository and its {netcode} relay transport. Set it as the Network Manager's transport, read the relay address and port from a settings asset, and add Host and Join room buttons: Host shows the 6-letter room code, Join takes one. Don't change my game logic."

4. Containerize the relay and create an app version

The relay is a .NET 8 console app with its own Dockerfile. Build it from the repository root, for Edgegap's platform, even on Apple Silicon:

docker build --platform linux/amd64 -f relay-server/Dockerfile -t registry.edgegap.com/<project>/lightnet-relay:<tag> .

Test it on your machine first: docker run --rm -p 7777:7777/tcp -p 7777:7777/udp registry.edgegap.com/<project>/lightnet-relay:<tag>. The log should read "LightNet relay listening on TCP 7777, UDP 7777".

Push to the Edgegap Container Registry: run docker login registry.edgegap.com yourself, with the username and token from the Container Registry page, then docker push. Use a new tag for every build, never latest.

Then create the application and its version in the dashboard:

  • Your image and tag, with registry credentials (without them, deployments fail with "Unable to pull image from registry").
  • One port: 7777, protocol TCP/UDP, named gameport. Two separate 7777 TCP and 7777 UDP entries are rejected as duplicates.
  • Start small on resources: the relay runs no game logic. To size it on real traffic, move off the free tier by adding a credit card (Pay as You Go): it unlocks detailed deployment metrics, so you can see the relay's CPU, memory and network use in a live environment and adjust.
  • Optional environment variables: RELAY_MAX_PEERS (players per relay, default 256) and RELAY_IDLE_EXIT_SECONDS (the relay exits after that many seconds with no room; 0 means never).

With your agent:

"Load the edgegap-containerize skill. Build the LightNet relay from relay-server/Dockerfile at the repository root for linux/amd64, push it to the Edgegap registry with a new tag, then create an Edgegap app and app version for it: one port 7777 with protocol TCP/UDP named gameport, registry credentials set, small resources, restart policy never."

5. Deploy the relay and connect players

Deploy your version from the dashboard (Deploy, pick a location close to your players), or ask your agent:

"Deploy my LightNet relay version near me, wait until it's ready, show me the logs, and give me the host URL and external port."

When the deployment is Ready, players connect to its Host URL (<id>.pr.edgegap.net) and External Port. Edgegap maps TCP and UDP to the same external port, so players pass it once:

  • In the sample: set the relay address and port in TanksSettings.asset, or use -relay <host>.pr.edgegap.net -relayPort <external port> on the command line.
  • In the relay's log, a peer that connects and leaves right after start is Edgegap's readiness check, not a player.

Keeping relays up:

  • Free tier: deployments stop after 60 minutes, which is enough to test.
  • Edge Cloud: deployments are meant to be recycled within 24 hours, and you're warned when one runs longer. Edge Cloud also bills egress, and a relay forwards every byte of every match. As such, it may be ideal for on-demand levels of usage, or for development, playtests and pre-production, but at scale, we recommend studios use Private Fleets for greater cost-effectiveness.
  • Private Fleets: once your game is live and relays run around the clock, Private Fleets are usually the better fit: reserved hosts in 58 locations worldwide, with 6 TB of egress included per host, enough for almost every game, and persistence settings to decide how long each relay runs.
  • Recycling: on any setup, recycling relays regularly is best practice, since a fresh game server is a healthy one (see Edgegap's deployment lifecycle). When, how and how often depends on your game, and the persistence guide covers planning restarts without hurting players. A simple way per region: start a new relay, give its address to players who host new rooms, and stop the old relay once its last room ends.
  • Test deployments: make sure to stop them from the dashboard or your agent when you're done, since a deployment bills while it runs.

6. Group players with room codes

The sample groups players with room codes, not a matchmaker:

  1. A player presses Host. The relay creates a room and returns a 6-letter code, shown in the HUD.

  2. The host shares the code: in a party screen, a friends list, a chat or a Discord message.

  3. Other players type the code and press Join room.

Codes skip I and O, so they're easy to read out loud. The room lasts as long as the host stays: when the host leaves, the relay closes the room and disconnects the others. The host can also kick a player.

To bring this into your game, show the code in your own UI and pass it through whatever already connects your players, such as Steam or Epic Online Services friend invites.

When you need matchmaking: Room codes work among friends. For public matches with strangers, casual or ranked, a cheater ruins everyone's fun, so give the match to a server: extend the relay with your game logic, or start with Mirror Networking, Fish-Networking, PurrNet or Netcode for GameObjects, which cover dedicated servers and Edgegap's Matchmaking end to end.

7. Test with two players

  1. Build the Windows client: Tanks > Build Windows client.
  2. Start two copies. In the first, press Host and note the room code. In the second, type the code and press Join room.
  3. Both tanks appear in both games. Drive and fire: the host sees the other tank move and its shots land.

Automated test: With the relay running, ./e2e.sh <host>.pr.edgegap.net <external port> starts a host and a client on each netcode and checks that both games see two tanks, that reliable and unreliable data went through the relay, and that a projectile spawned. Name netcodes to test only some: ./e2e.sh <host>.pr.edgegap.net <external port> FishNet NGO. It runs the Windows build from a Bash shell, such as Git Bash. The sample passed this test on Edgegap on all four netcodes on 29 October 2026.

Stop the deployment when you're done.

Next Steps

Next Steps

Ready for server authority? No host advantage, no cheating host, and the match survives anyone leaving: see the guides for Mirror Networking, Fish-Networking, PurrNet and Netcode for GameObjects. Or extend the LightNet relay with your own game logic. Or extend the LightNet relay with your own game logic. Prefer a managed relay instead of running your own? See Unity Relays.

Stuck? Ask our team and other studios on the Edgegap Discord.

常见问题

Common questions about running an extensible LightNet relay on a dedicated server for a host-client Unity game.

What is LightNet?

LightNet is a lightweight, open-source C# networking library (Apache 2.0) with server and client modes, reliable and unreliable channels, and no built-in game logic. In this sample, it runs as a relay: a .NET console app in a container that forwards traffic between a host player and the others in each room.

Is an extensible relay a dedicated game server?

Not out of the box. It runs on a dedicated server, but as shipped it runs no game logic: the host player's game owns the match, as in peer-to-peer. What it adds over peer-to-peer and shared relay services is your own relay: hidden IP addresses, no port forwarding, a location you choose, and code you can extend. Add game logic to the relay and it becomes a multi-room dedicated server with relay-like resource efficiency.

Does a relay stop cheating?

Not on its own. Whoever holds the match state can change it, and with a relay that's the host's game. A cheater ruins a match for everyone, whether it's casual or ranked. The LightNet relay does stop attacks on players' connections, since nobody sees another player's IP address. Stopping cheating takes server authority: add game logic so the relay holds the match, or use a small dedicated server per match.

Which netcodes does the sample support?

Mirror, Fish-Networking, PurrNet and Netcode for GameObjects, in one Unity 6 build, with one setting to switch. The relay doesn't know which netcode is used: it forwards bytes. Another netcode needs its own transport around the sample's RelayPeer client.

How is this different from Edgegap's Unity Relays?

Unity Relays are Edgegap's managed Distributed Relays: you create a session per match from an API call, and Edgegap picks the relay. With LightNet, you run the relay yourself as an Edgegap deployment, with your own code and room codes, you choose where it runs, and you can extend it with your own logic.

Can I use the LightNet relay for browser games?

Not with the sample as it is: its transports are TCP and UDP, which browsers can't open. For web games, see Browser Games, Colyseus or Manus AI.

客户

了解更多已接入 Edgegap 的客户案例

提供 31 个从其他平台迁移至 Edgegap 的工作室案例研究。

他们选择 Edgegap 的关键原因

了解 Edgegap 自动化游戏服务器编排如何带来无缝的多人游戏体验。

+平均延迟减少 58

+平均延迟减少 58

14M CCU 快速缩放

14M CCU 快速缩放

+615多全球位置

+615多全球位置

~2 秒。游戏服务器平均启动时间

~2 秒。游戏服务器平均启动时间

多版本支持和滚动更新

多版本支持和滚动更新

91% 填充率對局配對

91% 填充率對局配對

跨平台兼容

跨平台兼容

即时 DDoS 保护

即时 DDoS 保护

跨 17+ 家提供商的多云架构，提供 99.99% 可用性

跨 17+ 家提供商的多云架构，提供 99.99% 可用性

费用

定价

定价

通过混合编排优化成本与性能

通过混合编排优化成本与性能

通过混合编排优化成本与性能

边缘云

按需

$0.00115

/ vCPU

/ 分钟

按分钟计费，仅按实际使用量收费

只有在玩家在线玩游戏时才需付费。0 个活动服务器 = $0

在全球 615 多个边缘云节点中按实例部署游戏服务器。零承诺。

只需添加信用卡。

全球 615+ 家分店

每月流出流量 $0.10/GB

0.25 到 4 个 vCPU 的部署

比较功能与价格

边缘云

按需

$0.00115

/ vCPU

/ 分钟

按分钟计费，仅按实际使用量收费

只有在玩家在线玩游戏时才需付费。0 个活动服务器 = $0

在全球 615 多个边缘云节点中按实例部署游戏服务器。零承诺。

只需添加信用卡。

全球 615+ 家分店

每月流出流量 $0.10/GB

0.25 到 4 个 vCPU 的部署

比较功能与价格

专属物理机集群 (裸金属)

预留容量

$0.0261

/ vCPU

/ 小时

按月计费，始终开启

每个主机每月 $280（12个月标准价），或按月支付每月 $350

通过无出站流量费用的专用机队托管，优化您游戏服务器的成本效益。

持久在线，24/7全天候可用，您的工作室专属。

全球 58 个分支机构

包含出站流量

每台主机总计 16 个 vCPU（14.7 个可用）

比较功能与价格

专属物理机集群 (裸金属)

预留容量

$0.0261

/ vCPU

/ 小时

按月计费，始终开启

每个主机每月 $280（12个月标准价），或按月支付每月 $350

通过无出站流量费用的专用机队托管，优化您游戏服务器的成本效益。

持久在线，24/7全天候可用，您的工作室专属。

全球 58 个分支机构

包含出站流量

每台主机总计 16 个 vCPU（14.7 个可用）

比较功能与价格

您的账单因费率和使用量而异；这可能会根据游戏类型、玩家人数等因素而有所不同。

您的账单因费率和使用量而异；这可能会根据游戏类型、玩家人数等因素而有所不同。

使用我们的预估计算器模拟您的用量 ->

使用我们的预估计算器模拟您的用量 ->

Edgegap 的功能与价格：边缘云与私有集群（Private Fleets）详细对比

Edgegap 的功能与价格：边缘云与私有集群（Private Fleets）详细对比

对比

免费试用

边缘云

Private Fleets

账单与价格

每个 vCPU 的费率

免费

0.00115 美元/vCPU/分钟

$0.0261/vCPU/小时

定价模式

免费

按需（基于使用量）

预留容量

账单

无需信用卡

是的，通过 Stripe

是的，通过 Stripe

承诺

无

无

1、6 或 12 个月（含折扣）

出口

不适用

$0.10/GB/月

含每个主机每月 6 TB 流量

功能特色

分析与监控

账单警报

点击展开

还有 28 行

解锁

在帐户中添加信用卡后，即可解锁各项功能。

中国部署

DDoS 防御

全托管集群

常驻部署

对比

免费试用

边缘云

Private Fleets

账单与价格

每个 vCPU 的费率

免费

$0.00115 / vCPU / 分钟

$0.0261/vCPU/小时

定价模式

免费

按需（基于使用量）

预留容量

账单

无需信用卡

是的，通过 Stripe

是的，通过 Stripe

承诺

无

无

1、6 或 12 个月（含折扣）

出口

不适用

$0.10/GB/月

含每个主机每月 6 TB 流量

功能特色

分析与监控

账单警报

点击展开

还有 28 行

解锁

在帐户中添加信用卡后，即可解锁各项功能。

中国部署

DDoS 防御

全托管集群

常驻部署

对比

免费试用

边缘云

Private Fleets

账单与价格

每个 vCPU 的费率

免费

0.00115 美元/vCPU/分钟

$0.0261/vCPU/小时

定价模式

免费

按需（基于使用量）

预留容量

账单

无需信用卡

是的，通过 Stripe

是的，通过 Stripe

承诺

无

无

1、6 或 12 个月（含折扣）

出口

不适用

$0.10/GB/月

含每个主机每月 6 TB 流量

功能特色

分析与监控

账单警报

点击展开

还有 28 行

解锁

在帐户中添加信用卡后，即可解锁各项功能。

中国部署

DDoS 防御

全托管集群

常驻部署