Topper

This is a wiki to demonstrate all projects of Topper, a project / framework to handle single-value data tables.

Check the sidebar and choose a project to see more details.

Chapter 1

Topper (Spigot)

The documentation for the Spigot plugin of Topper.

Where to find the plugin:

Quick Start

This will quickly introduce you to the basics of the plugin, by creating a simple leaderboard.

Add a Top Holder

The unit that stores and manages the leaderboard data is called a Top Holder. Inside the Top Holder, you can define a Value Provider, which is responsible for providing the value of each entry in the leaderboard.

We will start by creating a Top Holder named jump and defining a Value Provider to count the number of times the player jumps. The Value Provider we will use is called Statistic Provider.

Open the config.yml file from the plugin’s folder (plugins/Topper/config.yml), head to the holders section, and add the following configuration:

holders:
  jump: # The name of the Top Holder
    type: statistic # The type of the Value Provider, which in this case is a Statistic Provider
    statistic: jump # The name of the statistic that will be used to count the number of jumps

That is all you need to do, now the plugin is ready to start counting the number of jumps.

Open your server terminal and type /reloadtop to apply the changes.

Display the Top Holder

There are several ways to display the leaderboard of a Top Holder. In this case, we will simply display the top 10 players in the chat.

To do this, type the following command:

/gettop jump 10

Add another Top Holder

Now, let’s add another Top Holder to show the amount of diamond ores a player has mined.

Open the config.yml file from the plugin’s folder (plugins/Topper/config.yml), head to the holders section, and add the following configuration:

holders:
  jump:
    type: statistic
    statistic: jump
  mine:
    type: statistic
    statistic: mine_block
    material: diamond_ore

mine_block needs a block material to work. Hence, we added the material field to specify the block material, which in this case is diamond_ore.

Open your server terminal and type /reloadtop to apply the changes.

Now, you can display the top 10 players who have mined the most diamond ores by typing the following command:

/gettop mine 10

What’s next?

This is just the beginning. You can check the other pages in the documentation to learn more about the plugin and its features. There could be something that you might find interesting for your server.

Happy building! 🚀

Commands & Permissions

Command	Permission	Description
`gettop <holder>`	`topper.top`	Get the top 10 players of a leaderboard provided by the specified `<holder>`
`gettop <holder> <number>`	`topper.top`	Get the top `<number>` players of a leaderboard provided by the specified `<holder>`
`gettop <holder> <from_index> <to_index>`	`topper.top`	Get the players from the specified index range of a leaderboard provided by the specified `<holder>`
`reloadtop`	`topper.reload`	Reload the plugin

Config

# The type of storage the plugin will use to store the value
# Available: FLAT, YAML, JSON, SQLITE, NEW-SQLITE, MYSQL
storage-type: yaml

# The settings for the Top Holders
holders: {}

# Should the plugin load all offline players when the server starts
load-all-offline-players: false
task:
  save:
    # How many entries should be saved per tick
    entry-per-tick: 10
    # How many ticks should the plugin wait before saving the leaderboard
    delay: 0
  update:
    # How many entries should be updated per tick
    entry-per-tick: 10
    # How many ticks should the plugin wait before updating the leaderboard
    delay: 0

Chapter 4

Value Provider

A unit that provides values to the Top Holder. Continue reading to learn more about the built-in value providers.

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

Example

holders:
  # Holder that shows the number of times a player has jumped
  jump:
    type: statistic
    statistic: JUMP
  # 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

Placeholder

Note

Requires PlaceholderAPI

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>
    # Whether the placeholder should be parsed asynchronously. Default is false
    async: <true/false>
    # Whether to show errors when parsing the placeholder. Default is false
    show-errors: <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

Frequently Asked Questions

I set the placeholder but it is not showing the value in the Top Holder

Make sure that the placeholder you are using is valid and that the plugin that provides the placeholder is installed and working correctly.
Try running the command /papi parse me <placeholder> to see if the placeholder is working as expected.
Check if the placeholder is for online players only. If so, set the online option to true in the configuration.
Try setting the show-errors option to true to see if there are any errors when parsing the placeholder.
If the placeholder is still not working, ask for help in the plugin’s support channel or forum (remember to enable show-errors and provide the logs to them for better support).

My placeholder gives a formatted value (e.g., 1,000.00 instead of 1000). Can I use it in the provider?

No, the placeholder provider only supports numerical values (only numbers and decimal separator . (dot) ). You must use a placeholder that returns a raw number without formatting, if possible. If the plugin that provides the placeholder does not have an option to return a raw number, you can try using a different placeholder or ask the plugin developer to add support for raw numbers.

Query

This page provides information about the query system, which is used to retrieve data from the Top Holder.

Format

The format of a query is as follows:

<holder>;<type>;<args>

<holder>: The Top Holder to query.
<type>: The type of data to retrieve.
<args>: Additional arguments for the query.

If the <type> does not require any arguments, the query can be simplified to:

<holder>;<type>

Types

