Statistic

This is a provider that provides statistic values of a player to the Top Holder.

Format

holders:
  <holder-name>:
    # The type of the provider
    type: statistic
    # The name of the statistic
    statistic: <statistic>
    # The name of the material. Used for some statistics that require an item.
    material: <material>
    # The name of the entity. Used for some statistics that require an entity.
    entity: <entity>

• Available values for <statistic> can be found here
• Available values for <material> can be found here
• Available values for <entity> can be found here

Behavior

• If the statistic is a Generic type, the material and entity fields are ignored. The provider will return the value of the statistic for the player.

• If the statistic is a Material type, the material field will be used:

  • If the material is not specified, the provider will return the value of the statistic for all materials.
  • If the material is specified, the provider will return the value of the statistic for the specified material.
  • The material field can be a string or a list of strings.

material: STONE

material:
  - STONE
  - COBBLESTONE

• If the statistic is an Entity type, the entity field will be used:
  • If the entity is not specified, the provider will return the value of the statistic for all entities.
  • If the entity is specified, the provider will return the value of the statistic for the specified entity.
  • The entity field can be a string or a list of strings.

entity: ZOMBIE

entity:
  - ZOMBIE
  - SKELETON

Example

holders:
  # Holder that shows the number of times a player has jumped
  jump:
    type: statistic
    statistic: JUMP
  # Holder that shows the number of blocks mined by a player
  mine:
    type: statistic
    statistic: MINE_BLOCK
  # Holder that shows the number of times a player has killed a zombie
  zombie:
    type: statistic
    statistic: KILL_ENTITY
    entity: ZOMBIE
  # Holder that shows the number of times a player has mined diamond ore
  diamond:
    type: statistic
    statistic: MINE_BLOCK
    material: DIAMOND_ORE
  # Holder that shows the number of times a player has mined diamond ore or gold ore
  diamond_or_gold:
    type: statistic
    statistic: MINE_BLOCK
    material:
      - DIAMOND_ORE
      - GOLD_ORE
  # Holder that shows the number of times a player has killed a zombie or a skeleton
  zombie_or_skeleton:
    type: statistic
    statistic: KILL_ENTITY
    entity:
      - ZOMBIE
      - SKELETON

Placeholder

This is a provider that allows you to use PlaceholderAPI placeholders as values in the Top Holder.

Format

holders:
  <holder-name>:
    # The type of the provider
    type: placeholder
    # The placeholder used to get the value
    placeholder: <placeholder>
    # Whether the placeholder should be parsed for online players only. Default is false (all players)
    online: <true/false>

Example

holders:
  # Holder that shows the amount of money a player has
  # Use the Vault expansion: /papi ecloud download Vault
  money:
    type: placeholder
    placeholder: "%vault_eco_balance%"
  # Holder that shows the number of diamonds a player has mined
  # Use the Statistic expansion: /papi ecloud download Statistic
  diamonds:
    type: placeholder
    placeholder: "%statistic_mine_block:DIAMOND_ORE%"
    online: true # Only get the value for online players

MiniPlaceholder

This is a provider that allows you to use MiniPlaceholders placeholders as values in the Top Holder.

Format

holders:
  <holder-name>:
    # The type of the provider
    type: mini-placeholder
    # The placeholder used to get the value
    placeholder: <placeholder>

Example

holders:
  # Holder that shows the amount of money a player has
  # Use the Vault expansion: https://modrinth.com/plugin/miniplaceholders-vault-expansion
  money:
    type: mini-placeholder
    placeholder: "<vault_eco_balance>"

MiniPlaceholders

The plugin provides a MiniPlaceholders placeholder to allow you to query data from the Top Holder.

Usage

<topper_global:<query>>
<topper_player:<query>>

Check the Query section for more information about how to set the <query>.

Example

<topper_global:money;top_name;1>
<topper_global:money;top_value;1>
<topper_global:money;top_value;1;#,###>
<topper_player:money;top_rank>

