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

MIT License

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