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

Gameye provides the GameyeAllocator module as a ready-to-deploy package. Contact [email protected] or reach out on Discord and we’ll send it to you directly — or deploy it for you as part of onboarding.

The package contains:

modules/GameyeAllocator/
├── GameyeAllocator.sln
├── CONFIGURATION.md
└── Project/
    ├── GameyeAllocator.cs       ← Configure this file
    ├── GameyeAllocator.csproj
    └── Client/
        ├── GameyeClient.cs
        └── Models/
            ├── SessionRequest.cs
            └── SessionResponse.cs

Setup

1. Configure the allocator

Open Project/GameyeAllocator.cs and update the three constants near the top of the file:

private const string ImageName = "MyGame";       // Your application name in the Gameye Admin Panel
private const string DefaultLocation = "europe"; // Your preferred region
private const int GamePort = 7777;               // The port your game server listens on

Constant	Where to find the value
`ImageName`	Gameye Admin Panel → Applications — must match exactly
`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.

Go to Unity Dashboard → your project → Administration → Secrets
Click Add Secret
Set the name to GAMEYE_API_TOKEN
Set the value to your Gameye API bearer token (obtain from your Gameye account or contact support)

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

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

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

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 Gameye API response — check here first if allocations are failing.

Region mapping

The allocator uses DefaultLocation for all allocations. If your matchmaker selects regions, map Unity region names to Gameye location IDs:

Unity 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`

To route allocations per-region, update the DefaultLocation constant or pass the region dynamically from your matchmaker queue configuration. Contact [email protected] if you need guidance on dynamic region selection.

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.