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.

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

{
  "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": "minecraft: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.

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

{
  "holders": {
    "jump": {
      "type": "statistic",
      "statistic": "minecraft:jump"
    },
    "mine": { // The name of the Top Holder
      "type": "statistic", // The type of the Top Holder
      "statistic-type": "minecraft:mined", // The type of the statistic
      "statistic": "minecraft:diamond_ore" // The name of the statistic
    }
  }
}

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

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
    # How many times should the plugin skip updating the value for the entry if it fails to update
    # This is useful to let the plugin prioritize other active entries
    max-skips: 1
    # How many ticks should the plugin wait before applying the updated value to the entry
    # Since the holder is updated partially, this is useful to prevent the plugin from applying the value too early
    # and to allow the plugin to apply the value in larger batches, creating the illusion of a single update
    set-delay: 20

{
  // The type of storage the plugin will use to store the value
  // Available: FLAT, SQLITE, MYSQL
  "storage-type": "flat",

  // The settings for the Top Holders
  "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
    },
    "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,
      // How many times should the plugin skip updating the value for the entry if it fails to update
      // This is useful to let the plugin prioritize other active entries
      "max-skips": 1,
      // How many ticks should the plugin wait before applying the updated value to the entry
      // Since the holder is updated partially, this is useful to prevent the plugin from applying the value too early
      // and to allow the plugin to apply the value in larger batches, creating the illusion of a single update
      "set-delay": 20
    }
  }
}

Frequently Asked Questions

I set my Value Provider, but it’s laggy

In most cases, you’d better enable async (Tutorial) so that your provider is run on an asynchronous thread that doesn’t affect your main server thread. However, some providers may not support asynchronous run and require to run on the main thread. In that case, either you have to find one that supports and test it or ask the author of that provider to add support for that.

Some providers may have an online option that determines whether the provider should only be run for online players (like PlaceholderAPI). If so, you are recommended to enable it to avoid unnecessary computations for offline players.

For those who are using statistic placeholder in the PlaceholderAPI Value Provider, you are recommended to either enable online option or check out the built-in Statistic Provider.

My name isn’t appearing in the Top Holder after I set it up

As Topper only registers players when they join the server, the issue can be solved by just re-joining the server.

The Top Holder doesn’t work

In most cases, there must be a reason why the holder is not working. Here are some common practices we gather from similar cases:

• Check if the configuration is properly set up: There are cases when there is a syntax error in the configuration file or the configuration is not formatted correctly. You should check the file with some validation tools such as YAML Lint.
• Check if the required settings are properly set up: Make sure to check your settings against the wiki. There are cases when users mixed up the settings or forgot to set some required settings, so please read the wiki carefully.
• Check if there is any errors: Make sure to check your logs for any errors related to your Top Holder. If there isn’t one, make sure to enable show-errors in the configuration (Tutorial).

After all, there must be a reason why the holder is not working. Please check thoroughly and provide more details about the issue when you report it in the support channel.

I set my PlaceholderAPI’s 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 show-errors to true to see if there are any errors when parsing the placeholder. (Tutorial)
• If the placeholder is still not working, ask for help in the plugin’s support channel or forum (remember to enable show-errors (Tutorial) 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.

If the value is a simple formatted number, you can try Handling the Formatted Value.

How can I know if a placeholder works with Topper?

Here is a rough list of criteria that a placeholder should have in order to work with Topper:

• The placeholder should only returns raw number
  • That means it should only have digits and one . (dot) as a decimal separator
    • Work: 100, 100.00, 100.123
    • Won’t work: abc, 1,000,000, 100,000.122, 100.000.000, 1 000 000
• The placeholder should work with both online and offline players
• If the placeholder doesn’t work with offline players, it should return an empty string or the placeholder itself
• If there is any error in the logic of the placeholder, it should return an empty string or the placeholder itself

I want to format the value returned by my placeholder in my leaderboard

First, you should ALWAYS use a placeholder that returns a raw number without formatting, if possible (Check the previous questions for more information).

Then in your query to get the value from the Top Holder, you can apply [Value Display]({{ ref “topper/extra/value_display” }}) to format the value.

In short, use the placeholder that returns a raw number when setting up the Top Holder, then apply Value Display settings when setting up the display of the leaderboard.

I want to shorten the number (e.g. 1000000 to 1M)

The [Value Display function]({{ ref “topper/extra/value_display” }}) can be used to shorten the number. For example, money:value:shorten will shorten the number of the value in the money Top Holder.

I am so confused about how to use Topper

Take a deep breath and read the wiki again. You should take it slow and read the wiki carefully as you can miss some important details if you read it too quickly. If you still have trouble, feel free to ask for help in the Discord server. Remember to provide a clear and concise description of your issue, including any relevant error messages or screenshots.

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