Skip to content

Tutorial

Jump to bottom
Tan Jin edited this page Apr 23, 2024 · 116 revisions

Overview

Before we go into the setup, here's a quick overview to understand the structure of the plugin. Firstly, as of version 2.0.0 the term entity is used widely throughout the entire plugin. Entity refers to either a player or a group and this is dependent on the enable-group option within the config.yml file. For the sake of clarity, entity refers to a player if enable-group is set to false. Otherwise, entity refers to a group if enable-group is set to true.

Now that we are clear on the above, there are 4 possible ways for calculating an entity's net worth:

  1. Balance
  2. Land Claims
  3. Inventory
  4. PlaceholderAPI (PAPI)

Choices for including balance, land claims, inventory and PAPI are managed via the include-bal, include-land, include-inventory and include-papi options respectively. All these options can be found within the config.yml file in their corresponding sections.

The important sections that users are strongly advised to look at during setup are Group Configurations, Balance Configurations, Land Configurations, Inventory Configurations and PlaceholderAPI Configurations. You may also refer to Example Setups that may aid your understanding in the configuration of the plugin.

Initial Setup

The initial setup of the plugin is very simple. By default, all options in config.yml are disabled so the likelihood of the plugin not running on server start is practically 0. Simply download the JAR file from spigot, drop it into your server and do a quick restart!

General Configurations

General options are found at the very top of config.yml under the General Configurations section and the fields are as listed below:

lang-file: en.yml
use-gui-stats: false
calculation-mode: 1
cache-duration: 3600

The plugin comes default with the English language. However, you can easily create a file in another language, drop it within the lang folder of the plugin and then update the lang-file field above in your config.yml to use the new file.

The use-gui-stats option defaults to false and stats are shown in the chat. To show entity stats in a GUI instead, set this option to true. Note that the use of GUI may incur a slightly longer time for calculations and leaderboard updates. In addition, the survtop.gui.details.self and survtop.gui.details.others permission nodes are also used to decide which players can click into subpages to view detailed breakdowns on the GUI. More information can be found in the section on Commands & Permissions.

The calculation-mode is set to 1 by default and it is recommended to keep it that way. There are a total of 3 calculation modes as described below:

  • 0: Adopts a greedy approach, calculates everything in real-time and will never use the cached results. Most heavy impact on performance.
  • 1: Adopts a balanced approach, calculates stats in real-time only if cached results cannot be found. Optimized performance.
  • 2: Adopts a conservative approach, calculations are done only during leaderboard updates and players will only be able to retrieve cached results. Best Performance.

For small servers without the computing resources or enormous servers that are very worried about lags, setting use-gui-stats to false and calculation-mode to 2 may help with server performance.

The cache-duration option is only used for calculation modes 1 and 2 which involves the use of cache. By default, cache expires after 1 hour (3600 seconds) although this value can be adjusted to your preferences. Note that calculation mode 0 does all calculations in real-time so this option will be ignored.

Group Configurations

Group Options can be found within the Group Configurations section. In particular, the following two fields are of our interest when managing group options:

enable-group: false
group-type: FactionsUuid

By default, enable-group is set to false and group-type is completely ignored. However, if enable-group is set to true, then a valid group-type needs to be set as well. Otherwise, the group option will refuse to work. Recall that if enable-group is set to true, then entity throughout the whole plugin would refer to a group.

The list of supported valid group types as of version 3.2.0 are as listed below:

Once enable-group is set to true and a valid group-type is provided, SurvivalTop will now calculate wealth based on groups. In other words, the net worth of all players within a group will be summed up together to give the total net worth of a group that is shown in the stats or leaderboard.

Balance Configurations

Balance option is a straightforward option to work with and is found under the Balance Configurations section of config.yml. It contains only one field of interest:

include-bal: false

By default, it is set to false. If set to true, it requires Vault as well as an economy plugin. Otherwise, this option will refuse to work.

Land Configurations

