Deploy from UGS

Follow this guide if you prefer to keep your Unity Matchmaker and deploy servers to Edgegap.

Looking for alternatives? Consider our managed Matchmaking with SDK integration and examples.

Getting Started

This guide focuses on adding Edgegap server hosting as a hosting provider, assuming:

• you have a working Unity Matchmaking setup,

• you have registered on Edgegap and uploaded your Unity server build.

Please refer to Unity's Matchmaking documentation for matchmaking topics.

See Switch From Multiplay for comparing and mapping Multiplay concepts to Edgegap hosting.

Choosing the right location for your server can reduce latency by up to 58% on average!

In this guide, we'll cover:

• building and deploying EdgegapAllocator cloud script module for your Matchmaker,

• retrieving players' public IP addresses used for optimal server placement,

• implementing a webhook listener in UGS cloud script and retrieving server assignment.

Edgegap Allocator

Start by downloading the hosting providers repository with EdgegapAllocator source code.

This is our cloud script used to start new servers, launched by Unity matchmaker once the match is assembled. This is an official Unity-approved integration.

Required Secrets

First, add these secrets in the Unity Dashboard under Administration > Secrets:

• EDGEGAP_API_TOKEN - Your Edgegap API token.

Find your token in the Edgegap Dashboard.

Required code changes

Edit Project/EdgegapAllocator.cs and update these constants:

Replace with your Edgegap application name from the Applications List.

ApplicationName (line 34)

private const string ApplicationName = "MyApp"; // TODO: Replace with actual application name

Replace with your Edgegap application's version name you want to use.

VersionName (line 35)

private const string VersionName = "MyVersion"; // TODO: Replace with actual version name

Replace with your Edgegap application version's port name that will be used for players to connect.

PortName (line 36)

private const string PortName = "gameport"; // TODO: Replace with actual port name

Deploy the module

Follow the official Unity instructions to deploy your customized module using CLI or Editor.

Retrieve Player IP

If no player IP address is provided, your deployments fall back to Los Alamos location.

To provide the optimal server location for each match on demand, Edgegap requires you to provide player IP addresses when making a deployment. While Unity does not provide this feature, you can use our C# snippet to implement this in your game clients using free service ipify:

PlayerNetworkBehaviour.cs

public class PlayerNetworkBehaviour : MonoBehaviour {
    public IEnumerator GetPublicIP(Action<string> callback)
    {
        UnityWebRequest request = UnityWebRequest.Get("https://api.ipify.org?format=json");
        yield return request.SendWebRequest();
    
        if (request.result == UnityWebRequest.Result.Success)
        {
            string responseText = request.downloadHandler.text;
            string clientIp = JObject.Parse(responseText)["ip"].ToString();
            callback(clientIp);
        }
        else
        {
            Debug.LogError("Failed to fetch public IP address.");
        }
        request.Dispose();
    }
}

Every player is expected to provide their public IP address using custom data in their tickets:

CreateTicketOptions ticketOptions = new CreateTicketOptions(
    queueName: "my-queue", 
    attributes: new Dictionary<string, object>
    {
        { "player_ip": "<insert-ip>" },
    }
);

Receiving Assignment

Assignment can be retrieved using the standard Unity matchmaking methods.

Our example will handle assignments for you using Status API, rate limited at 20 req/s.

This is sufficient for most games. If you expect more than 50,000 CCU, consider alternative methods.

Alternative Assignment

For large worldwide launches, a more scalable alternative using Webhooks is available.

Once the match is made, and your cloud script requests a new deployment, your response will not include the connection details yet. Instead, you will receive a form of receipt - a deployment ID.

Your allocator function needs to store this deployment ID in your UGS Game Data alongside the matched players' IDs, so you can look up the players and provide connection details later.

Now, you will need to create another cloud script function AssignmentProcessor with a public URL. This URL must be included in your Allocator's deployment request as webhook_on_ready .

Once Edgegap deploys your game server, it will send a webhook HTTP event including all connection details such as FQDN (URL) and the external port for client connections back to your new cloud script. Your AssignmentProcessor will need to look up the deployment ID, and store the connection details alongside it.

Your game clients must poll this game data and attempt connection as soon as the FQDN and external port are retrieved.