Ranking System

Overview

BeeHex uses an MMR (Match Making Rating) system to track player skill and create fair competitive matches. Your MMR determines your rank tier and position on the global leaderboard.

MMR System

What is MMR?

MMR (Match Making Rating) is a numerical skill rating that:

Starts at 500 for all new players
Increases when you win ranked games
Decreases when you lose ranked games
Determines matchmaking and rank tier

MMR is only affected by ranked games. Casual (Normal) and offline games do not change your rating.

How MMR Changes

After each ranked game, your MMR is adjusted based on:

Your current MMR vs. opponent’s MMR
Game outcome (win/loss)
Rating difference between players

The system calculates separate MMR changes for each player:

// Example from game history
game.EloChangeFirstPlayer  // +24 MMR (winner)
game.EloChangeSecondPlayer // -18 MMR (loser)

Beating higher-rated opponents gives more MMR, while losing to lower-rated players costs more points.

Rank Tiers

BeeHex features a 9-tier ranking system inspired by bee hierarchy:

Rank Structure

Faux-bourdon I

0-199 MMRBeginner tier—learning the basics

Faux-bourdon II

200-399 MMRNovice players developing strategy

Faux-bourdon III

400-599 MMRIntermediate beginners

Ouvrière I

600-799 MMRWorker tier—competent players

Ouvrière II

800-999 MMRSkilled workers

Ouvrière III

1000-1199 MMRAdvanced workers

Reine I

1200-1399 MMRQueen tier—expert players

Reine II

1400-1599 MMRElite queens

Reine III

1600+ MMRMaster tier—top players

Rank Calculation

The system maps your MMR to rank tiers using this logic:

function mmr_to_rank(mmr) {
  if (mmr < 200) return 0   // Faux-bourdon I
  if (mmr < 400) return 1   // Faux-bourdon II
  if (mmr < 600) return 2   // Faux-bourdon III
  if (mmr < 800) return 3   // Ouvrière I
  if (mmr < 1000) return 4  // Ouvrière II
  if (mmr < 1200) return 5  // Ouvrière III
  if (mmr < 1400) return 6  // Reine I
  if (mmr < 1600) return 7  // Reine II
  return 8                  // Reine III
}

Your rank badge updates automatically as your MMR changes. Check the leaderboard to see your current rank icon.

Leaderboard

The global leaderboard displays the top players across all BeeHex users.

Accessing the Leaderboard

Visit /rank or click “Classement” in the bottom navigation bar to view:

Position: Your global rank number
Username: Player display name
MMR: Current match making rating
Rank Badge: Visual tier indicator

Leaderboard Features

Browse Rankings

The leaderboard displays 5 players per page, sorted by MMR (highest first).

Navigate Pages

Use the chevron buttons to browse:

Left arrow: Previous 5 players
Right arrow: Next 5 players

The bottom shows: "Showing 1 to 5 of [total] players"

View Rank Icons

Each player’s row displays their rank badge icon, making it easy to identify skill tiers at a glance.

The leaderboard fetches live data from the server, showing up-to-date rankings. It refreshes when you navigate between pages.

Pagination System

The leaderboard uses a pagination system:

// Fetch 5 users starting from position 'first'
GET /get_all_users?first=0&limit=5

// Response includes:
{
  rows: [/* 5 user objects */],
  total: 1247  // Total registered players
}

Ranked vs. Casual Games

Ranked Games

Ranked games are competitive and affect your MMR:

Must be played online (not offline)
Cannot be played in private rooms
Use matchmaking to find fair opponents
Results are recorded on leaderboard

To play ranked:

Go to /game_mode
Select “Classé” as game type (when implemented)
Configure board size and time limit
Click “Jouer” to queue

Currently, the ranked option is available in the codebase but may need to be enabled in the UI. Check the game mode page for the “Classé” radio button option.

Casual Games

Casual games (“Normal” mode) allow you to:

Play online without MMR changes
Practice strategies risk-free
Try different board sizes
Play with friends in private rooms

Use casual games to learn new strategies before taking them into ranked play!

Game History Tracking

Your game history page (/game_mode sidebar) displays recent match results:

Recent Games Display

// Each game shows:
{
  gameId: "abc123",
  opponentUsername: "Player2",
  mmrChange: +24,           // Your MMR change
  mmrAfterGame: 524,        // Your MMR after this game
  gameDate: "2026-03-07",
  moves: "0 6 12 18..."     // Full move sequence
}

Victory/Defeat Indicators

The history shows:

Green “Victoire”: Games you won
Red “Défaite”: Games you lost
MMR change: Displayed with +/- prefix
Opponent name: Who you played against

Current MMR

Your current MMR is displayed at the top of the game history sidebar

Last 5 Games

See your 5 most recent matches with outcomes and MMR changes

Matchmaking

How Matchmaking Works

When you search for a ranked game:

Game search packet sent with your preferences:

{
  type: GAME_SEARCH,
  game_parameters: {
    ranked: true,
    board_size: 7,
    time_limit: 0
  }
}

Server searches for opponents within your MMR range
Game found callback triggered when suitable opponent is found
Both players redirected to game URL

MMR-Based Pairing

The matchmaking system considers:

Your MMR and opponent’s MMR
ELO range for fair matches
Queue time (range expands if waiting long)
Game parameters (board size, time limit)

The game search callback includes elo_range: [number, number] showing the current MMR range being searched.

Rank Progression Tips

Start with Smaller Boards

5×5 and 7×7 boards are great for learning patterns and building MMR steadily.

Review Your Games

Use the game review mode to analyze your mistakes and discover better moves.

Study Opponent Strategies

Watch how higher-ranked players approach the game in your match history.

Play Consistently

Regular play helps you internalize patterns and improve decision-making.

Rank Icons

Each rank tier has a unique visual badge displayed on:

Leaderboard (next to your name)
Profile page (your account overview)
Game history (past opponent ranks)

The icons use SVG graphics located in /assets/ranked_icons/ and are mapped to MMR ranges automatically.

Visit the /rank page to see all 9 rank badges with their names and MMR requirements in the visual gallery.

Rank Statistics

The ranking page displays:

Your current position in global rankings
Total player count across all BeeHex users
MMR distribution visible through browsing the leaderboard
All rank tiers with visual icons and MMR thresholds

Next Steps

Start Ranked Play

Begin your climb to Reine III

Private Rooms

Practice with friends in custom games

Get Started

Game Features

User Guide

Documentation Index

​Overview

​MMR System

​What is MMR?

​How MMR Changes

​Rank Tiers

​Rank Structure

Faux-bourdon I

Faux-bourdon II

Faux-bourdon III

Ouvrière I

Ouvrière II

Ouvrière III

Reine I

Reine II

Reine III

​Rank Calculation

​Leaderboard

​Accessing the Leaderboard

​Leaderboard Features

​Pagination System

​Ranked vs. Casual Games

​Ranked Games

​Casual Games

​Game History Tracking

​Recent Games Display

​Victory/Defeat Indicators

Current MMR

Last 5 Games

​Matchmaking

​How Matchmaking Works

​MMR-Based Pairing

​Rank Progression Tips

​Rank Icons

​Rank Statistics

​Next Steps

Start Ranked Play

Private Rooms

Build docs developers (and LLMs) love

Overview

MMR System

What is MMR?

How MMR Changes

Rank Tiers

Rank Structure

Rank Calculation

Leaderboard

Accessing the Leaderboard

Leaderboard Features

Pagination System

Ranked vs. Casual Games

Ranked Games

Casual Games

Game History Tracking

Recent Games Display

Victory/Defeat Indicators

Matchmaking

How Matchmaking Works

MMR-Based Pairing

Rank Progression Tips

Rank Icons

Rank Statistics

Next Steps