LeaderHeads

You can purchase the plugin here.

On this page:

Introduction
Setting up a placeholder
Setting up signs
Setting up armorstands
Setting up Citizens
Setting up holograms
PlaceholderAPI and MVdWPlaceholderAPI placeholders
Configuring a leaderboard
Commands and permissions
FAQ

Introduction

LeaderHeads is a Spigot plugin that allows you to create per-player leaderboards that can be indexed daily, weekly, monthly, yearly and alltime. It does by integrating into PlaceholderAPI and MVdWPlaceholderAPI. This means that if a plugin offers placeholders to display its player statistics, LeaderHeads is able to create a leaderboard based on it. LeaderHeads offers various ways to display these leaderboards by using skulls, signs, armorstands, NPC’s, holograms and placeholders.

Setting up a placeholder

Choosing the placeholder

The most important part of setting up the plugin is choosing a placeholder. LeaderHeads currently works with per-player numerical placeholders. LeaderHeads will integrate into PlaceholderAPI or MVdWPlaceholderAPI to fetch the value of these placeholders and then keeps its own copy to create a leaderboard based on it.

What is a ‘per-player numerical placeholder’?
Think of any placeholder that shows your own score as a number.
For example, using the PlaceholderAPI Vault expansion, %vault_eco_balance% might show 165485, which is your personal balance.
Another example, using the PlaceholderAPI Statistic expansion, %statistic_player_kills% might show 15, which is the number of player kills you have.

How does this work? LeaderHeads will save a copy of this personal placeholder for every player on the server and use that data to create a leaderboard.

Based on which plugin you want to integrate with, you can follow one of the following instructions. You don’t need both plugins, but they can be used at the same time if you want to. We personally recommend using PlaceholderAPI, since it is free and has a large community.

Using a PlaceholderAPI placeholder

Install PlaceholderAPI.
A general list of placeholders can be found here. Some plugins that work with PlaceholderAPI are not in the list, but have this information on their resource page so make sure to check there as well.
It is very important that if your placeholder requires an expansion, you have installed this expansion through the PlaceholderAPI Cloud. Make sure to use /papi reload after installing a new expansion.

Using a MVdWPlaceholderAPI placeholder

Install MVdWPlaceholderAPI.
A general list of placeholders can be found here. Some plugins that work with MVdWPlaceholderAPI are not in the list, but have this information on their resource page so make sure to check there as well.
Using an MVdWPlaceholderAPI placeholder requires you to have another premium plugin installed by Maximvdw.
Validating a placeholder

After you have chosen a placeholder and installed the necessary plugins and expansions, LeaderHeads offers an easy command to check if your placeholder actually works and if it is actually numerical.

Simply execute this command ingame with the placeholder you have chosen: /leaderheads validate <placeholder>
For example: /leaderheads validate %vault_eco_balance%

If you installed everything correctly, this should show the placeholder has been parsed correctly. If not, this means that the placeholder is either not installed or is not numerical.
If you can’t seem to get this working using PlaceholderAPI, it’s best to ask for help on the PlaceholderAPI Discord or on the forum.

If your placeholder could not be validated, there is no point in proceeding to the next steps because it will never work. Revisit the first step to understand what type of placeholders are compatible.
Enabling a placeholder

If the previous steps were successful, you can now enable the placeholder using /leaderheads enable <placeholder>.
For example: /leaderheads enable %vault_eco_balance%

This will generate a .yml file in the statistics folder.
If you’re just setting up a sign, you can skip this step since the statistic will be created if it doesn’t exist yet.

You can now use the statistic in any of the other components of the plugin. Remember that if you just started tracking a statistic, LeaderHeads will usually not know any information about the offline players. This means that in order to be on the leaderboard, you need to join at least once since the statistic started tracking.

Setting up signs

Choosing your placeholder

Follow the Setting up a placeholder section to choose your placeholder.
Placing a sign down

Place down a sign at the position you want to use it. You don’t need to write anything on the sign.
Linking the sign with the placeholder

While looking at the sign you placed, use the command /leaderheads setsign <statistic> <rank> [type]

