Set up your first MMR system

If you're here, you've most likely been onboarded by our team and ready to elevate your multiplayer's game with our skill rating system! Good to have you!

The goal of this guide: Use IVK Skill to calculate skill rating updates for your players after a match has concluded.

Prerequisites

  • A valid API key
  • At least one MMR model_id

If you haven't received an API key or model_id, please contact us.

The plan

Depending on your game or gamemode, the way you interact with IVK Skill API's might be a bit different.

In this guide, we'll be handling the most common scenario:

  1. The match has ended
  2. Your gameserver provides the match result to your game backend services (for persistence, etc)
  3. Your backend will sent part of this match result as well as some basic player information (current MMR, ...) to the IVK Skill API.
  4. In response, your backend receives the result of our MMR calculations, which you can store in your database

Other scenario's not covered by this guide, but certainly supported by IVK Skill:

  • Partial updates when a player leaves the match early
  • Immediate partial updates for Battle Royales
  • Precalculation of potential updates based on a limited set of possible outcomes (ex. tournament brackets) with the goal of showing win/lose rewards up front

Prepare the API request body

So the match has concluded, you've received the match results on your backend and now you want to calculate the MMR updates for the players of the match.

To do so, we'll be performing a POST call to the following endpoint: https://skill.ivk.dev/api/v2/{model_id}/match_result This endpoint requires a couple of things for it to work:

  1. A path parameter model_id
  2. A header x-ivk-apikey with your API key as the value
  3. A JSON request body which provides information about the match, teams and players.
{
  "match_id": "12904838",
  "player_sessions": [
    {
      "player_id": "player_1",
      "player_score": 9,
      "prior_games_played": 6,
      "prior_mmr": 0.5
    },
    {
      "player_id": "player_2",
      "player_score": 10,
      "prior_games_played": 10,
      "prior_mmr": 0.4
    }
  ],
  "teams": []
}

Let's talk through what we're seeing here: XXX

IVK SKill is completely stateless

Our API does not keep or consult any existing state (player MMR, etc). It operates exclusively on the data provided in the HTTP request body. Ofcourse, it is aware of the specific model configuration for your game or gamemode.

Send the match result and process the MMR updates

const match_result = {...} /// Omitted for brevity, see above example of the request body;
const model_id = "your_model_id";
const api_key = "your_api_key";

const response = await fetch({
  method: "POST",
  url: `https://skill.ivk.dev/api/v2/${model_id}/match_result`,
  data: JSON.stringify(match_result)
);

const mmr_result = await response.json();

This returns the following JSON result:

XXX

Extract the MMR updates from this result and update the player values

XXX