Skip to content

Tutorial

Jump to bottom
Tan Jin edited this page Apr 24, 2024 · 35 revisions

Overview

Welcome to the plugin tutorial! This plugin is compatible with any vault-based economy plugin (minimally, Vault and an economy plugin must be installed). It also comes with additional support for GriefPrevention for those who are looking to include property taxes (support for other forms of land claim plugins is currently not supported). The plugin currently also supports 5 ways to collect taxes:

  1. Collect from all players (collectall)
  2. Collect directly from a player (collectname)
  3. Collect based on rank (collectrank)
  4. Collect based on balance (collectbal)
  5. Collect based on activity (collectactivity)

Note: For configuring schedule.yml, please refer to the default configuration that can be found here where comprehensive examples with explanations have been included.

Initial Setup

The initial setup of the plugin is very simple. By default, there are no tax schedule collections enabled so it is safe to just load the plugin without fearing any economical damage. 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
enable-sound: true
play-sound: ENTITY_PLAYER_LEVELUP
debt-mode: 0
debt-commands:
  - broadcast &b%player% &cdoes not have enough money to pay taxes!

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.

In addition, you may optionally play a sound to players during tax collection via the enable-sound field. If enabled, then the sound chosen via the play-sound field will be played to players during tax collections.

The last 2 options debt-mode and debt-commands are only applied in cases where players do not have enough balance to pay off their taxes. There are a total of 3 debt modes:

  • 0 - player will not be taxed at all (exempted)
  • 1 - player will be taxed all current balance (balance will essentially be set to 0)
  • 2 - player will be taxed the full amount (player will end up with a negative balance)

Regardless of the chosen debt-mode, the debt-commands will run for any player that does not have enough money to pay taxes. This option is useful if you have other forms of penalty you wish to run via commands.

Leaderboard Configurations

The leaderboard section can be found within the Leaderboard Configuration section. The fields provided are as listed below:

update-interval: 3600
update-on-start: false

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

Storage Configurations

Storage is optional for collecting taxes using this plugin, although it is required for features such as tracking player stats as well as having a leaderboard. 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: quicktax
password: password
database-name: quicktax
table-name: quicktax

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.

Grief Prevention Integration

If you have grief prevention installed and wish to include it as a form of property tax, then this section is for you and contains the following fields:

tax-claims: false
active-claims-only: false
auto-remove-claims: false

By default, tax-claims is set to false. You will need to set it to true in order to collect taxes by claims. In addition, if active-claims-only is set to true, then only claimblocks that are used will be factored into the calculations for tax collection.

Lastly, if auto-remove-claims is set to true, players who do not have enough balance to pay taxes will have all their claims removed so use this option cautiously. Note that auto-remove-claims also requires tax-claims to be set to true to work.

Collecting Tax from All Players

Collecting tax from all players applies to offline players as well. The fields for collecting tax from all players are as shown below:

all:
  use-percentage: false
  bal-amount: 100
  claims-ratio: 0.0

As you may have guessed, bal-amount is the tax amount to be collected from players. This is a flat amount if use-percentage is set to false. However, if use-percentage is set to true, then bal-amount will be interpreted as a percentage where 0.1 = 10%. The last field, claims-ratio is used to determine how much to tax based on claimblocks where 0.1 = $0.1 for every 1 claimblock.

Note: Although not an encouraged use-case, it is possible as of version 1.4.3 to set negative values for balance amount which will give money from the server tax account to the players instead. Use this cautiously!

Collecting Tax from Named Player

There is no configuration needed for collecting taxes from a player directly. This is the only collection type that has no configuration as its usage is as shown in the example command below that taxes $100 from the player FruznFever:

/qt collectname FruznFever 100

Collecting Tax by Rank

For collecting tax by ranks, make sure you have a permissions plugin setup and that the ranks you configure here matches the ranks defined in the permission plugin. The fields for collecting tax from players by rank are as shown below:

