Matchmaking

Matchmaking puts players who want the same kind of game together. Each mode of your game is a queue with a smallest and largest number of players. A player, or a whole party, searches in a queue; once the queue holds enough players, Flock makes a match and seats the players in a session. A party is matched as one group and never split. Players are matched in the order they search.

Scope: matchmaking queues are defined per game.

Dashboard
Unity
Unreal

Make queues under Multiplayer → Matchmaking with Create Queue:

Queue Name: the name your game searches by, letter for letter, case included.
Min Players and Max Players: the smallest and largest match.
Same game version only: matches players of one build with each other only. Leave it on unless different builds can play together.
Allowed Segments: only players in these segments may search here. Leave it empty for everyone.
Queue metadata: notes for your own reference. Matching does not read them.

Multiplayer → Matchmaking Activity shows who is waiting in each queue now, and the matches made.

Search alone. A search that ends without a match is an outcome, not an exception. The examples run inside async methods of a MonoBehaviour of yours, with a player signed in. cancelButton is a UnityEngine.UI.Button of your screen, PlayAsync stands for your own method that takes the session and starts the netcode on it (see Connecting players), ShowMessage, ShowSearching and ShowLobby for your own screens, and party for the player’s party.

using System;
using System.Threading;
using Flock;
using Flock.Exceptions;
using Flock.Providers;

CancellationTokenSource searching = new CancellationTokenSource();
cancelButton.onClick.AddListener(searching.Cancel);
try
{
    FlockMatchmakingResult found = await FlockClient.Instance.Multiplayer.FindMatchAsync("coop-4", null, searching.Token);
    if (found.IsMatched && found.Session != null)
        await PlayAsync(found.Session);
    else if (found.Outcome == FlockMatchmakingOutcome.Expired)
        ShowMessage("Nobody found in 5 minutes. Search again?");
    else
        ShowMessage("The search stopped.");
}
catch (OperationCanceledException)
{
    ShowMessage("Search cancelled.");   // the search is cancelled on the server too
}
catch (FlockException ex) when (ex.ErrorCode == FlockErrorCode.MatchmakingQueueNotFound)
{
    ShowMessage("No queue is named coop-4.");
}

Search as a party. The leader’s game starts the search, and every member’s game hears it through the party, so handle the result in one place: SearchEnded is raised on every member’s game, the leader’s included.

using Flock.Providers;

party.SearchStarted += () => ShowSearching();
party.SearchEnded += result =>
{
    if (result.IsMatched && result.Session != null)
        _ = PlayAsync(result.Session);
    else
        ShowLobby();
};

if (party.IsLeader)
    await party.FindMatchAsync("coop-4");

The SDK checks a search every 3 seconds. FlockMatchmakingOptions.Attributes passes your own data with a search; matching does not use it yet.

Search alone. A search that ends without a match is an outcome, not a failure. The examples run in your game instance: Searching (an FFlockRequestHandle) and Party (a UPROPERTY UFlockParty*) are its members, Play takes the session and travels to it (see Connecting players), ShowMessage, ShowSearching and ShowLobby stand for your own screens, and every handler bound with AddDynamic is a UFUNCTION. A completion keeps a weak pointer to the game instance (Game), never this.

#include "FlockSubsystem.h"
#include "Multiplayer/FlockParty.h"

FFlockMultiplayerProvider* Multiplayer = GetSubsystem<UFlockSubsystem>()->GetMultiplayerProvider();
const TWeakObjectPtr<UMyGameInstance> Game = this;

Searching = Multiplayer->FindMatch(TEXT("coop-4"), FFlockMatchmakingOptions(),
    [Game](TFlockResult<FFlockMatchmakingResult> Found)
    {
        if (!Game.IsValid())
        {
            return;
        }
        if (!Found.IsSuccess())
        {
            if (Found.Error.Type == EFlockErrorType::Cancelled)
            {
                Game->ShowMessage(TEXT("Search cancelled."));   // the search is cancelled on the server too
            }
            else if (Found.Error.ErrorCode == EFlockErrorCode::MatchmakingQueueNotFound)
            {
                Game->ShowMessage(TEXT("No queue is named coop-4."));
            }
            return;
        }
        if (Found.Value.IsMatched() && Found.Value.Session != nullptr)
        {
            Game->Play(Found.Value.Session);   // held like any other session
        }
        else if (Found.Value.Outcome == FlockMatchmakingOutcomes::Expired)
        {
            Game->ShowMessage(TEXT("Nobody found in 5 minutes. Search again?"));
        }
        else
        {
            Game->ShowMessage(TEXT("The search stopped."));
        }
    });

