Skip to main content

Configure Quick Play with sub-game modes

Last updated on November 19, 2026

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.

Example settings

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​

Define the sub-game modes​

The alliance fields describe the number of teams and the number of players per team:

FieldMeaning
min_numberMinimum number of teams
max_numberMaximum number of teams
player_min_numberMinimum players per team
player_max_numberMaximum players per team

Use these requirements for the example:

Mode identifierInitial team shapeInitial total playersShape after 10 seconds
eliminationExactly 10 teams, each with 2–5 players20–501–10 teams, each with 1–5 players
teamdeathmatchExactly 2 teams of 5101–2 teams, each with 1–5 players
skirmishExactly 2 teams of 24Unchanged; no flexing rule

Elimination is a team-based mode in this example. Its initial configuration requires at least 20 players.

Minimum playable match

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.

  1. Create a ruleset, for example quickplay-ruleset, with the configuration above.
  2. Create one pool, for example quickplay-pool, referencing that ruleset and a shared session template. Follow Configure match pools.
  3. Check that your hosting implementation supports a 50-player session.
  4. 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 selectionsub_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​

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.

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.

CheckExpected result
Dedicated and Quick Play buttonsRequests use the same pool and the intended nonempty accepted-mode arrays
Single-mode tickets before flexingTeams meet that mode's initial requirements. Too few players stay in the queue
Elimination-only and Team Deathmatch-only tickets after 10 secondsEach mode uses its own flexed team requirements. Allow for matcher evaluation delay
Skirmish-only tickets after more than 10 secondsSkirmish still requires two teams of two
Disjoint accepted modesTickets remain unmatched during a documented observation interval
Two players who accept all three modes match after flexingThe 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 modesThe session array includes all three modes. Clients and server choose the same gameplay mode regardless of array order
Party sizesOffered modes and actual team assignments accommodate every party
Session capacityThe session maximum is 50 for both a four-player Skirmish match and a full Elimination match. Hosting supports all 50 players
Session membershipTickets resolve to the same session with the expected players and teams
Ticket lifecycleCancellation, replacement, expiration, and match-found races leave consistent client state
Hosting and cleanupPlayers 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.