Matchmaker #

The Nakama matchmaker feature enables users to search for, and be matched with, other users - whether as teammates or opponents - to form matches, groups, or participate in any other social features built into your project.

The matchmaker maintains a pool of users and their matchmaking requests (“tickets”), and places them together whenever a good match is found. The definition of a “good match” for any particular user is based upon the criteria defined in their matchmaker ticket. The length of time before a match is found is highly variable, depending on how narrowly defined the criteria is and the amount of users currently in the matchmaking pool. If matchmaking duration is too long, or matches are not being found at all, consider expanding the criteria.

Note that matchmaking is for active players only - users with an open socket connection. Once they have submitted a matchmaker ticket - adding themselves to the matchmaker pool of available players - users remain there until a match is found or they cancel their request. If a user disconnects, any pending matchmaking requests they had are also cancelled.

Matchmaking is distinct from Nakama’s match listing feature. Where the matchmaker is used to place users together to start a new match, match listing is used to show users existing matches that they can join immediately. Deciding between using matchmaking or match listing is a design consideration (rather than a technical one) based on your project goals and requirements.

Configuration #

There are several parameters available in your Nakama configuration that affect how the matchmaker functions.

You can prevent users from submitting abusive amounts of tickets, and never cancelling old ones, by setting a maximum number of concurrent tickets a user can have at any one time.

By setting the time interval the matchmaker attempts to find a user’s “ideal” (size) match, and the number of intervals before allowing a less ideal (in size) match, you can adjust how long your users are waiting and balance finding the ideal match versus getting into a match more quickly.

The reverse matching precision and threshold flags are used to dictate if, and for how long, reverse matching precision is active. If enabled (rev_precision set to true), the matchmaker will validate matches bidirectionally (i.e. when Player A matches with Player B, it will also check that Player B matches with Player A). If the match is not bidirectional, the matchmaker will continue to search for a bidirectional match for the duration of the rev_threshold intervals. If no bidirectional match is found within number of intervals (1 by default), the matchmaker will return to unidirectional matching.

Matchmaking criteria #

To begin matchmaking users add themselves to the matchmaking pool. As part of their matchmaker ticket there are optional criteria that can be included to describe the desired match: Properties, Minimum count and Maximum count, Count multiple, and a Query.

Properties #

Properties are key-value pairs, either string or numeric, that describe the user submitting a matchmaking ticket. Some common examples of what can be provided in properties include the user’s game rank/level, their skill rating, the connecting region, or selected match types (e.g. Free for All, Capture the Flag, etc.).

1
2
3
4
5
6
7

const stringProperties = {
  region: "europe"
};

const numericProperties = {
  rank: 8
};

1
2
3
4
5
6
7

var stringProperties = new Dictionary<string, string>() {
    {"region", "europe"}
};

var numericProperties = new Dictionary<string, int>() {
    {"rank", 8}
};

1
2

let stringProperties = ["region": "europe"]
let numericProperties: [String:Double] = ["rank": 8]

1
2
3
4
5
6

const stringProperties = {
  'region': 'europe',
};
const numericProperties = {
  'rank': 8,
};

1
2
3
4
5

NStringMap stringProperties;
NStringDoubleMap numericProperties;

stringProperties.emplace("region", "europe");
numericProperties.emplace("rank", 8.0);

1
2
3
4
5
6
7

Map<String, String> stringProperties = new HashMap<String, String>() {{
    put("region", "europe");
}};

Map<String, Double> numericProperties = new HashMap<String, Double>() {{
    put("rank", 8.0);
}};

1
2

var string_properties = { "region": "europe" }
var numeric_properties = { "rank": 8 }

1
2

var string_properties = { "region": "europe" }
var numeric_properties = { "rank": 8 }

1
2

local string_properties = { region = "europe" }
local numeric_properties = { rank = 8 }

These properties are submitted by the user when they begin the matchmaking process, and can be different for each ticket. The server merges all included properties to form the overall properties that are part of the matchmaker ticket.

When matchmaking completes these properties are visible to all matched users. You can store extra information without affecting the matchmaking process itself if it’s useful to clients - just submit properties that aren’t queried for as part of the matchmaking process.

You can also authoritatively control the properties using a before hook when adding the user to the matchmaker:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21

