How to Deploy Dedicated Servers from Unity's UGS Matchmaker with Edgegap
This tutorial covers how to connect Unity Gaming Services Matchmaker to Edgegap, so your matched players are deployed onto a dedicated game server spun up on demand, in a region close to your players, worldwide.
It picks up from a project that already runs dedicated servers on Edgegap. If you don't have that yet, our integration tutorials cover it across engines, netcodes, and backends. We also recommend following our documentation.
Let's get to it.
Part 1 - Setup
This tutorial assumes two things. First, you have a Unity project that already runs as a dedicated server on Edgegap, with an application and a live version on the platform. Second, you already use, or want to use, Unity's Matchmaker.
For this tutorial, we're using Edgegap's own fork of Unity's NGO Boss Room sample. We picked it because it already ships with everything a dedicated-server project needs. It also includes a small matchmaking client, a simple in-game "Matchmake" button that calls the UGS Matchmaker. Since that call flow is often unique to each project's structure, we'll cover how to recreate it later, both with the code reference from our fork and with a code-assistant prompt you can adapt to your own game.
Part 2 - Edgegap: Game Server Hosting & Orchestration
The first thing your project needs is the Unity Gaming Services packages and the three services this integration relies on: Authentication, Matchmaker, and Cloud Code. If you already have these running in your project, you can skip to the next part.
Start in the Unity editor and install the two packages you need:
Select "Window", then "Package Manager".
Set the packages source to "Unity Registry".
Search for "Cloud Code", select it, and select "Install".
Search for "Multiplayer Services" and select "Install". This package bundles the Matchmaker and pulls in Authentication for you.
After a few seconds, both appear in your project.
Next, turn the services on in the Unity Cloud dashboard. First, make sure your project is linked to a Unity Cloud project: under "Edit", "Project Settings", "Services", you should see a linked project and its ID. If it isn't linked yet, link it here. If you run into trouble at this step, Unity's support flow is the place to sort it out.
Then, in your browser, head to your project on cloud.unity.com and sign in. Enable the three services: Authentication, Matchmaker, and Cloud Code.
Take note of your environment, which is "production" by default. Everything you set up from here, your secret, your module, and your queue, has to live in that same environment, so keep it consistent.
We'll come back for the Matchmaker's queue later, once the piece it depends on exists.
Part 3 - The Edgegap Allocator
The heart of this integration is a small Cloud Code module that lets Unity's Matchmaker deploy a server on Edgegap. It's distributed officially by Unity, so you only need to configure and deploy it.
When a match forms, this module does two jobs. First, it asks Edgegap to deploy a server for your application. Then it polls that deployment until the server is ready, and hands its address and port back to the Matchmaker, which passes them to your players.
The module lives in Unity's Matchmaker hosting providers repository, separate from your game's project. Open a terminal and clone it next to your project. The clone command is the same on every OS; only the folder path differs:
macOS / Linux
Windows (PowerShell)
Open the cloned folder and browse to the Edgegap allocator. The one file you configure is the allocator itself; it has a few constants near the top, marked with a "TODO", that tell it which Edgegap application to deploy.
Set the application name to match your Edgegap application exactly as it appears in your dashboard, for example com-unity-multiplayer-samples-coop. A single character off here will fail silently later, so copy it rather than retype it.
Set the version name to the exact name of your application's version on the Edgegap platform.
The port name should already read gameport, which matches the port on our version. Note that this port is UDP on 7777 for this sample. This may be different with other netcodes. As such, make sure to review your netcode's documentation for the accurate port to your use case.
Leave the secret name as EDGEGAP_API_TOKEN; we'll create that secret next. Save the file.
Cloud Code reads your Edgegap API token from a secret, so the module never contains your key. From your Edgegap dashboard, select your organization, then "Tokens", and copy your token. Then, in the Unity Cloud dashboard, go to your project's secrets under the "Administration" menu, and add a secret:
Key:
EDGEGAP_API_TOKEN(all uppercase)Value: your Edgegap API token, and only the token, with no extra words or spaces
Environment: the same one as everything else (e.g. production)
Now deploy the module from the editor. Back in Unity, create a "Cloud Code C# Module Reference" in your project's main folder. Select it, and in the Inspector, point it at the allocator's solution file, the .sln file inside the repository you just cloned.
This is the step that trips people up: if the reference points at anything but the real solution file, the deployment will look like it worked but push an empty template instead. So make sure it's the actual .sln file.
Open the "Deployment" window under "Services". Your module appears there. Make sure it's checked and set to your environment, then select "Deploy Selected". It compiles, zips, and publishes. This uses the .NET SDK, version 8 or newer; you can confirm your version with:
Now the important part: verify the deploy landed, rather than trusting the success message. Back in the Unity Cloud dashboard, open your Cloud Code module and check its endpoints. You should see two, the allocate endpoint and the poll endpoint, each returning the allocator's own response type. If you see those two, your module is live. If a return type instead just reads "string", the module reference was pointing at the wrong file, so go back and fix it before continuing.
Part 4 - Wiring the Queue
With the module live, you can tell the Matchmaker to use it. This is where your existing matchmaker gets pointed at Edgegap, and for most projects, it's the only real change.
In the Matchmaker section, create a queue, for example bossroom-queue. For this simple test, allow two players per ticket.
Inside the queue, create a pool and set its hosting type to "Hosting via Cloud Code". This is the switch that sends allocation to your module instead of anywhere else. Point the pool at your module: the allocator, its allocate endpoint, and its poll endpoint. The allocation timeout is how long the Matchmaker waits for Edgegap to spin up a server; the default is plenty, since a fresh deployment can take a little time.
Finally, set the match rules. For the simplest possible match, one team of two players: one team, a team count of one, and a player count with a minimum and maximum of two. Leave backfill off and add no other rules for now; you can tailor all of this to your game later.
Save, and your queue goes active. That's the backend done, and your matchmaker now deploys to Edgegap.
Part 5 - The Matchmaking Client
Your players need a way to request a match, and something that takes the assigned server and connects them to it. In our fork, that client already exists, so we'll look at what it does and how to get the equivalent in your own game.
Walking through it: the client signs a player in, creates a matchmaking ticket on your queue, and waits while polling for a result. The moment the Matchmaker assigns a server, it reads that server's address and port and hands them to the game's own connect call.
That connect call is the one part specific to your netcode. In Boss Room, it's StartClientIp. In your game, it's whatever your project already uses to connect a client to a server by address and port. Everything else, creating the ticket, waiting, and reading the assignment, is the same for any Unity Gaming Services project.
If your project doesn't already have this client, you can give any AI coding assistant the prompt below. It first audits your project to find how your game connects to a server, then generates a small, self-contained matchmaking client that creates a ticket, waits for the assignment, and calls your own connect method, whatever netcode you use. It also adds a couple of testing conveniences our sample keeps simple: it gives each local instance a unique player identity so you can test two clients on one machine, and it polls with a longer interval. As always, the connect line depends on your game, so review what it produces.
Finally, wire the client into the scene, the one scene change the fork needs. In your start scene, in our case the main menu, create an empty game object: from the Hierarchy, right-click, "Create Empty", and name it "Matchmaker". With it selected, add the "Edgegap Matchmaker Client" component.
One field matters here: the queue name. Set it to the exact name of the queue you created, for example bossroom-queue. If it doesn't match your queue, tickets go nowhere, so double-check it. Save the scene.
Part 6 - Testing
Let's test the whole thing, end to end, with two clients on one machine. We'll simulate the second player with ParrelSync, which creates a separate copy of the project; the fork already includes it. Do not use Multiplayer Play Mode with this fork.
Press Play in the editor. Each player reaches the main menu, where you'll see a simple "Matchmake" button in the top-left, the temporary test trigger the client provides.
Select "Matchmake" in both. Each creates a ticket and starts waiting. Behind the scenes, the Matchmaker groups the two players, calls your allocator, and Edgegap deploys a fresh server for them. In the Edgegap dashboard, you can watch the server appear, tagged by the Matchmaker, in a location picked for your players.
Both players then connect to the same server automatically, without anyone ever typing an address. Move in one window, and it replicates in the other. You can confirm the whole loop in the server's container log: two tickets in, one match out, your allocator invoked, and a live server on Edgegap.
Congratulations, your Unity Matchmaker is now deploying and connecting players on Edgegap.
Part 7 - Next Steps
That is all for connecting the UGS Matchmaker to Edgegap, which empowers game developers with simple dedicated server hosting and orchestration, deployed on demand worldwide.
The likely next step in your game development will be to tailor your matchmaker's rules to your game, including your team sizes, skill ranges, and more. Unity's documentation covers those configurations. And for a fully managed alternative, Edgegap's own free, simple, and fully automated matchmaker has its own tutorial.
If you have any questions, join our Discord.
