ELO & Ranks

How ELO calculations function, details on the 34-tier rank progression tree, and rank customization guides.

How ELO Matchmaking Works

The ELO system measures a player's relative skill level. All players start at 1000 ELO. Following an eligible matchmaking duel, ratings are adjusted as follows:

Step-by-Step ELO Example Scenario

To see how ELO is calculated, let's look at a match between two players:

• WeThink: Overall ELO of 1200 (Gold V rank).
• ErRoR25: Overall ELO of 1000 (Silver V rank).

Step 1: Expected Score Calculation

First, the plugin calculates the Expected Score (win probability) for each player. Because WeThink has a higher rating, WeThink is expected to have a higher chance of winning:

• WeThink's Expected Score:

  Expected = 1 / (1 + 10^((1000 - 1200) / 400))
  Expected = 1 / (1 + 10^(-0.5))
  Expected = 1 / (1 + 0.316) ≈ 0.76 (76% chance of winning)

• ErRoR25's Expected Score:

  Expected = 1 / (1 + 10^((1200 - 1000) / 400))
  Expected = 1 / (1 + 10^(0.5))
  Expected = 1 / (1 + 3.162) ≈ 0.24 (24% chance of winning)

Step 2: Calculate Rating Adjustments (Win / Loss Scenarios)

Ratings are computed using the default parameters: base-gain: 25, base-loss: 20, min-gain: 1, max-gain: 40, min-loss: 1, and max-loss: 40 (verified against EloSettings.java).

Scenario A: WeThink Wins (The expected outcome)

• WeThink's Elo Gain:

  Gain = base-gain * 2.0 * (1.0 - Expected)
  Gain = 25 * 2.0 * (1.0 - 0.76) = 50 * 0.24 = 12.0
  Gain = clamp(min-gain, max-gain, round(12.0)) = +12 ELO

  WeThink's ELO increases from 1200 to 1212.

• ErRoR25's Elo Loss:

  Loss = base-loss * 2.0 * Expected
  Loss = 20 * 2.0 * 0.24 = 9.6
  Loss = Loss * 0.70x (Silver V loss multiplier) = 6.72
  Loss = clamp(min-loss, max-loss, round(6.72)) = -7 ELO

  ErRoR25's ELO decreases from 1000 to 993.

Scenario B: ErRoR25 Wins (The upset outcome)

• ErRoR25's Elo Gain:

  Gain = base-gain * 2.0 * (1.0 - Expected)
  Gain = 25 * 2.0 * (1.0 - 0.24) = 50 * 0.76 = 38.0
  Gain = clamp(min-gain, max-gain, round(38.0)) = +38 ELO

  ErRoR25's ELO increases from 1000 to 1038 (a much larger gain since this was an upset victory).

• WeThink's Elo Loss:

  Loss = base-loss * 2.0 * Expected
  Loss = 20 * 2.0 * 0.76 = 30.4
  Loss = Loss * 0.80x (Silver III loss multiplier) = 24.32
  Loss = clamp(min-loss, max-loss, round(24.32)) = -24 ELO

  WeThink's ELO decreases from 1200 to 1176.

ELO cannot drop below the configured min-elo (default 0). FFA matches and deaths do not affect ELO ratings.

How Min/Max Gain & Loss Work Together

The min-gain, max-gain, min-loss, and max-loss settings act as a safety range for ELO adjustments. They prevent extreme rating swings (such as losing hundreds of points in a single match) while ensuring there is always a meaningful rating change. For example, a win against a far stronger player is capped at max-gain (40 ELO) instead of awarding a massive rating boost, and a defeat by a far weaker player is capped at max-loss (40 ELO) to avoid excessive penalty. Conversely, the min-gain and min-loss floors guarantee that players always receive a token rating change (at least 1 ELO) even for completely expected matches.

Overall ELO vs. Per-Kit ELO

The plugin tracks two types of Elo metrics:

• Overall ELO: Used as the primary skill seed for matchmaking. The expected score and the resulting delta (gain/loss) are calculated using the overall Elo of the participants.
• Per-Kit ELO: Tracks a player's skill specific to each kit category. When a player wins or loses a match, their per-kit Elo is updated by the exact same delta computed from the overall Elo matchmaking formula.

Default Ranks Database

The 34 default ranks below ship in the bundled ranks.yml resource and are copied to plugins/ShyamDuels/ranks.yml on first start, where you can edit them:

Customizing Ranks

Define custom ranks inside ranks.yml under the elo.ranks section. The plugin orders ranks based on their minimum ELO thresholds:

yamlelo:
  enabled: true
  base-gain: 25
  base-loss: 20
  kill-gain: 5
  min-elo: 0

  ranks:
    iron:
      name: "Iron"
      colored: "&7[Iron]"
      min-elo: 0
      max-elo: 499
      loss-multiplier: 0.5
    gold:
      name: "Gold"
      colored: "&6[Gold]"
      min-elo: 500
      max-elo: 999
      loss-multiplier: 1.0
    diamond:
      name: "Diamond"
      colored: "&b[Diamond]"
      min-elo: 1000
      max-elo: 9999
      loss-multiplier: 1.5

The colored property supports Kyori MiniMessage components.

Tracked Player Statistics

The plugin tracks various player stats, accessible via /stats or PlaceholderAPI: