XRank Logo

0 Why is this here

Just. For. Fun.

I actually planned a title plugin like this before, so now I completed it, XRank.

1 Features

1.1 Quad-Route Rendering System

XRank stands out with its comprehensive 4-route rendering approach, covering every aspect of player representation:

TAB List → Player#setPlayerListName(String)
- Smart protocol-length truncation (supports RGB color codes)
- Auto-detects TAB plugin and yields rendering to avoid conflicts
- Fallback to plain name when tab name exceeds length limits
Chat Format → AsyncPlayerChatEvent#setFormat(String)
- Customizable format with %rank%, %name%, %message% placeholders
- Preserves other plugins' chat modifications (non-invasive)
- Highest priority event handling
Name Tag (Above Head) → Scoreboard#Team with setPrefix/setSuffix + Team#setColor (reflection)
- Color inheritance from rank display
- Automatic team creation/per-player management
- Conflict resolution when team names are occupied
System Messages → Player#displayName(Component) (Adventure, 1.16.5+) or reflection on NMS EntityPlayer#displayName (1.8.x–1.15.x)
- Full Adventure API support for modern servers
- NMS reflection fallback for legacy versions
- Applies to death messages and most of the server's system-generated text

Why this matters: Most rank plugins only handle 2 routes (TAB + CHAT), with some advanced ones adding NAMETAG. XRank is one of the few plugins that completes all 4 routes, ensuring a consistent rank display experience everywhere the player's name appears.

BUT, some messages, such as the messages for /tp, may still use the raw player name instead of the version that is handled by XRank.

This is because the rank in system messages is based on displayName, and some vanilla commands use the raw one instead of displayName. This is basically unavoidable.

You can regard it as a passive design that facilitates debugging... it would be silly to have to useless rank when teleporting, but having a prefix in death messages is fine.

1.2 Multi-Storage Support

YAML - Simple file-based storage
SQLite - Lightweight database for small to medium servers (default)
MySQL - Enterprise-grade database for large servers
Auto-Migration - Seamlessly migrate between storage types without data loss

1.3 Flexible Rank Management

Multiple ranks per player
Configurable rank display names with color codes (&)
Default rank assignment for new players
Permission-based default rank bypass (xrank.ignore_default)
Batch operations for online/offline/all players

1.4 PlaceholderAPI Support (Optional)

%xrank_ranks% - Full rank display (with colors)
%xrank_ranks_raw% - Raw rank names (without formatting)
%xrank_has_rank% - Returns true if player has any rank
%xrank_prefix% - Rank prefix from format
%xrank_suffix% - Rank suffix from format

1.5 Developer API

Async CompletableFuture based API
Per-UUID locking for thread-safe operations
RankChangeEvent for listening to rank updates
API toggle via allow_to_use_api config option

1.6 Multi-Version & Platform Support

Supports Minecraft 1.8.9 through 1.21+
Folia compatibility with RegionScheduler
Paper/Purpur optimized
Spigot/Bukkit legacy support
TAB plugin auto-detection (yields TabList rendering)

Known Limitation: On Folia servers, nametag ranks are not available due to the Bukkit scoreboard API being disabled. This is a platform limitation.

1.7 Internationalization

Multi-language message support via lang config
No hardcoded player messages
Auto-fix configuration with missing key completion

1.8 Thread-Safe Operations

Per-UUID locks ensure atomic read-modify-write operations
Async database operations don't block the main thread
ConcurrentHashMap for player data caching

2 Commands

Command	Permission	Description
`/xrank`	-	Shows plugin version and status
`/xrank give <player\|-all\|-online\|-offline> <rank>`	`xrank.give`	Give a rank to the player(s)
`/xrank remove <player\|-all\|-online\|-offline> <rank>`	`xrank.remove`	Remove a specific rank from player(s)
`/xrank remove <player\|-all\|-online\|-offline>`	`xrank.remove`	Remove ALL ranks (requires confirmation)
`/xrank list [player\|-all\|-online\|-offline]`	`xrank.list`	List ranks of player(s)
`/xrank reload`	`xrank.admin`	Reload configuration and apply changes