var (
	errInternal = runtime.NewError("internal server error", 13)
)

func InitModule(ctx context.Context, logger runtime.Logger, db *sql.DB, nk runtime.NakamaModule, initializer runtime.Initializer) error {
	initializer.RegisterBeforeRt("MatchmakerAdd", func(ctx context.Context, logger runtime.Logger, db *sql.DB, nk runtime.NakamaModule, in *rtapi.Envelope) (*rtapi.Envelope, error) {
		message, ok := in.Message.(*rtapi.Envelope_MatchmakerAdd)
		if !ok {
			return nil, errInternal
		}

		// If the string properties contains a region value of "europe", modify it to "europe-west"
		if value, ok := message.MatchmakerAdd.StringProperties["region"]; ok && value == "europe" {
			message.MatchmakerAdd.StringProperties["region"] = "europe-west"
		}

		return in, nil
	})

	return nil
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

function InitModule(ctx: nkruntime.Context, logger: nkruntime.Logger, nk: nkruntime.Nakama, initializer: nkruntime.Initializer) {
  initializer.registerRtBefore("MatchmakerAdd", beforeMatchmakerAdd)
}

const beforeMatchmakerAdd : nkruntime.RtBeforeHookFunction<nkruntime.EnvelopeMatchmakerAdd> = function (ctx: nkruntime.Context, logger: nkruntime.Logger, nk: nkruntime.Nakama, envelope: nkruntime.EnvelopeMatchmakerAdd) : nkruntime.EnvelopeMatchmakerAdd | void {
  const region = envelope.matchmakerAdd.stringProperties["region"];

  // If the string properties contain a region value of "europe", modify it to "europe-west"
  if (region && region == "europe") {
    envelope.matchmakerAdd.stringProperties["region"] = "europe-west";
  }

  return envelope;
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

nk.register_rt_before(function(context, payload)
    local region = payload.matchmaker_add.string_properties["region"]

    -- If the string properties contain a region value of "europe", modify it to "europe-west"
    if region == "europe" then
        payload.matchmaker_add.string_properties["region"] = "europe-west"
    end

    return payload
end, "MatchmakerAdd")

Minimum and maximum count #

When submitting a matchmaker request users must specify both a minimum and maximum count, where the minCount represents the smallest acceptable match size and maxCount represents the largest acceptable match size, with both being inclusive of the player submitting the request.

The matchmaker will always try to match at the provided maximum count. If there aren’t enough users, then the closest possible size to the maximum count will be returned as the match so long as it is above the minimum count.

For example, if using a minimum count of 2 and maximum count of 4, the matchmaker will try to find 3 other players to match the user with. If there are not 3 matching players available, the matchmaker will try to match 2 others, and finally just 1 other player if 2 are not available.

If there are not enough available users to meet even the minimum count, no match is returned and the user remains in the pool.

1
2
3
4

const query = "*";
const minCount = 2;
const maxCount = 4;
var ticket = await socket.addMatchmaker(query, minCount, maxCount);

1
2
3
4

var query = "*";
var minCount = 2;
var maxCount = 4;
var matchmakerTicket = await socket.AddMatchmakerAsync(query, minCount, maxCount);

1
2
3
4

let query = "*"
let minCount = 2
let maxCount = 4
let ticket = try await socket.addMatchmaker(query: query, minCount: minCount, maxCount: maxCount)

1
2
3
4
5
6
7
8
9

const query = '*';
const minCount = 2;
const maxCount = 4;
final ticket = await socket.addMatchmaker(
  query,
  minCount: minCount,
  maxCount: maxCount,
);

1
2
3
4

String query = "*";
int minCount = 2;
int maxCount = 4;
MatchmakerTicket matchmakerTicket = socket.addMatchmaker(query, minCount, maxCount).get();

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

var query = "*"
var min_count = 2
var max_count = 4

var matchmaker_ticket : NakamaRTAPI.MatchmakerTicket = yield(
    socket.add_matchmaker_async(query, min_count, max_count),
    "completed"
)

if matchmaker_ticket.is_exception():
    print("An error occurred: %s" % matchmaker_ticket)
    return

print("Got ticket: %s" % [matchmaker_ticket])

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

var query = "*"
var min_count = 2
var max_count = 4

var matchmaker_ticket : NakamaRTAPI.MatchmakerTicket = await socket.add_matchmaker_async(query, min_count, max_count)

if matchmaker_ticket.is_exception():
    print("An error occurred: %s" % matchmaker_ticket)
    return

print("Got ticket: %s" % [matchmaker_ticket])

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

auto successCallback = [](const NMatchmakerTicket& ticket)
{
    std::cout << "Matchmaker ticket: " << ticket.ticket << std::endl;
};

int32_t minCount = 2;
int32_t maxCount = 4;
string query = "*";

rtClient->addMatchmaker(minCount, maxCount, query, {}, {}, successCallback);

1
2
3
4
5

local query = "*"
local min_players = 2
local max_players = 4

local ticket = socket.matchmaker_add(min_players, max_players, query)

Users can search for an exact number of opponents by submitting the same minimum and maximum count:

1
2
3
4

const query = "*";
const minCount = 4;
const maxCount = 4;
var ticket = await socket.addMatchmaker(query, minCount, maxCount);

1
2
3
4

var query = "*";
var minCount = 4;
var maxCount = 4;
var matchmakerTicket = await socket.AddMatchmakerAsync(query, minCount, maxCount);

1
2
3
4

let query = "*"
let minCount = 4
let maxCount = 4
let ticket = try await socket.addMatchmaker(query: query, minCount: minCount, maxCount: maxCount)

1
2
3
4
5
6
7
8

const query = '*';
const minCount = 4;
const maxCount = 4;
final ticket = await socket.addMatchmaker(
  query,
  minCount: minCount,
  maxCount: maxCount,
);

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

auto successCallback = [](const NMatchmakerTicket& ticket)
{
    std::cout << "Matchmaker ticket: " << ticket.ticket << std::endl;
};

int32_t minCount = 4;
int32_t maxCount = 4;
string query = "*";

rtClient->addMatchmaker(minCount, maxCount, query, {}, {}, successCallback);

1
2
3
4
5

String query = "*";
int minCount = 4;
int maxCount = 4;

MatchmakerTicket matchmakerTicket = socket.addMatchmaker(query, minCount, maxCount).get();

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

var query = "*"
var min_count = 4
var max_count = 4

var matchmaker_ticket : NakamaRTAPI.MatchmakerTicket = yield(
    socket.add_matchmaker_async(query, min_count, max_count),
    "completed"
)

if matchmaker_ticket.is_exception():
    print("An error occurred: %s" % matchmaker_ticket)
    return

print("Got ticket: %s" % [matchmaker_ticket])

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

var query = "*"
var min_count = 4
var max_count = 4

var matchmaker_ticket : NakamaRTAPI.MatchmakerTicket = await socket.add_matchmaker_async(query, min_count, max_count)

if matchmaker_ticket.is_exception():
    print("An error occurred: %s" % matchmaker_ticket)
    return

print("Got ticket: %s" % [matchmaker_ticket])

1
2
3
4
5

local query = "*"
local min_players = 4
local max_players = 4

local ticket = socket.matchmaker_add(min_players, max_players, query)

You can also authoritatively control the minimum and maximum counts using a before hook when adding the user to the matchmaker:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

var (
	errInternal = runtime.NewError("internal server error", 13)
)

func InitModule(ctx context.Context, logger runtime.Logger, db *sql.DB, nk runtime.NakamaModule, initializer runtime.Initializer) error {
	initializer.RegisterBeforeRt("MatchmakerAdd", func(ctx context.Context, logger runtime.Logger, db *sql.DB, nk runtime.NakamaModule, in *rtapi.Envelope) (*rtapi.Envelope, error) {
		message, ok := in.Message.(*rtapi.Envelope_MatchmakerAdd)
		if !ok {
			return nil, errInternal
		}

		// Force min count to be 4 and max count to be 8
        message.MatchmakerAdd.MinCount = 4
        message.MatchmakerAdd.MaxCount = 8

		return in, nil
	})

	return nil
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

function InitModule(ctx: nkruntime.Context, logger: nkruntime.Logger, nk: nkruntime.Nakama, initializer: nkruntime.Initializer) {
  initializer.registerRtBefore("MatchmakerAdd", beforeMatchmakerAdd)
}

const beforeMatchmakerAdd : nkruntime.RtBeforeHookFunction<nkruntime.EnvelopeMatchmakerAdd> = function (ctx: nkruntime.Context, logger: nkruntime.Logger, nk: nkruntime.Nakama, envelope: nkruntime.EnvelopeMatchmakerAdd) : nkruntime.EnvelopeMatchmakerAdd | void {
  // Force min count to be 4 and max count to be 8
  envelope.matchmakerAdd.minCount = 4
  envelope.matchmakerAdd.maxCount = 8

  return envelope;
}

1
2
3
4
5
6
7

nk.register_rt_before(function(context, payload)
  -- Force min count to be 4 and max count to be 8
  payload.matchmaker_add.min_count = 4
  payload.matchmaker_add.max_count = 8

  return payload
end, "MatchmakerAdd")

Count multiple #

The countMultiple parameter can be used when you need to enforce a specific multiplier for the acceptable match sizes (i.e. results must be in multiples of 5).

For example, take the following request:

1
2
3
4
5

const query = "*";
const minCount = 5;
const maxCount = 25;
const countMultiple = 5;
var ticket = await socket.addMatchmaker(query, minCount, maxCount, countMultiple);

1
2
3
4
5

var query = "*";
var minCount = 5;
var maxCount = 25;
var countMultiple = 5;
var matchmakerTicket = await socket.AddMatchmakerAsync(query, minCount, maxCount, countMultiple);

1
2
3
4
5

let query = "*"
let minCount = 5
let maxCount = 25
let countMultiple = 5
let ticket = try await socket.addMatchmaker(query: query, minCount: minCount, maxCount: maxCount, countMultiple: countMultiple)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

const query = '*';
const minCount = 5;
const maxCount = 25;
const countMultiple = 5;
final ticket = await socket.addMatchmaker(
  query,
  minCount: minCount,
  maxCount: maxCount,
  countMultiple: countMultiple,
);

1
2
3
4
5

String query = "*";
int minCount = 5;
int maxCount = 25;
int countMultiple = 5;
MatchmakerTicket matchmakerTicket = socket.addMatchmaker(query, minCount, maxCount, countMultiple).get();

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

var query = "*"
var min_count = 5
var max_count = 25
var count_multiple = 5

var matchmaker_ticket : NakamaRTAPI.MatchmakerTicket = yield(
    socket.add_matchmaker_async(query, min_count, max_count, count_multiple),
    "completed"
)

if matchmaker_ticket.is_exception():
    print("An error occurred: %s" % matchmaker_ticket)
    return

print("Got ticket: %s" % [matchmaker_ticket])

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

var query = "*"
var min_count = 5
var max_count = 25
var count_multiple = 5

var matchmaker_ticket : NakamaRTAPI.MatchmakerTicket = await socket.add_matchmaker_async(query, min_count, max_count, count_multiple)

if matchmaker_ticket.is_exception():
    print("An error occurred: %s" % matchmaker_ticket)
    return

print("Got ticket: %s" % [matchmaker_ticket])

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

auto successCallback = [](const NMatchmakerTicket& ticket)
{
    std::cout << "Matchmaker ticket: " << ticket.ticket << std::endl;
};

int32_t minCount = 5;
int32_t maxCount = 25;
string query = "*";
int32_t countMultiple = 5;

rtClient->addMatchmaker(minCount, maxCount, query, {}, {}, countMultiple successCallback);

1
2
3
4
5
6

local query = "*"
local min_players = 5
local max_players = 25
local count_multiple = 5

local ticket = socket.matchmaker_add(min_players, max_players, query, nil, nil, count_multiple)

The matchmaker will only return results containing a total number of matched players that is a multiple of 5, first trying to return the maximum count of 25, then 20, 15, and so forth. Even if there are 23 matching players available, the returned result will be 20 players.

You can also authoritatively control the count multiple using a before hook when adding the user to the matchmaker:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

var (
	errInternal = runtime.NewError("internal server error", 13)
)

func InitModule(ctx context.Context, logger runtime.Logger, db *sql.DB, nk runtime.NakamaModule, initializer runtime.Initializer) error {
	initializer.RegisterBeforeRt("MatchmakerAdd", func(ctx context.Context, logger runtime.Logger, db *sql.DB, nk runtime.NakamaModule, in *rtapi.Envelope) (*rtapi.Envelope, error) {
		message, ok := in.Message.(*rtapi.Envelope_MatchmakerAdd)
		if !ok {
			return nil, errInternal
		}

		// Force the count multiple to be in multiples of 5
		message.MatchmakerAdd.CountMultiple = &wrapperspb.Int32Value{Value: 5}

		return in, nil
	})

	return nil
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

function InitModule(ctx: nkruntime.Context, logger: nkruntime.Logger, nk: nkruntime.Nakama, initializer: nkruntime.Initializer) {
  initializer.registerRtBefore("MatchmakerAdd", beforeMatchmakerAdd)
}

const beforeMatchmakerAdd : nkruntime.RtBeforeHookFunction<nkruntime.EnvelopeMatchmakerAdd> = function (ctx: nkruntime.Context, logger: nkruntime.Logger, nk: nkruntime.Nakama, envelope: nkruntime.EnvelopeMatchmakerAdd) : nkruntime.EnvelopeMatchmakerAdd | void {
  // Force the count multiple to be in multiples of 5
  envelope.matchmakerAdd.countMultiple = 5;

  return envelope;
}

1
2
3
4
5
6

nk.register_rt_before(function(context, payload)
  -- Force the count multiple to be in multiples of 5
  payload.matchmaker_add.count_multiple = 5

  return payload
end, "MatchmakerAdd")

Query #

Where properties describes the user searching for other players, the query describes what properties they are searching for in other users.

Every user’s matchmaker properties are available in queries under the properties prefix. You can find opponents based on a mix of property filters with exact matches or ranges of values.

See Query Syntax to learn about the grammar and operators available for your queries.

This example searches for opponents that must be in europe and must have a rank between 5 and 10, inclusive:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

const query = "+properties.region:europe +properties.rank:>=5 +properties.rank:<=10";
const minCount = 2;
const maxCount = 4;

const stringProperties = {
  region: "europe"
};

const numericProperties = {
  rank: 8
};

var ticket = await socket.addMatchmaker(query, minCount, maxCount, stringProperties, numericProperties);

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

var query = "+properties.region:europe +properties.rank:>=5 +properties.rank:<=10";

var stringProperties = new Dictionary<string, string>() {
    {"region", "europe"}
};

var numericProperties = new Dictionary<string, int>() {
    {"rank", 8}
};

var matchmakerTicket = await socket.AddMatchmakerAsync(query, 2, 4, stringProperties, numericProperties);

1
2
3
4
5

let query = "+properties.region:europe +properties.rank:>=5 +properties.rank:<=10"
let stringProperties = ["region": "europe"]
let numericProperties: [String:Double] = ["rank": 8]

let ticket = try await socket.addMatchmaker(query: query, minCount: 2, maxCount: 4, stringProperties: stringProperties, numericProperties: numericProperties)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

const query = '+properties.region:europe +properties.rank:>=5 +properties.rank:<=10';

const stringProperties = {
  'region': 'europe',
};

const Map<String, double> numericProperties = {
  'rank': 8,
};

final ticket = await socket.addMatchmaker(
  query,
  minCount: 2,
  maxCount: 4,
  stringProperties: stringProperties,
  numericProperties: numericProperties,
  countMultiple: 5,
);

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

auto successCallback = [](const NMatchmakerTicket& ticket)
{
    std::cout << "Matchmaker ticket: " << ticket.ticket << std::endl;
};

int32_t minCount = 2;
int32_t maxCount = 4;
string query = "+properties.region:europe +properties.rank:>=5 +properties.rank:<=10";
NStringMap stringProperties;
NStringDoubleMap numericProperties;

stringProperties.emplace("region", "europe");
numericProperties.emplace("rank", 8.0);

rtClient->addMatchmaker(minCount, maxCount, query, stringProperties, numericProperties, successCallback);

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

String query = "+properties.region:europe +properties.rank:>=5 +properties.rank:<=10";
int minCount = 2;
int maxCount = 4;

Map<String, String> stringProperties = new HashMap<String, String>() {{
    put("region", "europe");
}};

Map<String, Double> numericProperties = new HashMap<String, Double>() {{
    put("rank", 8.0);
}};

MatchmakerTicket matchmakerTicket = socket.addMatchmaker(query, minCount, maxCount, stringProperties, numericProperties).get();

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

var query = "+properties.region:europe +properties.rank:>=5 +properties.rank:<=10"
var string_properties = { "region": "europe"}
var numeric_properties = { "rank": 8 }

var matchmaker_ticket : NakamaRTAPI.MatchmakerTicket = yield(
    socket.add_matchmaker_async(query, 2, 4, string_properties, numeric_properties),
    "completed"
)

if matchmaker_ticket.is_exception():
    print("An error occurred: %s" % matchmaker_ticket)
    return

print("Got ticket: %s" % [matchmaker_ticket])

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

var query = "+properties.region:europe +properties.rank:>=5 +properties.rank:<=10"
var string_properties = { "region": "europe"}
var numeric_properties = { "rank": 8 }

var matchmaker_ticket : NakamaRTAPI.MatchmakerTicket = await socket.add_matchmaker_async(query, 2, 4, string_properties, numeric_properties)

if matchmaker_ticket.is_exception():
    print("An error occurred: %s" % matchmaker_ticket)
    return

print("Got ticket: %s" % [matchmaker_ticket])

1
2
3
4
5
6
7

local min_players = 2
local max_players = 4
local query = "+properties.region:europe +properties.rank:>=5 +properties.rank:<=10"
local string_properties = { region = "europe"}
local numeric_properties = { rank = 8 }

local matchmaker_ticket = socket.matchmaker_add(min_players, max_players, query, string_properties, numeric_properties)

The wildcard query "*" can be used to ignore opponents’ properties and match with anyone:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

const query = "*";
const minCount = 2;
const maxCount = 4;

const stringProperties = {
  region: "europe"
};

const numericProperties = {
  rank: 8
};

var ticket = await socket.addMatchmaker(query, minCount, maxCount, stringProperties, numericProperties);

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

var query = "*";
var minCount = 2;
var maxCount = 4;

var stringProperties = new Dictionary<string, string>() {
    {"region", "europe"}
};

var numericProperties = new Dictionary<string, int>() {
    {"rank", 8}
};

var matchmakerTicket = await socket.AddMatchmakerAsync(query, minCount, maxCount, stringProperties, numericProperties);

1
2
3
4
5
6
7
8

let query = "*"
let minCount = 2
let maxCount = 4

let stringProperties = ["region": "europe"]
let numericProperties: [String:Double] = ["rank": 8]

let ticket = try await socket.addMatchmaker(query: query, minCount: minCount, maxCount: maxCount, stringProperties: stringProperties, numericProperties: numericProperties)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

const query = '*';
const minCount = 2;
const maxCount = 4;

const stringProperties = {
  'region': 'europe',
};

const Map<String, double> numericProperties = {
  'rank': 8,
};

final ticket = await socket.addMatchmaker(
  query,
  minCount: minCount,
  maxCount: maxCount,
  stringProperties: stringProperties,
  numericProperties: numericProperties,
  countMultiple: 5,
);

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

auto successCallback = [](const NMatchmakerTicket& ticket)
{
    std::cout << "Matchmaker ticket: " << ticket.ticket << std::endl;
};

int32_t minCount = 2;
int32_t maxCount = 4;
string query = "*";
NStringMap stringProperties;
NStringDoubleMap numericProperties;

stringProperties.emplace("region", "europe");
numericProperties.emplace("rank", 8.0);

rtClient->addMatchmaker(minCount, maxCount, query, stringProperties, numericProperties, successCallback);

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

String query = "*";
int minCount = 2;
int maxCount = 4;

Map<String, String> stringProperties = new HashMap<String, String>() {{
    put("region", "europe");
}};

Map<String, Double> numericProperties = new HashMap<String, Double>() {{
    put("rank", 8.0);
}};

MatchmakerTicket matchmakerTicket = socket.addMatchmaker(query, minCount, maxCount, stringProperties, numericProperties).get();

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

var query = "*"
var min_count = 2
var max_count = 4
var string_properties = { "region": "europe" }
var numeric_properties = { "rank": 8 }

var matchmaker_ticket : NakamaRTAPI.MatchmakerTicket = yield(
    socket.add_matchmaker_async(query, min_count, max_count, string_properties, numeric_properties),
    "completed"
)

if matchmaker_ticket.is_exception():
    print("An error occurred: %s" % matchmaker_ticket)
    return

print("Got ticket: %s" % [matchmaker_ticket])

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

var query = "*"
var min_count = 2
var max_count = 4
var string_properties = { "region": "europe" }
var numeric_properties = { "rank": 8 }

var matchmaker_ticket : NakamaRTAPI.MatchmakerTicket = await socket.add_matchmaker_async(query, min_count, max_count, string_properties, numeric_properties)

if matchmaker_ticket.is_exception():
    print("An error occurred: %s" % matchmaker_ticket)
    return

print("Got ticket: %s" % [matchmaker_ticket])

1
2
3
4
5
6
7

local min_players = 2
local max_players = 4
local query = "*"
local string_properties = { region = "europe"}
local numeric_properties = { rank = 8 }

local matchmaker_ticket = socket.matchmaker_add(min_players, max_players, query, string_properties, numeric_properties)

You can also authoritatively control the query using a before hook when adding the user to the matchmaker:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

var (
	errInternal = runtime.NewError("internal server error", 13)
)

func InitModule(ctx context.Context, logger runtime.Logger, db *sql.DB, nk runtime.NakamaModule, initializer runtime.Initializer) error {
	initializer.RegisterBeforeRt("MatchmakerAdd", func(ctx context.Context, logger runtime.Logger, db *sql.DB, nk runtime.NakamaModule, in *rtapi.Envelope) (*rtapi.Envelope, error) {
		message, ok := in.Message.(*rtapi.Envelope_MatchmakerAdd)
		if !ok {
			return nil, errInternal
		}

		// Force the matchmaking request to use the * query
		message.MatchmakerAdd.Query = "*"

		return in, nil
	})

	return nil
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

function InitModule(ctx: nkruntime.Context, logger: nkruntime.Logger, nk: nkruntime.Nakama, initializer: nkruntime.Initializer) {
  initializer.registerRtBefore("MatchmakerAdd", beforeMatchmakerAdd)
}

const beforeMatchmakerAdd : nkruntime.RtBeforeHookFunction<nkruntime.EnvelopeMatchmakerAdd> = function (ctx: nkruntime.Context, logger: nkruntime.Logger, nk: nkruntime.Nakama, envelope: nkruntime.EnvelopeMatchmakerAdd) : nkruntime.EnvelopeMatchmakerAdd | void {
  // Force the matchmaking request to use the * query
  envelope.matchmakerAdd.query = "*";

  return envelope;
}

1
2
3
4
5
6

nk.register_rt_before(function(context, payload)
  -- Force the matchmaking request to use the * query
  payload.matchmaker_add.query = "*"

  return payload
end, "MatchmakerAdd")

Expanding criteria #

Based on the number of active users and the respective criteria used in matchmaking, it can sometimes be difficult or impossible to find the exact match desired.

To effectively “loosen” the criteria being used players should submit multiple tickets, each with a more permissive query than those before it.

For example, if a player wants to be matched with others that are in their region and at exactly the same skill level but is not getting any results, the subsequent tickets can expand to include other regions and allow for a range of skill levels close to the player’s own.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

let query = "+properties.region:europe +properties.rank:5";
const minCount = 2;
const maxCount = 4;

const stringProperties = {
  region: "europe"
};

const numericProperties = {
  rank: 8
};

var ticket = await socket.addMatchmaker(query, minCount, maxCount, stringProperties, numericProperties);

// ... if no match is found within a certain time, request a new ticket with looser criteria
query = "+properties.region:europe +properties.rank:>=3 +properties.rank:<=7";
var newTicket = await socket.addMatchmaker(query, minCount, maxCount, stringProperties, numericProperties);

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

var query = "+properties.region:europe +properties.rank:5";

var stringProperties = new Dictionary<string, string>() {
    {"region", "europe"}
};

var numericProperties = new Dictionary<string, int>() {
    {"rank", 8}
};

var matchmakerTicket = await socket.AddMatchmakerAsync(query, 2, 4, stringProperties, numericProperties);

// ... if no match is found within a certain time, request a new ticket with looser criteria
query = "+properties.region:europe +properties.rank:>=3 +properties.rank:<=7";
var newMatchmakerTicket = await socket.AddMatchmakerAsync(query, 2, 4, stringProperties, numericProperties);