Edgegap

Overview

Edgegap is a game server orchestration platform that deploys Dedicated Game Servers on demand, at the location with the best ping for the players in each match. Every deployment is a Docker Container started from a single HTTP API call and runs for the length of one match. To learn more about Edgegap, visit the official Edgegap website.

This page explains how to set up the Photon Fusion SDK to deploy and run a Dedicated Server on Edgegap. Matchmaking stays on Photon Cloud: the Edgegap deployment is the game server and clients find it through Photon by session name and region.

External Links

• Edgegap Documentation
• Edgegap Unity Guide
• Fusion Dedicated Server Sample
• Fusion Dedicated Server Docker Image

How to Run

Edgegap runs each Dedicated Server as a Docker Container. The Fusion Dedicated Server Docker Image sample runs on it with one small addition: a start script that passes Edgegap's deployment values to the server.

1. Setup

To deploy a Fusion Dedicated Server on Edgegap, you need an Edgegap account, an API Token and a container registry. Edgegap includes a private registry at registry.edgegap.com, and any other registry (Docker Hub, for example) also works. In the Edgegap dashboard, create an Application for your game, and copy your API Token and your Container Registry credentials. Refer to the Edgegap documentation for the detailed steps.

2. Dedicated Server Build

Follow the Fusion Dedicated Server Sample page to set up and build your project as a Dedicated Server: Linux target, x86_64 architecture, Server Build checked. Use IL2CPP as the Scripting Backend for the server build. We recommend testing the default sample on its own first, to understand the build and deploy process before you integrate it into your own project.

3. Server Docker Image

Create the Docker Image by following the Fusion Dedicated Server Docker Image page. That sample reads its configuration from command-line arguments (-s session name, -r region, -l lobby). Edgegap passes deployment values as environment variables instead, so add a small start script that maps them to those arguments:

Bash

#!/bin/bash
# edgegap-entrypoint.sh
# Session name = the Edgegap deployment ID, known to your backend as soon as it deploys.
ARGS=(-s "${ARBITRIUM_REQUEST_ID}")

# Photon region, set per deployment (see Region Reference Mapping below).
if [ -n "${PHOTON_REGION}" ]; then ARGS+=(-r "${PHOTON_REGION}"); fi

# Optional custom lobby.
if [ -n "${PHOTON_LOBBY}" ]; then ARGS+=(-l "${PHOTON_LOBBY}"); fi

# Replace with the path where the sample's Dockerfile copies bin/entrypoint.sh.
exec /path/to/entrypoint.sh "${ARGS[@]}"

In the sample's Dockerfile, copy this script into the image and set it as the ENTRYPOINT. Leave the -i and -p arguments empty: Fusion discovers the server's public address through STUN, which is what gives clients a Direct connection on Edgegap (see Bind and Public Address). Do not print the environment at startup, because it contains ARBITRIUM_DELETE_TOKEN.

Build the image for linux/amd64 and push it to your registry:

Bash

docker login registry.edgegap.com
docker build --platform linux/amd64 -t registry.edgegap.com/<project>/fusion-server:<tag> .
docker push registry.edgegap.com/<project>/fusion-server:<tag>

Use a new tag for each build.

4. Application Version

In the Edgegap dashboard, create a Version of your Application that points at the image you pushed:

• Image: registry.edgegap.com/<project>/fusion-server and the tag, with your registry credentials.
• Resources: 1 vCPU and 2 GB of memory is a good starting point. Adjust it after load testing.
• Port: 27015, protocol UDP (the sample's default port), with port verification turned off. Players reach it through a public port that Edgegap assigns per deployment and Fusion discovers that mapping on its own.
• Restart Policy: never, so the deployment ends when the server process exits at the end of the match.
• Max Duration: the longest a match can last, as a safety limit.

5. Server Deploy

Starting a new Dedicated Server on Edgegap is one HTTP request from your game backend. For the full API reference, see the Edgegap documentation.

Send a POST request to https://api.edgegap.com/v2/deployments with the header Authorization: token <edgegap api token> and a JSON body like the one below. Edgegap uses the players' public IP addresses to pick the location with the best ping for the whole group, and the server is up within seconds:

JSON

{
  "application": "<edgegap application name>",
  "version": "<edgegap version name>",
  "users": [
    { "user_type": "ip_address", "user_data": { "ip_address": "<player 1 public ip>" } },
    { "user_type": "ip_address", "user_data": { "ip_address": "<player 2 public ip>" } }
  ],
  "environment_variables": [
    { "key": "PHOTON_REGION", "value": "<photon region>", "is_hidden": false }
  ],
  "tags": ["<match id>"]
}

The response returns a request_id. Because the start script uses it as the Session Name, your backend can hand it to the players right away: clients start their NetworkRunner with GameMode.Client, that session name and the same PHOTON_REGION. To know when the server is running, add a webhook_on_ready URL to the request, or poll GET https://api.edgegap.com/v1/status/<request_id>.

Keep the Edgegap API Token in your backend only. Never ship it in the game client or in the server image.

Extra Information

Bind and Public Address

The server must bind to 0.0.0.0 (any address) and let Fusion discover its public address:

If your network setup requires an explicit public address, set it through CustomPublicAddress (the sample's -i and -p arguments) using ARBITRIUM_PUBLIC_IP and the external port Edgegap assigns.

Ending a Match

When the match is over, shut down the NetworkRunner and exit the server process. With the Restart Policy set to never, the deployment then stops and billing ends. The server can also stop its own deployment by calling ARBITRIUM_DELETE_URL with ARBITRIUM_DELETE_TOKEN, and the version's Max Duration acts as a final safety limit.

Region Reference Mapping

A Fusion Server must connect to the same Photon Cloud Region as its clients, or clients get GameNotFound. Pass the region your clients use as PHOTON_REGION in the deploy request. If clients pick their region by ping, use the Photon region closest to the Edgegap deployment location, which the server can read from ARBITRIUM_DEPLOYMENT_LOCATION (city, country and coordinates).

The table maps each area to its nearest Photon region. The full region list is on the Photon Regions page.