Integrate a matchmaker with zeuz
A matchmaker is a service you create, to match game clients to your game server. As part of your game development you might want to integrate your matchmaker with zeuz.
Matchmaking is the process of connecting players together for game playing sessions. See Wikipedia: Matchmaking for more information.
This page provides advice on what to incorporate into your matchmaker, to best integrate your game with zeuz.
Before you begin
Before you develop your matchmaker, we recommend that you perform these tasks:
Follow the zeuz Get Started tutorial. It guides you through setting up hosting for a session-based game with zeuz server hardware orchestration tools, and takes approximately 60-90 minutes to complete.
Set up hosting for your own session-based game project with zeuz server hosting orchestration tools. For instructions, refer to the Set up a project guide.
Overview
The following image shows the zeuz components, your game components, and the matchmaking interactions between them:

Image: zeuz matchmaking overview.
zeuz provides the following components:
zeuz SDK: A package of files which contains an SDK in Go, zeuz API wrappers for Unreal and Unity, and other resources that you can use when you set up your game with zeuz.
Note: You download the SDK as part of the Get Started tutorial. See the
README.txt
file in the unzipped package for a full description of the SDK contents.The zeuz API.
The hosting platform for your game servers.
zeuz SDK in Go
In the zeuz SDK download, we provide the SDK in Go. We recommend that you use it to develop your matchmaker. The SDK in Go provides the following:
Native representations of zeuz objects such as allocations, payloads, and machines.
Methods for serializing and de-serializing objects in compliance with the zeuz API.
Methods to correctly attach the sign-hash to requests you make to the zeuz API.
See Sign-hash generation for more information.
Helper functions.
You can use a different language to develop a matchmaker, but you will need to implement the above features yourself. The examples in this document use the zeuz SDK in Go.
Note: The Unreal and Unity wrappers in the zeuz SDK are designed to integrate directly with a game client and server you create with Unreal or Unity. You can’t use these wrappers to develop a matchmaker.
Refer to your game development software documentation for more information on how to develop a matchmaker for your platform.
Connection flow
We recommend the following connection flow for your matchmaker, as shown in the image above:
A game client requests a payload to connect to, from a matchmaking service.
The matchmaker uses the zeuz SDK to communicate with the zeuz API and identify unreserved payloads.
The matchmaker reserves a payload for game clients to connect to.
The matchmaker ensures that the payload is ready to accept connections.
Note: A payload is “ready” when its initialization is complete. See Payload readiness below for more information.
The matchmaker passes connection details to the game client (IP address and port number).
The game client uses the connection details to connect to the payload.
Authentication
To interact with the zeuz API, your matchmaker must first authenticate with it. Before you can authenticate, you need:
An API key and API secret.
See API keys for information on how to generate these.
Note: In the zeuz control panel (ZCP) the API secret is called the API key password.
Your zeuz project ID (visible in the left pane of the ZCP).
Your zeuz environment ID (visible in the left pane of the ZCP).
Note: Your matchmaker can’t authenticate directly with zeuz using the zeuz tool CLI. We don’t recommend using zeuz tool programmatically and not all zeuz API endpoints are supported by zeuz tool.
In your code, use the API key and API secret to produce a session ID and a session key. Use the session ID and session key, together with your project ID and environment ID, to make requests to the zeuz API.
It is important to do the following:
Incorporate the authentication that the zeuz base API requires. See API authentication for more information.
Use a globally cached session.
Track session validity and renew the session as needed. See Error handling for more information.
Example: Use the zeuz SDK to authenticate to the ZCP and make requests to the zeuz API (Go)
|
|
Payload scaling
We recommend that you let zeuz handle the scaling of your payloads. Ideally, your matchmaker should not need to directly add or remove a payload or machine. Your matchmaker should only reserve payloads.
Scaling up
zeuz ensures that the minimum number of unreserved payloads you specify in your allocation configuration are available to your game. This means that once you reserve enough payloads, zeuz automatically spins up new ones when needed.
Example: Use the zeuz SDK to reserve a payload (Go)
|
|
Scaling down
We recommend that you set a payload to stop running when a game session ends. This automatically frees up server hardware resources and saves you from manually unreserving the payload.
To enable this, add your API key and API key password to your allocation’s payload definition. See the information on automatic payload release for more details.
Payload readiness
Even if a payload is reserved, it might not be ready to accept player connections. Incorporate steps into your matchmaker to validate that a payload is ready to accept connections, before passing its connection details to game clients. This helps to ensure that connections are seamless and error-free.
To determine whether a payload is ready, use a utility such as netcat (Wikipedia: netcat) to check whether the payload’s port is occupied. If the port is occupied, the payload is ready.
Use a command similar to the following:
nc -vz <your.game.address> <port number>
For example:
nc -vz my.game.com 9000
Note: On a UDP server, the port to check is 9001.
For more information on payload scaling, see:
2021-aug-23 Page added with editorial review.