Challenge Eligibility

Introduction

In this tutorial, we'll look at setting up matchmaking based on a player's segments. To do this, we'll use segmentation to group players together and we'll use eligibility criteria to filter Challenges for those players. We'll also see how we can override a current player's settings to allow the client to determine what available Challenges to show at any time, and allow the player to join them.

To start with, let's set up a simple Challenge. We can then look at how to match players up.

1. Navigate to Configurator > Multiplayer. The page opens with the Challenges tab selected.

2. Click to Add a new Challenge.

3. Give it a Short Code of SC1.

4. Give it a Name - let's just call it Simple Challenge:

5. Click to Save and Close the new Challenge.

That's all we need for the purposes of this tutorial, so let's head over to the Test Harness and get our players set up.

Using a Player's Segments

We're going to segment our players based on level, with the aim of matching only those players who are the same level as each other to play against each other.

1. First, let's register our first two players, setting their level to Newbie:

[
  {
    "@class": ".RegistrationRequest",
    "displayName": "challengePlayer1",
    "password": "password",
    "segments": {
      "level": "Newbie"
                },
    "userName": "challengePlayer1"
  },
  {
    "@class": ".RegistrationRequest",
    "displayName": "challengePlayer2",
    "password": "password",
    "segments": {
      "level": "Newbie"
                },
    "userName": "challengePlayer2"
  }
]

2. Leave yourself authenticated as challengePlayer2 and let's create the Challenge instance. Since challengePlayer2 and challengePlayer1 don't yet know each other, we want to create a PUBLIC challenge and, importantly, we'll specify our eligibility criteria.

Here's the CreateChallengeRequest we use to do this:

{
  "@class": ".CreateChallengeRequest",
  "accessType": "PUBLIC",
  "challengeShortCode": "SC1",
  "eligibilityCriteria": {
    "segments": {
        "level": "Newbie"
                }
                          },
  "endTime": "2015-03-25T12:00Z"
}

What this means is that to be eligible to find or join this Challenge you must have a segment called level, with the value Newbie. The eligibility criteria can be more complex than this and we'll go into some more detail on this later.

3. Now we have our Challenge instance, let's authenticate as challengePlayer1 and find it.

Make a FindChallengeRequest specifying an accessType of PUBLIC and our Challenge Short Code of SC1:

{
  "@class": ".FindChallengeRequest",
  "accessType": "PUBLIC",
  "shortCode": "SC1"
}

And you should see the Challenge instance we just created showing in the Test Harness Inspector window:

{
  "@class": ".FindChallengeResponse",
  "challengeInstances": [
    {
      "challengeId": "5510136de4b08269846ec481",
      "state": "ISSUED",
      "scriptData": {},
        "shortCode": "SC1",
        "accepted": [
        {
          "name": "challengePlayer2",
          "id": "55100e8ce4b0a0e0ea03291b"
        }
                        ],
  "startDate": null,
  "challenger": {
    "name": "challengePlayer2",
    "id": "55100e8ce4b0a0e0ea03291b"
                },
  "expiryDate": null,
  "turnCount": {
    "55100e8ce4b0a0e0ea03291b": 0
                },
  "endDate": "2015-03-25T12:00Z",
  "challengeName": "Simple Challenge"
                }
                      ],
  "scriptData": null
}

4. Now we can send a JoinChallengeRequest with this challengeInstanceId:

{
  "@class": ".JoinChallengeRequest",
  "challengeInstanceId": "5510136de4b08269846ec481"
}

And we've just matched challengePlayer1 and challengePlayer2 based on their level - they're both Newbies. It really is that simple!

5. Now, let's add a new player, challengePlayer3. This player is a bit more experienced than our first two players, so their level is Advanced:

{
  "@class": ".RegistrationRequest",
  "displayName": "challengePlayer3",
  "password": "password",
  "segments": {
    "level": "Advanced"
              },
  "userName": "challengePlayer3"

}

6. Submit a new CreateChallengeRequest using challengePlayer3 as we did above, but this time set the level to be Advanced:

{
  "@class": ".CreateChallengeRequest",
  "accessType": "PUBLIC",
  "challengeShortCode": "SC1",
  "eligibilityCriteria": {
      "segments": {
        "level": "Advanced"
                  }
                          },
  "endTime": "2015-03-25T12:00Z"
}

7. Now authenticate as challengePlayer1 and let's see if we can find this Challenge to join:

{
  "@class": ".FindChallengeRequest",
  "accessType": "PUBLIC",
  "shortCode": "SC1"
}

