Discover how Edgegap works

Discover how Edgegap works

/

UGS Matchmaker

UGS Matchmaker

Deploy to Edgegap

Published

Published

Published

Last reviewed for accuracy

Last reviewed for accuracy

Last reviewed for accuracy

UGS Matchmaker: How to deploy dedicated servers on Edgegap from Unity Gaming Services Matchmaker

UGS Matchmaker: How to deploy dedicated servers on Edgegap from Unity Gaming Services Matchmaker

This guide shows you how to keep Unity Gaming Services (UGS) Matchmaker and host every match on Edgegap's dedicated game servers: when UGS forms a match, Edgegap deploys a server near the players and UGS hands its address to every player.

Once your game server is containerized, Edgegap deploys it worldwide to 615+ Edge Cloud locations (on-demand) from a simple API call and billed exclusively on usage: no entire server to rent, provision or keep running between matches. For persistent servers of reserved capacity, Edgegap offers Private Fleets.

The link between the two is Edgegap's allocator, a small Cloud Code module that Unity distributes officially. When a match forms, UGS calls it, it asks Edgegap to deploy your server, then hands the server's address and port back to UGS, which passes them to your players.

UGS Matchmaker with Edgegap: players create tickets, the queue and pool group them into a match, the matchmaker calls the Edgegap allocator in Cloud Code, which requests a deployment on Edgegap and returns the IP and port when ready; the matchmaker writes them into each ticket and game clients connect to the dedicated server

This guide covers:

  1. Preparing a working Edgegap app version and your UGS project

  2. Connecting your coding agent to Edgegap (optional)

  3. Turning on the UGS services

  4. Configuring and deploying Edgegap's allocator

  5. Adding the matchmaking client to your game

  6. Creating your queue and match rules

  7. Testing with two players

You can do it two ways, and mix them:

  • With a coding agent. Connect Claude Code, Cursor or another agent to the Edgegap MCP server and its agent skills. The agent configures the allocator, writes the matchmaking client and checks your app version and deployments. You handle the clicks in Unity and the Unity Cloud dashboard, the secrets, and playtest.

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

Prefer a hosted matchmaker with no Cloud Code? See Unity Matchmaking SDK.

No credit card required. Free tier includes the resources to deploy a real game server.

No credit card required. Free tier includes the resources to deploy a real game server.

Step-by-Step Guide

Detailed Integration Steps

1. Before you start

  • A free Edgegap account. Verify your email. No credit card is needed to test.

  • A working Edgegap app version of your game server: a server you deployed and joined at least once. UGS will deploy that version for every match, so it needs a functional, containerized game server to work end to end. If you don't have one yet, use our guides:

  • A Unity project linked to Unity Cloud (Edit → Project Settings → Services shows the linked project and its ID).

  • The .NET SDK, version 8 or newer, to deploy the Cloud Code module. Check with dotnet --version.

  • An Edgegap API token, from Dashboard → User Settings → Tokens. It goes into a Cloud Code secret in step 4, nowhere else: it is organization-wide, so never put it in your project, your game client, your game server or a chat.

Here, we use Edgegap's fork of Unity's Boss Room sample, which already runs as a dedicated server and includes a matchmaking client.

2. Connect your coding agent to Edgegap

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

The Edgegap MCP server lets your agent check your apps and versions, deploy test servers and read their logs on your account. The edgegap-deployments-api agent skill gives it the rules for backends that deploy Edgegap servers, UGS Cloud Code included: where the token lives, placing servers near players, and handling errors.

Claude Code (run in your own terminal, so the token never passes through the chat):

claude mcp add --transport http edgegap https://mcp.edgegap.dev/mcp -H "Authorization: token YOUR_EDGEGAP_API_TOKEN" --scope user

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

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/edgegap-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 and their versions, with each version's ports."

Note the exact application name, version name and port name: step 4 needs them.

3. Turn on the UGS services

This integration uses three UGS services: Authentication, Matchmaker and Cloud Code. Skip what your project already has.

  1. In Unity, open Window → Package Manager, set the source to Unity Registry, and install Cloud Code and Multiplayer Services (it includes Matchmaker and pulls in Authentication).

  2. On cloud.unity.com, open your project and enable Authentication, Matchmaker and Cloud Code.

  3. Note your environment (production by default). The secret, the module and the queue must all live in that same environment.

4. Configure and deploy Edgegap's allocator