<statistic> is the placeholder you chose in the first step
<rank> is the rank in the leaderboard that you want to show on this sign. This is the position of the player in the leaderboard, for example 1
[type] is the type of leaderboard you want. This indicates whether we want for example a leaderboard showing the weekly top players or just the alltime top players. The options are: alltime, daily, weekly, monthly, yearly. This argument is optional and will default to alltime

Example command: /leaderheads setsign %statistic_player_kills% 2 daily
This will configure the sign to show the second player in the daily kills leaderboard through the %statistic_player_kills% of the PlaceholderAPI Statistic expansion.
Configuring the statistic

In the .yml file of your statistic, you can edit the format of the signs. This file can be found in the statistics folder of the plugin.
This is important because by default the sign will look a bit boring. You can use /leaderheads reload to quickly test a new configuration.
You can right-click a sign to bring up a menu showing all top players for this leaderboard. You can configure this menu in the aforementioned .yml file.
Placing down a player head

This step is optional. You can place down a player head on top of the sign or on top of the block that the sign is connected to. The player head will update to the relevant leaderboard player’s skin.

Setting up armorstands

If you want to configure an armorstand to show a top player, follow these steps:

Placing a sign down

Follow the steps in the Setting up signs tutorial. You need to have a sign active to link an armorstand.
Spawning the armorstand

While looking at the sign you placed, use the command /leaderheads armorstand [size]

[size] is the size of the armorstand that will be placed.
Options: small, big. This argument is optional and will default to small

You can also manually spawn an armorstand if you want. If you place a sign down, put a block on top of it and put an armorstand on top of that block, it will also work.

In the future we are planning to make it possible to use armorstands independently of signs.
Configuring the armorstand nametag

You can change the nametag of the armorstand by changing the armorstand-nametag option in the .yml file of the statistic.

Keep in mind that LeaderHeads will not prevent any kind of damage to your armorstand. You will have to protect it through a plugin or rule.

Setting up Citizens

If you want to set up leaderboard NPCs with Citizens, follow these steps:

Placing a sign down

Follow the steps in the Setting up signs tutorial. You need to have a sign active to link an NPC.
Installing Citizens

Install Citizens. It is recommended to use the latest version.
Spawning the NPC

While standing on top of the block that the sign is connected to, execute the command /npc create LeaderHeads. The name of the NPC will change once the leaderboard is updated. You can use /npc type to change the type of the NPC.

If you place a sign down, put a block on top of it and put an NPC on top of that block, it will also work. In the future we are planning to make it possible to use NPC’s independently of signs.
Configuring the NPC nametag

You can change the nametag of the NPC by changing the citizens-nametag option in the .yml file of the statistic.

It is very important to note that occasionally, there will be some minor graphical glitches in human NPC nametags. Unfortunately, this is not an issue on our side. We’re currently looking into ways to mitigate this issue.

Setting up holograms

After following the Setting up a placeholder steps, you can follow these steps to set up holograms with placeholders.
You can choose between using HolographicDisplays or Holograms.

Using HolographicDisplays

Installing the plugins

Install HolographicDisplays. You can use a development build for support on newer Spigot versions.
Install HolographicExtension and PlaceholderAPI.
Install ProtocolLib. Make sure to install the recommended build for your version.
Using the placeholders

You can now set up HolographicDisplays like you normally would and use the LeaderHeads PlaceholderAPI placeholders in the lines of your hologram.
You will need to include a refresh holder at the start of your line to make sure the placeholders update. These are the options: {fastest}, {fast}, {medium}, {slow}, {slowest}.
More information can be found on the HolographicExtension resource page.

Here’s an example database.yml file from HolographicDisplays that shows the top 3 players that have gained the most money this day through the %vault_eco_balance% placeholder of the Vault expansion.
```
 my-hologram:
   location: world, -145.743, 73.915, 266.836
   lines:
     - '&eTop Daily Money Gained'
     - '{fast}&b%leaderheads_name_vault_eco_balance_daily_1% &f- &b$%leaderheads_value_vault_eco_balance_daily_1%'
     - '{fast}&b%leaderheads_name_vault_eco_balance_daily_2% &f- &b$%leaderheads_value_vault_eco_balance_daily_2%'
     - '{fast}&b%leaderheads_name_vault_eco_balance_daily_3% &f- &b$%leaderheads_value_vault_eco_balance_daily_3%'
```