We can see that the Advanced Challenge created by challengePlayer3 doesn't show up here.

8. However, we can register another Advanced player:

{
  "@class": ".RegistrationRequest",
  "displayName": "challengePlayer4",
  "password": "password",
    "segments": {
      "level": "Advanced"
                },
  "userName": "challengePlayer4"
}

9. And now do a FindChallengeRequest:

{
  "@class": ".FindChallengeRequest",
  "accessType": "PUBLIC",
  "shortCode": "SC1"
}

{
  "@class": ".FindChallengeResponse",
  "challengeInstances": [
  {
    "challengeId": "55102540e4b08269846f0952",
    "state": "ISSUED",
    "scriptData": {},
      "shortCode": "SC1",
      "accepted": [
      {
        "name": "challengePlayer3",
        "id": "551010d7e4b08269846eb7b4"
      }
                  ],
  "startDate": null,
  "challenger": {
  "name": "challengePlayer3",
  "id": "551010d7e4b08269846eb7b4"
  },
    "expiryDate": null,
    "turnCount": {
      "551010d7e4b08269846eb7b4": 0
  },
    "endDate": "2015-03-25T12:00Z",
    "challengeName": "Simple Challenge"
  }
                      ],
    "scriptData": null
}

Not only do they see the Advanced Challenge, but they don't see the Newbie Challenge.

Overriding Eligibility in the Client

We've seen that we can use segments to categorize players, and match players based on this. What if we'd rather it was just the Challenges that are categorized to make them more readily searchable, but any player could join them? No problem, we can do this as well.

Let's go back to using challengePlayer1 and challengePlayer2. We're not going to be using level any more, so it doesn't actually matter which players we use for this.

1. Authenticate as challengePlayer2 and let's create another Challenge. This time specify some other segment name, let's call it category - this is an arbitrary choice, it could be anything:

{
  "@class": ".CreateChallengeRequest",
  "accessType": "PUBLIC",
  "challengeShortCode": "SC1",
  "eligibilityCriteria": {
    "segments": {
      "category": "friendly"
}
},
  "endTime": "2015-03-25T12:00Z"
}

2. Now authenticate as challengePlayer1 and let's try and find that Challenge:

{
  "@class": ".FindChallengeRequest",
  "accessType": "PUBLIC",
  "shortCode": "SC1"
}

You can see the Challenge we have just created doesn't show up.

3. Let's modify that request slightly. Since we're using eligibility criteria to categorize Challenges rather than to group players, the client is going to own what the eligibility for the request is:

{
  "@class": ".FindChallengeRequest",
  "accessType": "PUBLIC",
  "shortCode": "SC1",
  "eligibility" : {
    "segments" : {
      "category" : "friendly"
                }
                  }
}

Here you can see we're specifying the eligibility for this request, which means the platform will use that value rather than taking the segments from the player. Now we can indeed see the Challenge we created.

4. As before, we'll not be able to join this Challenge unless we're eligible, and the same mechanism applies:

{
  "@class": ".JoinChallengeRequest",
  "challengeInstanceId": "55102a77e4b08269846f1d2a",
  "eligibility" : {
    "segments" : {
        "category" : "friendly"
                }
                  }
}

We're telling the server what the eligibility should be. Without it, the player's segments would again be used.

Advanced Eligibility Criteria

The eligibility criteria specified in the CreateChallengeRequest can be more complex than a simple name and value of a segment. We currently support specifying multiple segments, and for each a list of values. So we could do something like this:

{
  "@class": ".CreateChallengeRequest",
  "accessType": "PUBLIC",
  "challengeShortCode": "SC1",
  "eligibilityCriteria": {
    "segments": {
      "level": ["Newbie", "Advanced"],
        "country" : "UK"
                }
                        },
  "endTime": "2015-03-25T12:00Z"
}

When multiple segments are specified a player must match ALL of them. In the above example, our player would need to have both level AND country segments. When multiple segment values are specified, a player must match ONE of them (a player can only have one value for a segment, after all). So we could join the above Challenge with the player:

{
  "segments" : {
    "level" : "Advanced",
    "country" : "UK"
              }
}

or player:

{
  "segments" : {
    "level" : "Newbie",
    "country" : "UK"
              }
}

but NOT:

{
  "segments" : {
    "level" : "Newbie",
    "country" : "US"
              }
}

NOR:

{
  "segments" : {
    "level" : "Newbie"
              }
}

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