/xrk = /xrank

Batch Targets:

-all - All players (online + offline)
-online - All online players
-offline - All offline players

3 Permission Nodes

Permission	Description
`xrank.give`	Allows giving ranks to players
`xrank.remove`	Allows removing ranks from players
`xrank.list`	Allows viewing ranks of players
`xrank.admin`	Full administrative access (includes reload)
`xrank.ignore_default`	Player will not receive default rank

4 Configuration

4.1 Basic Settings

# Language (messages section key)
lang: "en"

# Debug mode (logs additional information)
debug: false

# Show logo on startup
show_logo: true

# Default rank for new players (empty = none)
default-rank: "default"

# Enable display name modification
display-name-enabled: true

# API access toggle
allow_to_use_api: true

# Remove confirmation timeout (seconds)
remove-confirm-timeout: 30

4.2 Storage Configuration

storage:
  # Options: yaml, sqlite, mysql
  type: "sqlite"
  
  mysql:
    host: "localhost"
    port: 3306
    database: "xrank"
    username: "root"
    password: "password"

4.3 Format Configuration

# Tab list / display format (supports %rank%, %name%)
format: "%rank%%name%"

# Chat format (supports %rank%, %name%, %message%)
chat-format: "%rank%%name%&f: %message%"

4.4 Rank Definitions

ranks:
  owner: "&4[&cOwner&4] "
  admin: "&c[Admin] "
  vip: "&6[VIP] "
  default: "&7[Player] "

4.5 Message Customization

Messages are organized by language key. Example for en:

messages:
  en:
    no-permission: "&cYou don't have permission to do this."
    player-not-found: "&cPlayer {player} not found."
    rank-given: "&aSuccessfully gave {rank} to {players}"
    rank-removed: "&aSuccessfully removed {rank} from {players}"
    rank-not-found: "&cRank {rank} not found for {players}"
    confirm-warning: "&6This will remove ALL ranks from {player}"
    confirm-again: "&6Type /xrank remove {player} again within {seconds}s to confirm"
    confirm-done: "&aRemoved all ranks from {players}"
    reload-done: "&aConfiguration reloaded successfully!"
    list-header: "&6--- Rank List ---"
    list-format: "&f{player}&7: {ranks}"
    list-no-ranks: "&f{player}&7: No ranks"
    list-footer: "&6--- End of List ---"
    usage-give: "&cUsage: /xrank give <player|-all|-online|-offline> <rank>"
    usage-remove: "&cUsage: /xrank remove <player|-all|-online|-offline> [rank]"
    no-ranks-record: "&cNo rank records found."

5 Developer API

5.1 Getting Player Ranks

Main.getInstance().getPlayerRanks(uuid).thenAccept(ranks -> {
    // ranks is a List<String>
});

5.2 Setting Player Ranks

Main.getInstance().setPlayerRanks(uuid, "PlayerName", Arrays.asList("admin", "vip"))
    .thenAccept(success -> {
        // success is Boolean
    });

5.3 Adding a Rank

Main.getInstance().addRank(uuid, "PlayerName", "vip")
    .thenAccept(changed -> {
        // changed is Boolean
    });

5.4 Removing a Rank

Main.getInstance().removeRank(uuid, "vip")
    .thenAccept(changed -> {
        // changed is Boolean
    });

5.5 RankChangeEvent

@EventHandler
public void onRankChange(RankChangeEvent event) {
    UUID uuid = event.getPlayerId();
    String name = event.getPlayerName();
    List<String> oldRanks = event.getOldRanks();
    List<String> newRanks = event.getNewRanks();
    // Handle rank change
}

6 Installation

Download the latest xrank-X.X.X.jar
Place it in your server's plugins/ folder
Restart or reload your server
Configure plugins/xrank/config.yml to your needs
Reload with /xrank reload

7 Requirements

Server: All Bukkit Based Server (1.8.9+)
Optional: PlaceholderAPI for placeholder support

9 Feedback

Just e-mail me with windblood@foxmail.com, thanks!

XRank

Compatibility

Minecraft: Java Edition

Platforms

Links

Tags

Creators

Details