
Port Mapping
Port mapping exposes a game server’s internal port on its host’s public address so players can reach it. When many servers share one machine, each needs its own external port. The mapping is what turns ‘a container is running’ into ‘a player can connect to it’.
Also called
container port mapping, port publishing
,
What Does Port Mapping Do for a Game Server?
A game server listens on a port inside its container: a number set in its build or launch arguments, such as Unreal Engine’s default 7777 (Epic Games). Players usually can’t reach that number directly. The host they connect to has a public address, usually shared by every server running on it, and port mapping is the rule that sends traffic arriving on one of the host’s ports to one container’s port.
On the way in, a player’s packet is translated at least at two points:
On the player’s side: a home router, and often the internet provider too, uses network address translation (NAT) to share one public address across many devices. As Michal Buras of Highwire Games put it, “your public IP is not your own public IP”: providers group “multiple users under single IP”, and the port that tells them apart is “temporarily assigned” (Live Service Game Summit, 2024). All of this sits outside the studio’s control.
At the game server’s host: the host maps one of its public ports to the container’s internal port. That is the mapping the studio, or its orchestrator, controls.
Because the player opens the connection, their router lets the replies back in, so joining a hosted server usually needs no setup on the player’s side, even behind a shared address. Shared addresses matter mostly when a player hosts (see the FAQ below).
Article's key insights
Build and Ship your code/game into a Container Package and push it to Edgegap as a new app version. It's as simple as creating a Dockerfile for your build and letting Edgegap handle the rest.
Test Live, Not Local! Skip the "iT wOrKs oN mY mAcHiNe <insert spongebob meme here>" headache by deploying to Edgegap's actual edge network in seconds. This approach eliminates the disparity between your dev environment and your production environment, like having a staging environment without having to pay for a second environment. You'll instantly know if your app runs properly in the real world across 615+ global locations, catching issues that local testing misses.
Add Your Developer Tools Deploy the supporting tools you need alongside your app - whether that's web utilities, network beacons for testing, proxy services, databases, or anything else that keeps your development workflow smooth and efficient.
Test Individual Components Quickly Deploy and test specific components or services in isolation without spinning up new clusters or affecting your production stack. Perfect for testing new APIs with “fake” backends, validating microservices, or experimenting with configuration changes in a live edge environment.
Why Does Each Game Server Get a Different Public Port?
Many matches can share one host, and on the same address, two servers can’t each listen directly on the same public port and protocol. So each server gets its own external port, while every container keeps listening on the same internal one. The build stays identical; only the mapping differs.
Some orchestrators also pick a new external port for each server they start. Either way, the public port is a property of one running server, not of the game.
A client that always dials the port it used in local testing works wherever the public port happens to equal the default, and fails wherever the two differ. The fix sits in the client: take the port from whatever tells it where the match is, rather than from a constant in the code.
How Do Players Get the Right Address and Port?
The external port often exists only once the server has started, so it has to travel to the player:
The orchestrator starts the server and records its public address and the external port for each internal one.
Whatever hands out connections reads them: a matchmaker in its match assignment, or a server browser in its listing.
The client receives the address and port, and connects.
The server sometimes needs the mapping too, for example to register itself in a server list with the port players will actually use. A server that reports its internal port sends players to the wrong port whenever the two differ.
On Edgegap, a deployment gets an external port for each internal port once it is ready, and the server can read both from environment variables (ARBITRIUM_PORT_<NAME>_INTERNAL and ARBITRIUM_PORT_<NAME>_EXTERNAL). External ports are randomized for each deployment, for security, and the mapping can be changed for new deployments by editing the app version, without rebuilding the server (Edgegap docs).
Which Ports Does a Game Server Need to Map?
One for gameplay, and often more. Each port is mapped on its own, and a port is a number plus a protocol (see UDP vs TCP), so every mapping has to name the protocol the server actually uses. A common set:
Port | Protocol | What it carries |
|---|---|---|
Gameplay | Usually UDP | Inputs and state updates during the match |
Query | Often UDP | Server name, map and player count for server lists |
Remote admin (RCON) | Often TCP | Commands from server operators |
Browser connection | Usually TCP (WebSocket) | Gameplay for builds that run in a web browser |
A protocol mismatch is easy to miss: a mapping set up for TCP lets a UDP game’s server start normally, while none of the players’ packets reach it. Container tools differ in their defaults, so check the protocol on every mapping rather than relying on one (the Docker case is in the FAQ below).
Browser builds can’t open raw UDP sockets, so they usually connect over WebSocket on a TCP port. A game that ships a native build and a browser build can need one mapping for each.
A word from our sponsor (ourselves!)
A region is a guess about where your players will be. Edgegap's Edge Cloud is a distributed, multi-cloud network of 615+ locations across 17+ providers, available on demand. Each server launches at the best available location on the network when the match starts, not at the nearest of a handful of regions.
Why Can’t Players Connect to My Game Server?
When a first deployment starts but nobody can join, the cause is often one of these, roughly in the order worth checking:
The server isn’t ready: the client connected before the server finished starting, or the server crashed on start. Read the server’s logs first.
The internal port doesn’t match: the port in the build’s network settings or launch arguments differs from the internal port in the mapping.
The server listens on localhost only: a server bound to
127.0.0.1accepts traffic only from its own network namespace (its container, or its Kubernetes pod). It needs to listen on all interfaces (0.0.0.0).The protocol is wrong: the mapping is TCP and the game uses UDP, or the reverse.
The client has the internal port: the client, or the address the server advertised, uses the internal port instead of the external one.
On machines a studio manages itself, a firewall rule on the host or in the cloud network can also block the external port. Browser builds add one more check, in the Take below.
Edgegap's Take (just our opinion, take it with a grain of salt!)
Give Your Browser Build a Secure WebSocket Port Before Its First Public Playtest
A browser build lets players join a match from a link, with nothing to install. It also adds a way for the connection to fail that native builds don’t face.
A game page served over HTTPS generally can’t open a plain ws:// connection: browsers block it as mixed content (websocket.org). The player sees no prompt; the only sign is an error in the browser console. A build tested from a local http:// page can pass every test and still fail for every player.
A useful check before the first public playtest: open the build from the HTTPS address players will use, join a match, and look in the browser console for a blocked or failed WebSocket. Repeat it whenever the hosting page or the server’s address changes.
On Edgegap, a WebSocket port can use a managed certificate: set the port to WS with TLS Upgrade enabled, and have clients connect with wss:// to the deployment’s Edgegap URL. Studios with their own domain can use WSS with their own certificate (Edgegap docs). For the transport choices behind browser games, see UDP vs TCP.
,










