Guide to stats and the stats.yml file
Stats are values that represent specific gameplay buffs called traits. A player's stat levels and their descriptions can be viewed in the stats menu using /stats or by clicking the stat item (their player head by default) in the main skills menu.
Stats are gained alongside leveling skills; each skill has a primary stat that increases for every skill level and a secondary stat that increases every other skill level. These are configured through stat rewards. Stats can also be increased through modifiers created with commands or on items.
Traits are values for the singular gameplay aspect that a stat affects. Since some stats have multiple effects, such as Wisdom's experience bonus and max mana increase, traits allow these effects to be configured independently as well as swapped between stats. Traits increase in value based on a constant multiplier of the stat level, which allows stat levels to display in a more user-friendly level while the trait is decimal that directly shows its effect.
There are 9 stats by default, with the trait(s) they level up also shown:
Strength -> Attack Damage
Health -> Hp
Regeneration -> Saturated Regen, Hunger Regen, Mana Regen
Luck -> Farming Luck, Foraging Luck, Mining Luck, Excavation Luck, Fishing Luck
Wisdom -> Experience Bonus, Anvil Discount, Max Mana
Toughness -> Damage Reduction
Crit Chance -> Crit Chance
Crit Damage -> Crit Damage
Speed -> Movement Speed
Stats and traits are configured in the stats.yml file. Each stat has a section named after its full Namespaced ID (prefixed with auraskills/ for all default stats) in the stats section. Each trait has a similar section under traits. Below is an example stat section for Regeneration with comments explaining each option:
The traits section contains configurable options specific to each trait. These options were formerly in their stats' section before 2.0. If the enabled option (common to all traits) is set to false, the trait will have no effect in game and will be hidden from menus.
hand_damage - Whether damage from hitting with an empty hand should be affected.
bow_damage - Whether damage from bows and projectiles should be affected.
display_damage_with_health_scaling - If true, the damage numbers in the menus and damage holograms will be scaled based on the action_bar_scaling option in the auraskills/hp trait section.
use_percent - Whether the attack damage bonus should be applied as a percent increase of the base damage. If false, damage will be added as the flat trait value.
health_scaling - Whether the player's displayed hearts should be scaled, meaning 2 HP = 1 heart does not apply at higher HP levels. This means it requires increasing amounts of HP to get an additional visual heart, which prevents hearts blocking too much of the screen at high HP values. This options is entirely visual and does not affect the real amount of HP of the player, which is what is shown on the action bar. The scaling amounts are configured by the hearts option.
hearts - A map of entries that determine when extra visual hearts are shown if health_scaling is enabled. The key is the index of the heart and the value is the real HP number needed for that heart to be shown. For example, '17': 48 means that the 17th heart (7th extra heart) will be shown when the player has at least 48 HP (number on the action bar).
action_bar_scaling - A number that is multiplied by the player's Minecraft HP to determine the HP number shown on the action bar (and damage numbers if display_damage_with_health_scaling in strength in enabled).
update_delay - The number of ticks to delay recalculating and applying the player's health on join or world change. Set this to 1 if you are having compatibility issues with mini-game plugins where health is too high when switching back to the main world.
force_base_health - If true, the player's base health attribute value will be forced to 20 on every refresh. Only enable if you have compatibility issues with other plugins.
keep_full_on_increase - If true, increases in a player's max health when the player is already at full HP will automatically set them at the new max HP.
ensure_scaling_disabled - Disables health scaling if the trait is disabled in order to remove past health scaling. Set to false if you have another plugin that is handling health scaling.
use_custom_delay - If true, the vanilla system for health regeneration will be replaced by a custom timer with a customizable delay and base value.
delay - The number of ticks between health regen if use_custom_delay is enabled.
base - The base HP to regenerate if use_custom_delay is enabled.
base - The base amount of mana to regenerate per second when the trait is at level 0.
max_percent - The cap for the percent chance to double drop blocks.
allow_overflow - Whether to allow mana amounts higher than max, such as when a player's max mana decreases but their previous mana was higher than the new max.
base - The base amount of max mana players have when the trait is at level 0.
formula - The formula for calculating damage reduction from the trait value. The input variable value is the trait value (which is after the stat value is multiplied by the trait modifier). The expression result is a decimal from 0 to 1 where 0 is no damage reduction and 1 is all damage blocked. For example, an expression result of 0.32 means 32% damage reduction.
base - The base amount of crit chance players have when the trait is at level 0.
base - The base amount of crit damage players have when the trait is at level 0.
max - The maximum movement speed value.
Guide to stat modifiers
Modifiers are temporary stat buffs on a player. They come in 3 different types and are interacted with primarily using commands. Regular modifiers are attached to a name and are always active unless removed. Item modifiers apply when holding an item. Armor modifiers apply when wearing armor.
Regular modifiers are the simplest type of modifier. You add and remove them using commands. Each modifier has 3 properties, a name, stat, and value.
The name is used to identify the modifier. You cannot have more than one modifier with the same name on a single player.
The stat property is which stat the modifier should be applied on. You must use the official stat names, which are health, strength, regeneration, luck, wisdom, and toughness.
The value property is how much the stat should increase/decrease. For example, a value of 50 would add 50 levels to whatever stat it was applied on. Negative values subtract levels.
The commands used to interact with them are:
/sk modifier add [player] [stat] [name] [value] (silent) - Adds a stat modifier to a player
/sk modifier remove [player] [name] (silent) - Removes a specific stat modifier from a player
/sk modifier list (player) (stat) - Lists all or a specific stat's modifiers for a player
/sk modifier removeall (player) (stat) (silent) - Removes all stat modifiers from a player
Item modifiers are like regular modifiers but stored on items. The modifier will only be applied when the player is holding the item. The commands will by default apply lore displaying the modifier's stat and value. The item modifier itself is independent of lore and is stored as custom NBT data. Therefore, you can modify lore however you want and it will still work. You can add multiple modifiers, but you can only have 1 modifier of each stat type.
The commands used to interact with them are:
/sk item modifier add [stat] [value] (lore) - Adds an item stat modifier to the item held, along with lore by default
/sk item modifier remove [stat] (lore) - Removes an item stat modifier from the item held, and the lore associated with it by default
/sk item modifier list - Lists all item stat modifiers on the item held
/sk item modifier removeall - Removes all item stat modifiers from the item held
Armor modifiers are exactly like item modifiers, except they only apply when the player is wearing the item as armor. You can have both item and armor modifiers on the same item and can have an item with an item and armor modifier of the same stat.
The commands used to interact with them are:
/sk armor modifier add [stat] [value] (lore) - Adds an armor stat modifier to the item held, along with lore by default
/sk armor modifier remove [stat] (lore) - Removes an armor stat modifier from the item held, and the lore associated with it by default
/sk armor modifier list - Lists all item armor modifiers on the item held
/sk armor modifier removeall - Removes all armor stat modifiers from the item held