Type	Argument	Description	Example	Explanation
`top_name`	`<position>`	The name of the player at the specified position.	`money;top_name;1`	Retrieve the name of the player at the first position in the Top Holder named `money`
`top_key`	`<position>`	The UUID of the player at the specified position.	`money;top_key;1`	Retrieve the UUID of the player at the first position in the Top Holder named `money`
`top_value`	`<position>`	The value of the player at the specified position.	`money;top_value;1`	Retrieve the value of the player at the first position in the Top Holder named `money`
`top_value`	`<position>;<format>`	The formatted value of the player at the specified position.	`money;top_value;1;#,###`	Retrieve the formatted value of the player at the first position in the Top Holder named `money`
`top_value_raw`	`<position>`	The raw value of the player at the specified position.	`money;top_value_raw;1`	Retrieve the raw value of the player at the first position in the Top Holder named `money`
`top_rank`		The rank of the player.	`money;top_rank`	Retrieve the rank of the player in the Top Holder named `money`
`value`		The value of the player.	`money;value`	Retrieve the value of the player in the Top Holder named `money`
`value`	`<format>`	The formatted value of the player.	`money;value;#,###`	Retrieve the formatted value of the player in the Top Holder named `money`
`value_raw`		The raw value of the player.	`money;value_raw`	Retrieve the raw value of the player in the Top Holder named `money`

Chapter 6

Hook

Details about the hooks provided by the plugin.

PlaceholderAPI

Note

Install 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%

Chapter 7

Extra

Extra tutorials for common features and tasks.

Note

Parts of the tutorials in this section assume that you’ve done the Quick Start. If there is anything you don’t understand from the tutorials, you may want to go back and do the Quick Start.

Change 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

Create a Hologram

Note

Requires PlaceholderAPI and a hologram plugin that supports PlaceholderAPI such as DecentHolograms

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

Note

Requires PlaceholderAPI and VarBlocks

Create a Top Skull

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}%

Place the skull
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

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

/varblocks block argument jump_1 index 1

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

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

Place the sign
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

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

/varblocks block argument jump_sign_1 index 1

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

Note

Requires PlaceholderAPI and Citizens

Create a player NPC

/npc create %topper_jump;top_name;1%

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.

Migrate from 2.X

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

Reversed Leaderboard

By default, the top 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

Chapter 2

TimedTopper

The documentation for TimedTopper, a Spigot plugin for timely leaderboards.

Where to find the plugin:

SpigotMC

Config

# The type of storage the plugin will use to store the value
# Available: YAML, SQLITE, MYSQL
storage-type: yaml

# The settings for each holder
#
# EXAMPLE SETTING
# holders:
#   money_daily: # The holder name
#     top: money # The top holder it will be based on
#     cron: "0/30 * * ? * * *" # The cron expression for the holder indicating when it will be reset
#     rewards: # The rewards for the holder
#       ?: # Reward for all players
#         - "give {name} dirt 1"
#       1: # Reward for the top 1 player
#         - "give {name} diamond 1"
#       2: # Reward for the top 2 player
#         - "give {name} iron 1"
#
# CRON EXPRESSION
# You can use https://www.freeformatter.com/cron-expression-generator-quartz.html to generate the cron expression
# Here are some examples:
# - DAILY: 0 0 0 * * ? *
# - WEEKLY: 0 0 0 ? * 2 *
# - MONTHLY: 0 0 0 1 * ? *
# - HOURLY: 0 0 0/1 * * ? *
#
# REWARD PLACEHOLDERS
# {name} - The name of the player
# {uuid} - The UUID of the player
# {rank} - The rank of the player
holders: {}

task:
  save:
    # How many entries should be saved per tick
    entry-per-tick: 10
    # How many ticks should the plugin wait before saving the leaderboard
    delay: 0

Query

The query system is the same as the one used in Topper, with the addition that the <holder> is the name of the Holder speficied in the configuration file of TimedTopper.

Refer to the Topper Query page for more information.

New Types

Type	Argument	Description	Example	Explanation
`remain_time`		The remaining time in millis until the next reset.	`money;remain_time`	Retrieve the remaining time in millis until the next reset of the Holder named `money`
`remain_time`	`<format>`	The remaining time until the next reset.	`money;remain_time;HH:mm:ss`	Retrieve the remaining time until the next reset of the Holder named `money`
`end_time`		The time of the next reset in epoch millis.	`money;end_time`	Retrieve the time of the next reset in epoch millis of the Holder named `money`
`end_time`	`<format>`	The time of the next reset.	`money;end_time;yyyy-MM-dd HH:mm:ss`	Retrieve the time of the next reset of the Holder named `money`

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%

Topper

Subsections of Topper

Topper (Spigot)

Subsections of Topper (Spigot)

Quick Start

Add a Top Holder

Display the Top Holder

Add another Top Holder

What’s next?

Commands & Permissions

Config

Value Provider

Subsections of Value Provider

Statistic

Format

Example

Placeholder

Format

Example

Frequently Asked Questions

I set the placeholder but it is not showing the value in the Top Holder

My placeholder gives a formatted value (e.g., 1,000.00 instead of 1000). Can I use it in the provider?

Query

Format

Types

Hook

Subsections of Hook

PlaceholderAPI

Usage

Example

Extra

Subsections of Extra

Change default values

Create a Hologram

Create a Top Block

Create a Top Skull

Create a Top Sign

Create an NPC

Migrate from 2.X

Reversed Leaderboard

TimedTopper

Subsections of TimedTopper

Config

Query

New Types

PlaceholderAPI

Usage

Example