The allocator lives in Unity's matchmaker hosting providers repository, separate from your game project.

  1. Clone it next to your project: git clone https://github.com/Unity-Technologies/matchmaker-hosting-providers.git

  2. Open the Edgegap allocator's EdgegapAllocator.cs and set the three constants marked TODO, copied from your Edgegap dashboard, not retyped: ApplicationName (your application), VersionName (your app version) and PortName (gameport). Leave EdgegapApiTokenSecretName as EDGEGAP_API_TOKEN.

  3. In the Unity Cloud dashboard, under Administration → Secrets, add a secret in the same environment: key EDGEGAP_API_TOKEN, value your Edgegap API token only, with no extra words or spaces.

  4. In Unity, create a Cloud Code C# Module Reference in your project and point it at the allocator's solution file (.sln) in the cloned repository. Pointing it at anything else deploys an empty template while looking like it worked.

  5. Open Services → Deployment, check the module, select your environment, and select Deploy Selected.

  6. Check it landed: in the Unity Cloud dashboard, the module shows two endpoints, Matchmaker_AllocateServer and Matchmaker_PollAllocation, each returning the allocator's own type. A return type of just "string" means the reference pointed at the wrong file.

The three constants to set in EdgegapAllocator.cs: ApplicationName, VersionName and PortName, each marked TODOCloud Code module endpoints in the Unity Cloud dashboard: Matchmaker_AllocateServer and Matchmaker_PollAllocation

With your agent: "In the cloned matchmaker-hosting-providers repository, set ApplicationName, VersionName and PortName in EdgegapAllocator.cs to my Edgegap app, version and port. Don't touch the secret name, and don't write my token anywhere." You add the secret and deploy the module yourself.

Here's our video tutorial of UGS Matchmaker with Edgegap, using Edgegap's fork of Boss Room:

5. Add the matchmaking client to your game

Your game needs a client that signs the player in, creates a ticket on your queue, waits for the assignment, and connects to the server. Only the connect call depends on your netcode (in Boss Room, StartClientIp).

Send each player's public IP in their ticket. Edgegap places the server using the players' locations; without IPs, deployments fall back to a default location. Add it to the ticket's attributes as player_ip; the Edgegap documentation includes a snippet that gets it.

No client yet? Give any AI coding assistant this prompt:

"Add a self-contained Unity Gaming Services Matchmaker client to my game, without changing my netcode. First, audit (read-only) and tell me: the method my project calls to connect a client to a server by address and port (file, line, signature, and the port parameter's type), and the transport in use. Then create one MonoBehaviour that initializes UGS and signs in anonymously; for same-machine testing, sets a unique profile per running instance before sign-in; gets the player's public IP; creates a ticket on a serialized queue-name field with the signed-in player ID and the IP as the player_ip attribute; polls the ticket at most every 3 seconds, retrying failed polls until an assignment arrives or a timeout; then passes the assigned IP and port to my connect method, converting the port to the type it expects. Add a temporary on-screen Matchmake button. Keep it minimal and commented."

Then add it to your start scene: create an empty game object named Matchmaker, add the component, and set its queue name to the queue you create in step 6.

6. Create your queue and match rules

In the Unity Cloud dashboard, open Matchmaker:

  1. Create a queue, for example mygame-queue, with up to 2 players per ticket for this test.

  2. In the queue, create a pool and set its hosting type to Hosting via Cloud Code. Point it at your module, its allocate endpoint and its poll endpoint. The default allocation timeout leaves Edgegap enough time to start a server.

  3. Set the match rules for the simplest test: one team, team count 1, a player count of minimum and maximum 2. Leave backfill off.

  4. Save. The queue goes active, and your matchmaker now deploys to Edgegap.

Then tailor the rules to your game (team sizes, skill ranges, regions) with Unity's Matchmaker documentation. Edgegap only needs the allocator.

7. Test with two players

  1. Run two clients on one machine. With Edgegap's Boss Room fork, use ParrelSync (included), not Multiplayer Play Mode.

  2. Select Matchmake in both. UGS groups the two tickets, calls your allocator, and Edgegap deploys a server near the players. You can watch it appear in the Edgegap dashboard, tagged by the matchmaker.

  3. Both players connect to the same server automatically. The server's container log shows two tickets in, one match out.

  4. Leave the match: your server stops its own deployment when the match ends (see your server guide), so you only pay while players play.

The allocator gets each server's address by polling Edgegap's status API, which is plenty for most games. For very large launches (tens of thousands of concurrent players), switch to Edgegap's ready webhook, described in the Edgegap documentation.

