Configure cross-platform matchmaking

Last updated on November 15, 2024

Overview

Cross-platform play (cross-play) enables players on any platform your game supports to play together. While this is generally the preferred experience for players, some platforms require that games support the ability for players to opt-out.

AccelByte Gaming Services (AGS) Matchmaking defaults with cross-play on, but can be configured to support player control using custom parameters passed from the game client to the service when requesting a match. This allows players to fully opt in or out of cross-play, or choose a subset of platforms they would prefer to match with. The player session attribute can also be used to configure the player preference.

This article will show you how to configure a match ruleset to support cross-play validation and pass a player's preferences as a custom parameter as part of the matchmaking process.

note

This guide assumes you are using the default match function available with AGS Matchmaking. If you plan to write your own function using AGS Extend, your required logic may differ.

Goals

This article aims to provide an overview of how to configure a match ruleset to respect a player's choice for opting in or out of cross-play and show you how to submit a match ticket with a custom parameter related to that choice.

Prerequisites

In order to complete all the steps in this article, you will need:

A familiarity with AGS Lobby, Session, and Matchmaking.
A session template, match ruleset, and match pool created and configured.
To have integrated AGS Matchmaking into your Unreal or Unity project.
To have implemented a player cross-play setting in your game client.

Configure a match ruleset to support custom parameters

To support player control, you need to configure a match ruleset with custom parameter criteria specific to cross-play. To do this, you need to update the ruleset JSON configuration to include match options, as the below example illustrates.

In the below example, it's assumed your game is a four-player co-op game and has been released on Steam, Xbox Live (XBL), and PlayStation Network (PSN). In the ruleset JSON, you can see a match option with the name cross_platform has been added with the type all. The name of the option will act as the key for the values to be passed as a parameter from the game client. Type allows you to define the criteria used to evaluate the passed values, and can be set to one of these options:

All - Players must be matched with others who have the same parameters and values.
Any - Players must be matched with others who have the same option parameter name and at least one matching value.
Unique - Players must be matched with others who have the same option parameter name, but different values.

Because all is set in this example, only players who have the exact matching values as their preference can be matched together. For example, if one player set Steam and another set XBL and Steam, they would not be able to match.

{
    "auto_backfill": true,
    "alliance": {
        "min_number": 1,
        "max_number": 1,
        "player_min_number": 4,
        "player_max_number": 4
    },
    "match_options": {
        "options": [
            {
                "name": "cross_platform",
                "type": "all"
            }
        ]
    }
}

Add the player cross-play selection to the matchmaking request in the game client

Once a match ruleset is configured, you can update the matchmaking call in the game client to support passing player preferences as custom parameters as part of the match request.

Below are examples of how the passed values will be interpreted with example codes showing how to pass custom parameters from the game client as part of the matchmaking request.

Player wants to cross-play with any platform user:
- "cross_platform": ["steam", "xbl", "ps5", "ps4"]
Player wants to play only with other XBL platform users:
- "cross_platform": ["xbl"]
Player wants to cross-play with only console users (no PC users):
- "cross_platform": ["xbl", "ps5", "ps4"]

info

The backend will do a validation to prevent malicious players from tampering the cross_platform value. The backend will check the cross_platform value sent by a player if it contains the player's active platform. For example, when a Steam player sends a cross_platform value of ["ps5", "ps4"], the backend will add steam into the value, e.g., ["steam", "ps5", "ps4"].

OSS
Unreal Engine
Unity

const IOnlineSubsystem* Subsystem = Online::GetSubsystem(GetWorld());
if (!ensure(Subsystem != nullptr))
{
    return;
}

const FOnlineSessionAccelBytePtr SessionInterface = StaticCastSharedPtr<FOnlineSessionV2AccelByte>(Subsystem->GetSessionInterface());
if (!ensure(SessionInterface.IsValid()))
{
    return;
}
const FUniqueNetIdPtr LocalPlayerId = GetUniquePlayerId();
if (!ensure(LocalPlayerId.IsValid()))
{
    return false;
}

// Create a new search handle instance for matchmaking. IMPORTANT: you will need to set the match pool that you are searching for with SETTING_SESSION_MATCHPOOL, as shown below.
TSharedRef<FOnlineSessionSearch> MatchmakingSearchHandle = MakeShared<FOnlineSessionSearch>();
MatchmakingSearchHandle->QuerySettings.Set(SETTING_SESSION_MATCHPOOL, FString(TEXT("YOUR_MATCHPOOL_NAME_GOES_HERE")), EOnlineComparisonOp::Equals);