Using Holograms

Installing the plugins

Install Holograms, Holograms-Placeholders and PlaceholderAPI.
Install ProtocolLib. Make sure to install the recommended build for your version.

Using the placeholders

You can now set up Holograms like you normally would and use the LeaderHeads PlaceholderAPI placeholders in the lines of your hologram.

Here’s an example holograms.yml file from Holograms that shows the top 3 players that have gained the most money this day through the %vault_eco_balance% placeholder of the Vault expansion.

 holograms:
   my-hologram:
     location: world;-147.7390153955581;73.53292827534491;268.5887224348062;65.54988;210.79431
     lines:
         - '&eTop Daily Money Gained'
         - '&b%leaderheads_name_vault_eco_balance_daily_1% &f- &b%leaderheads_value_vault_eco_balance_daily_1% cm'
         - '&b%leaderheads_name_vault_eco_balance_daily_2% &f- &b%leaderheads_value_vault_eco_balance_daily_2% cm'
         - '&b%leaderheads_name_vault_eco_balance_daily_3% &f- &b%leaderheads_value_vault_eco_balance_daily_3% cm'

PlaceholderAPI and MVdWPlaceholderAPI placeholders

Besides using existing plugin’s placeholders to create leaderboards, LeaderHeads also exposes information about its leaderboards by offering PlaceholderAPI and MVdWPlaceholderAPI placeholders. After following the Setting up a placeholder steps, you can follow these steps to use their values as placeholders in PlaceholderAPI and MVdWPlaceholderAPI.

The components of the placeholders:
<statistic>: the name of your statistic, but without any %, { or } characters. For example, %vault_eco_balance% becomes vault_eco_balance and {stat_walk_cm} becomes stat_walk_cm.
<time>: which timetype of the leaderboard to show. Options: alltime, daily, weekly, monthly, yearly.
<rank>: which rank in the leaderboard to show. Must be a number.

PlaceholderAPI placeholders

%leaderheads_name_<statistic>_<time>_<rank>% shows the name of the player in the leaderboard. %leaderheads_value_<statistic>_<time>_<rank>% shows the value of the player in the leaderboard

Example: %leaderheads_name_statistic_player_kills_daily_5% shows the name of the 5th player in the daily kills leaderboard based on the %statistic_player_kills% placeholder of the Statistic expansion.

Example: %leaderheads_value_ezblocks_broken_alltime_1% shows the amount of blocks broken by the 1st player in the alltime blocks broken leaderboard based on the %ezblocks_broken% placeholder of the EZBlocks expansion.

MVdWPlaceholderAPI placeholders

{leaderheads_name_<statistic>_<time>_<rank>} shows the name of the player in the leaderboard. {leaderheads_value_<statistic>_<time>_<rank>} shows the value of the player in the leaderboard

Example: {leaderheads_name_statistic_player_kills_daily_5} shows the 5th player in the daily kills leaderboard based on the %statistic_player_kills% placeholder of the Statistic expansion.

Configuring a leaderboard

After following the Setting up a placeholder steps, a .yml file will be created in the statistics folder of the plugin-folder. You can edit this file to change multiple aspects, such as:

How often a statistics fetches new data from online players
The appearance of the signs of the leaderboard
The appearance of the players menu of the leaderboard, such as the size, title and commands
The nametags of the armorstands and Citizens nametags
The type of statistic. The type of the statistic is used when formatting its value in signs, menus, holograms etc. Options:
- default: will just format the number regularly
- money: if your statistic represents a very large monetary amount, such as 5 quadrillion, this will format your very large numbers properly, using the money-format configured in the config.yml
- time-seconds: if your statistic represents a time in seconds his will format your time properly and split it into days, hours, minutes and seconds
  using the time-format configured in the config.yml
- time-milliseconds: similar to the other time options, this type is used for statistic that represent a time in milliseconds
- time-minutes: similar to the other time options, this type is used for statistic that represent a time in minutes
- time-hours: similar to the other time options, this type is used for statistic that represent a time in hours