PlaceholderAPI

The plugin provides a PlaceholderAPI placeholder to allow you to query data from the Top Holder.

Usage

%topper_<query>%

Check the Query section for more information about how to set the <query>.

Example

%topper_money;top_name;1%
%topper_money;top_value;1%
%topper_money;top_value;1;#,###%
%topper_money;top_rank%

Create a Hologram

You can use the top_name and top_value placeholders to display players in the leaderboard.

Here is an example of a hologram that displays the top 5 players in the leaderboard:

&b&lJUMP LEADERBOARD
&7#1 &f%topper_jump;top_name;1% &7- &b%topper_jump;top_value;1%
&7#2 &f%topper_jump;top_name;2% &7- &b%topper_jump;top_value;2%
&7#3 &f%topper_jump;top_name;3% &7- &b%topper_jump;top_value;3%
&7#4 &f%topper_jump;top_name;4% &7- &b%topper_jump;top_value;4%
&7#5 &f%topper_jump;top_name;5% &7- &b%topper_jump;top_value;5%

Create a Top Block

Create a Top Skull

1. Prepare a skull template named jump_skull that returns the UUID of the player at the specific {index} of the jump leaderboard

/varblocks template add jump_skull %topper_jump;top_key;{index}%

2. Place the skull

3. While looking at the skull, run the following command to assign the jump_skull template to the skull

/varblocks block add jump_1 skull jump_skull

4. Set the {index} of the skull to 1 to display the top player

/varblocks block argument jump_1 index 1

5. Create another skull for the second player

/varblocks block add jump_2 skull jump_skull
/varblocks block argument jump_2 index 2

Create a Top Sign

1. Prepare a sign template named jump_sign that displays the player’s name and value at the specific {index} of the jump leaderboard

/varblocks template add jump_sign
/varblocks template add jump_sign &6#{index}&7: &f%topper_jump;top_name;{index}%
/varblocks template add jump_sign &e%topper_jump;top_value;{index}%
/varblocks template add jump_sign

2. Place the sign

3. While looking at the sign, run the following command to assign the jump_sign template to the sign

/varblocks block add jump_sign_1 sign jump_sign

4. Set the {index} of the sign to 1 to display the top player

/varblocks block argument jump_sign_1 index 1

5. Create another sign for the second player

/varblocks block add jump_sign_2 sign jump_sign
/varblocks block argument jump_sign_2 index 2

Create an NPC

1. Create a player NPC

/npc create %topper_jump;top_name;1%

2. Set the skin of the NPC

/npc skin %topper_jump;top_name;1%

The NPC will display the skin of the top player of the jump leaderboard.

Customize Value Provider

Asynchronous Provider

You can set async to true to make the provider asynchronous, meaning it will be executed in a separate thread. This can be useful if the provider is slow or if it performs a lot of calculations.

holders:
  jump:
    <your other settings>
    async: true

Default Values

You can change the default values, returned by some queries and commands, by adding some settings to your holder settings.

holders:
  jump:
    <your other settings>
    null-name: "---" # Default value for the name
    null-uuid: "---" # Default value for the uuid
    null-value: "---" # Default value for the value
    line: "&7[&b{index}&7] &b{name} &7- &b{value}" # Default format for the top line in the top list

Reversed Leaderboard

By default, the leaderboard is measured by the player with the highest value first. If you want to change that (e.g. show the player with the least value first), you can set reverse to true.

holders:
  jump:
    <your other settings>
    reverse: true

Handle Formatted Values

If the output of a Value Provider (Placeholder for example) is a formatted value and you are confident that you can get the raw value from it with a simple method of taking only numbers and the decimal separator, you can enable the formatted option in your Holder Setting.

holders:
  example-formatted-value-provider:
    <your other settings>
    formatted: true
    formatted-settings: # Optional settings for the formatted value
      decimal-separator: "." # Change this to the decimal separator of the formatted value

