Currency System
The New Economy supports multiple currencies, which range in various types from world-specific to WorldGuard Region-specific. On top of the type of currency, TNE also supports multiple categories of currencies. These categories are item, virtual and experience.
In this section, we'll cover the various currency categories, and what each is.
The item category sets the currency to be based on an in-game item. A common example of this would be Gold Ingots. Using this category would mean whenever a player picks up a gold ingot, they'd gain more money for their overall balance.
The experience category sets the currency to be based on a player's total experience that they have obtained via experience orbs, or other methods. When using this category, a player's balance is displayed where their experience level is located.
The virtual category is based on nothing. Essentially, it is just a value stored in a database with no physical form backing it. This is also one of the most common currency categories found in Minecraft Servers, as well as, online games in general.
Some basic terminology used within this page. It will be assumed that you have read through the following terms throughout the documentation on this page.
This is a currency denomination. Examples(in USD): Penny, Nickel, Dime, Ten Dollar Bill, One Dollar Bill.
This is a currency tier, which is a whole number and greater than 0. This is equivalent to a real-world note, or paper bill.
This is a currency tier, which is a decimal. This is equivalent to a real-world coin.
In this section, we'll cover the different parts of a currency, as defined in the config.yml Core.Currency section.
This section contains basic information about the currency.
Accepted Values: true, false What it does: If set to true, it'll make TNE use the currency configuration in advanced.yml, instead of the one in config.yml. If you set this to true, skip to the Advanced Currency Anatomy section for how to configure your currency system.
This section contains the configurations nodes used to configure a basic currency system for your server. Note: This section of config.yml is ignored if Core.Currency.Info.Advanced is set to true.
This is used to specify the singular form of your major currency tier's name. Example: Dollar
This is used to specify the plural form of your major currency tier's name. Example: Dollars
This is used to specify the singular form of your minor currency tier's name. Example: Cent
This is used to specify the plural form of your minor currency tier's name. Example: Cent
This is used to specify the valid prefixes that will be used when you have included in your currency format. This is based on this site's chart http://www.unitarium.com/si-prefixes.
Example: k for thousands, M for millions
This is used to specify the character to use as a symbol for your currency. Example: $ for United States Dollar
This is used to specify if your currency should be categorized as an item-based currency. Please see the above Currency Categories sections for more information about the Item Category.
This is used to specify if your currency should be categorized as an experience-based currency. Please see the above Currency Categories sections for more information about the Experience Category. Note: This configuration is ignored if ItemCurrency is set to true.
This section holds items, and their values if ItemCurrency is set to true. The format is Minecraft Material Name: Value.
This section holds items, and their values if ItemCurrency and ExperienceCurrency are both set to false. The format is Tier Name: Value. Tier Name should be unique, and is equivalent to denomination name.
This section contains various options that may be used to control your currency in greater detail.
This is the format to use for the currency. Formatting is used anytime an amount of money is sent in chat. If you have anywhere in your format, the format specified will be ignored, and the predefined short format will be used by TNE. Variables allowed:
<symbol> - The currency's symbol
<decimal> - The currency's decimal.
<major> - A combination of the currency's major amount and name
<minor> - A combination of the currency's minor amount and name
<major.name> - The currency's major name.
<minor.name> - The currency's minor name.
<major.amount> - The currency's major amount.
<minor.amount> - The currency's minor amount.
<short.amount> - The currency's shortened amount.
<shorten> - Added to make the outputted value shortened
You may also use the following colour codes in your format.
Char Alt &b <aqua> &0 <black> &9 <blue> &3 <dark_aqua> &1 <dark_blue> &8 <dark_gray> &2 <dark_green> &5 <dark_purple> &4 <dark_red> &6 <gold> &7 <gray> &a <green> &d <purple> &c <red> &f <white> &e <yellow> &k <magic> &l <bold> &o <italic> &r <reset> &m <strike> &n <underline>
This is the max amount of currency any player may have at one time. The max supported value is 900 Nonvigintillion.
This is the amount of money players start with when they first log in.
This is the character to use as a decimal in your currency amounts. In the US we use the decimal point ".". Some countries use a comma ",".
Whether or not to include currency items that are in a player's ender chest in their available balance. Note: This value is ignored if ItemCurrency is set to false.
Whether or not to separate the major value of a player's balance during formatting. If set to false a formatted balance may look like this: 900000. If set to true a formatted balance may look like this: 900,000.
This is the character to use for separation if Major_Separate is set to true. In the example above, the Major_Separator value is set to ",". Note: If Major_Separate is set to false this value is ignored.
This is the amount of minor denominations are used to make one major denomination. Example: 100 pennies in 1 dollar for the United States Dollar.
This section contains various options that are used for currency noting, i.e. /money note. Currency noting is used to withdraw an amount of virtual currency into a physical item for storage, or trading.
This is to specify whether or not players may use /money note with the basic currency.
This is the fee charged to the player when using /money note.
This is the minimum value of a virtual currency that a note may be.
In this section, we'll cover the different parts of a currency, as defined in the plugins/TheNewEconomy/currencies/ directory.
Before Reading Further: Please remember to read the terminology section above. The advanced currency system enables TNE server owners to configure an unlimited amount of tiered-currencies for their server. This can be a simple single tier currency or a complete recreation of a real-world currency such as the United States Dollar.
After your initial run you'll notice a new directory called "currencies" gets created in TheNewEconomy directory of your plugins folder.
This directory, by default, contains USD.yml. This is where all the main configurations pertaining to the USD currency are kept(outlined in red). The name of the YAML file is simply for organizational purposes, but it is recommended to keep it the same as your actual currency's name.
You'll also notice a directory, outlined in blue, called "USD." This is where all the configuration files for USD's tiers, or denominations, are kept.
The first thing you may notice is that USD has two tiers, one and penny. The file names don't have to be the same name as the tiers themselves, but it is recommended for organizational purposes.
In this portion, we'll cover the contents of USD.yml, which contains the basic configurations of the currency.
This configuration deep dive is broken down into the parts of the configuration file(Info, Options, Note, and Conversion). We'll cover each configuration node, and what the purpose of it is.
This section of the configuration file contains options that are used to identify the currency. These are the main options of the currency.
Description: This is the name of the server the currency belongs to. This is for data saving purposes.
Default: Main Server
Description: This is a unique identifier for the currency. This value is used for data purposes, as well as identifying the currency in command arguments.
Default: "USD"
Description: This is used to specify the singular form of your major currency tier's name.
Default: Dollar
Description: This is used to specify the plural form of your major currency tier's name.
Default: Dollars
Description: This is used to specify the singular form of your minor currency tier's name.
Default: Cent
Description: This is used to specify the plural form of your minor currency tier's name.
Default: Cent
Description: This is used to specify the valid prefixes that will be used when you have included in your currency format. This is based on this site's chart http://www.unitarium.com/si-prefixes.
Default: kMGTPEZYXWVUN
Example: k for thousands, M for millions
Description: This is used to specify the character to use as a symbol for your currency.
Default: $ for United States Dollar
Description: This sets whether or not this currency is the default for the world. Please note only one currency should be set as the world default.
Default: true
Description: This is the worlds that this currency is able to be used in. The format is - "world name". Please note that each world name entry should be put on a new line. This is ignored if Global is set to true.
Default: - "world"
Description: This sets whether or not this currency is a global currency and is able to be used in every world.
Default: true
Description: This sets whether or not this currency is disabled. Disabled currencies are not able to be used in any world.
Default: false
Description: This is the format to use for the currency. Formatting is used anytime an amount of money is sent in chat. If you have anywhere in your format, the format specified will be ignored, and the predefined short format will be used by TNE. Variables allowed:
<symbol> - The currency's symbol
<decimal> - The currency's decimal.
<major> - A combination of the currency's major amount and name
<minor> - A combination of the currency's minor amount and name
<major.name> - The currency's major name.
<minor.name> - The currency's minor name.
<major.amount> - The currency's major amount.
<minor.amount> - The currency's minor amount.
<short.amount> - The currency's shortened amount.
<shorten> - Added to make the outputted value shortened
You may also use the following colour codes in your format.
Char Alt &b <aqua> &0 <black> &9 <blue> &3 <dark_aqua> &1 <dark_blue> &8 <dark_gray> &2 <dark_green> &5 <dark_purple> &4 <dark_red> &6 <gold> &7 <gray> &a <green> &d <purple> &c <red> &f <white> &e <yellow> &k <magic> &l <bold> &o <italic> &r <reset> &m <strike> &n <underline>
Default: <major.amount><minor.amount>
Description: This is the max amount of currency any player may have at one time. The max supported value is 900 Nonvigintillion.
Default: 900000000000000000000000000000000000000000000
Description: This is the amount of money players start with when they first log in.
Default: 200.0
Description: This is the character to use as a decimal in your currency amounts. In the US we use the decimal point ".". Some countries use a comma ",".
Default: .
Description: This is the amount of decimal places shown when displaying the player's balance. The maximum value is 4.
Default: 2
Description: This is the currency type, referred to above in the Currency Categories section. The valid values are virtual, item, and experience
Default: virtual
Description: Whether or not to include currency items that are in a player's ender chest in their available balance. Note: This value is ignored if Type is not item
Default: true
Description: Whether or not to separate the major value of a player's balance during formatting. If set to false a formatted balance may look like this: 900000. If set to true a formatted balance may look like this: 900,000.
Default: true
Description: This is the character to use for separation if Major_Separate is set to true. In the example above, the Major_Separator value is set to ",". Note: If Major_Separate is set to false this value is ignored.
Default: ,
Description: This is the amount of minor denominations are used to make one major denomination. Example: 100 pennies in 1 dollar for the United States Dollar.
Default: 100
This section of the configuration file contains options that affect currency notes for the currency. These are obtained using /money note.
Description: This denotes if the currency is able to be noted. If this is set to true then players may create currency notes for this currency.
Default: false
Description: This is the fee charged for creating a currency note for this currency. If this is set to 10 and a player creates a note for 20 monies then the player will receive a currency note with a value of 20 but will be charged a total of 30 monies for creating the note.
Default: 0.00
Description: This is the minimum value a currency note for this currency may be. Please note the lowest possible value is 0.0.
Default: 0.00
Description: This contains configurations relating to what the currency note item is. By default currency notes are a piece of paper, but this allows you to let them be anything from Diamonds to custom resource pack items.
Description: This is the name of the item that the currency note is. The value of this configuration should align with your items.yml file in TheNewEconomy directory.
Default: PAPER
Description: This is the model data for the material item. This is used for custom resource pack items and should align with their model data value. A deeper explanation of model data may be found here.
Default: 0
Description: This is the base64 of a custom texture if Material is set to PLAYER_HEAD. This is used to use custom player heads. There's plenty of sites to obtain this value from, I recommended minecraft-heads.com.
Default: eyJ0ZXh0dXJlcyI6eyJTS0lOIjp7InVybCI6Imh0dHA6Ly90ZXh0dXJlcy5taW5lY3JhZnQubmV0L3RleHR1cmUvZDA0NzE5YjNiOTdkMTk1YTIwNTcxOGI2ZWUyMWY1Yzk1Y2FmYTE2N2U3YWJjYTg4YTIxMDNkNTJiMzdkNzIyIn19fQ
Note: The default value for this sets the player head to a money bag texture for a more immersive economic experience.
Description: This allows you to add enchantments to currency notes. The format is - "enchantment name". Remember that each enchantment entry should be on a new line. For a list of valid values please check here.
Default: - "example_enchantment"
Description: This allows you to add item flags to currency notes. These allow you to add various settings to the item such as hide enchantments. The format is - "flag name". Remember that each flag entry should be on a new line. For a list of valid values please check here.
Default: - "example flag"
This section of the configuration file contains options which affect converting between this currency and others.
Description: This is the conversion power of the currency. This is based on a decimal conversion system where 1.0 is equivalent to 100%, or a 1-to-1 conversion.
Default: 1.0
In order to create additional currencies, you'll want to create a new YAML file in the /currencies directory, and copy over the contents of USD.yml and modify to your likings. The recommended naming scheme is .yml.
In this portion, we'll cover the contents of one.yml, which contains the configurations of a currency tier, or denomination. The tier configuration files are located in plugins/TheNewEconomy/currencies//.
This configuration deep dive is broken down into the parts of the configuration file(Info, Options). We'll cover each configuration node, and what the purpose of it is. You'll notice some configurations will have "Note: Optional" under their description, this notates that the specific configuration is not required and doesn't have to be in the tier YAML file. Another thing to note is that you may see "Note: Item Only" under some configuration descriptions. This means that the configuration is only used if your currency's type is set to "item" and not "virtual" or "experience."
This section of the configuration file contains options that are used to identify the tier. These are the main options of the tier.
Description: This is the type of currency tier, or denomination, that this file represents. There's two viable options for this configuration, which are major and minor. The major type should be used to represent tiers that have a value that is a whole number such as 1, 5, 10, etc. Minor tiers should be used to represent tiers that have a value that is decimal-based such as .5, .01, .25, etc.
Default: Major
Description: This is used to specify the singular form of your tier's name.
Default: One
Description: This is used to specify the plural form of your tier's name.
Default: Ones
Description: This is the weight of the tier. Major weights are 1 based while minor weights are .01 based. This means that a Minor Tier with the weight of 1 is actually equivalent to 0.01 while a Major Tier with the same weight is equivalent to 1.
Default: 1
Description: This is the name of the item that represents this currency tier. The value of this configuration should align with your items.yml file in TheNewEconomy directory.
Note: Item Only
Default: PAPER
Description: This is the damage value of the item that is used to represent the currency tier. This is a legacy Minecraft value and should be ignored in versions above 1.8.
Note: Item Only
Note: Optional
Default: 0
Description: This is the name that is shown on the item that represents the currency tier. This is displayed in the image above outlined in red.
Note: Item Only
Note: Optional
Default: "One"
Description: This is the lore string that is shown on the item that represents the currency tier when hovered over. This value is not able to be added onto items by players, which makes crafting your currency by normal means impossible. This is displayed in the image above outlined in blue.
Note: Item Only
Note: Optional
Default: "Server Currency"
Description: This is the model data for the material item. This is used for custom resource pack items and should align with their model data value. A deeper explanation of model data may be found here.
Default: 0
Description: This allows you to add enchantments to currency tier items. The format is - "enchantment name". Remember that each enchantment entry should be on a new line. For a list of valid values please check here.
Default: - "example_enchantment"
Description: This allows you to add item flags to currency tier items. These allow you to add various settings to the item such as hide enchantments. The format is - "flag name". Remember that each flag entry should be on a new line. For a list of valid values please check here.
Default: - "example flag"
TNE provides configurations to add custom crafting recipes for your currency items. This configuration section covers all options relating to this custom crafting system for the currency tier. This section is only relevant if your currency type is "item." The image below is the result of the default crafting configurations and will be referenced below.
Description: This sets whether or not the currency tier item may be crafted.
Default: false
Description This sets whether the recipe is shapeless, or shaped. A shapeless recipe just requires the correct amount of materials. While a shaped recipe requires that the materials be in a specific order in the crafting matrix. An example of a shaped recipe is minecart rails.
Default: false
Description: This is the amount of currency items the recipe will return. If this is set to 5 then the player will get 5 currency items for every time they craft the recipe.
Default: 1
Description: These are the materials that each character in the Recipe configuration represent. The format is Character:Material Name. If you wish to use other currency items in your crafting recipe the format is Character:CURRENCY:World Name:Currency Identifier:Tier Singular Name. If you wish to use other currency items, you'll have to set Shapeless to false and be on Minecraft 1.13 or higher.
Default:
- "X:GOLD_NUGGET"
- "Y:PAPER"Description: This is the crafting recipe for the currency tier item. The crafting recipe should be a maximum of 3 lines with a maximum of 3 characters in length for each line. A space character represents an empty slot if Shapeless is set to false. The characters in the recipe should match the ones set in the Crafting.Materials configuration. The following recipe is the one used for the example recipe image at the top of the Crafting section of this documentation.
Default:
- " X "
- "XYX"
- " X "Expanded Explanation: In the default value, the X, as defined in Materials, represent Gold Nuggets, while the Y represents paper. This gives us a shaped recipe that is identical to the one in the image above.
In order to create additional tiers, you'll want to create a new YAML file in the /currencies// directory, and copy over the contents of one.yml and modify to your likings. The recommended naming scheme is .yml.