Integrating Unity Matchmaker

Unity Matchmaker is part of Unity Gaming Services (UGS). It handles player ticket submission, queue management, and match rules — but it needs an external allocator to actually start a dedicated server.

Gameye provides a Cloud Code module — GameyeAllocator — that bridges Unity Matchmaker to the Gameye Session API. When a match is formed, Matchmaker calls the allocator, Gameye starts a dedicated server, and connection details are passed back to your game clients. No polling, no retry loops.

How it works

Game Client → Unity Matchmaker → Cloud Code (GameyeAllocator)
                                         ↓
                                     Gameye API (POST /session)
                                         ↓ ~0.5s
                                  Dedicated game server
                                         ↓
              Game Client ← Unity Matchmaker (IP + port delivered)

Gameye’s POST /session returns the server IP and port synchronously on the allocation call. The Poll function is implemented for compatibility with Unity’s two-phase Allocate/Poll contract — it resolves immediately on the first call in almost all cases.

Prerequisites

Before setting up the allocator, make sure you have:

• A Gameye account with an application and at least one image tag in Ready status — see the Getting Started guide
• A Unity project with Unity Gaming Services enabled
• Unity Matchmaker configured with at least one queue
• .NET SDK 9.0+
• UGS CLI

npm install -g @unity-services/ugs-cli

Getting the module

The GameyeAllocator module is available as open source from Unity’s matchmaker-hosting-providers repository. Clone or download the repo, then work from the modules/GameyeAllocator/ directory:

git clone https://github.com/Unity-Technologies/matchmaker-hosting-providers.git
cd matchmaker-hosting-providers/modules/GameyeAllocator

If you’d prefer Gameye to deploy and configure the module for you as part of onboarding, contact [email protected] or reach out on Discord.

The module contains:

modules/GameyeAllocator/
├── GameyeAllocator.sln
├── CONFIGURATION.md
└── Project/
    ├── GameyeAllocator.cs        ← Allocate + Poll logic
    ├── GameyeAllocatorConfig.cs  ← Edit this to configure the allocator
    ├── GameyeAllocator.csproj
    └── Client/
        ├── GameyeClient.cs
        └── Models/
            ├── SessionRequest.cs
            └── SessionResponse.cs

Setup

1. Configure the allocator

Open Project/GameyeAllocator.cs and edit the GameyeAllocatorConfig block in ModuleConfig.Setup():

config.Dependencies.AddSingleton(new GameyeAllocatorConfig
{
    // Required — the application image name registered in the Gameye Admin Panel.
    ImageName = "MyGame",

    // The API environment. Use Sandbox for development, Production for live.
    Environment = GameyeEnvironment.Production,

    // Default deployment region — used when no region mapping matches.
    DefaultLocation = "eu-west",

    // Primary game server port (must match your Dockerfile EXPOSE / Admin Panel config).
    GamePort = 7777,
});

Field	Where to find the value
ImageName	Gameye Admin Panel → Applications — must match exactly
Environment	Sandbox for development, Production for live
DefaultLocation	See available locations
GamePort	Must match the port exposed in your Dockerfile

2. Add your Gameye API token as a secret

The allocator reads your API token from Unity’s Secret Manager at runtime — it is never hardcoded.

1. Go to Unity Dashboard → your project → Administration → Secrets
2. Click Add Secret
3. Set the name to GAMEYE_API_TOKEN
4. Set the value to your Gameye API bearer token (create or retrieve it in the Admin Panel)

3. Deploy the module

Authenticate with Unity and deploy:

# Log in to UGS
ugs login

# Link to your Unity project (follow the prompts for Project ID and environment)
ugs init

# Deploy the module
cd modules/GameyeAllocator
ugs deploy

Deployment typically takes under a minute. You’ll see a confirmation in the terminal when the module is live.

4. Configure your Matchmaker queue

