Configure Quick Play with sub-game modes
Overview
Use sub-game modes to offer several gameplay modes through one match pool. A player selects the modes they are willing to play, and your game submits one match ticket containing those selections. A dedicated mode button can submit a single accepted mode to the same pool, allowing its players to share the queue with compatible Quick Play players.
This guide uses Elimination, Team Deathmatch, and Skirmish as an example. It covers the combined ruleset, accepted-mode ticket attributes, and how to choose a gameplay mode from the resulting session.
The player counts, flexing thresholds, and latency ceiling in this guide are example values. Adapt them to your game and complete the configuration checks with your intended player counts and hosting model before deploying.
Prerequisites
- Familiarity with Introduction to Matchmaking, Configure match rulesets, and Configure match pools.
- Access to the AGS Admin Portal and a namespace with Matchmaking v2.
- A session template and a hosting implementation that supports the largest match in your ruleset (50 players in this example).
- A game client with authenticated players, an active Lobby connection, and an existing matchmaking and session flow. See Integrate matchmaking (Unity) or Integrate matchmaking (Unreal).
- For Unity, the AccelByte Unity SDK installed and configured in your project.
- For Unreal, AccelByte OSS V2 with Sessions V2 enabled and the
OnlineSubsystemAccelBytemodule available to your game code.
Define the sub-game modes
The alliance fields describe the number of teams and the number of players per team:
| Field | Meaning |
|---|---|
min_number | Minimum number of teams |
max_number | Maximum number of teams |
player_min_number | Minimum players per team |
player_max_number | Maximum players per team |
Use these requirements for the example:
| Mode identifier | Initial team shape | Initial total players | Shape after 10 seconds |
|---|---|---|---|
elimination | Exactly 10 teams, each with 2–5 players | 20–50 | 1–10 teams, each with 1–5 players |
teamdeathmatch | Exactly 2 teams of 5 | 10 | 1–2 teams, each with 1–5 players |
skirmish | Exactly 2 teams of 2 | 4 | Unchanged; no flexing rule |
Elimination is a team-based mode in this example. Its initial configuration requires at least 20 players.
The Elimination and Team Deathmatch flexing rules below permit a match with only one team and one player after 10 seconds. If Team Deathmatch must always have two opposing teams, set its flexed min_number to 2. Choose the flexed player minimum according to the smallest playable team size for your game.
Set the shared session capacity
Matchmaking forms teams using the alliance of the sub-game mode it matches on. For new sessions from the pool, Matchmaking calculates the maximum player count as max_number * player_max_number from the top-level alliance. This value overrides the session template's maximum when it is greater than zero. Set the top-level maximums to accommodate your largest match.
{
"min_number": 1,
"max_number": 10,
"player_min_number": 1,
"player_max_number": 5
}
This example sets a session capacity of 10 * 5 = 50 players for every new match from the pool, including a four-player Skirmish match. Use the gameplay mode's team requirements for game logic and player-count UI.
Configure the ruleset and shared pool
Put each mode's alliance_flexing_rule inside its sub-game mode. Matchmaking applies those rules to that mode's alliance. A top-level alliance_flexing_rule applies only to the top-level alliance.
The following JSON contains the ruleset's configuration data. In the Admin Portal, use it in the Configuration (JSON) field. For an administrative API or CLI operation, use it as the operation's data field and supply the wrapper fields separately, following Configure match rulesets.
{
"alliance": {
"min_number": 1,
"max_number": 10,
"player_min_number": 1,
"player_max_number": 5
},
"auto_backfill": false,
"region_latency_max_ms": 200,
"rebalance_enable": false,
"sub_game_modes": {
"elimination": {
"name": "elimination",
"alliance": {
"min_number": 10,
"max_number": 10,
"player_min_number": 2,
"player_max_number": 5
},
"alliance_flexing_rule": [
{
"duration": 10,
"min_number": 1,
"max_number": 10,
"player_min_number": 1,
"player_max_number": 5
}
]
},
"teamdeathmatch": {
"name": "teamdeathmatch",
"alliance": {
"min_number": 2,
"max_number": 2,
"player_min_number": 5,
"player_max_number": 5
},
"alliance_flexing_rule": [
{
"duration": 10,
"min_number": 1,
"max_number": 2,
"player_min_number": 1,
"player_max_number": 5
}
]
},
"skirmish": {
"name": "skirmish",
"alliance": {
"min_number": 2,
"max_number": 2,
"player_min_number": 2,
"player_max_number": 2
}
}
}
}
This example disables automatic backfill and rebalancing and sets a shared latency ceiling of 200 milliseconds. It adds no skill or role requirements.
- Create a ruleset, for example
quickplay-ruleset, with the configuration above. - Create one pool, for example
quickplay-pool, referencing that ruleset and a shared session template. Follow Configure match pools. - Check that your hosting implementation supports a 50-player session.
- Read back the resources and complete the runtime checks below. The resource names in this guide are examples; check your existing resources before creating or updating them.
Submit accepted modes in one ticket
The ruleset key is plural: sub_game_modes. The ticket attribute is singular: attributes.sub_game_mode, and its value is an array of accepted mode identifiers:
{
"matchPool": "quickplay-pool",
"attributes": {
"sub_game_mode": ["elimination", "teamdeathmatch", "skirmish"]
}
}
Use the exact identifiers configured in the ruleset. The list specifies acceptable outcomes; its order does not request a mode preference ranking.
| Player selection | sub_game_mode value |
|---|---|
| Quick Play, any mode | ["elimination", "teamdeathmatch", "skirmish"] |
| Elimination only | ["elimination"] |
| Team Deathmatch only | ["teamdeathmatch"] |
| Skirmish only | ["skirmish"] |
| Team Deathmatch or Skirmish | ["teamdeathmatch", "skirmish"] |
All selections target the same pool. A Team Deathmatch-only player can match with a Quick Play player who also accepts Team Deathmatch. Players with disjoint selections must not match together.
For parties larger than two players, omit Skirmish because its per-team maximum is two. Validate the other accepted modes against the party size and your party-placement requirements. The party leader submits one ticket with the party session ID.
Submit through your game engine
- Unity
- Unreal (OSS)
Use CreateMatchmakingTicket to submit the accepted mode array. Supply measured region latencies when using region matching:
using System;
using System.Collections.Generic;
using AccelByte.Api;
using AccelByte.Core;
using AccelByte.Models;
using UnityEngine;
public static class QuickPlayTickets
{
public static void Create(
string poolName,
string[] acceptedModes,
Dictionary<string, int> measuredLatencies,
Action<string> onCreated,
string partySessionId = null)
{
if (string.IsNullOrWhiteSpace(poolName))
throw new ArgumentException("A match pool is required.", nameof(poolName));
if (acceptedModes == null || acceptedModes.Length == 0)
throw new ArgumentException("Select at least one mode.", nameof(acceptedModes));
var options = new MatchmakingV2CreateTicketRequestOptionalParams
{
attributes = new Dictionary<string, object>
{
["sub_game_mode"] = acceptedModes
},
latencies = measuredLatencies,
sessionId = partySessionId
};
var matchmaking = AccelByteSDK.GetClientRegistry()
.GetApi().GetMatchmakingV2();
matchmaking.CreateMatchmakingTicket(poolName, options, result =>
{
if (result.IsError)
{
Debug.LogError($"Matchmaking failed: {result.Error.Message}");
return;
}
onCreated?.Invoke(result.Value.matchTicketId);
});
}
}
In your queue button handler, pass the selected mode array and store the returned ticket ID. For example, with measuredLatencies and activeTicketId maintained by your client:
QuickPlayTickets.Create(
"quickplay-pool",
new[] { "elimination", "teamdeathmatch", "skirmish" },
measuredLatencies,
id => activeTicketId = id);
For a Team Deathmatch-only button, pass new[] { "teamdeathmatch" } instead. Prevent duplicate submissions while ticket creation is in progress, and restore the UI state if creation fails. If the player changes selections while a ticket is active, call DeleteMatchmakingTicket and wait for successful cancellation before creating a replacement. Handle expiration and a match-found event racing with cancellation through your existing matchmaking flow.
Use the AccelByte search-setting helper to store a TArray<FString> under sub_game_mode. The OSS converts that setting to a JSON array in the ticket's attributes. Passing a comma-separated string or a JSON string does not supply the required array.
The helper below accepts your existing OSS V2 session interface, authenticated local player ID, and start-request completion delegate. Set bUseP2P to match your session template: true for P2P, or false for AMS dedicated servers.
#include "OnlineSessionInterfaceV2AccelByte.h"
#include "OnlineSessionSettingsAccelByte.h"
#include "OnlineSubsystemAccelByteSessionSettings.h"
bool StartQuickPlayMatchmaking(
const FOnlineSessionV2AccelBytePtr& SessionInterface,
const FUniqueNetIdRef& LocalPlayerId,
const TArray<FString>& AcceptedModes,
bool bUseP2P,
const FOnStartMatchmakingComplete& OnStarted,
TSharedPtr<FOnlineSessionSearchAccelByte>& OutSearchHandle)
{
if (!SessionInterface.IsValid() || AcceptedModes.Num() == 0)
{
return false;
}
TSharedRef<FOnlineSessionSearchAccelByte> SearchHandle =
MakeShared<FOnlineSessionSearchAccelByte>();
SearchHandle->SetIsP2PMatchmaking(bUseP2P);
SearchHandle->QuerySettings.Set(
SETTING_SESSION_MATCHPOOL,
FString(TEXT("quickplay-pool")),
EOnlineComparisonOp::Equals);
FOnlineSearchSettingsAccelByte::Set(
SearchHandle->QuerySettings,
FName(TEXT("sub_game_mode")),
AcceptedModes,
EOnlineComparisonOp::Equals);
if (!SessionInterface->StartMatchmaking(
USER_ID_TO_MATCHMAKING_USER_ARRAY(LocalPlayerId),
NAME_GameSession,
FOnlineSessionSettings(),
SearchHandle,
OnStarted))
{
return false;
}
OutSearchHandle = SearchHandle;
return true;
}
Call the helper from your queue handler. Here, LocalPlayerId is a valid FUniqueNetIdPtr, OnStartMatchmakingCompleteDelegate is your bound FOnStartMatchmakingComplete, and ActiveSearchHandle is a TSharedPtr<FOnlineSessionSearchAccelByte> class member retained for the search:
const TArray<FString> AcceptedModes = {
TEXT("elimination"), TEXT("teamdeathmatch"), TEXT("skirmish")
};
const bool bRequestStarted = StartQuickPlayMatchmaking(
SessionInterface,
LocalPlayerId.ToSharedRef(),
AcceptedModes,
bUseP2P,
OnStartMatchmakingCompleteDelegate,
ActiveSearchHandle);
For a Team Deathmatch-only button, pass a TArray<FString> containing only TEXT("teamdeathmatch") to the same helper. If bRequestStarted is false, restore your queue UI immediately. A true return and the start-request completion delegate concern starting matchmaking; handle the eventual result with FOnMatchmakingCompleteDelegate as described in Integrate matchmaking (Unreal).
Prevent duplicate in-flight submissions. For a party, only the leader starts matchmaking; OSS attaches the current party session ID. Before replacing an active selection, call CancelMatchmaking and wait for a successful FOnCancelMatchmakingCompleteDelegate callback. Account for a match forming during cancellation.
After joining the matched game session, read sub_game_mode from the session settings.
TArray<FString> SessionModes;
const FOnlineSessionSettings* Settings =
SessionInterface->GetSessionSettings(NAME_GameSession);
const bool bHasModes = Settings != nullptr
&& FOnlineSessionSettingsAccelByte::Get(
*Settings, FName(TEXT("sub_game_mode")), SessionModes);
If bHasModes is false or the array is empty, handle the missing mode data in your session flow. Otherwise, use the priority order in the next section to choose the gameplay mode. See Integrate game session attributes for more on session attributes in OSS.
Join the session and choose the gameplay mode
After a match forms, follow your normal session invitation and join flow. Read the sub_game_mode array from the matched session's attributes. It contains the modes that every matched ticket accepts and whose active team requirements the formed teams satisfy, including any flexing that has taken effect. For example, when two players who accept all three modes match after flexing, the array contains "elimination" and "teamdeathmatch" in either order.
Use a fixed priority order shared by your game clients and server. Pick the first mode in that priority order that appears in the session array. For example, with Elimination first, Team Deathmatch second, and Skirmish third, the two-player match uses Elimination.
Use Integrate matchmaking (Unity) or Integrate matchmaking (Unreal) for notifications, session joining, and the hosting connection path. Use each mode's team requirements for gameplay and player-count UI, even if the shared session capacity is larger.
Validate the configuration
Run these checks in your target deployment. Inspect actual ticket and session data; successful ticket creation or ruleset read-back alone does not establish matchmaking behavior.
| Check | Expected result |
|---|---|
| Dedicated and Quick Play buttons | Requests use the same pool and the intended nonempty accepted-mode arrays |
| Single-mode tickets before flexing | Teams meet that mode's initial requirements. Too few players stay in the queue |
| Elimination-only and Team Deathmatch-only tickets after 10 seconds | Each mode uses its own flexed team requirements. Allow for matcher evaluation delay |
| Skirmish-only tickets after more than 10 seconds | Skirmish still requires two teams of two |
| Disjoint accepted modes | Tickets remain unmatched during a documented observation interval |
| Two players who accept all three modes match after flexing | The session lists Elimination and Team Deathmatch in either order and has a 50-player maximum |
| Two teams of two after flexing, with every ticket accepting all three modes | The session array includes all three modes. Clients and server choose the same gameplay mode regardless of array order |
| Party sizes | Offered modes and actual team assignments accommodate every party |
| Session capacity | The session maximum is 50 for both a four-player Skirmish match and a full Elimination match. Hosting supports all 50 players |
| Session membership | Tickets resolve to the same session with the expected players and teams |
| Ticket lifecycle | Cancellation, replacement, expiration, and match-found races leave consistent client state |
| Hosting and cleanup | Players complete the configured connection flow; test tickets and sessions are cleaned up |
Test each mode at its intended player counts and flexing thresholds, including the 50-player Elimination match. If the team composition or session modes differ from what you expect, inspect the ticket and session data before deployment.
Review whether the 10-second thresholds produce matches that are too small, and whether the 200 millisecond latency ceiling suits your players. Automatic backfill is disabled in this example, so relaxed matches will not be automatically filled through that setting.