Land options look like a daunting section but the setup is actually very straightforward. The fields of our interest can be found under the Land Configurations section and are as listed below:

include-land: false
land-type: GriefPrevention
max-land-height: default
min-land-height: default
include-spawners: false
include-containers: false
container-type:
  - CHEST
  - TRAPPED_CHEST

By default, include-land, include-spawners and include-containers are set to false and the values of land-type and container-type are ignored. To use this section, the include-land option must be set to true and a valid land-type must be set as well. Otherwise, no matter what the other fields are configured to be, all land options will refuse to work.

The list of supported valid land types as of version 3.2.0 are as listed below:

The two options max-land-height and min-hand-height defaults to the heights used by your land claim plugin and minecraft version. It is recommended to keep this at default unless you have many large claims and are looking to improve update/calculation times. What this option does is that it overrides the default heights of your plugin and minecraft version and only considers blocks within your specified height in calculating wealth. For example, to only include blocks within Y-level 0 to 100, you would set max-land-height to 100 and min-land-height to 0.

include-spawners and include-containers are both very straightforward options. If both are set to false, then the land wealth calculation would simply only take into account blocks in the claim. On the other hand, if include-spawners and include-containers are set to true, then land wealth calculations will also take spawners and containers into account.

Values for blocks, spawners and containers are configured within their respective files blocks.yml, spawners.yml and containers.yml which can be found in the calculations folder. The list of supported materials (for blocks and containers) can be found here. The list of supported entities (for spawners) can be found here. As of version 2.2.0, container types are now customizable and users can choose the kind of containers they wish to include. This is done by setting a list of containers within the container-type option which already has CHEST and TRAPPED_CHEST set by default as shown above.

Inventory Configurations

Inventory option is straightforward to work with and is found under the Inventory Configurations section of config.yml. It contains only one field of interest:

include-inventory: false

By default, it is set to false. If set to true, player inventories will be taken into account in the calculation of wealth. Values for items in inventories are configured within inventories.yml which can be found in the calculations folder. The list of supported materials can be found here. Note that as of version 2.2.0, only players who are online will have their inventories included in calculations.

PlaceholderAPI Configurations

PlaceholderAPI (PAPI) option is an advanced configuration that allows users to include PAPI values from other plugins in wealth calculation. Due to the great amount of customisation that this section brings about, do prepare for a lengthy read! The option to enable this can be found under the PlaceholderAPI Configurations section of config.yml. It contains only one field of interest:

include-papi: false

By default, it is set to false. If set to true, PAPI values (from other plugins) will be taken into account in the calculation of wealth. Values for PAPI are configured within papi.yml which is found in the calculations folder. Read on below to find out how to configure papi.yml.

By default, an example placeholder is provided within papi.yml under the custom category tax-paid. It uses the placeholder provided by one of my other plugins (QuickTax) as shown below:

tax-paid:
  - player;1.0;%qtax_player_total_paid%

You may create any amount of categories as you like, each with any number of PAPI placeholders you want (placeholders in same category will all be summed up). Note that for each placeholder, there are 3 important components to it (each separated by a semi-colon). From the example above, the 3 components would be player, 1.0 and %qtax_player_total_paid%.

The first component specifies the type of the placeholder. There are only 2 types, player and group. If enable-group is set to false (i.e. entity = player), then this value will always be player. On the other hand, if groups are enabled, then you will have to decide which type the placeholder value belongs to. For example, if your placeholder refers to a value belonging to the group as a whole, then the type will be group. On the other hand, if your placeholder value is retrieved from individual players within the group, then the type will have to be set as player. It may seem confusing at first so do try out both types if you are unsure.

The second component is much more straightforward and serves as the multiplier. This allows you to adjust how much of the values should be added into your wealth calculation. For example, if only half of the paid tax amount should be factored into the wealth, then the multiplier would be 0.5.

The third and also last component is simply the PAPI placeholder provided by the plugin of your interest. Note that you may use {name} to replace the name of your entity inside the placeholder.