Show Errors

By default, any errors that occur during the execution of a provider will be truncated. If you want to show the errors instead, you can set show-errors to true.

holders:
  jump:
    <your other settings>
    show-errors: true

Ignore Permission

You can specify a set of permissions so that the Holder will skip updating the value of the player if they have one of the permissions.

holders:
  jump:
    <your other settings>
    ignore-permission: exclude.permission

Migrate from 2.X

1. Download and install Topper 3.0.0 here
2. Install VarBlocks if you use Top Signs or Top Skulls here
3. Run the server and let Topper convert your data
4. You’re done! Enjoy the new features of Topper 3.0.0!

Playtime Leaderboard

This will guide you on how to create an unreliable playtime leaderboard for your server using the built-in Statistic Value Provider and format the value using Value Display.

Add the Holder

Open the config.yml file and add the following holder:

holders:
  playtime:
    type: statistic
    statistic: PLAY_ONE_MINUTE # Or PLAY_ONE_TICK if your server is running on 1.12 or below

This will create a holder named playtime that shows the total playtime of a player in ticks.

But the value is in ticks, which is not human-readable. So, we need to format it. Add the following line:

holders:
  playtime:
    type: statistic
    statistic: PLAY_ONE_MINUTE
    line: "&7[&b{index}&7] &b{name} &7- &b{value_time:pattern=HH:mm:ss&type=duration&unit=ticks}"

We added the line setting to the holder and override the default line. The {value_time:pattern=HH:mm:ss&type=duration&unit=ticks} will format the value to a human-readable time format.

Now when you save and restart the server, you should see the playtime leaderboard in the /gettop playtime command.

Display the Leaderboard

We will display it in a hologram

Here is an example of a hologram that displays the top 5 players in the leaderboard:

&b&lPLAYTIME LEADERBOARD
&7#1 &f%topper_playtime;top_name;1% &7- &b%topper_playtime;top_value;1;time:pattern=HH:mm:ss&type=duration&unit=ticks%
&7#2 &f%topper_playtime;top_name;2% &7- &b%topper_playtime;top_value;2;time:pattern=HH:mm:ss&type=duration&unit=ticks%
&7#3 &f%topper_playtime;top_name;3% &7- &b%topper_playtime;top_value;3;time:pattern=HH:mm:ss&type=duration&unit=ticks%
&7#4 &f%topper_playtime;top_name;4% &7- &b%topper_playtime;top_value;4;time:pattern=HH:mm:ss&type=duration&unit=ticks%
&7#5 &f%topper_playtime;top_name;5% &7- &b%topper_playtime;top_value;5;time:pattern=HH:mm:ss&type=duration&unit=ticks%

Value Display

Some places like {value} in line and the value and top_value queries can be expanded to format the value in a more readable way. This is done by specifying some settings for them like:

• {value_<format>}
• <holder>;value;<format>
• <holder>;top_value;<position>;<format>

The following section will guide you through the available formats to replace <format>, we will use the <holder>;value;<format> query as an example.

Available Formats

Decimal Format

Format: decimal:setting1=value1&setting2=value2

Example: jump;value;decimal:decimalSeparator=,&groupingSeparator=.&groupingSize=3&maximumFractionDigits=2

Time Format

Format: time:setting1=value1&setting2=value2

Example: playtime;value;time:pattern=HH:mm:ss&type=duration&unit=ticks

Link a Top Holder

First, you add some settings to link a Top Holder to this Timed Holder, which means the Timed Holder will listen to the Top Holder for value changes and updates.

holders:
  jump_daily: # The timed holder name
    top: jump # The top holder it will be based on

This example will set that the Timed Holder jump_daily will listen to the Top Holder jump (Click here if you don’t know what jump is).

Continue reading to learn how to set up time settings.

Set time interval

Now you will set the duration of the Timed Holder. When the duration of the Timed Holder is over, the holder will be reset.