rank-bracket:
  use-percentage: false
  ranks:
    Knight:
      bal: 300
      claims-ratio: 0.0
      use-percentage: false
    Apprentice:
      bal: 200
      claims-ratio: 0.0
    Novice:
      bal: 100
      claims-ratio: 0.0

Notice that similar to Collecting Tax from All Players, there are the use-percentage, bal and claims-ratio fields. These fields are used in the same way as defined in the above section.

The difference lies in the fact that each rank you wish to tax is defined under ranks, along with their own bal and claims-ratio. Notice that use-percentage is defined twice, once at the top of the section and once within each tax bracket. The use-percentage within tax brackets is optional and serves to override the top value if you wish to apply percentage tax to only specific brackets. In the example above, the Knight, Apprentice and Novice ranks have been defined.

Collecting Tax by Balance

A common use-case, collecting tax by balance allows you to collect more from the richer players while sparing those who are just starting out. The fields for collecting tax from players by balance are as shown below:

bal-bracket:
  use-percentage: false
  amount:
    100000:
      bal: 300
      claims-ratio: 0.0
      use-percentage: false
    10000:
      bal: 200
      claims-ratio: 0.0
    1000:
      bal: 100
      claims-ratio: 0.0

Notice that similar to Collecting Tax from All Players, there are the use-percentage, bal and claims-ratio fields. These fields are used in the same way as defined in the above section.

The difference lies in the fact that there are different balance brackets defined under amount, along with their own bal and claims-ratio. In the example above, the $100000, $10000 and $1000 balance brackets have been defined. In the example above, players with balance >= $100000 are taxed $300, players with balance >= $10000 are taxed $200 while players with balance >= $1000 are taxed $100. This also means players with less than $1000 are not taxed.

If you need clarifications on why use-percentage appears twice, refer to the section on Collecting Tax By Rank.

Collecting Tax by Activity

This option is for taxing players based on their last seen activity (last login). The fields for collecting tax from players by activity are as shown below:

activity-bracket:
  use-percentage: false
  last-seen:
    604800:
      bal: 300
      claims-ratio: 0.0
      use-percentage: false
    86400:
      bal: 200
      claims-ratio: 0.0
    0:
      bal: 100
      claims-ratio: 0.0

Notice that similar to Collecting Tax from All Players, there are the use-percentage, bal and claims-ratio fields. These fields are used in the same way as defined in the above section.

The difference lies in the fact that there are different activity brackets defined under last-seen, along with their own bal and claims-ratio. In the example above, the 604800 (1 week), 86400 (1 day) and 0 (online) balance brackets have been defined. In the example above, players who last logged in over a week ago are taxed $300, players who last logged in over a day ago are taxed $200 while players who logged in less than a day ago or are online are taxed $100.

If you need clarifications on why use-percentage appears twice, refer to the section on Collecting Tax By Rank.

Paying Taxes / Withdrawing Money

Players are able to pay taxes at their own discretion if permission is given for the /qt pay command. This is useful in cases where you want to encourage players to pay taxes on their own accord as opposed to using collection schedules.

On the otherhand, the /qt server withdraw command takes money from the server tax balance and gives it to the command sender or a specified player. Note that this feature requires storage to be enabled since the server tax balance needs to be valid.

Finally, if you are an admin, you may also modify the server balance directly by using the /qt server admin add, /qt server admin take or /qt server admin set commands. These commands will modify the server tax balance without affecting the balance of anyone. As you may have guessed, these commands also require storage to be enabled to access the server tax balance.

Commands & Permissions

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

Permission Nodes Recommended for Players:

  • quicktax.help

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

  • quicktax.pay

    • Command: /qt pay
    • Description: pay tax to the server

  • quicktax.top

    • Command: /qt top
    • Description: view tax payer leaderboard

  • quicktax.stats

    • Command: /qt stats
    • Description: view your own tax stats

  • quicktax.schedule.view.enabled

    • Command: /qt schedule view
    • Description: view enabled tax collection schedules

