Seasons

The rating system supports seasons. You can at any point start a new season for a game. This will lead to:

• The ranking points of all players being reset to 0.
• (Optional) The rating points being adjusted towards the new player default by a specific factor.

info

To ensure a consistent player experience, there can only be one season active across all game modes for a game_slug. Of course, you can manage seasons separately between different stages (beta, int and prod) to develop and test in parallel to running your game in production.

Scheduling the start of a new season

To allow fine control when new seasons start without having to send a request at exactly the right time, the start of a new season is scheduled and not a synchronous action. This section describes the steps to do this.

Obtaining an IdToken for the Admin API

You can start a new season via our REST Admin API. The first step is to obtain an IdToken for authorization of the request.

For this, you need to send a POST request to https://cognito-idp.eu-central-1.amazonaws.com/ with the following body:

{
  "AuthParameters": {
    "USERNAME": "<admin-username>",
    "PASSWORD": "<admin-password>"
  },
  "AuthFlow": "USER_PASSWORD_AUTH",
  "ClientId": "3k2ggp8qdmo9jhnb389smvbod3"
}

info

The credentials for the Admin API are different to the ones for the Matchmaking API. If you don't have credentials for the Admin API yet, reach out to match@idem.gg and we'll set them up for you.

Admin credentials are valid across all stages.

If successful, the request will return a response in the following format:

{
    "AuthenticationResult": {
        "AccessToken": "eyJra...bk8mA",
        "ExpiresIn": 3600,
        "IdToken": "eyJra...4YGUA",
        "RefreshToken": "eyJjd...YRtaA",
        "TokenType": "Bearer"
    },
    "ChallengeParameters": {}
}

For the next step, you will need the IdToken from that response.

Sending the Admin API request

To start a new season, you need to make POST request to the following endpoint:

https://admin-api.<stage>.idem.gg/admin/season/reset

Replace <stage> with either beta, int or prod.

You need to add the IdToken from the previous step as an Authorization header.

The payload of the request needs to have the following parameters:

seasonName

Each season automatically gets an identifier in our system that follows the nomenclature S<season_number>. season_number is starting at 1 and incremented every time you start a new season. This is what you see in matchmaking messages from Idem, e.g. the updateMatchCompletedResponse.

seasonNameis an additional human-readable identifier for the season.

seasonStart

Starting a new season is a scheduled event and does not become effective immediately. With seasonStart, you can define when the new season should start.

This must be a datetime value in ISO format, e.g. 2024-12-05T14:30:00+02:00. If the value does not include a timezone identifier, it is interpreted as being in UTC, e.g. 2024-12-05T14:30:00 will be parsed as 2024-12-05T14:30:00+00:00

The value must also be at least 1 minute in the future. Otherwise the endpoint will reject the request with the following error:

"error": {
    "code": 400,
    "id": "invalid_season_start",
    "message": "The season_start must be at least 1 minute in the future. Provided value: {seasonStart}"
}

info

You do not have to factor in processing and transfer times on your end. There is a grace period included in the endpoint so that you can use 1 minute in your code if you want to start a season as soon as possible. The typical use of the endpoint is for comfortably scheduling a season for some time in the future, e.g. midnight of the first day of the next month.

gameSlug

This specifies which game the new season should be started for.

percentages

For each new season, ranking points of all players are reset to 0. With the percentages parameter you can optionally also adjust the rating points of players toward the default for each game mode. The parameter needs to be an object with a value between 0 and 1 for each game mode existing for the game.

To understand the behavior of the values, consider the following scenario:

• Default rating points: 1500
• Player1's rating before starting a new season: 1800

Parameter value	Rating points after reset	Explanation
0	1800	0 means no updating.
1	1500	1 means full reset.
0.5	1650	0.5 means updating by half the difference of the current rating to the default. (1800 - 1500)/2 = 150 1800 - 150 = 1650

info

You must specify all existing game modes in the request. If any game mode is missing, the request will result in a 400 error like:

{
    "error": {
        "code": 400,
        "id": "missing_request_data",
        "message": "Missing reset percentage for game mode '3v3'"
    },
    "additionalInfo": {
        "missingFields": [
            "percentages"
        ],
        "gameId": "3v3"
    }
}

Here is an example payload:

{
  "seasonName": "2024-december",
  "seasonStart": "2024-12-05T14:30:00+02:00",
  "gameSlug": "999-test-game",
  "percentages": {
      "1v1": 0.8,
      "1v1-no-items": 1,
      "3v3": 0,
}

Response

If the request was successful, the endpoint returns a 200 response with the following content:

{
  "nextSeasonId": "S3",
  "nextSeasonName": "2024-december",
  "nextSeasonStart": "2024-12-05T14:30:00+02:00",
  "gameSlug": "999-test-game",
  "percentages": {
      "1v1": 0.8,
      "1v1-no-items": 1.0,
      "3v3": 0
}

Behavior at season change

To prevent cross-contamination of ratings between seasons, data for each season is strictly separated. This is achieved through the following principles:

Only players for the current season are matched

Once a new season begins, the matchmaker ensures that only players who have queued for the current season are matched. This provides a consistent experience for players and prevents them from entering a new season with reset ratings without knowing, which can result in an unexpectedly different match experience otherwise.

At the start of a new season, we recommend removing any waiting players from the previous season. This is also a great opportunity to notify players in the game menu that a new season has started and share any related updates or news.

tip

The reponse from the getPlayersResponse includes the season info for each queued player, allowing easy access to the relevant players.

failMatch allows to only remove players for previous season matches

To maintain consistency and prevent players from being matched in a new season unknowingly, failMatch is designed to remove all players from a failed match without requeueing them if the match is from the previous season.

completeMatch actions update rating and ranking for the relevant season

Matches that start shortly before a season change may finish after the new season begins. If a completeMatch action is sent for such a match, the results will update ratings, rankings, and the leaderboard for the season in which the match was created.

This behavior offers flexibility in deciding when to finalize data for a season:

• Include all matches started during a season
  To count all matches that began during a season, send completeMatch actions for each match, even if they conclude after the season ends. Note that this allows the leaderboard to change after the season officially ends.

• Freeze data at the season’s end:
  If you want the season’s data to remain fixed from the time the season ends, simply don't send completeMatch actions for matches that finish after the season change.

The choice between these approaches depends on the dynamics you wish to create for your game.