Configure region-based matchmaking

Last updated on October 24, 2024

Overview

AccelByte Gaming Services (AGS) Matchmaking gives you the ability to allow players to be matched based on geographic region. This article shows you how to implement region-based matchmaking into your game.

Prerequisites

To complete all the steps in this article, you will need:

• A familiarity with AGS Lobby, Matchmaking and Session.
• To have configured a session template, match ruleset, and match pool.
• To have integrated the AGS Game SDK into your game client.

Configure matchmaking request with all available regions

During a matchmaking request, the game client can provide a region list in the latencies field as the preference region for the matchmaking result. The following is an example payload for requesting matchmaking:

POST /match2/v1/namespaces/{namespace}/match-tickets

{
  "attributes": {},
  "latencies": {
    "us-west-2":44,
    "eu-west-2":187,
    "ap-northeast-1":600
  },
  "matchPool": "matchpool_test",
  "sessionID": ""
}

You can get the list of available regions from Quality of Service (QoS) using the following API endpoint:

GET /qosm/public/qos

OSS

// Using the StartMatchmaking() method, 
// the OSS will automatically fill matchmaking tickets with all available QoS regions

// Matchmaking to all regions
TSharedRef<FOnlineSessionSearch> NewSearchHandle = MakeShared<FOnlineSessionSearch>();
NewSearchHandle->QuerySettings.Set(SETTING_SESSION_MATCHPOOL, "5v5bf", EOnlineComparisonOp::Equals);

if (!SessionInterface->StartMatchmaking(TArray<FSessionMatchmakingUser>{{LocalUserId1}}, NAME_GameSession, FOnlineSessionSettings(), NewSearchHandle, OnStartMatchmakingCompleteDelegate))
{
    // Matchmaking failed to start
    return false;
}

Unreal Engine

TArray<TPair<FString, float>> Latencies = AccelByteApiClient->Qos.GetCachedLatencies();

FAccelByteModelsV2MatchTicketOptionalParams Optionals;
Optionals.Latencies = Latencies;

AccelByteApiClient->MatchmakingV2.CreateMatchTicket(MatchPoolName,
        CreateTicketSuccessHandler,
        CreateTicketErrorHandler,
        Optionals);

Unity

var qos = AccelByteSDK.GetClientRegistry().GetApi().GetQos();
var matchmaking = AccelByteSDK.GetClientRegistry().GetApi().GetMatchmakingV2();

string matchPoolName = "match-pool";

// Get latencies
qos.GetServerLatencies(result => 
{
    if (result.IsError)
    {
        // Do something if GetServerLatencies fails
        Debug.Log($"Error GetServerLatencies, Error Code: {result.Error.Code} Error Message: {result.Error.Message}");
        return;
    }

    var optionals = new MatchmakingV2CreateTicketRequestOptionalParams()
    {
        latencies = result.Value
    };

    matchmaking.CreateMatchmakingTicket(matchPoolName, optionals, result => 
    {
        if (result.IsError)
        {
            // Do something if CreateMatchmakingTicket fails
            Debug.Log($"Error CreateMatchmakingTicket, Error Code: {result.Error.Code} Error Message: {result.Error.Message}");
            return;
        }

        // Do something if CreateMatchmakingTicket succeeds
    });
});

Configure matchmaking requests for a specific region

To get a specific region during matchmaking results, the game client can only send one region (latency) when creating a match ticket.

If you're using AccelByte Multiplayer Servers (AMS), ensure that you add the region that you want to use or choose the deployment config regions, which will be used by the session template.

Make sure the region that will be chosen is active in the region setting. To do this, follow these steps:

1. In the AGS Admin Portal, go to AccelByte Multiplayer Servers > QoS Regions.

2. On the QoS Regions page, switch on the Active toggle button of the country you want to set to active.

The following is an example for a game client to always request for matchmaking in the region "us-west-2":

POST /match2/v1/namespaces/{namespace}/match-tickets

{
  "attributes": {},
  "latencies": {
    "us-west-2":44
  },
  "matchPool": "matchpool_test",
  "sessionID": ""
}

OSS

// Region names can be provided by setting the SearchSetting with `SETTING_GAMESESSION_REQUESTEDREGIONS` key

TSharedRef<FOnlineSessionSearch> NewSearchHandle = MakeShared<FOnlineSessionSearch>();
NewSearchHandle->QuerySettings.Set(SETTING_SESSION_MATCHPOOL, "5v5bf", EOnlineComparisonOp::Equals);
// Insert the region you want to lock to here
NewSearchHandle->QuerySettings.Set(SETTING_GAMESESSION_REQUESTEDREGIONS, "us-west-2", EOnlineComparisonOp::Equals);

if (!SessionInterface->StartMatchmaking(TArray<FSessionMatchmakingUser>{{LocalUserId1}}, NAME_GameSession, FOnlineSessionSettings(), NewSearchHandle, OnStartMatchmakingCompleteDelegate))
{
    // Matchmaking failed to start
    return false;
}

Unreal Engine

TArray<TPair<FString, float>> Latencies = AccelByteApiClient->Qos.GetCachedLatencies();
        
FAccelByteModelsV2MatchTicketOptionalParams Optionals;
// Filter the latencies list to only send region us-west-2
Optionals.Latencies = Latencies.FilterByPredicate([](const TTuple<FString, float>& Latency)
{
    return Latency.Key == "us-west-2";
});

AccelByteApiClient->MatchmakingV2.CreateMatchTicket(MatchPoolName,
        CreateTicketSuccessHandler,
        CreateTicketErrorHandler,
        Optionals);

Unity

var qos = AccelByteSDK.GetClientRegistry().GetApi().GetQos();
var matchmaking = AccelByteSDK.GetClientRegistry().GetApi().GetMatchmakingV2();

string matchPoolName = "match-pool";  

// Get latencies
qos.GetServerLatencies(result => 
{
    if (result.IsError)
    {
        // Do something if GetServerLatencies fails
        Debug.Log($"Error GetServerLatencies, Error Code: {result.Error.Code} Error Message: {result.Error.Message}");
        return;
    }

    // Only select latencies where the key is us-west-2
    Dictionary<string, int> selectedLatencies = (Dictionary<string, int>)result.Value.Where(pair => pair.Key == "us-west-2");

    var optionals = new MatchmakingV2CreateTicketRequestOptionalParams()
    {
        latencies = selectedLatencies
    };

    matchmaking.CreateMatchmakingTicket(matchPoolName, optionals, result => 
    {
        if (result.IsError)
        {
            // Do something if CreateMatchmakingTicket fails
            Debug.Log($"Error CreateMatchmakingTicket, Error Code: {result.Error.Code} Error Message: {result.Error.Message}");
            return;
        }

        // Do something if CreateMatchmakingTicket succeeds
    });
});

note

If you're using Armada (deprecated), there will be a failover if the preferred region is full or there is an outage. Then, the Dedicated Server Management Controller (DSMC) service will request a dedicated server in another region listed in the deployment config. This means that there is still a small possibility that the session gets a dedicated server from another region even when you request matchmaking only using one region.