Commands and permissions

Command	Permission	Info
`/leaderheads setsign <statistic> <rank> [type]`	leaderheads.setsign	Set the statistic for the sign that you are currently looking at
`/leaderheads armorstand [size]`	leaderheads.armorstand	Put an armorstand with a skull above the sign you are currently looking at
`/leaderheads help [help]`	leaderheads.help	Show information about the command
`/leaderheads update <statistic> [updatemode]`	leaderheads.update	Updates a statistic that is currently activated. Use `all` to update all statistics. Use the `updatemode` argument (options: `online`, `offline`) to chose whether to update the data for only online or all players. Take in mind that not all plugins allow you to fetch placeholders for offline players
`/leaderheads removesign`	leaderheads.removesign	Removes the statistic for the sign that you are currently looking at
`/leaderheads reload`	leaderheads.reload	Reload LeaderHeads completely
`/leaderheads validate <placeholder>`	leaderheads.validate	Validate whether a placeholder is correctly installed
`/leaderheads enable <statistic>`	leaderheads.enable	Enables a statistic that is currently not activated
`/leaderheads info`	leaderheads.info	Shows general information about the plugin and enabled statistics
`/leaderheads include <player> [statistic]`	leaderheads.include	Includes a previous excluded player on the leaderboard of a statistic that is currently activated. Use `all` to include the player in all statistics
`/leaderheads exclude <player> [statistic]`	leaderheads.exclude	Excludes a specific player from the leaderboard of a statistic that is currently activated. Use `all` to exclude a player from all statistics
`/leaderheads excluded`	leaderheads.excluded	Shows which players have been excluded from which statistics

FAQ

Q: I want to track some statistic and show it in a menu, but I don’t want a sign for it, how do I still use it?
A: After following the Setting up a placeholder steps, you can enable force-update in the .yml file of your statistic. This will make sure the statistic updates even if no signs are active.

Q: The previous version of LeaderHeads (< 4.0.0) had feature x that I used, will it come back in this version?
A: Yes, we are planning to bring back every feature the previous versions had, but we’re adding them based on how important and popular they were, so it might take a while for a certain feature to come back. Don’t hesitate to contact us about this.

Q: Will the plugin receive active updates?
A: Yes, we will actively update the plugin with additional features and support for later Spigot versions.

Q: My Minecraft server is physically located in timezone x but most of my players are in timezone y. How do I deal with this?
A: The config.yml has a timezone option that lets you choose the timezone that will be used for calculating the daily, weekly, monthly and yearly leaderboards.

Q: I’m trying to use placeholder %statistic_time_played% to display the players with the most play time, but it doesn’t work.
A: LeaderHeads can only handle numerical values. The placeholder %statistic_time_played% does not return a numerical result but rather a formatted string.
Instead, you should use the placeholder %statistic_seconds_played%. This is a numerical placeholders that returns the number of seconds played. This is the format that LeaderHeads can use. After the .yml file is generated, you should set statistic-type to time-seconds to make sure LeaderHeads properly formats the value.

Q: How do I stop tracking statistic x?
A: Simply delete the .yml file of the statistic.

LeaderHeads

Introduction

Setting up a placeholder

Choosing the placeholder

Using a PlaceholderAPI placeholder

Using a MVdWPlaceholderAPI placeholder

Validating a placeholder

Enabling a placeholder

Setting up signs

Choosing your placeholder

Placing a sign down

Linking the sign with the placeholder

Configuring the statistic

Placing down a player head

Setting up armorstands

Placing a sign down

Spawning the armorstand

Configuring the armorstand nametag

Setting up Citizens

Placing a sign down

Installing Citizens

Spawning the NPC

Configuring the NPC nametag

Setting up holograms

Using HolographicDisplays

Installing the plugins

Using the placeholders

Using Holograms

Installing the plugins

Using the placeholders

PlaceholderAPI and MVdWPlaceholderAPI placeholders

PlaceholderAPI placeholders

MVdWPlaceholderAPI placeholders

Configuring a leaderboard

Commands and permissions

FAQ