Matchmaker

Skill rating and matchmaking algorithms for competitive games. Currently supports Glicko-2 and Elo.

Supported Rating Systems

Glicko-2

Glicko-2 is an improved version of the classic Elo rating system. While Elo just tracks a single number, Glicko-2 tracks three things:

• Rating: Your skill level (usually starts at 1500)
• Rating Deviation (RD): How certain we are about your rating. New players have high RD, which drops as they play more
• Volatility: How consistent you are. Erratic players have high volatility

Best for: Games with varying player activity, 1v1 competitive games, any scenario where you need to track rating uncertainty.

Elo

The classic rating system developed by Arpad Elo for chess. Simple and effective - just one number that goes up when you win and down when you lose. Rating differences directly translate to win probabilities using a logistic curve.

• Clean mathematical foundation (logistic function)
• No uncertainty tracking - just skill level
• Easy to understand and explain to players
• Battle-tested across decades of competitive chess

Best for: Simple 1v1 games, when you want something straightforward, or when rating updates need to be transparent to players.

Installation

Add this to your package's pubspec.yaml file:

dependencies:
  matchmaker: ^0.1.0

Usage

Glicko-2

Quick Start

import 'package:matchmaker/matchmaker.dart';

void main() {
  const glicko = Glicko2();

  // New players start with default ratings
  const ricardo = Glicko2Rating(
    rating: 1500,
    rd: 200,
    volatility: 0.06,
  );

  const lucas = Glicko2Rating(
    rating: 1400,
    rd: 30,
    volatility: 0.06,
  );

  // Ricardo plays against Lucas and wins
  final results = [MatchResult.win(lucas)];

  // Calculate Ricardo's new rating
  final newRating = glicko.calculateNewRating(ricardo, results);

  print('New rating: ${newRating.rating.toStringAsFixed(0)}');
  print('New RD: ${newRating.rd.toStringAsFixed(2)}');
}

Tournament with multiple matches

const glicko = Glicko2();

const ricardo = Glicko2Rating(rating: 1500, rd: 200, volatility: 0.06);
const lucas = Glicko2Rating(rating: 1400, rd: 150, volatility: 0.06);
const rodrigo = Glicko2Rating(rating: 1600, rd: 180, volatility: 0.06);

// Ricardo plays three games
final results = [
  MatchResult.win(lucas),
  MatchResult.loss(rodrigo),
  MatchResult.draw(rodrigo),
];

final newRating = glicko.calculateNewRating(ricardo, results);

Predict match outcomes

const strong = Glicko2Rating(rating: 1800, rd: 50, volatility: 0.06);
const weak = Glicko2Rating(rating: 1200, rd: 200, volatility: 0.06);

final winChance = glicko.predictOutcome(strong, weak);
print('Win probability: ${(winChance * 100).toStringAsFixed(1)}%');

Confidence intervals

const player = Glicko2Rating(rating: 1650, rd: 80, volatility: 0.06);
final interval = player.getConfidenceInterval();

print('95% confident true skill is between '
      '${interval.lower.toStringAsFixed(0)} and '
      '${interval.upper.toStringAsFixed(0)}');

Handle inactive players

When a player doesn't compete, their rating stays the same but uncertainty increases:

var player = const Glicko2Rating(rating: 1600, rd: 50, volatility: 0.06);

// No games this period
player = glicko.calculateNewRating(player, []);

print('Rating: ${player.rating}');   // Still 1600
print('RD: ${player.rd}');           // Increased

Configuration

Customize the Glicko-2 system if you want:

const glicko = Glicko2(
  volatilityConstraint: 0.5,  // How much volatility can change (0.3-1.2)
);

volatilityConstraint: Lower (0.3-0.6) for stable games, higher (0.8-1.2) for unpredictable ones. Default 0.5 works well for most cases.

Rating Periods

Glicko-2 works best when you batch games into rating periods instead of updating after every single game. Think of it like updating ratings once a week instead of after each match.

How many games per period? Aim for 10-15 games per player, minimum 5.

How long should a period be?

• Active games: 1 day to 1 week
• Normal activity: 1-2 weeks
• Slow games: 2 weeks to 1 month

Here's the basic flow:

// Collect all matches during the rating period
final playerMatches = <String, List<MatchResult>>{};

// ... games happen ...

// At the end of the period, update everyone at once
for (final playerId in playerMatches.keys) {
  final currentRating = getCurrentRating(playerId);
  final matches = playerMatches[playerId]!;
  
  final newRating = glicko.calculateNewRating(currentRating, matches);
  saveRating(playerId, newRating);
}

Elo

Quick Start

import 'package:matchmaker/matchmaker.dart';

void main() {
  const elo = Elo();

  // Players start with a rating (usually 1500)
  const ricardo = EloRating(rating: 1500);
  const lucas = EloRating(rating: 1400);

  // Ricardo beats Lucas
  final results = [MatchResult.win(lucas)];
  final newRating = elo.calculateNewRating(ricardo, results);

  print('Ricardo new rating: ${newRating.rating.toStringAsFixed(0)}');
  // Output: Ricardo new rating: 1521
}

Predict match outcomes

const elo = Elo();
const stronger = EloRating(rating: 1700);
const weaker = EloRating(rating: 1500);

final winChance = elo.predictOutcome(stronger, weaker);
print('Win probability: ${(winChance * 100).toStringAsFixed(1)}%');
// Output: Win probability: 76.0%

Series of games

const elo = Elo();
var player = const EloRating(rating: 1500);
const opponent = EloRating(rating: 1600);

// Player loses, then wins, then draws
player = elo.calculateNewRating(player, [MatchResult.loss(opponent)]);
player = elo.calculateNewRating(player, [MatchResult.win(opponent)]);
player = elo.calculateNewRating(player, [MatchResult.draw(opponent)]);

print('Final rating: ${player.rating.toStringAsFixed(0)}');

Multiple games at once

const elo = Elo();
const player = EloRating(rating: 1500);
const opponent = EloRating(rating: 1600);

// Process multiple games in one batch
final results = [
  MatchResult.win(opponent),
  MatchResult.loss(opponent),
  MatchResult.draw(opponent),
];

final newRating = elo.calculateNewRating(player, results);

Configuration

const elo = Elo(
  kFactor: 16,        // How fast ratings change (10-32)
  defaultRating: 1500, // Starting rating for new players
);

kFactor: Controls how much ratings change per game

• 32: Fast changes, good for newer players (USCF standard)
• 24: Medium speed
• 16: Slower changes, good for established players
• 10: Very stable, for high-level play (FIDE standard)

Lower K-factors make ratings more stable but slower to adjust. Higher values let ratings adapt quickly but can be more volatile.

License

MIT