Format

cron: <cron-expression>

The cron is a QUARTZ expression, which is usually an expression with 7 parts.

You can go to this page to generate your own cron expression.

Built-in

The plugin provides some built-in cron expressions in case you don’t want to make the expression yourself:

• HOURLY: The holder would be reset at the start of the next hour
• DAILY: The holder would be reset at the start of the next day
• WEEKLY: The holder would be reset at the start of the next week
• MONTHLY: The holder would be reset at the start of the next month
• YEARLY: The holder would be reset at the start of the next year

Example

holders:
  # The holder that resets every day
  jump_daily:
    top: jump
    cron: DAILY
  # The holder that resets every month
  jump_monthly:
    top: jump
    cron: MONTHLY
  # The holder that resets every half of the month
  jump_custom_time:
    top: jump
    cron: 0 0 0 1,15 * ? *

Set up Reward

Now you will set the rewards to give to the players when the Timed Holder is reset.

Format

rewards:
  ?: # Rewards for all players in the holder
    - "command_1"
    - "command_2"
    - ...
  1: # Rewards for the 1st player
    - "command_1"
    - "command_2"
    - ...
  2: # Rewards for the 2nd player
    - "command_1"
    - "command_2"
    - ...
  3: # Rewards for the 3rd player
    - "command_1"
    - "command_2"
    - ...
  4: # Rewards for the 4th player
    - "command_1"
    - "command_2"
    - ...
  <more ranks>

?, 1, 2, 3, etc. are optional. You don’t have to set all of them.

Reward Variable

The plugin provides some variables to apply in the reward commands

• {name}: The name of the player
• {uuid}: The UUID of the player
• {rank}: The rank of the player, starts from 1
• {initial}: The initial value of the player in the holder
• {current}: The current value of the player in the holder
• {value}: The value of the player in the holder - The distance between {initial} and {current}

Example

holders:
  jump_daily:
    top: jump
    cron: DAILY
    rewards:
      ?:
        - give {name} stone 1
      1:
        - give {name} diamond 1
        - say {name} got a diamond for jumping the most
      2:
        - give {name} iron 1
        - say {name} got iron for jumping the second most

PlaceholderAPI

The plugin provides a PlaceholderAPI placeholder to allow you to query data from the Holder.

Usage

%timedtopper_<query>%

Check the Query section for more information about how to set the <query>.

Example

%timedtopper_money;top_name;1%
%timedtopper_money;top_value;1%
%timedtopper_money;top_value;1;#,###%
%timedtopper_money;top_rank%
%timedtopper_money;remain_time;HH:mm:ss%
%timedtopper_money;end_time;yyyy-MM-dd HH:mm:ss%

Link a Top Holder

First, you add some settings to link a Top Holder to this Group Holder, which means the Group Holder will listen to the Top Holder for value changes and updates.

holders:
  jump_group: # The group holder name
    top: jump # The top holder it will be based on

This example will set that the Group Holder jump_group will listen to the Top Holder jump (Click here if you don’t know what jump is).

Continue reading to learn how to set up group settings.

PlaceholderAPI

The plugin provides a PlaceholderAPI placeholder to allow you to query data from the Group Holder.

Usage

%grouptopper_<query>%

Check the Query for more information about how to set the <query>

Example

%grouptopper_jump_group;top_name;1%
%grouptopper_jump_group;top_value;1%
%grouptopper_jump_group;top_value;1;#,###%
%grouptopper_jump_group;top_rank%

PlaceholderAPI

The plugin provides a PlaceholderAPI placeholder to allow you to query data from the Group Holder.

Usage

%cachy_<query>%

Check the Query for more information about how to set the <query>

Example

%cachy_jump;name;HSGamer%
%cachy_jump;uuid;7acc67dc-8b84-4f8d-b7ad-ec81e758f5a1%
%cachy_jump;name;{player_name}%
%cachy_jump;uuid;{player_uuid}%