Match Listing

Where the matchmaker can be used by players to find opponents (or teammates) to play with in a new match, match listing is used to show players currently active matches that they can join right away.

You can use match listing to simply return any given number of active matches, but using the match label to query active matches and filter the results according to your player’s desired criteria will provide more relevant matches and a more engaging user experience.

In addition the a match label, you can filter results by their authoritative status and player count. See the function reference for all available parameters.

Filter vs. query

There are two ways of using match label fields to list results: exact-match filtering and querying.

For example, if we want to list matches with a label skill=100-150, exact-match filtering would be as follows:

// Server
function getMatchListings(context: nkruntime.Context, logger: nkruntime.Logger, nk: nkruntime.Nakama) {
  const limit = 10
  const isAuthoritative = true;
  const label = "skill=100-150";
  const minSize = 0;
  const maxSize = 4;
  const matches = nk.matchList(limit, isAuthoritative, label, minSize, maxSize, "");

  matches.forEach(function (match) {
    logger.info("Match id '%s'", match.matchId);
  });
}

Remember that here we are filtering based on the string value of the label, so results will only include matches with the exact label skill=100-150. A match with label skill=100 or skill=150 would not be returned.

While any returned result would be precisely what the player is searching for, this can lead to frustration when no matching results are found at all.

The alternative would be using a query to list available matches filtered based on our desired criteria, in this case a range in skill:

// Server
function findMatch(context: nkruntime.Context, logger: nkruntime.Logger, nk: nkruntime.Nakama) {
  const limit = 10
  const isAuthoritative = true;
  const minSize = 0;
  const maxSize = 4;
  const query = "+label.skill>=100 +label.skill<=150";
  var matches = nk.matchList(limit, isAuthoritative, minSize, maxSize, query);

  matches.forEach(function (match) {
    logger.info("Match id '%s'", match.matchId);
  });
}

With this method, the results will include any match will a skill label between 100 and 150, inclusive.

Learn how to use the query syntax grammar to filter and sort results.

Find or create

To provide a seamless gameplay experience for your users, if match listing fails to return any matching results you can create a new match for the user directly.

Using our filter example from above:

// Server
function findOrCreateMatch(context: nkruntime.Context, logger: nkruntime.Logger, nk: nkruntime.Nakama): string {
  var matches = nk.matchList(limit, isAuthoritative, label, minSize, maxSize, "");

  // If matches exist, sort by match size and return the largest.
  if (matches.length > 0) {
    matches.sort(function (a, b) {
      return a.size >= b.size ? 1 : -1;
    });
    return matches[0].matchId;
  }

  // If no matches exist, create a new one using the "lobby" module and return it's ID.
  var matchId = nk.matchCreate('supermatch', {});
  return JSON.stringify({ matchId });
}

The same can be done when querying matches as well:

// Server
function findOrCreateMatch(context: nkruntime.Context, logger: nkruntime.Logger, nk: nkruntime.Nakama) {
  const query = "+label.skill>=100 +label.skill<=150";
  var matches = nk.matchList(10, true, "", 2, maxSize, query);

  // If matches exist, sort by match size and return the largest.
  if (matches.length > 0) {
    logger.info("Match id '%s'", matches[0].matchId);
  }

  // If no matches exist, create a new one using the "lobby" module and return it's ID.
  var matchId = nk.matchCreate('supermatch', {});
  logger.info(matchId);
}

Examples

Player count #

The minSize and maxSize parameters can be used to list only matches containing the specified number of players. This can be useful for returning results that are already nearly full (and so the match is almost ready to start).

For example, let’s assume a match will begin once 8 players join so we’ll only list matches with between 5-7 players:

// Server
function getMatchListings(context: nkruntime.Context, logger: nkruntime.Logger, nk: nkruntime.Nakama) {
  const limit = 10
  const isAuthoritative = true;
  const minSize = 5;
  const maxSize = 7;
  const matches = nk.matchList(limit, isAuthoritative, minSize, maxSize, "");

  matches.forEach(function (match) {
    logger.info("Match id '%s'", match.matchId);
  });
}