Next Steps

Next Steps

Moving from Multiplay? Edgegap's documentation maps Multiplay concepts to Edgegap. Prefer a hosted matchmaker with no Cloud Code to maintain? See Unity Matchmaking SDK.

Going live? Ask your agent to run the edgegap-launch skill's checklist: version rollouts, restart policy, maximum duration, cost control.

Stuck? Ask your agent to load edgegap-troubleshoot, or ask our team and other studios on the Edgegap Discord.

Frequently Asked Questions

Common questions about hosting Unity Gaming Services Matchmaker matches on Edgegap's dedicated servers.

Can I keep Unity's UGS Matchmaker and host my servers on Edgegap?

Yes. Keep your queues and rules in UGS, and add Edgegap's allocator as a Cloud Code module. When a match forms, it deploys your server on Edgegap and returns the address and port to UGS, which hands them to your players.

Is the Edgegap allocator for UGS official?

Yes. It's an official, Unity-approved integration, distributed in Unity's matchmaker hosting providers repository. You set your app, version and port, add your token as a secret, and deploy it.

Where does my Edgegap API token go with UGS?

Only in a Cloud Code secret named EDGEGAP_API_TOKEN, in the same environment as your module and queue. Never in your game client, your game server or your project files.

How does Edgegap choose the server location for a UGS match?

From the players' public IP addresses, sent in their matchmaking tickets. Edgegap picks the location with the best ping for the whole group. Without IPs, deployments fall back to a default location.

Should I use UGS Matchmaker or Edgegap's matchmaker?

Keep UGS if your game already uses its matchmaker or other Unity Gaming Services. Edgegap's matchmaker is hosted, free to test and needs no Cloud Code, and deploys servers near players by itself.

Clients

Learn more from clients who integrated Edgegap

31 case studies are available from studios that moved to Edgegap from another platform.

Key reasons why they chose Edgegap

Discover the impact of Edgegap's automated game server orchestration for a flawless multiplayer experience.

Cost

Pricing

Optimize costs and performance with hybrid orchestration

Optimize costs and performance with hybrid orchestration

Optimize costs and performance with hybrid orchestration

Edge Cloud

On-Demand

$0.00115

/ vCPU

/ MINUTE

Billed by the Minute, Only on Usage

Pay only when players play. 0 active servers = $0

Deploy game servers worldwide, per instance, to all 615+ edge cloud locations. Zero commitment.

Simply add a credit card.

Edge Cloud

On-Demand

$0.00115

/ vCPU

/ MINUTE

Billed by the Minute, Only on Usage

Pay only when players play. 0 active servers = $0

Deploy game servers worldwide, per instance, to all 615+ edge cloud locations. Zero commitment.

Simply add a credit card.

Private Fleet (Bare Metal)

Reserved Capacity

$0.0282

/ vCPU

/ HOUR

Billed Monthly, Always On

$280 per host/month (12 mo rate), or $350 monthly

Optimize the cost effectiveness of your game server with egress-free hosting of Private Fleets.

Persistent, available 24/7, exclusive to your studio.

Private Fleet (Bare Metal)

Reserved Capacity

$0.0282

/ vCPU

/ HOUR

Billed Monthly, Always On

$280 per host/month (12 mo rate), or $350 monthly

Optimize the cost effectiveness of your game server with egress-free hosting of Private Fleets.

Persistent, available 24/7, exclusive to your studio.

Your bill varies per rate and usage; which can vary per game type, player count, & more.

Your bill varies per rate and usage; which can vary per game type, player count, & more.

Model your usage with our estimate calculator ->

Model your usage with our estimate calculator ->

Edgegap's features & price: detailed comparison between Edge Cloud & Private Fleets

Edgegap's features & price: detailed comparison between Edge Cloud & Private Fleets

COMPARE

Free Trial

Edge Cloud

Private Fleets

FEATURES

Analytics & Monitoring

Billing Alarms

Click to Expand

28 more rows

Unlocks

Capabilities are unlocked when a credit card is added to the account.

COMPARE

Free Trial

Edge Cloud

Private Fleets

FEATURES

Analytics & Monitoring

Billing Alarms

Click to Expand

28 more rows

Unlocks

Capabilities are unlocked when a credit card is added to the account.

COMPARE

Free Trial

Edge Cloud

Private Fleets

FEATURES

Analytics & Monitoring

Billing Alarms

Click to Expand

28 more rows

Unlocks

Capabilities are unlocked when a credit card is added to the account.