Permission Nodes Recommended for Admins:

  • quicktax.stats.others

    • Command: /qt stats
    • Description: views a specific player's tax stats

  • quicktax.collectall

    • Command: /qt collectall
    • Description: taxes all players

  • quicktax.collectrank

    • Command: /qt collectrank
    • Description: taxes players based on rank

  • quicktax.collectbal

    • Command: /qt collectbal
    • Description: taxes players based on balance

  • quicktax.collectactivity

    • Command: /qt collectactivity
    • Description: taxes players based on activity

  • quicktax.collectname

    • Command: /qt collectname
    • Description: taxes a specific player

  • quicktax.server.stats

    • Command: /qt server stats
    • Description: views the server total tax stats

  • quicktax.server.withdraw.self

    • Command: /qt server withdraw
    • Description: withdraws money to self from server tax balance

  • quicktax.server.withdraw.others

    • Command: /qt server withdraw
    • Description: withdraws money to player from server tax balance

  • quicktax.server.admin.add

    • Command: /qt server admin add
    • Description: adds money to the server tax balance

  • quicktax.server.admin.take

    • Command: /qt server admin take
    • Description: takes money from the server tax balance

  • quicktax.server.admin.set

    • Command: /qt server admin set
    • Description: Sets the server tax balance

  • quicktax.schedule.start

    • Command: /qt schedule start
    • Description: starts tax collection schedule

  • quicktax.schedule.stop

    • Command: /qt schedule stop
    • Description: stops tax collection schedule

  • quicktax.schedule.view.*

    • Command: /qt schedule view
    • Description: views all schedules

  • quicktax.schedule.view.disabled

    • Command: /qt schedule view
    • Description: view disabled tax collection schedules

  • quicktax.update

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

  • quicktax.reload

    • Command: /qt reload
    • Description: reload the plugin

  • quicktax.sign.add

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

  • quicktax.sign.remove

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

Permission Nodes For Tax Exemptions:

  • quicktax.exempt.*

    • Command: None
    • Description: exempts a player from all forms of tax collections

  • quicktax.exempt.collectname

    • Command: None
    • Description: exempts a player from collection by name

  • quicktax.exempt.collectall

    • Command: None
    • Description: exempts a player during collection from all players

  • quicktax.exempt.collectrank

    • Command: None
    • Description: exempts a player from collection by rank

  • quicktax.exempt.collectbal

    • Command: None
    • Description: exempts a player from collection by balance

  • quicktax.exempt.collectactivity

    • Command: None
    • Description: exempts a player from collection by last seen activity

Leaderboard Signs Setup

  • Place a wall sign and type the following:

    • 1st line of sign: quicktax
    • 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: quicktax
    • 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 1.6.0, the plugin also supports hex color codes in messages. An example usage for red (#ff0000) color in the reload message is as shown below:

  • '#ff0000QuickTax 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!

PAPI Placeholders

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

You may find leaderboard placeholders below.

  • %qtax_top_name_{rank}%: name of entity at specified leaderboard position, default is "None"
  • %qtax_top_tax_{rank}%: tax paid by entity at specified leaderboard position, default is "0"

More placeholders are also available as shown:

  • %qtax_server_tax_collected% - total server tax collected
  • %qtax_server_tax_balance% - total server tax balance
  • %qtax_player_total_paid% - player's total tax paid
  • %qtax_player_last_paid% - player's last tax paid
  • %qtax_schedule_type_{scheduleName}% - get the schedule type
  • %qtax_schedule_freq_{scheduleName}% - get the schedule frequency (seconds)
  • %qtax_schedule_next_run_{scheduleName}% - get the time for schedule's next run
  • %qtax_schedule_timezone_{scheduleName}% - get the schedule timezone
  • %qtax_schedule_last_collected_{scheduleName}% - get the last collected tax amount for schedule
  • %qtax_top_name_{rank}% - get the player name at specified rank
  • %qtax_top_tax_{rank}% - get the player total tax paid at specified rank
Clone this wiki locally