After adding PAPI values into wealth calculations, you are likely to also want them to show up in user stats. Depending on whether you have GUI stats enabled, the stats will either be shown in the chat or in the GUI:

Adding to chat is extremely simple. Once you have your PAPI category setup properly, you can simply use the category name as the placeholder in your stats. For example, the category tax-paid will have the placeholder %tax-paid%. Simply adding this under entity-stats in your language file will allow the value for tax-paid to show up. An example built on top of the default template is as shown below (in the last line):

entity-stats: |
  &b----- &6%entity%'s Wealth &b-----
  &aTotal Wealth: &b%total-wealth%
  &aBalance Wealth: &b%balance-wealth%
  &aLand Wealth: &b%land-wealth%
  &aBlock Wealth: &b%block-wealth%
  &aSpawner Wealth: &b%spawner-wealth%
  &aContainer Wealth: &b%container-wealth%
  &aInventory Wealth: &b%inventory-wealth%
  &aTax Paid Wealth: &b%tax-paid%

For adding to GUI, refer to the GUI Customisation Section.

Leaderboard Configurations

The leaderboard section comes with extensive options (that look daunting at first but are actually very easy to understand) and can be found within the Leaderboard Configuration section. They are as listed below:

update-interval: 3600
update-on-start: false  
minimum-wealth: 0
filter-last-join: false
last-join-time: 2592000
total-leaderboard-positions: -1
leaderboard-positions-per-page: 10
use-interactive-leaderboard: false
commands-on-start:
  - broadcast &aSurvivalTop leaderboard update has started!
commands-on-end:
  - broadcast &aSurvivalTop leaderboard update has been completed!
leaderboard-blacklist:
  - FruznFever

By default, the update-interval is 3600 seconds which means the leaderboard updates every 1 hour. The update-on-start option also defaults to false which means the leaderboard will not perform an initial update on server start.

For users who wish to set a threshold for entities to appear on the leaderboard, the minimum-wealth option allows you to set a minimum wealth that an entity must have before they are included (defaults to 0).

The filter-last-join option is set to false by default and the value of last-join-time is ignored. This option is targeted mostly at very old or large servers that may have thousands or even tens of thousands of player data, many of them who no longer play actively and so calculating wealth for them may not be as relevant. With that in mind, setting filter-last-join to true will enable a filter to exclude players whose last join time exceeds the value set in last-join-time (in seconds). The lower the value, the more players excluded which will allow you to save plenty of time in making a leaderboard update.

For example, to exclude players who have not logged in the past 30 days, you will set last-join-time with a value of 2592000. Adjust this value accordingly based on your preferences. If 30 days is too long, try 14 days! Note that checking of stats remain unaffected by this option and that if you have enable-group set to true, then this option will be completely ignored.

The total-leaderboard-positions allows you to control how many players should be shown on the leaderboard while the leaderboard-positions-per-page lets you specify the number of entities that should be shown on each page.

There is also an option use-interactive-leaderboard that provides a breakdown of an entity's stats when players hover over them on the leaderboard. If use-gui-stats is set to true, players can even click entities on the leaderboard to open their GUI stats! This is disabled by default but enabling it would be a good quality of improvement for your players!

For taking actions during a leaderboard update, you may use commands-on-start and commands-on-end to specify commands to run before and after an update. In particular, commands-on-end provides 2 types of placeholders for you to access the entities on the leaderboard (maybe to reward them). The 2 types of placeholders are as such:

  • %player-{number}%
  • %group-{number}%

Replace {number} above with the position of the entity on the leaderboard. For example, to reward the top player with $1000 (using essentials), the command would be:

- eco give %player-1% 1000

Note that if you have groups enabled, %player-1% will refer to all players belonging to the group that is first in position. In addition, you will also have access to the %group-{number}% placeholder which gives you the name of the group.

