Friends Matchmaking

Introduction

This tutorial provides an example of how to set up matchmaking for friends. We're going to look for Drop In/Drop Out Matches that are in progress and that our friends currently belong to and join one of these "friends Matches".

Read First! It would be useful to first read through our How to Match Players guide to familiarize yourself with the basics of our Matchmaking system. In particular for this tutorial, please review the Working with Custom Scripts section on that page.

Creating the Match Configuration

First, we’ll create a simple Match configuration for testing our scenario. Here are the Match configuration settings we're going to use:

For Thresholds we’ll use the following settings:

For the Custom Script we’ll be using the following script:


var players = pendingMatch.getPlayersDetails();
for(var i in players){
    players[i].setCustomQuery(null);
}

Normally, the customQuery has to be satisfied in both inbound and outbound directions for a Match to be successfully made. Because the players friends list will vary from player to player, we’ll use this script to set the customQuery back to null for all players in the pendingMatch. This means that only the incoming customQuery with the unique friends list will need to be satisfied.

NOTE: This guide makes use of automatic matching. The player will be matched with a friend automatically if any friends are in available eligible Matches. You can turn manual matching on if you would like to give the player the choice of what friends Match to join. For more details on manual matching, see the Manual Matching section on the How to Match Players page.

Testing the Setup

To test our set up, we'll open three windows in the Test Harness. In the first window we’ll register p1:


{
  "@class": ".RegistrationRequest",
  "displayName": "p1",
  "password": "",
  "userName": "p1"
}

In the second window, we’ll register p2:


{
  "@class": ".RegistrationRequest",
  "displayName": "p2",
  "password": "",
  "userName": "p2"
}

In the third window, we’ll register p3:


{
  "@class": ".RegistrationRequest",
  "displayName": "p3",
  "password": "",
  "userName": "p3"
}

We now have 3 players created and authenticated. We are ready to proceed with our test.

NOTE: The playerIds in the customQueries in the following example will need to be replaced with playerIds from your own game. They are included here for guidance purposes only.

Back in window one, we can send the MatchmakingRequest for p1 as follows to create the pendingMatch:


{
  "@class": ".MatchmakingRequest",
  "matchShortCode": "friendMatch",
  "skill": 2
}

In window two, we can send the send the MatchmakingRequest for p2 as follows to join the pendingMatch. The id in the customQuery here belongs to p1:


{
  "@class": ".MatchmakingRequest",
  "customQuery":{"players.playerId":{"$in":["5a58dd087eebc044b8ea0f45"]}},
  "matchShortCode": "friendMatch",
  "skill": 2
}

In window three, we can send the send the MatchmakingRequest for p3 as follows to join the pendingMatch. The ids in the customQuery here belongs to p1 and p2:


{
  "@class": ".MatchmakingRequest",
  "customQuery":{"players.playerId":{"$in":["5a58dd107eebc044b8ea0f57","5a58dd087eebc044b8ea0f45"]}},
  "matchShortCode": "friendMatch",
  "skill": 2
}

When the Match gets updated as players join or leave, our Custom Script executes and sets the customQuery for all participants to null.

It's important to understand why the Custom Script is necessary to ensure we achieve "friends only" matchmaking. If these MatchmakingRequests are sent in the sequence above without the Custom Script in place, then the following would occur as the Matchmaking process plays out:

  1. A pendingMatch would be created for p1's request - we’ll call this Match A.
  2. A pendingMatch would be created for p2's request (Match B), which is then joined with Match A because Match A satisfies the customQuery of p2. At this point, Match B is removed and both p1 and p2 are now in Match A.
  3. A pendingMatch would be created for p3's request (Match C). This will not join Match A because although Match A satisfies p3’s customQuery, Match C doesn't satisfy the customQuery of one or more of the players already in match A (in this case p2’s customQuery).

We've seen that the Custom Script clears the customQuery of each player in the created Pending Match, so, once we have the script in place, steps 1. & 2. will behave the same as above but at step 3, Match C will now join with Match A. The reason this works is that Match A satisfies p3's custom query (as before), and since our Custom Script has removed all customQueries from Match A, Match C no longer needs to satisfy any customQueries.

NOTE: The above example uses the ids of 3 unrelated players that we have registered. To apply it to your friends, you can simply get the current players friends with the SparkPlayer getFriendIds call or by sending the ListGameFriendsRequest.

Did this page help you? Please enter your feedback below. For questions about using this part of the platform, please contact support here