TierSense

Automatic server-side PvP skill rating and tier tracking for Paper.

TierSense watches PvP fights, evaluates player performance, assigns an independent tier for each supported PvP mode, and displays ranked modes above the player's nametag.

No client-side mods required.

✨ Features

⚔️ Automatic PvP Rating

TierSense automatically observes PvP fights and rates players based on their performance.

Each fight is classified into a PvP mode using the player's equipment and combat context.

Supported modes:

• 💠 Crystal PvP
• 🧪 Netherite Pot PvP
• 🧪 Diamond Pot PvP
• 🪓 Axe PvP
• ⚔️ Sword PvP
• 🏹 UHC PvP

Each mode has its own independent rating.

For example, a player can be:

Crystal   → LT3
NethPot   → HT4
DiaPot    → LT4
Axe       → HT3
Sword     → LT2
UHC       → LT4

📊 Elo-Style Rating

TierSense uses an Elo-style rating system.

• Starting rating is configurable
• Stronger opponents are worth more rating
• K-factor starts at 32 and gradually decreases with experience
• Rating changes are capped at ±35 per rated match
• First 10 rated matches are provisional
• Provisional players appear as Unranked
• Promotions happen immediately
• Demotions require 3 consecutive rated losses below the tier threshold

This keeps tiers from changing dramatically because of one bad fight.

🏆 Tier Ladder

The default ladder contains 9 tiers:

LT5
HT4
LT4
HT3
LT3
HT2
LT2
HT1
LT1

Tier thresholds and colors are configurable in tiers.yml.

🛡️ Anti-Farming Protection

TierSense includes safeguards against artificially farming rating.

• Maximum 3 rated matches against the same opponent per 30 minutes
• Rematches within 20 seconds receive reduced rating impact
• Very short fights are ignored
• Fights with insufficient total damage are ignored
• Excessively distant interactions are ignored
• Matches have a maximum duration
• Invalid or incomplete fights do not affect ratings

👤 Floating Tier Nametag

Ranked modes can be displayed above a player's nametag using a native Minecraft TextDisplay.

Example:

💠 HT1  🧪 LT3  🪓 HT2
       PlayerName

The display:

• Follows the player
• Uses tier-specific colors
• Shows all ranked modes on one line
• Uses PvP-mode item icons
• Interpolates movement smoothly
• Hides while sneaking
• Hides until the player has a ranked tier
• Cleans itself up when players leave or change worlds
• Does not require a client-side mod

💾 Persistent Profiles

Player data is stored individually using their UUID.

plugins/TierSense/
├── config.yml
├── tiers.yml
├── messages.yml
└── playerdata/
    └── <uuid>.yml

Profiles contain:

• Ratings
• Current tiers
• Match statistics
• Combat statistics
• Tier history
• Ranking information

Player data is automatically saved periodically.

🔐 Premium & Offline Server Support

TierSense supports both online-mode and offline-mode servers.

In premium/online mode, player identity is associated with their Minecraft UUID.

Offline-mode support can be enabled through the plugin configuration.

TierSense does not require Microsoft passwords, authentication tokens, or any private account information.

🔧 Admin Overrides

Server administrators can manually assign a tier when necessary.

Manual overrides take priority over automatic ranking and will not be overwritten by the ranking system until the override is removed.

Example:

/tier set PlayerName crystal LT3

🧩 Developer API

TierSense provides a Bukkit ServicesManager API for other plugins.

Developers can access:

• Player ratings
• Player tiers
• PvP mode information

Included events:

PvpMatchStartEvent
PvpMatchEndEvent
PlayerTierChangeEvent

This makes TierSense suitable as a foundation for larger PvP servers, leaderboards, matchmaking systems, websites, and other ranking-related plugins.

---

Commands