Finally, the leaderboard-blacklist option allows you to specify players/groups to be exempted from showing up on the leaderboard. This may be useful if for example you wish to exclude administrators from the leaderboard. Note that if enable-group is false, then the names in the blacklist refer to player names. Otherwise if enable-group is true, then the names in the blacklist refers to group names.

Storage Configurations

Storage is optional for the functionality of this plugin and for the majority of the users, it is likely that this will be disabled. There is little reason to store the leaderboard unless for example, you have your own website that you wish to show the leaderboard on as well (in which case, storing it in MySQL and pulling the information from it is a viable use case).

Storage options can be found in the Storage Configurations section and comes with the following fields:

storage-type: None
host: 127.0.0.1
port: 3306  
user: survtop  
password: password  
database-name: survtop  
table-name: survtop

Note that the following three options are available for storage-type:

  • None
  • YAML
  • MySQL

By default, storage-type is set to None and you can ignore this entire section. If set to MySQL, you will need some knowledge on setting up a MySQL server for storing the leaderboard data. If set to YAML, then the creation of the YAML files are automatically done for you so there is no additional work required of you.

The remaining options of this section are only relevant if you are using MySQL and knowledge of these options are assumed if you choose to use this option.

Miscellaneous Configurations

The field below is classified as a miscellaneous option since it is irrelevant for most users.

town-block-size: 16

The town-block-size option is specific for Towny Advanced users. This option basically has to be the same as the town block size set in your Towny Advanced config.

Commands & Permissions

The plugin comes with the following permissions and their associated commands/actions:

Permission Nodes Recommended for Players:

  • survtop.help

    • Command: /st help
    • Description: list all commands

  • survtop.stats.self

    • Command: /st stats
    • Description: view your own wealth stats

  • survtop.gui.details.self

    • Command: None
    • Description: allow viewing of block/spawner/container/inventory breakdown in GUI for self

  • survtop.top

    • Command: /st top
    • Description: view wealth leaderboard

  • survtop.iteminfo

    • Command: /st iteminfo
    • Description: view balance, block, spawner, container and inventory item values info

Permission Nodes Recommended for Admins:

  • survtop.stats.others

    • Command: /st stats
    • Description: view wealth stats of others

  • survtop.gui.details.others

    • Command: None
    • Description: allow viewing of block/spawner/container/inventory breakdown in GUI for others

  • survtop.update

    • Command: /st update
    • Description: trigger an update for the leaderboard

  • survtop.reload

    • Command: /st reload
    • Description: reload the plugin (existing calculations will be terminated)

  • survtop.dump

    • Command: /st dump
    • Description: dump logs for debugging

  • survtop.sign.add

    • Command: None
    • Description: allow adding of leaderboard signs

  • survtop.sign.remove

    • Command: None
    • Description: allow removing of leaderboard signs

Leaderboard Signs Setup

  • Place a wall sign and type the following:

    • 1st line of sign: survivaltop
    • 2nd line of sign: <rank>

  • Note that the above refers to the leaderboard rank that you wish to set the sign for. So for example, here is what you will type exactly for a leaderboard rank 1 sign:

    • 1st line of sign: survivaltop
    • 2nd line of sign: 1

  • The 3rd and 4th line will be automatically updated with information about the player at that particular position.

  • Player heads are optional and should you wish to include them, you may place any player head one block directly above the sign or one block above the block on which the wall sign is being placed on.

  • The leaderboard signs and heads will then automatically update themselves on every leaderboard update.

Hex Color Codes