// The cancel button.
Searching.Cancel();

Search as a party. The leader’s game starts the search, and every member’s game hears it through the party, so handle the result in one place: OnSearchEnded is raised on every member’s game, the leader’s included.

Party->OnSearchStarted.AddDynamic(this, &UMyGameInstance::ShowSearching);
Party->OnSearchEnded.AddDynamic(this, &UMyGameInstance::HandleSearchEnded);

if (Party->IsLeader())
{
    Party->FindMatch(TEXT("coop-4"), FFlockMatchmakingOptions(), nullptr);
}

void UMyGameInstance::HandleSearchEnded(const FFlockMatchmakingResult& Result)
{
    if (Result.IsMatched() && Result.Session != nullptr)
    {
        Play(Result.Session);
    }
    else
    {
        ShowLobby();
    }
}

Another member’s game hears of the leader’s search through the party’s refresh (Party Refresh Seconds); with it at 0, only through its own Party->FindMatch, which waits for the leader’s search and completes with the same match.The SDK checks a search every 3 seconds. FFlockMatchmakingOptions::Attributes passes your own data with a search; matching does not use it yet. A player searches once at a time: a second FindMatch while one runs is refused (Validation) without a request.In Blueprint, Flock Find Match and Flock Party Find Match fire On Matched (the result: its Session is where the players play), On No Match (its Outcome says how the search ended) or On Failure. Their Async Action pin hands out the node, whose Cancel stops the search on the server and fires no pin. Compare an Outcome with the Flock Matchmaking Outcome nodes, and keep a default.

How a search ends

The outcome is a string on both engines. On Unity it is one of the FlockMatchmakingOutcome constants; on Unreal, one of the constants of FlockMatchmakingOutcomes. Both carry the same names (FlockMatchmakingOutcomes::PartyChanged is party_changed).

Unity	Unreal	When	What to do
`Matched`	`matched`	Players were matched. `Session` is where they play; `PlayerIds` lists them, the longest waiting first.	Connect the players. If `Session` is null, `GetMySessionAsync` (Unreal: `GetMySession`) finds it; with Create a session when a match forms off, there is none and your game makes one.
`Expired`	`expired`	Nobody was found within 5 minutes.	Offer to search again.
`PartyChanged`	`party_changed`	A player joined or left the party during the search.	The leader searches again.
`Cancelled`	`cancelled`	Another game stopped it: a party member’s, or the player’s own on another device.	Show the lobby.

A search your game cancels ends the call another way: with an OperationCanceledException on Unity (through its token), and as a failure of type Cancelled on Unreal (through its handle). The server can add outcomes, so treat any other as ended without a match.

Party members and game versions

On a Same game version only queue, the server takes each member’s version from their game’s last read of the party. Have every member’s game read the party (GetMyPartyAsync, or GetMyParty on Unreal) once it is running, or the search is refused with MatchmakingVersionMismatch.

What matching does not use yet

Matching is first come, first served. Skill, region and latency rules, teams and backfill are not built yet; what a search sends in its attributes is stored for them. Until then, make a queue per mode and region (coop-4-eu, coop-4-na).

Errors

Each code is a FlockErrorCode on Unity and an EFlockErrorCode on Unreal, with the same name, and the error carries a hint naming the fix.

`ErrorCode`	When	What to do
`MatchmakingQueueNotFound`	No queue has that exact name.	Search by the queue’s name as the dashboard shows it, letter case included, or create the queue there.
`MatchmakingPlayerNotEligible`	The player is not in the queue’s allowed segments.	Check the queue’s Allowed Segments in the dashboard.
`MatchmakingPartyTooLarge`	The party is bigger than the queue’s largest match.	Raise the queue’s Max Players, or search with a smaller party.
`MatchmakingNotPartyLeader`	A party member tried to start the search, or the lead moved before it went out.	Read the party again and let its leader search.
`MatchmakingVersionMismatch`	Party members are on different builds, or one has not read the party yet.	Update every member’s game, and have each read the party once it is running.
`MatchmakingAlreadyQueued`	A player in the search is already searching: the party’s search, or a member searching alone.	Wait for that search to end, or cancel it, then search again.

Getting Started

Concepts

Features

Reference

How a search ends

Party members and game versions

What matching does not use yet

Errors