Configure matchmaking for regions

Last updated on April 23, 2024

Overview

When using AccelByte Unreal OSS, the game client will send all the available regions by default during matchmaking requests. However, you can also configure the matchmaking process for a specific region only.

Prerequisites

• You are familiar with configuring the Lobby, Matchmaking and Session services.
• You have configured a session template, match ruleset, and match pool.
• You have integrated the AccelByte 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 a 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": ""
}

We can get the list of available regions from the QoS service using the following API endpoint:

GET /qosm/public/qos

OSS

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

// Matchmaking to all region
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

// Get latencies
accelByteApiClient.GetQos().GetServerLatencies(OnGetLatenciesDone);

private void OnGetLatenciesDone(Result<Dictionary<string, int>> result)
{
    if (result.IsError)
    {
        // Get QoS latencies failed
        return;
    }

    ApiClient accelByteApiClient = MultiRegistry.GetApiClient();

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

    accelByteApiClient.GetMatchmakingV2().CreateMatchmakingTicket(matchPoolName, optionals, CreateMatchmakingTicketDone);
}

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 AMS or Armada v3, ensure that you add the region that you want to use or choose into 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 AccelByte Gaming Services (AGS) Admin Portal, go to Dedicated Server Management > Servers.

2. On the Servers page, click the Available Regions button.

3. In the QoS Servers section, 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 we 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 so we 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

// Get latencies
accelByteApiClient.GetQos().GetServerLatencies(OnGetLatenciesDone);

private void OnGetLatenciesDone(Result<Dictionary<string, int>> result)
{
    if (result.IsError)
    {
        // Get QoS latencies failed
        return;
    }

    ApiClient accelByteApiClient = MultiRegistry.GetApiClient();

    // 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");

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

    accelByteApiClient.GetMatchmakingV2().CreateMatchmakingTicket(matchPoolName, optionals, CreateMatchmakingTicketDone);
}

note

If you're using Armada, there will be a failover if the preferred region is full or 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 we request matchmaking only using one region.