Voidium Docs

🏅 Auto‑Rank

Auto‑Rank promotes players based on playtime and optional custom conditions (mob kills, biome visits, block mining/placing). Each rank can assign a prefix or suffix with full color code & RGB support.

To enable: set enableRanks: true in general.json. Then customize ranks in ranks.json.

Jump to

⚙️How it works
Playtime, conditions, promotions
📝Configuration
ranks.json fields
🎯Custom conditions
KILL, VISIT, BREAK, PLACE
💬Hover tooltips
Playtime info on hover

⚙️ How it works

  1. Playtime check — Voidium reads the player’s PLAY_TIME stat (ticks → hours) every checkIntervalMinutes (default 5).
  2. Custom conditions — If a rank definition includes custom conditions, the player must also meet those (tracked via ProgressTracker).
  3. Highest wins — The rank with the highest hours requirement that the player qualifies for is applied.
  4. Promotion message — When a player reaches a new rank for the first time, they see promotionMessage in chat.
  5. Display — The rank prefix/suffix appears in the TAB list (if Player List module is enabled) or in the chat display name.

📝 Configuration

File: config/voidium/ranks.json

Field Type Default Description
enableAutoRanks boolean true Master switch
checkIntervalMinutes int 5 How often to check playtime (min 1)
promotionMessage string &aCongratulations! You have earned the rank &b%rank%&a! Message on rank up. Placeholders: %rank%, {player}, {hours}
tooltipPlayed string §7Played: §f%hours%h Hover text showing played hours
tooltipRequired string §7Required: §f%hours%h Hover text showing required hours
ranks array (see below) List of rank definitions

Rank definition

Each entry in the ranks array:

{
  "type": "PREFIX",
  "value": "&6[Veteran] ",
  "hours": 100,
  "customConditions": []
}
Field Description
type "PREFIX" or "SUFFIX"
value The text shown (supports & color codes, &#RRGGBB hex)
hours Minimum playtime hours required
customConditions Optional array of extra requirements

Default ranks

Rank Type Hours Display
Member PREFIX 10 &7[Member]
Veteran PREFIX 100 &6[Veteran]
Star SUFFIX 500 ` &e★`

🎯 Custom conditions

Custom conditions let you require achievements beyond playtime. Each condition has a type and a count:

{
  "type": "PREFIX",
  "value": "&c[Hunter] ",
  "hours": 50,
  "customConditions": [
    { "type": "KILL", "count": 500 }
  ]
}

Condition types

Type Tracks Example
KILL Mob kills (any type) 500 kills → “Hunter”
VISIT Unique biome visits 10 biomes → “Explorer”
BREAK Blocks broken (any type) 1000 blocks → “Miner”
PLACE Blocks placed (any type) 500 blocks → “Builder”

Progress is tracked per-player in config/voidium/storage/player_progress.json and persists across restarts.

You can combine multiple conditions on a single rank:

{
  "type": "SUFFIX",
  "value": " &d♦",
  "hours": 200,
  "customConditions": [
    { "type": "KILL", "count": 1000 },
    { "type": "VISIT", "count": 15 }
  ]
}

The player must meet all conditions (AND logic).

💬 Hover tooltips

When a player’s rank prefix or suffix is displayed, hovering over it shows:

This works in chat and in the TAB player list.

Integration with Player List

When the Player List module is enabled (enablePlayerList: true in general.json), rank prefixes and suffixes are applied via scoreboard teams in TAB. The RankManager defers to PlayerListManager to avoid duplicate display.

When Player List is disabled, ranks are applied directly to the player’s display name in chat.