// Custom attributes can be added to the SearchHandle's QuerySettings:
MatchmakingSearchHandle->QuerySettings.Set(
    FName(TEXT("cross_platform")),
    TEXT("steam"), EOnlineComparisonOp::Equals);

// Bind a function that has a return type of void and these parameters:
// FName SessionName, bool bWasSuccessful
const FOnMatchmakingCompleteDelegate OnMatchmakingCompleteDelegate = /* Bind to lambda or class method */;
SessionInterface->AddOnMatchmakingCompleteDelegate_Handle(OnMatchmakingCompleteDelegate);

if (SessionInterface->StartMatchmaking(USER_ID_TO_MATCHMAKING_USER_ARRAY(LocalPlayerId.ToSharedRef()), NAME_GameSession, FOnlineSessionSettings(), MatchmakingSearchHandle, OnStartMatchmakingCompleteDelegate))
{
    // Update the current search result handle class member with the search handle passed to AGS Matchmaking.
    CurrentMatchmakingSearchHandle = MatchmakingSearchHandle;
}

// Set the match pool name
FString MatchPoolName = "YOUR_MATCHPOOL_NAME_GOES_HERE";

// Get the default API client to call the AGS backend endpoints
FApiClientPtr ApiClient = FMultiRegistry::GetApiClient();

// Set the optional parameter attributes to save the option selected
FAccelByteModelsV2MatchTicketOptionalParams Optionals;
TSharedPtr<FJsonObject> Attributes = MakeShared<FJsonObject>();

// Add the platforms the player wants to cross-play with any platform
TArray<TSharedPtr<FJsonValue>> CrossPlayValues = {
  MakeShareable(new FJsonValueString(TEXT("steam")))
};

Attributes->SetArrayField("cross_platform", CrossPlayValues);
Optionals.Attributes.JsonObject = Attributes;

auto OnSuccess = THandler<FAccelByteModelsV2MatchmakingCreateTicketResponse>::CreateLambda(
  [&](const FAccelByteModelsV2MatchmakingCreateTicketResponse& Result)
{
  // Do something on create ticket success
});
auto OnError = FErrorHandler::CreateLambda([&](int32 Code, const FString& Message)
{
  // Do something on create ticket error
});

// Request matchmaking with the optional parameter attached to the match ticket.
ApiClient->MatchmakingV2.CreateMatchTicket(MatchPoolName, OnSuccess, OnError, Optionals);

// Get the matchmaking API client to call the AGS backend endpoints
var matchmaking = AccelByteSDK.GetClientRegistry().GetApi().GetMatchmakingV2();

// Set the match pool name
string matchPoolName = "YOUR_MATCHPOOL_NAME_GOES_HERE";

// Set the optional parameter attributes to save the option selected
MatchmakingV2CreateTicketRequestOptionalParams Optionals = new MatchmakingV2CreateTicketRequestOptionalParams();

// Add the platforms the player wants to cross-play with
Optionals.attributes = new Dictionary<string, object>()
{
    { "cross_platform", "steam" }
};

// Request matchmaking with the optional parameter attached to the match ticket.
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
});

Recommended: Configure the player session attribute for cross-play preference

Setting up the cross_platform in the matchmaking ticket request gives the game client the flexibility to control the platforms for cross-play. However, it will require a game client change when adding additional platforms in the future. The second way to configure the player cross-play preference is using the player session attribute. By setting the player session attribute crossplayEnabled to true or false, the backend will populate the cross_platform value even when there is no cross_platform attribute in the match ticket.

crossplayEnabled:true: if the match ticket doesn't contain the cross_platform attribute, the matchmaking will populate cross_platform with all active login methods that are being configured in the game namespace.
crossplayEnabled:false: if the match ticket doesn't contain the cross_platform attribute, the matchmaking will populate cross_platform with the current platform where the player is logged in.

Example case

In this scenario, the game is being distributed in Steam, PS5, and Xbox.

Player Platform	Cross-play Enabled	Cross Platform value
Steam	`true`	["steam", "ps5", "xbox"]
PS5	`false`	["ps5"]
PS5	`true`	["steam", "ps5", "xbox"]
Xbox	`false`	["xbox"]

info

When setting the session attribute, there will be validation in the backend for the currentPlatform and platforms information. The currentPlatform value can only be a platform in which the player is logged in. Theplatforms value can only be the active login methods in the current game namespace. Hence, the player cannot tamper the value with a wrong information.