As of version 3.1.1, the plugin also supports hex color codes throughout the plugin. An example usage for red (#ff0000) color in the reload message is as shown below:

  • '#ff0000SurvivalTop has been reloaded!'

Note that since # is now identified as a special character for hex color code, you will need to escape it with \# if you want to use # in your string without it being interpreted as a color code.

Normal minecraft color codes (e.g. '&c') are still supported!

GUI Customisation

All GUI menus found in the plugin are completely customisable. There are 2 types of GUI (1 for item info and 1 for stats) and each of them comes with a main page and several subpages. The settings for the GUI may be found inside their respective info.yml and stats.yml file contained inside the menu folder. Both files share a similar configuration structure and comments have been written above each setting to guide users (the approach for customising both GUI are the same). You will find the following settings for customizing the main page:

  • main-page-title
  • main-page-size
  • main-page-buttons
  • main-page-background

As the main-page-title setting imply, this is used to set the title of the main page. Naturally, main-page-size decides the size of the menu. Note that sizes have to be in multiples of 9 (other values will be rounded up to the nearest multiple). Under main-page-buttons, settings for the buttons that appear on the main page are set. However, only block, spawner, container and inventory buttons are clickable (i.e. able to access subpages) since these come with more detailed breakdowns while others do not. Within each button, you will also find a list of fields which are slot, name, lore, material and enchanted. These are self-explanatory fields for setting the position and details of the items to use for the buttons. Finally, main-page-background is used to set the slot and material to use for the main page background.

For the subpages, we have the following settings:

  • sub-page-block-title
  • sub-page-spawner-title
  • sub-page-container-title
  • sub-page-inventory-title
  • sub-page-size
  • sub-page-buttons
  • sub-page-items
  • sub-page-background

The title, size, buttons and background settings above are similar to their counterpart settings for the main page. However, for the subpages, the buttons are for returning to main menu or navigating the pages. There is also a unique setting here with no counterpart on the main page, that is sub-page-items. Within this, you will find a list of fields which are name, lore and slots. These are also self-explanatory fields for setting the positions and details of the items in subpages that are set in blocks.yml, spawners.yml, containers.yml and inventories.yml.

Finally, it is also possible to add your own buttons (although unclickable) for the PAPI values that you have included in your wealth calculations. Adding to GUI is slightly more complicated than adding to chat but is still relatively straightforward. Note that the instructions here applies to both item info and stats menu (in case you want to add your PAPI category to both). More specifically, to add to the stats GUI, you would open up the stats.yml file and under main-page-buttons, add a new button with the key being the name of your PAPI category. For example, to add the tax-paid category into your stats GUI, the new entry would look as such:

tax-paid:
    slot: 17
    name: "&bTax Paid Wealth"
    lore:
      - "&eValue: &a%value%"
    material: GOLD_INGOT
    enchanted: false

Ensure that the key used here is exactly the same as your PAPI category in order for the values to show up correctly in your GUI!

PAPI Placeholders

The plugin also provides its own PlaceholderAPI support. Note that {} brackets indicate variable names e.g. {position} represents leaderboard position and {name} represents entity name

You may find leaderboard placeholders below.

  • %survtop_top_name_{position}%: name of entity at specified leaderboard position, default is "None"
  • %survtop_top_wealth_{position}%: wealth of entity at specified leaderboard position, default is "0"

You may find entity stats placeholders below. Note that if {name} is omitted e.g. %survtop_entity_position%, then the name of the sender is used instead (i.e. stats retrieved are those of the sender).

  • %survtop_entity_position_{name}%: position of entity for its given name, default is "None"
  • %survtop_entity_total_wealth_{name}%: total wealth of entity as last calculated in leaderboard update, default is "0"
  • %survtop_entity_bal_wealth_{name}%: balance wealth of entity as last calculated in leaderboard update, default is "0"
  • %survtop_entity_land_wealth_{name}%: land wealth of entity as last calculated in leaderboard update, default is "0"
  • %survtop_entity_block_wealth_{name}%: block wealth of entity as last calculated in leaderboard update, default is "0"
  • %survtop_entity_spawner_wealth_{name}%: spawner wealth of entity as last calculated in leaderboard update, default is "0"
  • %survtop_entity_container_wealth_{name}%: container wealth of entity as last calculated in leaderboard update, default is "0"
  • %survtop_entity_inv_wealth_{name}%: inventory wealth of entity as last calculated in leaderboard update, default is "0"
Clone this wiki locally