1. Go to Unity Dashboard → Matchmaker → Queues
2. Select your queue (or create one)
3. Open the Pools tab and create or edit a pool
4. Set Hosting Type to Cloud Code
5. Fill in the allocator function names:

Field	Value
Module Name	GameyeAllocator
Allocate Function Name	Matchmaker_AllocateServer
Poll Function Name	Matchmaker_PollAllocation

6. Save the pool

5. Test the integration

Start a matchmaking request from your game client. When a match is formed:

• Matchmaker calls Matchmaker_AllocateServer
• Gameye provisions a dedicated server (~0.5 seconds)
• Matchmaker calls Matchmaker_PollAllocation — connection data is returned immediately
• Your game clients receive the server IP and port

Debugging: Cloud Code logs are available at Unity Dashboard → Cloud Code → Logs. Each allocator invocation logs the resolved region and the Gameye API response — check here first if allocations are failing.

Region routing

The allocator supports two approaches to region routing, evaluated in priority order:

Option A — Unity QoS automatic region selection (recommended)

Unity Matchmaker runs QoS measurements to determine the lowest-latency region for each group of matched players and writes the result to MatchProperties["Region"]. The allocator reads this value and maps it to a Gameye location using LocationByRegion.

This approach requires no per-region pools — a single global pool can serve all regions.

config.Dependencies.AddSingleton(new GameyeAllocatorConfig
{
    ImageName = "MyGame",
    Environment = GameyeEnvironment.Production,
    DefaultLocation = "eu-west",
    GamePort = 7777,

    LocationByRegion = new Dictionary<string, string>
    {
        { "eu-west",        "eu-west"        },
        { "us-central",     "us-central"     },
        { "asia-northeast", "asia-northeast" },
    },
});

On first run, check Cloud Code logs to confirm the exact value Unity writes for your QoS regions — it may be a human-readable name or a UUID depending on your Matchmaker configuration. If the value has no entry in LocationByRegion, the allocator logs a warning and falls through to the next step.

Option B — Pool-name mapping

If Unity QoS is not configured, or as a fallback when LocationByRegion has no match, the allocator maps the matched pool’s name to a Gameye location using LocationByPool.

This requires one pool per region in your Matchmaker queue, with QoS rules routing players to the correct pool before matching.

LocationByPool = new Dictionary<string, string>
{
    { "eu-west-pool",    "eu-west"        },
    { "us-central-pool", "us-central"     },
    { "ap-ne-pool",      "asia-northeast" },
},

Pools not in the map fall back to DefaultLocation.

Priority order

Priority	Source	Config property
1	MatchProperties["Region"] (Unity QoS)	LocationByRegion
2	Pool name	LocationByPool
3	Static fallback	DefaultLocation

Reference: Unity region → Gameye location

Unity QoS region	Gameye location
us-east	us-east
us-west	us-west
eu-west	europe
eu-central	europe
asia-east	asia-southeast
asia-southeast	asia-southeast
southamerica-east	southamerica
australia-southeast	australia

For the full list of Gameye location IDs, see Available Locations.

Advanced configuration

Pinning an image version

By default, Gameye starts sessions using the highest-priority image tag configured in the Admin Panel. To pin a specific tag:

Version = "v1.2.3",

Additional ports

If your game server exposes more than one port (e.g. a query port or RCON), list them in AdditionalPorts. They are returned in the match assignment data alongside the primary port so game clients can access them.

AdditionalPorts = new Dictionary<string, int>
{
    { "query", 27015 },
    { "rcon",  27020 },
},

The primary port is available to clients as port. Additional ports appear as port_query, port_rcon, etc.

Warm pool behaviour

If a warm pool is configured for the region and image, Gameye returns an already-running server instantly — sub-second allocation. In this case, env values set in the allocator code are ignored; configure any required environment at the warm pool level instead.

Further reading

• Gameye Session API — POST /session
• Available locations
• Unity Matchmaker documentation
• Unity Cloud Code modules
• Getting started with Gameye