Matchplay: A Matchmaker and Multiplay sample
Important: For most users, the Dedicated game server sample replaces this Matchplay sample. Starting with Unity 6, the Multiplayer Services package is the one-stop solution for adding multiplayer elements to your game.
Note: This sample was tested with Unity 2021.2 for PC and OSX clients, and Linux Headless servers.
The Matchplay sample demonstrates how to create a Matchmake button: a basic networked client-server game with a matchmaking feature from end-to-end using the Unity Engine and Cloud Services SDK.
Note: This is not a “drag-and-drop” solution; the Matchlay sample is not a minimal code sample intended to be copied into a full-scale project. Rather, it demonstrates how to use multiple services in a vertical slice with some basic game logic and infrastructure. Use it as a reference to learn how Matchmaker and Multiplay Hosting work together to make a common end-user feature.
Features
- Matchmaking Ticket Config: Players set their preferences for the map and game mode they want.
- Matchmaking: Players click the Matchmake button to begin looking for a match.
- Matchmaker Allocation Payload: The server gets information about the match and configures the server accordingly.
- Multiplay Server Allocation: Spins up a dedicated cloud server and passes its information to the player.
- Client Server Netcode: A lightweight server that can be hosted on Multiplay Hosting.
Project overview
The project runs in client or server modes and in local service modes. The server will attempt to find services for 5 seconds, and if it can’t, it starts the server with some default settings for local testing. The client can directly connect to this server using the local host IP address.
Scenes
- bootStrap: You must play from this scene for the sample to work.
- mainMenu: Displays the matchmake and local connection buttons to users.
- game_lab: A game scene with a table.
- game_space: A game scene which features a sphere.
Run as a client
The project runs as a client in the following scenarios:
- You play the Matchplay project in-editor from the bootStrap scene.
- You run a non-server build on your platform of choice.
- You play a ParrelSync clone project with “client” in the arguments field from the bootStrap scene.
The client can either connect using the Matchmaker or through a local connection with the UI.
Matchmaker won't run without services being set up; follow the Sample Setup Guide to set them up.
Run as a server
The project will run as a server in the following scenarios:
- You run a server build on your platform of choice.
- You run a ParrelSync clone project with “server” in the argument field from the bootStrap scene.
- Multiplay Hosting will run the server automatically when the matchmaker finds a match.
Depending on the context the server is running in, it will either fetch its configuration from the matchmaker or start with the default values.
Test Netcode locally with ParrelSync
To test Netcode locally with ParrelSync:
- Go to the top bar and select ParrelSync > Clones Manager > Add new Clone. This duplicates your project folder and synchronizes the contents to allow for iteration.
- Input "server" in the arguments field so the clone plays in local server mode.
- Once the server starts, return to the base project and select Play.
- Once the mainMenu scene loads, select local and Play to connect to the local server.
Note: The default IP for local servers is (127.0.0.1:7777).
Cloud project and organization
To use Unity’s Multiplayer services, you need a cloud organization ID for your project. Follow the How do I create a new Organization guide to set up your org.
To learn how to connect your project with services, follow the Setting up Project Services guide.
Services
Authentication
Matchmaker and Multiplay depend on Unity Authentication 2.0 for credentials. This sample uses Unity Authentication’s anonymous login feature to create semi-permanent credentials unique to each player but do not require developers to maintain a persistent account for them.
Matchmaker
The Matchmaker service allows players to search for other players with the same preferences as them and puts them in a match together.
The Matchmaker documentation contains code samples and additional information about the service. It includes comprehensive details for using the Matchmaker along with additional code samples, and it might help you better understand the Matchplay sample.
Manage the Matchmaker service in the Unity Cloud Dashboard.
Multiplay Hosting
The Multiplay Hosting service hosts game servers in the cloud to allow for easy connection between players from around the world with the best ping performance possible.
The Multiplay Hosting documentation contains code samples and additional information about the service. It includes comprehensive details for using Multiplay Hosting along with additional code samples to help you better understand the Matchplay sample.
Manage the Multiplay Hosting service in the Unity Cloud Dashboard.
Sample setup guide
Link your Editor project to the Cloud Project as described in Cloud Project and Organization.
To build the server, go to your Matchplay project, and select BuildTools > Linux Server.
It should automatically build your project as a server build, and output it to:
<project root>/Builds/Matchplay-<platformBuildType>_<dateTime>Upload the server to Multiplay and configure server hosting. Go to your Unity Cloud Dashboard > Multiplay Setup Guide > Create a build.
Fill out the Details fields and move to Upload Files. Drag your Linux Headless Build into the dropbox and select Upload Files.
Continue to set up the build configuration. Complete the fields and enter Matchplay.x86_64 in the game server executable field.
Select SQP as your query type, and fill in the following as the custom launch parameters:
-ip 0.0.0.0 -port $$port$$ -queryPort $$query_port$$ -logFile $$server_log_dir$$/matchplaylog.log
To create a fleet, enter a fleet name, and select the previously created build configuration. For the scaling settings, select 1 as the minimum available, and 5 as the maximum. The Multiplay Hosting fleet is now ready.
Unity Matchmaker
Now that we have our server fleet, we can set up the Matchmaker by selecting Matchmaker Setup Guide. You can click through Integrate Matchmaker for this guide, as the sample already has it integrated in the project.
Select Create Queue and enter a name for the queue. The queue name must be between 1 and 36 characters and contain only alphanumeric or hyphen characters.
Name the queue 'casual-queue' and set the maximum players on a ticket to 10.
The exact string queue name defined in the UDash must match the input string in the following SDK sample:
To create a pool, select your previously created Multiplay Hosting fleet and build configuration. Set the timeout to 15 seconds.
Note: If your server fleet scaling settings have 0 minimum servers, you may need to increase the timeout duration to 180 seconds to accommodate the server initial startup duration.
Match rules
The match rules are the filters that we use in the sample to match the players by their preferences. Within the pools and queues, every player’s settings are evaluated against every other player.
To set up the match definition rules:
- Set up the region you are playing from. This should be the same as your server fleet region.
- Set up the basic team definitions and skip the advanced rules.
- Select Finish to finalize the configuration of the matchmaker.
Now you should be able to play the Project in the Unity Editor and have the Matchmake button find you a match, connect you to a Multiplay Hosting server, and await more players.
You can use ParrelSync or multiple builds to connect several people to the same server using the Matchmake button.
