!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

1. Download the latest xrank-X.X.X.jar
2. Place it in your server's plugins/ folder
3. Restart or reload your server
4. Configure plugins/xrank/config.yml to your needs
5. 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!