leaderboards

Leaderboards in DialogMaster are created using standard menu configurations, typically notice or multiAction types, combined with PlaceholderAPI and ajLeaderboards placeholders.

DialogMaster does not calculate, fetch, or store leaderboard data natively. Instead, it delegates all leaderboard indexing, sorting, and caching to the dedicated ajLeaderboards plugin, resulting in peak performance, zero TPS overhead, and infinite flexibility.

---

How Leaderboards Work

Track statistics with ajLeaderboards

ajLeaderboards handles the background tracking of statistics, such as money, kills, blocks mined, and playtime.

Define a DialogMaster menu

Define a DialogMaster menu, for example, menus/lb-money.yml, using the notice or multiAction type.

Display ranked entries

In the menu body lines, display ranked entries using ajLeaderboards PAPI placeholders, such as %ajlb_lb_<stat>_<rank>_alltime_name%.

Display player skins

To display player skins, prefix names with the native <head:...> tag.

Link to the leaderboard menu

Link players to the leaderboard menu from other menus, such as the main hub menu, using the standard open-menu action.

Dynamic Skin Head Support

DialogMaster supports client-rendered player head skins using the <head:PlayerName> or <head:%placeholder%> tag. Since ajLeaderboards exposes the name of the player at each rank, you can natively display their skin head:

- type: plain-message
  content: "<gold>#1 <reset><head:%ajlb_lb_vault_eco_balance_1_alltime_name%> <white>%ajlb_lb_vault_eco_balance_1_alltime_name% <gray>, <gold>%ajlb_lb_vault_eco_balance_1_alltime_value%"

The Minecraft client fetches and renders these skins automatically, no resource packs required!

Example Menu Configurations

Economy Leaderboard (menus/lb-money.yml)

Displays the richest players on the server using Vault/ajLeaderboards:

lb-money:
  title: "<gold><bold>Top Richest"
  type: notice
  body:
    - type: plain-message
      content: "<dark_gray>──────────────────────"
      width: 300
    - type: plain-message
      content: "<gold>#1 <reset><head:%ajlb_lb_vault_eco_balance_1_alltime_name%> <white>%ajlb_lb_vault_eco_balance_1_alltime_name% <gray>, <gold>%ajlb_lb_vault_eco_balance_1_alltime_value%"
      width: 300
    - type: plain-message
      content: "<gold>#2 <reset><head:%ajlb_lb_vault_eco_balance_2_alltime_name%> <white>%ajlb_lb_vault_eco_balance_2_alltime_name% <gray>, <gold>%ajlb_lb_vault_eco_balance_2_alltime_value%"
      width: 300
    - type: plain-message
      content: "<gold>#3 <reset><head:%ajlb_lb_vault_eco_balance_3_alltime_name%> <white>%ajlb_lb_vault_eco_balance_3_alltime_name% <gray>, <gold>%ajlb_lb_vault_eco_balance_3_alltime_value%"
      width: 300
    - type: plain-message
      content: "<gold>#4 <reset><head:%ajlb_lb_vault_eco_balance_4_alltime_name%> <white>%ajlb_lb_vault_eco_balance_4_alltime_name% <gray>, <gold>%ajlb_lb_vault_eco_balance_4_alltime_value%"
      width: 300
    - type: plain-message
      content: "<gold>#5 <reset><head:%ajlb_lb_vault_eco_balance_5_alltime_name%> <white>%ajlb_lb_vault_eco_balance_5_alltime_name% <gray>, <gold>%ajlb_lb_vault_eco_balance_5_alltime_value%"
      width: 300
    - type: plain-message
      content: "<gold>#6 <reset><head:%ajlb_lb_vault_eco_balance_6_alltime_name%> <white>%ajlb_lb_vault_eco_balance_6_alltime_name% <gray>, <gold>%ajlb_lb_vault_eco_balance_6_alltime_value%"
      width: 300
    - type: plain-message
      content: "<gold>#7 <reset><head:%ajlb_lb_vault_eco_balance_7_alltime_name%> <white>%ajlb_lb_vault_eco_balance_7_alltime_name% <gray>, <gold>%ajlb_lb_vault_eco_balance_7_alltime_value%"
      width: 300
    - type: plain-message
      content: "<gold>#8 <reset><head:%ajlb_lb_vault_eco_balance_8_alltime_name%> <white>%ajlb_lb_vault_eco_balance_8_alltime_name% <gray>, <gold>%ajlb_lb_vault_eco_balance_8_alltime_value%"
      width: 300
    - type: plain-message
      content: "<gold>#9 <reset><head:%ajlb_lb_vault_eco_balance_9_alltime_name%> <white>%ajlb_lb_vault_eco_balance_9_alltime_name% <gray>, <gold>%ajlb_lb_vault_eco_balance_9_alltime_value%"
      width: 300
    - type: plain-message
      content: "<gold>#10 <reset><head:%ajlb_lb_vault_eco_balance_10_alltime_name%> <white>%ajlb_lb_vault_eco_balance_10_alltime_name% <gray>, <gold>%ajlb_lb_vault_eco_balance_10_alltime_value%"
      width: 300
    - type: plain-message
      content: "<dark_gray>──────────────────────"
      width: 300
    - type: plain-message
      content: "<gray>Your rank: <yellow>#%ajlb_rank_vault_eco_balance_alltime%"
      width: 300
  ok-button:
    label: "<item:oak_door> <gray>Back"
    width: 100
    action: back
    action-key: "dm:back"

