Logo
EloRanks
PluginMIT

EloRanks

A competitive 1v1 Elo-based ranking system for Minecraft 1.21 servers with matchmaking, auto-arena loading, and dynamic K-factor.

85
Downloads
1
Followers
1 months ago
Updated
📦
4
Versions
paper
Download Latestvv2.1.0View on Modrinth

📖About EloRanks

Please report issues here: Bugs and feature requests

EloRanks

A competitive 1v1 Elo-based ranking system for Minecraft 1.21 servers with matchmaking, auto-arena loading, and dynamic K-factor.

Features

  • Elo Rating System: Dynamic K-factor based on games played and Elo rating
  • Placement Matches: 5 placement matches for new players with bonus Elo for beating higher-rated opponents
  • Matchmaking: Queue-based matchmaking with expanding Elo range over time
  • Auto-Arena Loading: FAWE-based arena system with automatic loading/unloading
  • 1v1 Duels: UHC-style kits with custom countdown timers
  • Surrender: Available after 30 seconds - instant loss (full Elo penalty)
  • Scoreboard & Bossbar: Real-time rank, Elo, and opponent health display
  • Ranked Nametags: Color-coded rank prefixes on nametags (#1-50)
  • Detailed Config: Highly customizable with extensive options
  • Auto Update Checker: Notifies server owners when a new version is available on Modrinth

Commands

Player Commands

Command Aliases Description
/er elo, elostats, erstats View your Elo stats and rank
/er <player> View another player's stats
/er top View top players
/duel <player> Challenge a player to duel
/duel accept <player> Accept a duel request
/duel decline <player> Decline a duel request
/duel match queue, mm Enter matchmaking queue
/duel cancel stop Cancel matchmaking
/surrender forfeit, sq Surrender from active duel (30s min)
/leaderboard lb View global Elo leaderboard

Admin Commands (/eradmin)

Command Aliases Description
makeduel <p1> <p2> [force] startduel Create duel (force=true for instant)
addarena createarena Add new arena instance
reload rl Reload configuration
resetall wipedata Reset all player data
resetplayer <p> resetp Reset specific player's stats
setelo <p> <elo> setrating Set player's Elo
adde <p> <amt> addrating Add Elo to player
arenainfo arenastatus Show arena information
forcereset <id> cleararena Force reset specific arena
endduel <p> cancelduel End a player's active duel
tparena [p] [id] arenatp Teleport to arena
getpos <id> arenapos Get arena coordinates
heal <p> Heal a player
feed <p> Feed a player
stats plstats Show plugin statistics
debug diag Show debug information

Permission: er.admin (defaults to OP)

Permissions

Permission Description
er.duel Allow dueling other players
er.duel.request Allow sending duel requests
er.duel.accept Allow accepting duel requests
er.duel.matchmaking Allow using matchmaking queue
er.duel.surrender Allow surrendering from duels
er.stats.view Allow viewing own stats
er.stats.view.others Allow viewing other players' stats
er.leaderboard Allow viewing the leaderboard
er.admin Admin access

Configuration

All configuration is stored in config.yml (generated on first run).

Elo Settings

elo:
  starting: 1000              # Starting Elo for new players
  min: 0                      # Minimum Elo
  max: 10000                  # Maximum Elo
  k-factor:
    win: 32                   # Base K-factor for wins
    draw: 16                  # Base K-factor for draws
    dynamic:
      enabled: true           # Enable dynamic K-factor
      by-games:
        enabled: true
        threshold: 20         # Games before reducing K
        new-player-k: 48      # K-factor for new players (first games)
      by-elo:
        enabled: true
        threshold-1: 1500     # First Elo threshold
        threshold-2: 2000    # Second Elo threshold
        k-at-1500: 24        # K at first threshold
        k-at-2000: 16        # K at second threshold
  placement:
    enabled: true
    min-players: 5            # Players needed for placement system
    match-count: 5            # Placement matches
    k-factor-games: 5         # K-factor for placement games
    bonus-beating-higher: true # Bonus Elo for beating higher-rated players

Duel Settings

duel:
  cooldown: 60                # Seconds between duels
  request-timeout: 30        # Request expiration (seconds)
  arena-world: "duel_arena"  # World for arenas
  allow-spectators: true
  spectator-permission: "er.spectate"

Surrender Settings

surrender:
  enabled: true
  min-duel-time-seconds: 30  # Must wait 30 seconds before surrendering
  instant-loss: true        # Full Elo penalty (not halved)

Matchmaking Settings

matchmaking:
  enabled: true
  initial-elo-range: 50      # Starting Elo range
  range-increase-per-second: 10  # Range increase per second
  max-elo-range: 500        # Maximum range
  bidirectional-check: true # Both players must be in range
  check-interval-seconds: 1

Countdown Settings

countdown:
  teleport-seconds: 5        # Teleport countdown duration
  duel-start-seconds: 20    # Duel start countdown duration
  show-title: true          # Show title
  show-subtitle: true       # Show subtitle
  show-chat-messages: true  # Show chat messages
  colors:
    seconds-20-to-6: "BLUE"
    second-5: "DARK_RED"
    second-4: "RED"
    second-3: "GOLD"
    second-2: "YELLOW"
    second-1: "GREEN"

Arena Settings

arena:
  initial-count: 10          # Initial arena count
  spacing: 100               # Distance between arenas
  schematic: "cloudy.schematic"
  auto-expand: true          # Auto-add arenas when needed
  expand-count: 5            # Arenas to add when expanding
  respawn-delay: 3           # Respawn delay (seconds)
  load-timeout: 10           # Schematic load timeout

Kit Settings

kit:
  enabled: true
  sword: "DIAMOND_SWORD"
  bow: "BOW"
  arrows: 64
  helmet: "DIAMOND_HELMET"
  chestplate: "DIAMOND_CHESTPLATE"
  leggings: "DIAMOND_LEGGINGS"
  boots: "DIAMOND_BOOTS"
  offhand: "SHIELD"
  food: "GOLDEN_APPLE:10"
  blocks: "COBWEB:16,OAK_PLANKS:64"
  buckets: "WATER_BUCKET,LAVA_BUCKET"

Potion Effects

effects:
  speed: true
  speed-level: 2
  speed-duration: 180  # 3 minutes in seconds
  strength: true
  strength-level: 2
  strength-duration: 180

World & Gameplay

world:
  void-world: true           # Arena is void world
  spawn-protection: false
  pvp-enabled: true

gameplay:
  fall-damage: false
  fire-damage: false
  hunger-depletion: false
  keep-inventory: true
  natural-regeneration: false
  potion-effects-disabled: true

Scoreboard & Bossbar

scoreboard:
  enabled: true
  show-title: true
  title-animation: true
  show-rank: true
  show-elo: true
  show-world: true
  show-opponent-in-duel: true
  update-interval: 2  # seconds

bossbar:
  enabled: true
  show-opponent-health: true
  health-update-interval: 5

Chat Messages

chat:
  duel-request: true
  duel-start: true
  duel-end: true
  rank-up: true
  matchmaking-search: true
  pre-duel-instructions: true

Debug Settings

debug-mode: false
debug:
  show-elo-calculations: false
  show-matchmaking: false
  show-countdown: false

Requirements

  • Minecraft Paper 1.21+
  • FAWE (FastAsyncWorldEdit) for arena system
  • WorldGuard (recommended for arena protection)

Installation

  1. Install FastAsyncWorldEdit on your server
  2. Place EloRanks-2.1.0.jar in your plugins folder
  3. Restart or reload the server
  4. Configure config.yml as needed
  5. Add your arena schematic to plugins/EloRanks/arenas/

Arena Setup

  1. Build your arena in Minecraft using WorldEdit
  2. Place RED_WOOL where you want player 1 to spawn
  3. Place BLUE_WOOL where you want player 2 to spawn
  4. Export the arena as a .schematic file (using FAWE: /schem save name)
  5. Name it cloudy.schematic (or match your config)
  6. Place the schematic in plugins/EloRanks/arenas/

How It Works

Elo Calculation

  • K-factor starts at 48 for new players (first 5 placement games)
  • K-factor reduces as players gain games and Elo
  • Higher-rated players have less to gain, more to lose
  • Bonus Elo for beating higher-rated players during placement

Matchmaking

  • Players join queue with /duel match
  • Elo range starts at 50 and increases by 10 per second
  • Maximum range is 500 Elo
  • Both players must be in each other's range to match

Duel Flow

  1. Player A challenges Player B (or both use matchmaking)
  2. Player B accepts the challenge (or auto-matched)
  3. Both players see 5-second teleport countdown
  4. 20-second countdown with color progression before fight:
    • Seconds 20-6: Blue
    • Second 5: Dark Red
    • Second 4: Red
    • Second 3: Orange
    • Second 2: Yellow
    • Second 1: Green
    • Second 0: GO!
  5. Fight until one player dies or surrenders (30s minimum)
  6. Winner gains Elo, loser loses Elo

Surrender

  • Available after 30 seconds of duel start
  • Counts as instant loss - full Elo penalty applied
  • Opponent receives full Elo reward (no halving)

Building

# Using the build script
cd EloRanks
mvn clean package

The built JAR will be in target/EloRanks-{version}.jar

License

EloRanks © 2026 by i_c0de is licensed under CC BY-ND 4.0

Changelog

v2.1.0

  • Added automatic Modrinth update checker - notifies server owners when a new version is available

v2.0.1

  • Minor bug fixes and improvements

v2.0.0

  • Initial release with full Elo ranking system
  • Matchmaking queue
  • Auto-arena loading with FAWE
  • 1v1 duels with UHC-style kits
  • Dynamic K-factor based on games played and Elo rating
  • Placement matches for new players
  • Surrender feature
  • Scoreboard and bossbar display

bStats
bStats