Command	Description	Permission
/tier [player]	View a player's tier summary	tiersense.view
/tier stats <player> [mode]	View combat statistics	tiersense.stats
/tier history <player>	View recent tier changes	tiersense.stats
/tier set <player> <mode> <tier>	Set a manual tier override	tiersense.set
/tier reset <player> <mode>	Remove a tier override	tiersense.set
/tier evaluate <player>	Re-evaluate a player's rating and tier	tiersense.set
/tier reload	Reload configuration	tiersense.reload
/tier debug <player>	View internal combat state	tiersense.debug

Administrator Permission

tiersense.admin

tiersense.admin grants access to all TierSense administrative permissions.

---

Configuration

TierSense provides separate configuration files for different parts of the plugin.

config.yml

Controls:

• Account identification
• Ranking settings
• Combat detection
• Nametag display
• Icons
• PvP modes
• Allowed worlds
• Autosave
• Other plugin behavior

tiers.yml

Controls:

• Tier names
• Rating thresholds
• Tier colors

messages.yml

Controls player-facing messages and supports customizable color codes and placeholders.

playerdata/

Contains one profile per player UUID.

---

How Rating Works

TierSense does not attempt to claim that one statistic can perfectly measure mechanical PvP skill.

Instead, it combines server-observable information from fights and uses the result to maintain a rating.

Depending on the PvP mode, tracked information can include things such as:

• Damage dealt
• Damage received
• Hits
• Fight duration
• Distance
• Relevant item usage
• Mode-specific combat actions
• Wins
• Losses
• Match history

The exact information available depends on what Minecraft/Paper exposes for that mode.

The result is an automated statistical estimate of PvP performance, not a replacement for human tournament judging.

---

Match Detection

A combat session begins when players enter combat and ends when one of the following occurs:

• A player dies
• There has been no relevant interaction for 10 seconds
• The fight reaches the configured maximum duration
• The fight otherwise becomes invalid

By default, matches are ignored when they are:

• Too short
• Below the minimum total damage requirement
• Too far apart
• Otherwise invalid for ranking

These values can be configured.

---

PvP Mode Detection

TierSense determines the fight style using equipment and combat context.

Detection priority:

Crystal
↓
NethPot
↓
DiaPot
↓
Axe
↓
Sword
↓
UHC

Each mode has an independent rating.

Adding another PvP mode is designed to be straightforward for developers through the PvpMode system.

---

Requirements

• Minecraft Java Edition
• Paper 1.21.11
• Java 21

Client Mods

None required.

TierSense is a server-side plugin.

---

Compatibility

TierSense is designed for:

• Paper 1.21.11
• Java Edition servers
• Online-mode servers
• Offline-mode servers when enabled

Bedrock players connecting through Geyser may have reduced visual functionality depending on client/resource-pack support. The underlying server-side ranking system can still operate.

---

Performance

TierSense is designed around event-driven combat tracking rather than constantly calculating player statistics every tick.

It uses:

• Cached player profiles
• Periodic persistence
• Event-based combat tracking
• Controlled display entity management
• Configurable debug logging

The goal is to provide PvP analytics without unnecessarily adding server load.

---

For Developers

TierSense exposes a Bukkit service through:

TierSenseApi

This can be used by other plugins to query player ranking information.

Example use cases:

• PvP leaderboards
• Matchmaking
• Tournament systems
• Websites
• Discord integrations
• Scoreboards
• Custom matchmaking queues
• Rank-based rewards

Documentation:

docs/CONTEXT.md
docs/usage.md

---

Important Limitations

TierSense can only evaluate information available to the Minecraft server.

It cannot directly observe:

• Mouse movement
• Raw CPS
• Client-side aim
• Private client information
• Microsoft account credentials
• Information hidden from the server

Therefore, TierSense should be considered an automated PvP performance ranking system, rather than a perfect measurement of mechanical skill.

---

License

See the license included with the project.

Links

Source Code: Add your GitHub repository here.

Issues / Bug Reports: Add your GitHub Issues page here.

Documentation: Add your documentation link here.