PvP Killers Leaderboard (menus/lb-kills.yml)

Displays the players with the most kills:

lb-kills:
  title: "<red><bold>Top Killers"
  type: notice
  body:
    - type: plain-message
      content: "<dark_gray>──────────────────────"
      width: 300
    - type: plain-message
      content: "<red>#1 <reset><head:%ajlb_lb_statistic_player_kills_1_alltime_name%> <white>%ajlb_lb_statistic_player_kills_1_alltime_name% <gray>, <red>%ajlb_lb_statistic_player_kills_1_alltime_value% kills"
      width: 300
    # Add rankings 2 to 10 using the same pattern...
    - type: plain-message
      content: "<gray>Your rank: <yellow>#%ajlb_rank_statistic_player_kills_alltime%"
      width: 300
  ok-button:
    label: "<item:oak_door> <gray>Back"
    width: 100
    action: back
    action-key: "dm:back"

Opening Leaderboards from Other Menus

Because leaderboards are standard menus, they are opened using the normal open-menu action with the target menu ID as the target parameter.

Here is an example setup inside a central leaderboard-hub.yml:

leaderboard-hub:
  title: "<gold><bold>Leaderboards"
  type: multiAction
  columns: 2
  command: "/leaderboards"
  body:
    - type: plain-message
      content: "<gray>Choose a leaderboard below."
  buttons:
    - label: "<item:gold_ingot> <gold>Money"
      tooltip: "<gray>Top richest players"
      width: 150
      action: open-menu
      target: lb-money
      action-key: "dm:leaderboard_open"

    - label: "<item:iron_sword> <red>Kills"
      tooltip: "<gray>Top PvP killers"
      width: 150
      action: open-menu
      target: lb-kills
      action-key: "dm:leaderboard_open"

ajLeaderboards Placeholder Reference

Metric	Name Placeholder	Value Placeholder	Player's Own Rank
Vault Economy	%ajlb_lb_vault_eco_balance_<rank>_alltime_name%	%ajlb_lb_vault_eco_balance_<rank>_alltime_value%	%ajlb_rank_vault_eco_balance_alltime%
Player Kills	%ajlb_lb_statistic_player_kills_<rank>_alltime_name%	%ajlb_lb_statistic_player_kills_<rank>_alltime_value%	%ajlb_rank_statistic_player_kills_alltime%
Custom Stats	%ajlb_top_<stat>_<rank>_name%	%ajlb_top_<stat>_<rank>_value%	%ajlb_top_<stat>_rank_%player_name%%