Manage the cross-play via match pool

When the ruleset contains cross_platform in the match options, admins can configure the match pool behavior from the match pool config. The cross-play config in the match pool will take precedence over the player's cross-play preference.

...
    "match_options": {
        "options": [
            {
                "name": "cross_platform",
                "type": "all"
            }
        ]
    }
...

There are three cross-play options that can be set in the match pool configuration:

Match Pool Cross-play config

Cross-Play: by default, AGS is cross-play enabled.
Platform Group: all match tickets in the match pool (queue) will play with their platform group, regardless of the player's cross-play preference (player session attribute or match ticket's cross_platform value).
Platform Exclusive: all match tickets in the match pool (queue) will play with their own platform, regardless of the player's cross-play preference (player session attribute or match ticket cross_platform value).

Admin intention	Players intention	Result
Game admins DISABLE the cross-platform play on the match pool.	Players want a cross-platform play.	Players will only play with the same platform or platform group. (SAME PLATFORM PLAY)
Game admins DISABLE the cross-platform play on the match pool.	Players do not want a cross-platform play.	Players will only play with the same platform or platform group. (SAME PLATFORM PLAY)
Game admins ENABLE the cross-platform play on the match pool.	Players want a cross-platform play.	Players can play with other platforms. (CROSS-PLATFORM PLAY)
Game admins ENABLE the cross-platform play on the match pool.	Players do not want a cross-platform play.	Players will only play with the same platform. (SAME PLATFORM PLAY)

Cross-play for party session

In matchmaking with a party, parties can consist of players on multiple platforms. If the game sends the cross-play preference using the match ticket attribute cross_platform, regardless of the party composition, the cross_platform value will be used to search the potential platforms to match. However, if the game uses the player session attribute, then the party leader's preference will be used for matchmaking. The behavior of the game only using the party session attributes can be seen in the following table:

Party Leader Platform	Cross-play enabled	Party Composition	Match pool Config	Behavior
Steam	`true`	same platform	enable cross-play	Will match with all platforms
Steam	`true`	same platform	disable cross-play	Will match with the same platform (Steam)
Steam	`true`	mixed platforms	enable cross-play	Will match with all platforms
Steam	`true`	mixed platforms	disable cross-play	Will fail to create a match ticket
Steam	`false`	same platform	enable cross-play	Will match with the same platform (Steam)
Steam	`false`	same platform	disable cross-play	Will match with the same platform (Steam)
Steam	`false`	mixed platforms	enable cross-play	Will match with the same platform (Steam)
Steam	`false`	mixed platforms	disable cross-play	Will fail to create a match ticket

Cross-play with "any" rule

When we are building cross-platform matchmaking, there are cases when we want the player who enables cross-play to still match with a player who disables cross-play as long as they log in on the same platform. We can achieve this behaviour by using the any rule inside the match options. Here are some example use cases.

...
    "match_options": {
        "options": [
            {
                "name": "cross_platform",
                "type": "any"
            }
        ]
    }
...

Case 1

Player A Steam enables cross-play: [“steam“, “ps5“, “xbox“]
Player B Xbox disabled cross-play: [“xbox“]
Matchmaking result: Players A and B will not match. It is because even though Player A includes Xbox in the preferences, Player B disable cross-play, which only wants to match with another Xbox player.

Case 2

Player A Steam enables cross-play: [“steam“, “ps5“, “xbox“]
Player B Steam disabled cross-play: [“steam“]
Matchmaking result: Players A and B can match.

Platform group

Admins need to set up the platform group to enable Platform Group cross-play in the match pool. Players can still play with other platforms when the cross-play preference is disabled if they are within the same platform group.

Match Pool Cross-play config

Sample case

The following is an example use case that uses the platform group:

"As a game developer, I want to allow desktop players to only match and play with each other, and console players to only match and play with each other, but I don't want desktop players and console players to match with each other."

How should I set up the platform group?"

For this case, you can set up the platform group as follows

desktop: steam, epicgames
console: ps5, xbox

Overview​

Goals​

Prerequisites​

Configure a match ruleset to support custom parameters​

Add the player cross-play selection to the matchmaking request in the game client​

Recommended: Configure the player session attribute for cross-play preference​

Example case​

Manage the cross-play via match pool​

Cross-play for party session​

Cross-play with "any" rule​

Case 1​

Case 2​

Platform group​

Sample case​

On this page