The amount of XP required to level up skills can be configured in the xp_requirements.yml file.

Expressions and Variables

Within a section, such as the default section, you will see an expression value that contains the expression/equation used to calculate the XP requirements.

The expression can be changed as you wish, but it must be a valid EvalEx expression. You can view the supported operators and functions here.

Variables are also supported in expressions. In order to have a different XP required for each level, you must have the level variable in the expression somewhere. This variable corresponds to the level that is unlocked upon reaching the required XP. The level starts at the config.yml start_level+1 and goes up to the maximum level of the skill. For example, the result of the expression when level is 5 is the XP need to go from level 4 to 5.

Custom variables are also supported, which allow you to label and organize the parts of your expression. Instead of using the numbers directly in the expression, you can turn it into a variable that is specified in its own key. In the default expression shown below, multiplier and base are examples of custom variables.

multiplier * (level - 2) ^ 2 + base

As you can see, the numeric values of multiplier and base are specified as keys with the same name as the variable:

default:
  expression: 'multiplier * (level - 2) ^ 2 + base'
  multiplier: 100.0
  base: 100.0

You can use any variable name, as long as the value of the variable is defined in a separate key of the same name.

Skill Overrides

You can create different XP requirements for each skill by adding a skills.[skillName] section that will override the default section. The keys and values in the skill section are the same as the default section.

Here is an example of Alchemy XP requirements that override the default:

default:
  expression: 'multiplier * (level - 2) ^ 2 + base'
  multiplier: 100.0
  base: 100.0
skills:
  alchemy:
    expression: 'multiplier * (level - 2) ^ 3 + base'
    multiplier: 20.5
    base: 20.0

Direct List of Values

Instead of using an equation, XP requirements can be defined using a direct list of values. Create a list called values under either the default section or a specific skill section.

Here is an example of XP requirements using a value list:

default:
  values:
    - 100
    - 200
    - 300
    - 500
    - 750
    - 1250
    - 1720

The first value in the list is the XP required to get from level 1 to level 2.

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

Configuration

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:

auraskills/regeneration:
  # Whether the stat is enabled. Disabled stats will have no effect and
  # will be hidden from menus.
  enabled: true
  # A map of traits that this stat controls.
  traits:
    auraskills/saturation_regen: # The trait for health regen at full hunger
      # The increase in the trait per stat level. In this case, the player 
      # regenerates 0.008 more HP per Regeneration stat level.
      modifier: 0.008 
    auraskills/hunger_regen:
      modifier: 0.008
    auraskills/mana_regen:
      modifier: 0.01

Trait options

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.

Attack damage

• 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.

Hp

• 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.

Saturation regen and hunger regen

• 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.

Mana regen

• base - The base amount of mana to regenerate per second when the trait is at level 0.

Double drop

• max_percent - The cap for the percent chance to double drop blocks.

Max mana

• 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.

Damage reduction

• 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.

Crit chance

• base - The base amount of crit chance players have when the trait is at level 0.

Crit damage

• base - The base amount of crit damage players have when the trait is at level 0.

Movement speed

• max - The maximum movement speed value.

Multipliers are a way of increasing the amount of skill XP a player receives without changing the sources config.

Multipliers are permission based, meaning you can add them to individual players or groups of players (such as ranks). If your permissions plugin supports temporary permissions, you can even create temporary XP multiplier events.

Adding Multipliers

To add a multiplier, use your permissions plugin to add a permission in the following format:

auraskills.multiplier.[percent]

Replace [percent] with the percent more XP you want the multiplier to give. For example, the permission auraskills.multiplier.100 will give 100% more or 2x XP. The percent supports decimals using . (e.g. auraskills.multiplier.10.5).

Skill Specific Multipliers

Multipliers can also be added to only multiply XP from sources of a specific skill. The format of the permission is auraskills.multiplier.[skill].[percent] where [skill] is the default English name of the skill in lowercase.

Example permission for 1.5x farming multiplier: auraskills.multiplier.farming.50

Multiple Multipliers

If a player has more than one multiplier permission, the multipliers will add together and work as if there was only a single multiplier. For example, 100 (2x) and 50 (1.5x) multipliers will add to 150 (2.5x).

If you want multiplier multipliers that have the same value, you cannot simply use the same permission because inherently permissions must be unique. As a workaround, you can add trailing decimal zeros so that they are technically unique, but have the same value.

For example, auraskills.multiplier.100 will work the same as auraskills.multiplier.100.0. You can continue adding trailing zeros to add as many duplicates as you like.

LuckPerms Examples

The following are examples of adding multipliers using LuckPerms, a popular permissions plugin. If you use a different permissions plugin, use the commands from that plugin to add the multiplier like any other permission.

Adding a 2x multiplier to a player:

Adding a 1.5x multiplier to a rank called vip:

Adding a temporary 3x multiplier to everyone for 12 hours:

Removing a 2x multiplier from a player:

Item and Armor Multipliers

Multipliers can also be added to items and armor similar to stat modifiers. Item multipliers increase XP when holding the item. Armor multipliers increase XP when wearing the item. Multipliers can be either global or only for a specific skill.

The commands used for item/armor multipliers:

• /sk item/armor multiplier add <target> <value> [lore]

• /sk item/armor multiplier remove <target>

• /sk item/armor multiplier list

• /sk item/armor multiplier removeall

Use either item or armor in the command depending on the type of multiplier you want. Target can be either global or the name of a skill. The value of the multiplier is the percent more XP gained (works the same as permission multipliers).

These multipliers are included in the /sk multiplier command, which can display skill-specific multipliers if they are different from the global multiplier.

Requirements allow you to add skill level requirements in order to use an item. For example, you can create a pickaxe that only works when the player reaches Mining 15. There are two types of requirements: item and armor.

Item requirements apply when using the item in the player's hand. Armor requirements only apply when equipping/wearing the item.

There are also two different scopes and ways to add requirements: using commands or global requirements.

Command Requirements

Using commands to add requirements only adds the requirement to the specific item you are holding when creating the requirement. Therefore, you must distribute exact copies of that item in order for it to work.

Commands:

• /sk item/armor requirement add <skill> <level> [lore] - Adds an item/armor requirement to the held item. skill is the name of the skill that is required. level is the minimum skill level needed to use the item. lore is an optional true/false argument that determines whether lore should be added to the item. Lore is completely separate from the functionality of the requirement, so you can change or remove any lore.

• /sk item/armor requirement remove <skill> [lore] - Removes an item/armor requirement from the item held. If lore is true, the lore that was originally added will be attempted to be removed from the item. This may not work if you added custom lore.

• /sk item/armor requirement list - Lists the item/armor requirements on the item held.

• /sk item/armor requirement removeall - Removes all item requirements from the item held.

Global Requirements

Global requirements allow adding skill requirements to all items of a certain type/material. To add global requirements, you must add a global list to the requirement.item or requirement.armor section of config.yml.

The basic format for an entry in the list is: - MATERIAL SKILL:LEVEL

Here is an example of a global item requirement for diamond swords requiring Fighting 10 to use, including where it is located in the config:

Multiple global requirements on a single item are also supported:

The config.yml is the main plugin configuration file found in the plugins/AuraSkills folder. It is used for general or miscellaneous config options related to storage/database, external plugin hooks, languages, action bar, boss bar, worlds/regions, modifiers, requirements, and more.

Options for each and stat were formerly here, but have been moved to their own skills.yml and stats.yml files.

If an option you see in the config is missing, this page may not have been updated yet or the option may have been removed. You can find any config additions and changes in the full plugin .

Last Updated Version: 2.2.3

Options

SQL

sql:

• enabled - Whether SQL should be used for data storage (requires a restart to enable).

• type - The type of SQL database to use; currently only mysql is supported.

• host - SQL hostname

• port- Port (must be number)

• database - Database name (must be created already)

• username - SQL username

• password - SQL password

• load_delay - Number of ticks to delay loading data after a player joins, useful for syncing multiple servers to a single database.

• always_load_on_join - If true, player data will always be loaded from the database when a player joins, regardless if it is already in memory.

• ssl - Whether to use SSL.

• maximum_pool_size, minimum_idle, connection_timeout, max_lifetime, keepalive_time - Options used to configure the Hikari connection pool. These should not be changed unless you have issues with connection stability and know what you are doing.

Languages

default_language - The default language for players; must have a file that matches (ex: messages_en.yml for en)

try_detect_client_language - If set to true, the plugin will try to use the client's language, if available and valid. This is only for players who have not set a language using commands, or if their language was reset after a server restart. If the client language is not a valid plugin language, it will use the default-language. If set to false, all unset players will use the default-language.

languages - A list of languages players can switch to using /skills lang <language>; must also have a file that matches. Custom language files are defined here.

Hooks

hooks:

• enabled - Whether the hook to the given plugin should be registered. Hooks will only attempt to be loaded if the given plugin is detected and enabled, so hooks can be set to true without having the plugin on the server. Some hooks, like HolographicDisplays and DecentHolograms perform the same function, so one must be disabled before the other can be enabled.

Specific options for each hook are under the section with the plugin name below:

LuckPerms

• LuckPerms:

  • use_permission_cache - Whether to enable the system that caches LuckPerms multiplier permissions for optimizing multiplier calculations. If you change multiplier permissions using certain features that don't trigger LuckPerms events, such as world contexts, this feature may have to be set to false.

WorldGuard

• WorldGuard:

  • blocked_regions - Players in regions on this list will not be able to gain XP naturally in any skill.

  • blocked_check_replace_regions - Regions on this list will disable block sources checking if the block broken has been player placed.

Action Bar

action_bar:

• enabled - Whether the action bar should be enabled/disabled. (Must be set to true to have any action bars; setting to false disables all action bar types).

• idle - Controls the idle action bar (not gaining xp). Set this to false if you don't want health and mana at the bottom of the screen.

• ability - Controls the action bar for ability messages (raise/lower, activate, etc.). If set the false, the ability messages will be sent through chat instead.

• xp - Controls the action bar for gaining xp (not maxed)

• maxed - Controls the action bar when xp is gained in a maxed skill.

• update_period - How often the action bar should update, in ticks (Increase this value if action bar is causing lag).

• round_xp - If enabled, current xp will be rounded to an integer.

• placeholder_api - Whether PlaceholderAPI placeholders should be replaced in the action bar, given that you have PlaceholderAPI.

• use_suffix - Whether to format the current player's XP with number suffixes (k, m, etc). Only applies if xp is set to true.

• format_last - If true, parsing of MiniMessage will happen after placeholders (like hp and mana) are replaced on each send. This makes MiniMessage gradients work at the cost of performance.

• update_async - If true, the idle action bar will be updated and sent asynchronously. This is an experimental option.

Boss Bar

boss_bar:

• enabled - Whether boss bars should be enabled for xp gains.

• mode - Can be either single or multi. multi means multiple boss bars will display if gaining XP from different types of skills, single is only one at a time.

• stay_time - How long the boss bar should stay up after not gaining xp, in ticks.

• update_every - Controls how often the boss bar should update when gaining xp consecutively, increase if having lag issues.

• round_xp - If enabled, the current xp will be rounded to an integer.

• use_suffix - Whether to format the current player's XP with number suffixes (k, m, etc).

• format - The format list allows you to change the boss bar color and style for each skill:

  • Format: '[SKILL] [COLOR] [STYLE]'

  • Available colors are BLUE, GREEN, PINK, PURPLE, WHITE, RED, and YELLOW

  • Available styles are PROGRESS, NOTCHED_6, NOTCHED_10, NOTCHED_12, and NOTCHED_20

• animate_progress - Toggles boss bar animation (the delay when updating progress).

Jobs

jobs:

• enabled - Whether the jobs system is enabled. Even if selection is disabled, this option must be enabled in order for source income to work. The Vault plugin and an economy plugin must be installed in order for income to be given.

• selection:

  • require_selection - Whether players need to select skills as jobs through the level progression menu in order to earn income while gaining XP. If false, all skills will give income with XP.

  • default_job_limit - The default maximum number of jobs a player can have active at once. This limit can be changed per-player using the auraskills.jobs.limit.[number] permission node.

  • disable_unselected_xp - If true, players will be blocked from gaining XP in all skills besides the skills that are active jobs.

  • cooldown_sec - The number of seconds players have to wait to select a new job after selecting one.

• income:

  • use_xp - Whether the default.income_per_xp should be used as the default income value for sources.

  • use_expression - Whether the default.expression should be used as the default income value for sources. This overrides use_xp.

  • default:

    • income_per_xp - The multiplier for the source XP that determines how much income is given for a source by default. For example, gaining 14 skill XP from a source with an income_per_xp of 0.1 will give 1.4 Vault currency to the player.

    • expression - An expression used to calculate the income given for a source by default if use_expression is true. The available variables include xp, base_xp (value without multipliers), level (skill level), power, and skill_average.

  • batching:

    • enabled - If true, accumulated income will be given in an interval instead of immediately. This can reduce lag from a large amount of calls to Vault economy for large servers. The effective rate of income gain from sources does not change.

    • interval_ms - The minimum delay between income gains when batching is enabled is defined by the interval_ms parameter. For example, with an interval_ms of 2000, each time XP is gained, the system checks the timestamp of the last batched income gain. If more than 2 seconds have passed since the last gain, the income is given immediately. If less than 2 seconds have passed, the income is added to the next batch and will be distributed when XP is gained 2 seconds after the last batch time.

    • display_individual - If true, the boss bar will display the original individual income instead of the batched income. This means if this is false and batching is enabled, some boss bars will not display any income gain, and the boss bar for a batch execution will display the accumulated amount.

  • use_final_xp - If set to false, the calculation for income_per_xp will exclude all XP multipliers.

enable_roman_numerals - Whether Roman numerals should be used for skill levels.

Anti-AFK

anti_afk:

• enabled - Whether the anti-AFK system is enabled. If false, all aspects of the system are disabled.

• logging_enabled - Whether logging for failing anti-AFK checks is enabled. Logs will be sent to any online player with the auraskills.antiafk.notify permission (op by default).

• log_threshold - An expression determining the count of identical conditions required for logging an event. The min_count variable can be used in this expression to reference the min_count in the checks section for a check type.

• checks:

  • [check_name]:

    • enabled - Whether this individual check type is enabled.

    • min_count - The minimum number of failed conditions in a row to start blocking XP gain. The counter increments for every identical condition (position, yaw, pitch, or identity) and resets when a differing condition is detected.

    • max_distance - The maximum distance moved to still be counted as a check failure for position/coordinates based checks.

Damage Holograms

damage_holograms:

• enabled - Enable/disable damage holograms (requires either HolographicDisplays or DecentHolograms hook to be enabled and that plugin to be on the server).

• scaling - Whether the damage displayed on holograms should be scaled according to the action_bar_scaling option of the hp trait in stats.yml.

• decimal:

  • display_when_less_than: - Display decimals in damage holograms when less than a specified damage.

  • max_amount - The maximum amount of decimal digits to display.

• offset:

  • x - X coordinate offset

  • y - Y coordinate offset

  • z - Z coordinate offset

  • random:

    • enabled - Whether random hologram positions should be enabled.

    • x_min - Minimum X coordinate offset

    • x_max - Maximum X coordinate offset

    • y_min - Minimum Y coordinate offset

    • y_max - Maximum Y coordinate offset

    • z_min - Minimum Z coordinate offset

    • z_max - Maximum Z coordinate offset

Leaderboards

leaderboards:

• update_period - How often leaderboards should be updated, in ticks.

• update_delay - How long after server startup should the leaderboards be updated, in ticks (does not include the immediate update on startup).

start_level - The skill level that players start at. Defaults to 0, use 1 to revert to Beta mechanics.

enable_skill_commands - Whether skill name commands should be enabled such as /farming or /mining (Requires restart to have an effect).

check_block_replace:

• enabled - Whether blocks placed by players should not give xp; keep true unless you are having plugin compatibility issues.

• blocked_worlds - A list of worlds that should not be checked for block replacement. Checking will be disabled in these worlds regardless of what enabled is set to.

Worlds and Regions

blocked_worlds - Players in worlds on this list will not be able to gain xp naturally in any skill.

disabled_worlds - Most of the plugin's gameplay functionality will be disabled in worlds on this list, including but not limited to stats, abilities, gaining xp, and the action bar (commands and menus will still be available).

disable_in_creative_mode - Whether players should not be able to gain xp while in creative mode.

Data validation

data_validation:

• correct_over_max_level - If true, the plugin will prevent skill levels being over max level on join.

Death options

on_death:

• reset_skills - Whether to reset a player's skill levels when they die.

• reset_xp - Whether to reset a player's XP in their current skill levels when they die. Skill levels are not changed.

Auto-save

auto_save:

• enabled - Whether data for online players should save periodically instead of just when they log out. This is useful if you experience skill data losses due to server crashes.

• interval_ticks - How often (in ticks) to auto-save.

Leveler

leveler:

• title:

  • enabled - Whether a title should be displayed to players on skill level up.

  • fade_in - Title fade in time, in ticks

  • stay - How long the title should last, in ticks

  • fade_out - Title fade out time, in ticks

• sound:

  • enabled - Whether a sound should be played to players on skill level up.

  • type - The name of the sound that should be played (must be a valid sound name).

  • category - The sound category the sound should be played in.

  • volume - Sound volume

  • pitch - Sound pitch

• double_check_delay - The level up check delay for large xp gains at once, in ticks (lower is faster).

Mana

mana:

• enabled - If false, mana abilities will not cost mana to use and mana displays will be hidden from the action bar and menus.

• cooldown_timer_period - The number of ticks between counting down mana ability cooldowns. Increasing can help reduce lag caused by TimerCooldown for mana abilities. The overall cooldown time remains the same. Requires a restart to take effect.

Modifier

modifier:

• armor:

  • equip_blocked_materials - A list of blocks that should not grant stats of armor when right-clicked; add to this list when stats are given but armor is not equipped.

• item:

  • check_period - How often, in ticks, the item held in a player's hand should be checked for stat item modifiers (increase if you have lag)

  • enable_off_hand - Whether stat modifiers should work in the off hand

• auto_convert_from_legacy - Whether the old modifier nbt format should be converted to the new one. Set to true if you have items from Beta with modifiers that no longer work.

Requirement

requirement:

• enabled - Whether requirements should be checked at all. If you do not use requirements, disabling will improve performance.

• item:

  • prevent_tool_use - Whether block breaking should be blocked when a player does not meet a requirement

  • prevent_weapon_use - Whether attacking entities should be blocked when a player does not meet a requirement

  • prevent_block_place - Whether block placing should be blocked when a player does not meet a requirement

  • prevent_interact - Whether interacting (right clicking) should be blocked when a player does not meet a requirement

  • global - Define item requirements that should apply to every item of that type. Format: - '[material] [skill_1]:[level_1] [skill_2]:[level_2] ...'

• armor:

  • prevent_armor_equip - Whether armor should be unable to be equipped when a player does not meet a requirement

  • global - Define armor requirements that should apply to every item of that type. Format: - '[material] [skill_1]:[level_1] [skill_2]:[level_2] ...'

• override_global - If true, global requirements will be ignored if item-specific requirements are defined.

Critical

critical:

• base_multiplier - The base damage multiplier for critical hits

• enabled - Options in this category control whether that item type should be able to deal critical hits. (hand is for empty fist, other is for holding any other item not on the list)

Source

grindstone:

• blocked_enchants - A list of enchantments that should be blocked from counting XP for grindstone sources. Add unremovable enchants/curses from custom enchant plugins here.

statistic:

• gain_period_ticks - How often statistic sources should give XP. This does not change the effective rate of XP gain, just the time between statistic checks.

entity:

• give_alchemy_on_potion_combat - Whether killing/damaging an entity using potions should be counted as Alchemy XP instead of Fighting/Archery.

Menus

menus:

• lore_wrapping_width - The number of characters per line before newlines are automatically inserting in menu lore lines where wrapping is enabled.

• placeholder_api - Whether PlaceholderAPI placeholders should be used in menus.

• stats:

  • show_trait_values_directly - If true, stats that have a single trait with a modifier of exactly 1 will show the value of the trait instead in menus. This allows trait base values, such as the 20 HP every player has by default, to be included in the shown level.

Loot

loot:

• update_loot_tables - Whether new loot items introduced in default configs should be automatically added when updating the plugin.

• directly_to_inventory - If true, all bonus item drops from luck traits and loot will always add directly to the player's inventory instead of being dropped in the world. This option does not affect vanilla item drops.

check_for_updates - Whether the plugin should check for new updates on startup and when a player with the auraskills.checkupdates permission joins

Automatic Backups

automatic_backups:

• enabled - Whether automatic backups should be taken on server shutdown

• minimum_interval_hours - The minimum interval, in hours, between automatic backups. Automatic backups will only be taken at least this amount of hours after the last one.

• max_users - If the server has over this many total users, automatic backups will be skipped.

save_blank_profiles - If false, player data of players who have not leveled any skills or gained any XP will not be saved into storage.

Not to be confused with .

Abilities are passive gameplay buffs unlocked and leveled up alongside leveling skills. By default, each skill has 5 abilities that unlock at skill levels 1-5 (or 2-6 if start_level in config.yml is 1) and level up every 5 skill levels. Abilities are not fixed to their default skill; swapping abilities to other skills or disabling an ability can be easily done by removing it from the abilities list in the skill's section of skills.yml.

Configuration

All ability-related configuration other than linking with skills is done in the abilities.yml file. Each ability contains many common options, and some have options specific to the ability.

Common options

• enabled - Whether the ability should be enabled. Disabled abilities will have no effect and be hidden from menus. This does the same thing as removing it from the abilities list in skills.yml, though this enabled option is more suited for temporarily disabling an ability.

• base_value - The value this ability has at level 1 (when it is just unlocked). An ability's value determines it's power/effect and is directly shown wherever the ability is described in the menus. An ability that has a certain chance to activate usually has the chance controlled directly by the value in percent. For example, if Bountiful Harvest has a base_value of 5.0, it has a 5% chance to activate at level 1.

• value_per_level - A number that the value of the ability is increased by for each level of the ability past 1. The formula for effective value is value = base_value + (value_per_level * (level - 1)), where level is the level of the ability, not the skill. See the level_up option below for how the ability level is calculated.

• unlock - The skill level the ability is unlocked at. This can either be a fixed integer, or a string expression using the placeholder {start}, which is value of the start_level option in config.yml. The default configs use this method to have the first ability always unlock when you first level up a skill up to the fifth unlock.

• level_up - The interval in skill levels between when the ability levels up. The formula for a user's ability level is level = (skill_level - unlock)/level_up + 1, not including any cap by max_level.

• max_level - The maximum level the ability can be (not the skill level). Setting the value to 0 indicates no maximum level, making the max ability level determined by the max skill level and the above formula.

• secondary_base_value - Some abilities have a secondary base value to control another variable. Works the same as base_value.

• secondary_value_per_level - Some abilities have a secondary value per level to control another variable. Works the same as value_per_level.

Ability-specific options

The following table of options only apply to one or a few abilities.

Menu

The abilities menu displays all abilities and mana abilities of a skill, with their descriptions and levels. It can be accessed by clicking the ability item in the level progression menu (light blue dye by default).

Ability descriptions are also shown on each skill level pane as rewards in the level progression menu. A shortened version of the description known as the info message is shown in the skills menu on each skill item.

Messages

The name, description, and info messages of abilties are configured in the abilities section of the messages file.

AuraSkills (formerly Aurelium Skills) is a Minecraft plugin that adds , , , and other RPG-related features. Developed for the Spigot and Paper server platforms, the plugin can be downloaded for free on the official , , , and . The plugin is fully configurable and customizable, enabling use on a wide-range of server types from small SMPs to large, custom MMORPG networks.

This wiki contains documentation on how to set up, configure, and use the plugin. Support from the developer is provided on the server, where users can also give suggestions, report bugs, and get announcements. AuraSkills is open-sourced on .

Overview

Players level up by gaining skill XP through general Minecraft tasks, such as Farming, Mining, Fighting, or Enchanting. Increasing levels for each skill gives the player , unlocks and levels up and , and other customizable . Using /skills, players can view all the relevant information about skills and gameplay in fully-configurable inventory GUI . Certain Fishing and Excavation abilities drop custom loot, which can be customized and extended to other skills through . Players can compete with each other through leaderboards and rankings. Custom items can also be created that give when held or worn, to use, and . Numerous and allow server admins to manage players and control access to features.

Skills

Main article:

There are 11 default skills included in AuraSkills which level up as players gain skill XP through various XP sources. By default, each skill has two that increase every 1 or 2 skill levels. Most skills also have 5 passive that unlock the at first five levels and level up every 5 skill levels. Some skills have a , which is a special ability that must be activated by the player, costs mana, and has a cooldown.

The 11 skills are Farming, Foraging, Mining, Fishing, Excavation, Archery, Defense, Fighting, Agility, Enchanting, and Alchemy. The existing 15 skills from Beta can be added back by loading the legacy preset.

Skills can be viewed using /skills or by using the command for an individual skill, such as /farming, /mining, etc.

The skills.yml file is where skills are configured, including enabling/disabling skills, changing max levels and other skill-related options, as well as which abilities and mana abilities they have.

Configuration

There are multiple configuration files in the plugins/AuraSkills directory that are used to configure the plugin.

Main Config

The main config.yml file is used for general or miscellaneous config options related to storage/database, external plugin hooks, languages, action bar, boss bar, worlds/regions, modifiers, requirements, and more.

Skills

The skills.yml file is used to configure skills, including:

• Disabling/enabling skills

• Changing the max level of skills

• Removing or switching the abilities of skills

• Removing or switching the mana ability of skills

• Other skill-related config options

Rewards

The rewards/ folder contains the rewards files for each skill. The name of the file is the name of the skill it corresponds to. Rewards are given when a player levels up a skill and can be used to level stats, execute commands, grant permissions, give items, or deposite money (Vault). The global.yml is used to add rewards that apply to all skills (not a combined level, just saves time from adding same rewards to each file).

Loot

The loot/ folder contains loot tables for certain skills. By default, Fishing and Excavation include loot tables that are dropped by certain abilities in those skills. Custom loot tables can be added for Mining or Foraging by creating a file of the skill name (mining.yml or foraging.yml).

Menus

The menus/ folder contains the menu files used to change the appearance of the plugin's GUI menus such as /skills. Almost anything related to a menu's appearance can be customized, including adding new items or adding actions to execute when clicking an item.

API

AuraSkills provides an extensive API that allows developers to hook into the plugin and interact with users, listen to events, and add custom content.

Overview

The Fishing and Excavation skills have abilities that can drop custom loot, which is configured in the loot folder. For Fishing, the treasure_hunter ability corresponds to the rare pool and the epic_catch ability gives items from the epic loot pool. The metal_detector ability in Excavation gives rare loot while the lucky_spades ability gives epic loot.

Beyond changing the items dropped for these abilities, the files enable adding custom loot pools unrelated to abilities, executing commands as loot, as well as creating new loot tables for other skills (Foraging and Mining).

File structure

Loot tables are separated into files for each skill in the loot folder. The name of the file is the skill that the file corresponds to. By default, there are excavation and fishing loot tables. You can optionally add loot tables for mining and foraging, as long as they follow the format.

Loot pools

Loot pools are lists of loot entries, and each loot table file can have multiple loot pools. In the default excavation and fishing loot tables, there are the rare and epic loot pools. However, you can add any amount of new loot pools.

Loot pools are defined in the pools section of the loot file. Each pool must have a unique name for the config section name. In excavation and fishing, rare and epic are reserved names that integrate with abilities, so it is discouraged to change them.

Keys:

• base_chance - The chance to select this pool without any added ability bonuses (1 = 1% chance) (defaults to 1)

• selection_priority - The order the pools are potentially selected, a higher priority means that it will attempt to select before lower priority pools (defaults to 1)

• override_vanilla_loot - Whether the regular loot from the block should be replaced with the selected loot. Does not apply to fishing (defaults to 1).

• chance_per_luck - The amount the chance of selecting the pool should increase by per Luck stat level the player has (0.1 = +0.1% chance per Luck) (defaults to 0)

• require_open_water - For Fishing, only give items in the pool when the player fishes in open water (5x5x5 volume of water) when set to true. This prevents giving loot when using most AFK fish farms (defaults to false).

Each pool has a loot section containing a map list of the loot entries. This uses the same type of syntax as rewards, which is explained here.

Loot entries

Currently, there are two types of loot: item loot and command loot. Each loot entry must have certain required keys and can optionally have more. Optional keys are either notated with (optional) or have their default values specified on this page. Each key is explained below:

Universal Keys (apply to any loot type):

• type - The type of loot, either item or command

• weight - The weight of the entry compared to other loot in the same pool. A higher weight means the loot entry is more likely to be selected (defaults to 10).

• message - A chat message to send to the player when they get the loot. This supports color codes and PlaceholderAPI (optional).

• sources - A list of sources or source tags that this loot should exclusively apply to. The names of sources should match the exact name in sources_config.yml. Does not support custom block sources yet (optional).

• xp - The amount of skill xp to give when this loot is dropped (defaults to the original source amount)

Item loot

(type: item)

Item loot keys:

• material - The material of the item, must be valid bukkit material name (not case sensitive). Use material:id to specify legacy data if on 1.12

• amount - Controls the amount of item to give. This can either be a single number like '5' or a range of numbers such as '1-5', which gives a random amount from 1 to 5 (both inclusive) (defaults to 1)

• key - References an item key registered using /skills item register. If this is specified, material and all keys below do not apply

• display_name - The display name of the item, supports & for color codes unless escaped with \& (optional)

• lore - The lore of the item, must be a list of each line, supports & for color codes unless escaped with \& (optional)

• enchantments - A list of enchantments, one enchantment per line. Use a space between the enchantment name and the level, such as 'sharpness 5' (optional)

• potion_data - A section containing potion data, see below for keys (optional):

  • type - The type of potion, must be a bukkit PotionType

  • extended - Whether the potion has an extended duration

  • upgraded - Whether the potion has an upgraded level

• custom_effects - A map list of effects, keys for each section below (optional):

  • type - The name of the effect, must be a bukkit PotionEffectType

  • duration - The duration of the effect, in ticks

  • amplifier - The amplifier of the effect (0 means level 1)

• glow - Set to true to make the item glow without enchantments showing (optional)

• nbt - Section for any custom NBT data (optional)

• flags - List of item flags to add to the item (optional)

• ignore_legacy - If true, the plugin will skip loading the item if the server version is below 1.13 to prevent material parsing errors. The only reason you should use this if you are planning on using the same config for legacy and modern versions and an item you have does not exist in 1.12. The plugin is able to recognize modern material names on legacy versions without any issues. (optional)

Examples

Basic example of an item loot:

- type: item
  material: iron_ingot
  weight: 10
  amount: 1-3

Here is a more complex example with display name, lore, and enchantments:

- type: item
  material: diamond_sword
  weight: 5
  amount: 1
  display_name: '<red>Fire Sword'
  lore:
    - '<gray>Powerful weapon'
    - ' '
    - '<blue>RARE'
  enchantments:
    - sharpness 5
    - fire_aspect 2
    - looting 3

Here is a potion with base potion data and custom effects:

- type: item
  material: potion
  weight: 10
  amount: 1
  potion_data:
    type: speed
    upgraded: true
  custom_effects:
    - type: jump
      duration: 1000
      amplifier: 2
    - type: regeneration
      duration: 40
      amplifier: 3

An item with hidden enchants using item flags and custom model data using the nbt section

- type: item
  material: paper
  weight: 10
  amount: 1
  custom_model_data: 14
  enchantments:
    - knockback 2
  flags:
    - hide_enchants

Command loot

(type: command)

Command loot is used to execute any command when the player gets the loot, either through console or by the player.

Command loot keys:

• executor - Who should execute the command, either console or player (defaults to console)

• command - The command without the beginning /, supports {player} placeholder and all PlaceholderAPI placeholders

Example:

- type: command
  weight: 10
  executor: console
  command: say hi

Entity loot

(type: entity)

Entity loot spawns an entity when the player gets the loot. Currently only Fishing supports catching entity loot.

Entity loot keys:

• entity - Defines the type of entity caught.

  • Vanilla entities/mobs are defined by name (e.g. entity: zombie)

  • MythicMobs can be used with the mythicmobs: prefix (e.g. entity: mythicmobs:SkeletonKing)

• health - Overrides the entity max health attribute.

• damage - Overrides the entity attack damage attribute.

• level - Defines the AuraMobs or MythicMobs level.

• velocity:

  • horizontal - Overrides the default horizontal velocity of the entity when spawned.

  • vertical - Overrides the default vertical velocity of the entity when spawned.

• hand, off_hand, feet, legs, chest, head - Defines equipment on the spawned entity. The value is a mapping in the same item format as regular item loot (Using keys material, enchantments, etc.)

Loot selection

The way loot is selected is fairly straightforward:

1. The loot table is determined by skill that corresponds to the action the player does. For block based loot, the block must be a source for a supported skill (foraging, mining, excavation).

2. A loot pool is selected from the loot table starting from the highest priority loot pool. Whether pool is selected is base on the pool's base_chance and any added chances. If a pool is not selected, the pool with the next highest selection priority will be attempted. If no loot pool gets selected, the below steps do not apply.

3. A single loot entry is selected from the pool based on the weight of the entry. A higher weight makes it more likely for it to be selected. The exact chance is calculated by weight / sum of all weights in pool.

Custom loot tables

Completely new loot table files can be created for any skill with block sources or for mobs. This means the following new loot table file names are supported in the loot/ folder:

• farming.yml

• foraging.yml

• mining.yml

• mob.yml

Mob

For the mob loot table, add a mobs list to a loot entry to specific which mob it drops from. You should also specific type: mob at the beginning of the file. For example, the following loot entry drops a custom enchanted book (from a different plugin) when killing a blaze:

type: mob
pools:
  adrenaline:
    base_chance: 0.5
    loot:
      - type: item
        material: enchanted_book
        enchantments: [adrenaline 1-3]
        mobs: [blaze]

Block

Block loot tables must have type: block at the top of the file. When specifying the sources list, the values must be the exact name used as the section name inside the corresponding sources config file (not the material name).

The following is an example custom Farming loot table that has a 0.05% chance to drop an enchanted golden apple when breaking carrots. This will automatically handle breaking only fully-grown crops (for crops with growth stages) and naturally-grown crops (for things like melon and pumpkin).

type: block
pools:
  carrot:
    base_chance: 0.05
    loot:
      - type: item
        material: enchanted_golden_apple
        amount: 1
        sources: [carrot]

Introduction

Rewards are a powerful way of performing actions or giving things when a player levels skills. There are many different types of rewards, including stats, commands, permissions, items, and money. Rewards also support custom messages in menus and level-up chat messages.

Yaml syntax

Configuring rewards requires Yaml syntax that you might not have seen before, technically known as map lists. These are basically an array of objects in JSON. Map lists are defined like this:

patterns:
  - type: stat # Start of first object in list
    stat: strength
    value: 1
    pattern:
      interval: 1
  - type: stat # Start of second object in list
    stat: health
    value: 1.5
    pattern:
      interval: 1

File structure

Rewards are configurable in files in the rewards folder, and the name of the file corresponds to the skill it configures (eg. farming.yml controls Farming rewards only). Theglobal.yml file configures rewards for all skills, so rewards added in it will be applied to all skills. You will already see files for each skill containing the default rewards. Each file is split into two main sections, patterns and levels.

Patterns section

The patterns section is for rewards that repeat in a regular pattern within a skill's progression. Each reward in this section should have a pattern section that can define a start, interval, and stop. Patterns can be used for every type of reward.

The start value is the skill level the reward should first appear at; this should be at least 2 since the first level up possible is from level 1 to 2. If start isn't specified, it will default to 2.

The interval is the difference between consecutive rewards; an interval of 2 means the reward appears every other level (2, 4, 6,...). The default interval is 1.

The stop number is the maximum level the reward should appear at, so there will only be that reward below or at the specified stop level. This defaults to the max-level option of that skill in skills.yml.

Example pattern reward for a command that executes every level up:

patterns:
  - type: command
    executor: console
    command: 'say this executes every level up'
    pattern:
      start: 2
      interval: 1

Levels section

The levels section is for defining single rewards at a specific level. You must first define a section of the level you want to define for, like so:

levels:
  5:
    - type: command
      executor: console
      command: say hi

This command reward will be executed when the player levels up to skill level 5.

Reward types

Every reward must have a type value of the reward type it is. Each type of reward has different keys you can define that configure the reward, both required and optional.

Stat rewards (stat)

Stat rewards level up an AuraSkills stat, which includes health, regeneration, strength, luck, wisdom, and toughness. Menu and level-up chat messages are automatically handled.

Keys:

• stat - The name of the stat the reward should level, use the default English names like strength (Required)

• value - The amount of the stat to level, defaults to 1 (Optional)

Example:

- type: stat
  stat: strength
  value: 1

Command rewards (command)

Command rewards allow you to execute any command, either through console or the player.

Keys:

• command - The command to execute; do not include the beginning slash. (Required)

  • Supported placeholders:

    • {player} - The player's name

    • {level} - The level of the skill that the player just leveled up to

    • {skill} - The name of skill that was leveled up

    • All PlaceholderAPI placeholders (requires the PlaceholderAPI plugin installed). Built-in placeholders are applied before PlaceholderAPI placeholders so you can combine them together.

  • Color codes work using "&" unless escaped using "\&"

• executor - Defines who executes the command, either console or player. Using a player executor may still take into account permissions. Defaults to console. (Optional)

• revert_command - Revert commands allow you to execute a command when a player loses the skill level due to admin commands. Placeholders work the same as the normal command value. (Optional)

• revert_executor - Defines who executes the revert command, console or player (Optional)

Example:

- type: command
  executor: console
  command: say leveled up!
  revert_executor: console
  revert_command: say removed level up

Permission rewards (permission)

Permission rewards grant a permission node to a player. Permission rewards are better than using command rewards to add permissions because:

1. Permissions are automatically removed when the player loses the level

2. Missing permissions are automatically granted if you added the reward to a level below what a player already has (applies on player join)

Permission rewards currently only work if you use LuckPerms as your permissions plugin.

Keys:

• permission - The permission node to give (Required)

• value - The value of the permission, either true or false, but defaults to true (Optional)

Example:

- type: permission
  permission: some.permission.node
  value: true

Item rewards (item)

Item rewards give an item to the player, supporting any item through a key and registry system. Items must first be registered to a unique key in-game using /skills item register [key] and holding the item you want to register in your main hand. Items can be unregistered using /skills item unregister [key]. When a player's inventory is full, they will be notified and the item will be added to the player's unclaimed items. They can then claim the items using /skills claimitems. Unclaimed items are saved between restarts.

Keys:

• key - The key of the item that was registered using /skills item register [key] (Required)

• amount - The amount of that item to give, can exceed max stack size. If the amount exceeds the maximum stack size of an item, the given items will still follow the item's max stack size but will just be divided into multiple stacks. If items can't fit into the player's inventory they will be added to unclaimed items like normal. The amount defaults to the original amount of the item registered. (Optional)

Example:

- type: item
  key: some_item_key
  amount: 24

Money rewards (money)

Money rewards simply give money on level up through Vault Economy.

Keys:

• amount - The amount of money to give

• formula - An expression for determining the amount of money to give for a given level variable. Cannot be used with amount.

Example:

- type: money
  amount: 1000

Example patterns section in for replacing legacy money rewards:

patterns:
  - type: money
    formula: '100+10*level*level'
    pattern:
      interval: 1

If you don't use Vault or have special currencies, you can still give money using command rewards. Here is an example:

- type: command
  executor: console
  command: eco give {player} %math_{level}*2+100%

Messages

Command, permission, and item rewards support custom menu and chat messages. The menu_message key is for the message that will show on the level item in the level progression menu (accessible by clicking any skill in the /skills menu). This will appear under the "Rewards:" section right after stat rewards and before ability unlock/level ups. The chat_message key is for the message that will show on the list of rewards in chat when the player levels up. If the menu_message and chat_message you want are the same, you can simply use message instead as a shorthand.

The value of a message can either be a direct string (exactly what you put) or the path of a message key in the messages file. The plugin will first try to replace a message key and if not found will just use the direct string. Messages also support color codes using "&".

Note: Messages do not include new lines by default, you must use \n at the beginning if you want a new line for each reward.

Example of a menu and chat message being defined:

- type: permission
  permission: some.permission.node
  value: true 
  menu_message: \n  Some message in the menu
  chat_message: \n  Some message in chat

Example using the message shorthand for both menu and chat messages:

- type: command
  executor: console
  command: say leveled up!
  message: \n  Both a menu and chat message

Default and automatically handled reward messages

Item rewards by default use the display name or localized name of the item in the format of the rewards.item section's message keys in the messages file. If the item does not have a display name, it will not have any messages by default.

Stat reward messages are automatically handled because it always uses the menus.level_progression_menu.rewards_entry message key for menu messages and the leveler.stat_level message key for chat messages. You should edit those values in the messages file to change what stat reward messages look like.

Money reward messages are automatically handled through the menus.level_progression_menu.money_reward message key for menu messages and the leveler.money_reward message key for chat messages. All money rewards amounts for a particular level are added together into a single message.

The options under the sql section of the main config.yml file allow the storage of player data in a SQL database instead of the default YAML flatfile format. Currently only MySQL (and MariaDB) databases work. Using SQL for data storage enables better performance at high player counts, allows syncing of data between multiple servers, and makes it easier for third-party applications to interact with data.

Basic Setup

Before configuring the AuraSkills config, a SQL database must already be created separately (either through the server panel or terminal). This database should have a host (usually an IP address), database name, port, username, and password.

The options for configuring SQL are under the sql section of config.yml. To enable SQL, set the enabled option to true. Enter the host address under host and the name of your database under database. Then, enter the username and password of the database under their corresponding options. Enter the port number of the database under port. If desired, SSL can be enabled under the ssl option.

Once the server is restarted, SQL should be successfully working. AuraSkills will automatically create tables in the database. If SQL is not working, check the server console for any errors on startup and double check your database credentials are correct.

Migrating Data From YAML

Enabling SQL alone will not migrate player data from the default YAML storage method. To migrate data, a few extra steps are required:

1. While still on YAML, create a backup of the player data using /skills backup save

2. Shut down the server

3. Follow the instructions in the Basic Setup section and switch to MySQL (make sure you restart the server after)

4. Run /skills backup load [fileName], with fileName being the name of the backup file you saved before (seen in the backups folder)

Skills are measures of a player's experience or progress in different aspects of the game. As the main feature of AuraSkills, all other features are connected or related to skills. All information about skills is viewed in the skills menu using /skills. Each skill has a set of sources: specific tasks or actions used to gain XP in that skill. Players level up by reaching the XP requirement for the next level, which increases with higher skill levels.

Upon reaching a new skill level, players can be rewarded with:

• Stat levels

• Ability unlocks and level-ups

• Mana Ability unlocks and level-ups

• Other customizable rewards, including:

  • Commands

  • Permissions

  • Items

  • Money

There are 11 default skills included in the plugin:

• Farming

• Foraging

• Mining

• Fishing

• Excavation

• Archery

• Defense

• Fighting

• Agility

• Enchanting

• Alchemy

There are 4 skills present in Beta that were merged or removed in default configs. Servers that migrated from Beta or loaded the legacy preset have these additional skills:

• Endurance (merged into Agility in default)

• Healing (merged into Alchemy in default)

• Forging (merged into Enchanting in default)

• Sorcery (removed from default)

Configuration

Skills are configured in the skills.yml file. Each skill has a section named after its full Namespaced ID (prefixed with auraskills/ for all default skills). Below is an example skill section for Farming with comments explaining each option:

auraskills/farming: # The Namespaced ID of the skill
  abilities: # The list of abilities the skill levels up
    - auraskills/bountiful_harvest
    - auraskills/farmer
    - auraskills/scythe_master
    - auraskills/geneticist
    - auraskills/triple_harvest
  mana_ability: auraskills/replenish # The mana ability of the skill (optional)
  options: # Configurable options for the skill, see below for details on each option
    enabled: true
    max_level: 97
    check_cancelled: true
    check_multiplier_permissions: true

Abilities

The abilities key is a list of the abilities attached to the skill (will level up as the skill levels up). The ability name must be a full Namespaced ID. All other configuration for abilities is done in abilities.yml.

Mana ability

The mana_ability key is the name (full Namespaced ID) of the mana ability of the skill. This is an optional value, as not all skills have mana abilities. All other configuration for mana abilities is done in mana_abilities.yml.

Options

General options

• enabled - Whether the skill and all its connected features should be enabled. If set to false, players cannot gain XP in the skill, use the abilities or mana abilities, and the skill will be hidden from menus. Disabling a skill will not reset player levels, so re-enabling a skill will retain previously gained levels.

• max_level - The maximum attainable level of a skill. Lowering this level will not decrease player levels that are already higher than the new max level.

• check_cancelled - Whether source levelers should ignore cancelled events when giving XP. This should not be changed unless you have a specific compatibility issue that requires it.

• check_multiplier_permissions - Whether permission-based multipliers (auraskills.multiplier.*) should work. If you do not use permission multipliers, setting this to false may improve performance.

Archery and fighting options

• spawner_multiplier - Multiplies the given XP by this value for mobs spawned by a mob spawner block. Set to 0 to disable XP from spawners.

Defense options

• max - The maximum amount of XP to reward for defense.

• min - The minimum amount of XP required to be rewarded. If the XP is lower than min, no XP will be given.

• allow_shield_blocking - Whether XP should be given when a player is hit while blocking with a shield.

Alchemy options

• ignore_custom_potions - If true, potions with custom effects (non-brewable potions) will not work with Alchemy abilities such as Alchemist, Sugar Rush, and Splasher.

Commands

The names of skills can be used to directly open the level progression menus for that skill, such as /farming, /archery, etc. This can be disabled by setting enable_skill_commands to false in config.yml.

Skill levels can be manipulated using the following commands:

• /skills skill setlevel <player> <skill> <level>

• /skills skill setall <player> <skill> <level>

• /skills skill reset <player> [skill]

Menu

The skills menu is accessed using /skills. The design and format of the menu is configured in menus/skills.yml.

Messages

The display names and descriptions of skills can be changed under the skills section of the messages file.

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

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

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

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

AuraSkills provides PlaceholderAPI placeholders that work out of the box, without needing to download an ecloud expansion. Due to the plugin renaming in 2.0, existing placeholders prefixed with %aureliumskills_ will still work alongside %auraskills_ placeholders. However, you should slowly migrate your placeholders to use %auraskills_, since the old prefix may be removed in later versions.

List

• %auraskills_power% - Combined skill level

• %auraskills_[skill]% - Level for a certain skill (ex: %aureliumskills_farming%)

• %auraskills_[skill]_roman% - Level for a certain skill as a roman numeral

• %auraskills_[stat]% - Level for a certain stat (ex: %aureliumskills_health%)

• %auraskills_[stat]_int% - Level for a certain stat rounded to an integer

• %auraskills_average% - Average skill level

• %auraskills_average_int% - Average skill level rounded to an integer

• %auraskills_average_1% - Average skill level rounded to one decimal

• %auraskills_hp% - Hp as an integer

• %auraskills_hp_1% - Hp rounded to 1 decimal

• %auraskills_hp_2% - Hp rounded to 2 decimals

• %auraskills_hp_max% - Max hp

• %auraskills_hp_percent% - Percent hp as an integer

• %auraskills_mana% - Current player mana

• %auraskills_mana_int% - Mana of a player rounded to an integer

• %auraskills_mana_max% - Max mana

• %auraskills_mana_max_int% - Max mana rounded to an integer

• %auraskills_lb_power_[place]% - Gets a formatted value of username and level for the power leaderboard at a certain place

• %auraskills_lb_power_[place]_name% - Gets the username for the power leaderboard at a certain place

• %auraskills_lb_power_[place]_value% - Gets the level for the power leaderboard at a certain place

• %auraskills_lb_[skill]_[place]% - Gets a formatted value of username and level for a skill leaderboard at a certain place

• %auraskills_lb_[skill]_[place]_name% - Gets the username for a skill leaderboard at a certain place

• %auraskills_lb_[skill]_[place]_value% - Gets the level for a skill leaderboard at a certain place

• %auraskills_rank% - Gets the power leaderboard rank

• %auraskills_rank_[skill]% - Gets a skill leaderboard rank

• %auraskills_xp_required_formatted_[skill]% - Gets the required XP for the next level of a player formatted with suffixes (ex: 5k)

• %auraskills_xp_required_[skill]% - Gets the required XP for the next level of a player as an exact number

• %auraskills_xp_progress_int_[skill]% - Gets the percent progress to the next level rounded to an integer

• %auraskills_xp_progress_1_[skill]% - Gets the percent progress to the next level rounded to 1 decimal place

• %auraskills_xp_progress_[skill]% - Gets the exact percent progress to the next level

• %auraskills_xp_int_[skill]% - Gets the current XP for a player rounded to an integer

• %auraskills_xp_formatted_[skill]% - Gets the current XP for a player formatted with suffixes

• %auraskills_xp_[skill]% - Gets the exact skill XP for a player

• %auraskills_multiplier% - Gets a player's permission XP multiplier rounded up to 2 decimal places (1 = normal, 2 = 2x XP)

• %auraskills_multiplier_[skill]% - Gets a player's permission XP multiplier for a specific skill rounded up to 2 decimal places (1 = normal, 2 = 2x XP)

• %auraskills_multiplier_percent% - Gets a player's permission XP multiplier as a percent more value rounded to an integer (40 = 40% more XP)

• %auraskills_multiplier_percent_[skill]% - Gets a player's permission XP multiplier for a specific skill as a percent more value rounded to an integer (40 = 40% more XP)

• %auraskills_actionbar_status% - Gets whether the idle action bar is enabled for a player. Returns true or false.

• %auraskills_[ability]% - Gets an ability level. Replace [ability] with the default English name of an ability in lowercase.

• %auraskills_[ability]_roman% - Gets ability level as a Roman numeral.

• %auraskills_[ability]_value% - Gets an ability value.

• %auraskills_[ability]_value_int% - Gets ability value rounded to an integer.

• %auraskills_[ability]_value_2% - Gets the secondary value of an ability if it exists.

• %auraskills_[ability]_value_2_int% - Gets secondary ability value rounded to an integer if it exists.

• %auraskills_mability_[ability]% - Gets the player's mana ability level.

• %auraskills_mability_[ability]_roman% - Gets mana ability level as a Roman numeral.

• %auraskills_mability_[ability]_value% - Gets the mana ability value.

• %auraskills_mability_[ability]_value_int% - Gets mana ability value rounded to an integer

• %auraskills_mability_[ability]_active% - Returns true if mana ability is active, false otherwise.

• %auraskills_trait_[trait]% - Gets the effective level of a trait.

• %auraskills_trait_[trait]_bonus% - Gets the bonus level of a trait (level excluding the base value).

• %auraskills_trait_[trait]_menu% - Gets the trait in the same format displayed in the stats menu.

• %auraskills_jobs_list% - Lists active jobs in a comma separated list of default skill names in all lowercase.

• %auraskills_jobs_list_formatted% - Lists active jobs in a comma separated list with the skill display name of the config default_language.

• %auraskills_jobs_count% - Gets the number of jobs the player currently has active.

• %auraskills_jobs_limit% - Gets the maximum number of jobs the player is allowed to have active at the same time.

• %auraskills_jobs_active_[skill]% - Returns true/false whether the job is active (ex: %auraskills_jobs_active_farming%)

Sources are the gameplay actions that give players XP in a skill. This includes things like mining blocks or killing mobs. Sources for each skill are configured in the sources folder, with a different file for each skill. Each source's XP value can be changed, and entirely new sources can be added based on a source type and its options.

Default section

The default section is used in a source file to save lines by not having to write out the same options for every source. Each key in the default section is copied to every single source in the sources section, unless it is overriden by a key with the same path in the specific source.

For example, the consider following source configuration with a default section:

default:
  type: brewing
  trigger: takeout
  menu_item:
    material: potion
sources:
  awkward:
    ingredient: nether_wart
    xp: 10
    menu_item:
      potion_data:
        type: awkward

This is the same as the following source configuration without the default section:

sources:
  awkward:
    type: brewing # Copied from previous default
    trigger: takeout # Copied from previous default
    ingredient: nether_wart
    xp: 10
    menu_item: # The menu_item section is combined with the previous default section
      material: potion # Material from the previous default
      potion_data: # Defined key from the source itself
        type: awkward

The default section is useful in making the file more concise for skills with sources of mostly one type that also share common options.

Types

Each source must have a type key that defines the type of action the source is. If you see a source that doesn't specify a type, that means it's using the type in the default section.

Each source has a name, which is simply the name of the section it is defined in. This name can be used in the tags section to reference the source. Sources must have unique names within a single skill.

Global options

The following is a list of options that apply to all source types:

• xp - The XP amount to give for the source. This is the base amount and does not include any ability, permission, or item multipliers. (Required)

• display_name - The readable name used in menus to identify the source. Default sources already have display names defined in the messages file at the path sources.[type].[name]. Only define a display_name on the source if you want to override the messages value or for newly created sources you don't need to be localized.

• menu_item - A section that defines the item used in the sources menu to represent the source. Placeholders to other keys can be used in material for example, to only need to define a single menu_item in the default section. See #Menu item for details.

  • Oraxen items are support by using a string key prefixed with oraxen:. For example, menu_item: oraxen:mythril will use the exact item defined in Oraxen, including any NBT. This is defined as a string value directly on the menu_item key rather than the map section used for normal menu items.

• unit - A placeholder that defines the name of the unit for some sources whose XP amount is dynamic, such as Defense XP per damage or Forging XP per anvil cost experience. This is needed for some units to function when giving XP. See the section for the specific type for valid values.

• income_per_xp - Gives money based on the value times the XP gained. Only works if jobs are enabled in the Main Config. This works the same as the income_per_xp in the main config, but overrides it for the specific source. Mutually exclusive with income and income_expression.

• income - Gives a fixed decimal money amount when the source is gained. Only works if jobs are enabled. Mutually exclusive with income_per_xp and income_expression.

• income_expression - An expression to calculate the income, works the same as the jobs.income.default.expression in the Main Config. Only works if jobs are enabled. Mutually exclusive with income_per_xp and income.

Anvil

The anvil source (type: anvil) gives XP when combining items in an anvil.

Options

• left_item - An item filter defining valid items in in the left slot. (Required)

• right_item - An item filter defining valid items in the right slot. (Required)

• multiplier - A placeholder for multiplying the base XP. Currently must be the value '{repair_cost}', which is the amount of experience levels used in the anvil.

Block

The block source (type: block) gives XP for breaking or interacting with blocks. The options can be used to define complex sources involving multiple blocks or specific block states.

Options

• block - The block type/material. This must be a valid Bukkit Material in all lowercase. (Required)

  • Oraxen custom blocks are supported by prefixing the block name with oraxen:. For example, block: oraxen:mythril_ore will automatically register the block state from Oraxen without neeeding to manually define a state.

• blocks - A list of multiple block types used to group multiple blocks to the same source. Overrides block.

• trigger - The type of action on the block. Can be either break or interact. break is simply when a block is broken by a player with left click. interact is when the block is right clicked. (Required)

• triggers - A list of multiple triggers.

• check_replace - Whether player-placed blocks should not give XP. If true, placed blocks will not give XP. If false, any block that matches the source will give XP. Defaults to true.

• state - A section of keys that defines the specific block state the block must match.

• states - A list of block state sections to match any of the block states in the list.

• after_state - A block state that is checked to match one tick after the block is interacted with. If the block does not match the after_state, XP will not be given. Only works if trigger is set to interact.

• after_states - A list of block states to check on tick after. XP is given if the block still matches any states in the list.

• state_multiplier - An expression with block state variables that evaluates to a number to multiply the base xp given.

• support_block - A direction defined for some blocks that will automatically break if an adjacent block is broken. Valid values are above, below, side, and none. This ensures that the block can be unmarked as a player placed block when it is indirectly broken. Defaults to none.

• trunk - Whether the block is a tree trunk. Used by Treecapitator for checking valid blocks to break. Defaults to false.

• leaf - Whether the block is a leaf block. Used by Treecapitator for checking valid blocks to break. Defaults to false.

Brewing

The brewing source (type: brewing) gives XP when brewing potions in a brewing stand.

Options

• ingredient - An item filter defining valid potion ingredients

• trigger - When to give XP, either on brew or takeout. Using brew means that auto-brewers will still give XP to the player who placed the brewing stand.

Damage

The damage source (type: damage) gives XP when the player takes damage. In the default sources, this handles both the Defense sources and fall damage in Agility. The resulting XP given is the xp key multiplied by the amount of damage taken.

Options

• cause - The cause of the damage that is required for the source. Must be a valid Bukkit DamageCause in all lowercase.

• causes - A list of multiple damage causes.

• excluded_cause - A cause that is excluded for the source. If no cause/causes is specified, any cause other than the excluded_cause will work.

• excluded_causes - A list of multiple excluded damage causes.

• damager - A specific entity type that the player must be damaged from. Can be either mob, player, or any Bukkit EntityType in all lowercase. Specifying a damager automatically excludes the source from non-entity damage, like fall damage.

• damagers - A list of multiple valid entity types.

• excluded_damager - A specific entity type that is excluded from giving XP for the source.

• excluded_damagers - A list of entities types excluded from giving XP.

• must_survive - Whether the player must survive the damage taken in order to gain XP. Defaults to true.

• use_original_damage - Whether the XP given should be multiplied by the original damage dealt without any damage reduction modifiers (armor, stats, abilties, etc). Defaults to true.

• cooldown_ms - A delay before XP can be gained again in milliseconds (200 by default).

Enchanting

The enchanting source (type: enchanting) gives XP when enchanting an item in an enchanting table.

Options

• item - An item filter defining the valid items to enchant. (Required)

• unit - The unit to use to multiply XP. Currently must be '{sources.units.enchant_level}'

Entity

The entity source (type: entity) gives XP for a player killing or damaging an entity.

Options

• entity - A valid Bukkit EntityType that specifies the type of entity the player kills/damages. (Required)

• trigger - The trigger for when to given XP, either on entity death or damage. (Required)

• triggers - A list of multiple triggers.

• damager - A damager to match when giving XP, which can either be player, projectile, or thrown_potion.

• damagers - A list of multiple valid damagers.

• scale_xp_with_health - If the trigger is damage, the damage XP multiplier will be scaled by the damaged mob's max health. The total XP gained from killing a mob will be consistent between death and damage triggers. Defaults to true.

• cause - The cause of the damage that is required for the source. Must be a valid Bukkit DamageCause in all lowercase.

• causes - A list of multiple damage causes.

• excluded_cause - A cause that is excluded for the source. If no cause/causes is specified, any cause other than the excluded_cause will work.

• excluded_causes - A list of multiple excluded damage causes.

Fishing

The fishing source (type: fishing) is used for players fishing.

Options

• item - An item filter defining the item the player fishes up.

Grindstone

The grindstone source (type: grindstone) gives XP for disenchanting items in a grindstone.

Options

• multiplier - A placeholder to multiply the base xp by when giving XP. Currently can only be '{total_level}', which is the sum of the enchantment levels of all the enchants removed by the grindstone.

Item consume

The item consume source (type: item_consume) gives XP when players consume a potion or eat an item.

Options

• item - An item filter defining the item that is consumed. (Required)

Jumping

The jumping source (type: jumping) gives XP for the player jumping.

Options

• interval - The number of jumps required to give XP. The XP given per jump is xp/interval. Defaults to 100.

Mana ability use

The mana ability use source (type: mana_ability_use) gives XP when the player uses a mana ability. The amount of XP given is the xp multiplied by the amount of mana consumed.

Options

• mana_ability - The name of a specific mana ability to only give XP for when used.

• mana_abilities - A list of mana abilities to only give XP for using.

Potion splash

The potion splash source (type: potion_splash) gives XP when a player uses a splash or lingering potion.

Options

• item - An item filter defining the type of potion splashed. (Required)

Statistic

The statistic source (type: statistic) gives XP when a Minecraft player statistic increases. XP is given at a fixed interval controlled by the xp_gain_period option under Endurance in skills.yml. The default period is every 5 minutes. For the source to work, stats.disable-saving in the server's spigot.yml must be false (it's false by default, so only check if you changed it).

Options

• statistic - The name of the statistic to track increases and give XP for. Must be a valid Bukkit Statistic in all lowercase. (Required)

• multiplier - An flat amount to multiply the XP gained by. (Defaults to 1)

• minimum_increase - The minimum amount the statistic has to increase by within the check period in order for XP to be given. If the amount gained is less than the minimum, it will still be added towards the next time the amount is checked. (Defaults to 1)

Item filter

Multiple sources that have an item, ingredient, or similar options use the item filter format, which defines a filter the item used in the source type generally has to pass in order to be matched to the specific source. This allows specifying only one specific item with an exact material and meta, or more general filters allowing multiple materials.

General options

• material - A single specific material the item must be. This should be a valid Bukkit Material in all lowercase.

• materials - A list of multiple materials the filter can match.

• excluded_material - A single material to exclude from being matched.

• excluded_materials - A list of multiple materials to exclude from being matched.

• category - A category name to match all items from. Valid values are weapon, armor, tool, fishing_junk, and fishing_treasure.

Direct value

In cases where you only need a single material in the filter, you can directly specify the material name as a value, instead of in the subsection.

For example:

ingredient: nether_wart

is equivalent to

ingredient:
  material: nether_wart

Meta options

Further options can be used to narrow down the item more specifically than just the material. These options are placed in the same indentation level as the general options (one level to the right of the section name like item or ingredient).

• display_name - A string display name that must exactly match with the item.

• lore - A list of strings defining the lore that must exactly match with the item.

• potion_data - A section containing options specifying the type of potion to match.

  • type - A valid Bukkit PotionType to match in all lowercase.

  • types - A list of multiple types of potions to match.

  • excluded_type - A PotionType to exclude from matching.

  • excluded_types - A list of multiple types of potions to exclude from matching.

  • extended - Whether the potion must have an extended duration.

  • upgraded - Whether the potion must have an upgraded level.

• custom_model_data - An integer to match the CustomModelData id of an item. Both the material and custom_model_data must match to pass the filter.

Examples

Example of an item filter used in an item_consume source:

drink_regular:
  type: item_consume
  item: # The item filter section name
    material: potion # The item consumed must be a potion
    potion_data:
      # The type of potion cannot be mundane, thick, awkward, or a water bottle
      excluded_types: [ mundane, thick, water, awkward ]
      extended: false # The potion cannot be extended
      upgraded: false # The potion cannot be upgraded
  xp: 20

Example of an item filter used in a brewing source:

regular:
  type: brewing
  trigger: takeout
  ingredient: # The item filter section name
    # The ingredient cannot be any of these materials
    excluded_materials: [ redstone, glowstone_dust, nether_wart, gunpowder, dragon_breath ]
  xp: 15

Menu item

Built-in placeholders can be used to reference other keys inside the menu_item.

default:
  type: block
  trigger: break
  menu_item:
    material: '{block}'

The above example default section for a block source will replace the {block} placeholder with the value of block for each source below. So if the dirt source has block: dirt, the resulting menu item material will be material: 'dirt'.

Tags

The tags section of a source file is used to configure plugin-provided list of sources for certain abilities or mechanics. You cannot add or remove tags from the section, only modify the list of the provided tags.

For example, the farming_luck_applicable tag is the list of sources that will apply the double drop bonus of the Farming Luck trait.

Wildcards and exclusions

By default you might not see the names of sources in the list, since many just the symbol * on the list. This adds all the sources in the skill to the tag.

If you want to exclude a source from the list that already has a wildcard without addding every single other source, you can prefix the source name with ! to exclude it.

tags:
  farming_luck_applicable:
    - '*'
    - '!sugar_cane'

In the example above, all farming sources except sugar cane will apply to Farming Luck.

tags:
  farming_luck_applicable:
    - wheat
    - potato
    - carrot
    - beetroot

This example shows making Farming Luck only applicable to wheat, potato, carrot, and beetroot. Note that the names used in the list are the source names (section names under sources), not the value of block within the source.

Not to be confused with passive abilities.

Mana abilities are active abilities that consume mana when activated. By default, mana abilities unlock at skill level 6 and level up every 6 skill levels. Each skill can have at most one mana ability. Mana abilities can be swapped between skills by changing the mana_ability option in skills.yml.

List

Configuration

Configuring mana abilities is done in mana_abilities.yml. The format is similar to the normal ability configuration, but with some different options.

Common options

• enabled - Whether the mana ability should be enabled. Disabled mana abilities will have no effect and be hidden from menus. This does the same thing as removing it from mana_ability option in skills.yml, though this enabled option is more suited for temporarily disabling a mana ability.

• base_value - The value this mana ability has at level 1 (when it is just unlocked). The value determines the duration for most mana abilities, except Sharp Hook (damage dealt), Charged Shot (damage per mana), and Lightning Blade (attack speed increase).

• value_per_level - A number that the value of the mana ability is increased by for each level of the ability past 1. The formula for effective value is value = base_value + (value_per_level * (level - 1)), where level is the level of the ability, not the skill. See the level_up option below for how the ability level is calculated.

• base_cooldown - The cooldown of this mana ability at level 1 in seconds. The cooldown starts counting down after the mana ability wears off.

• cooldown_per_level - The change in the cooldown per mana ability level. By default the this is negative so the cooldown decreases as you level up. If you are increasing the max skill level or mana ability level, be careful to make sure this doesn't make the cooldown negative.

• base_mana_cost - The cost in mana to activate the mana ability at level 1.

• mana_cost_per_level - The change in mana cost per mana ability level. Player's won't be able to use the mana ability if the cost is higher than their max mana (increased by the Wisdom stat).

• unlock - The skill level the ability is unlocked at. This can either be a fixed integer, or a string expression using the placeholder {start}, which is value of the start_level option in config.yml. The default configs use this method to have the first ability always unlock when you first level up a skill up to the fifth unlock.

• level_up - The interval in skill levels between when the ability levels up. The formula for a user's ability level is level = (skill_level - unlock)/level_up + 1, not including any cap by max_level.

• max_level - The maximum level the ability can be (not the skill level). Setting the value to 0 indicates no maximum level, making the max ability level determined by the max skill level and the above formula.

Ability-specific options

Messages

The names and descriptions of mana abilities can be edited in the mana_abilities section of the messages file.

Disabling mana

While mana is a core component of the mana abilities system, the mana system can be essentially disabled through a few steps:

1. Set the mana.enabled option in config.yml to false. This removes mana costs from mana abilities and most mentions of mana in menus. While most mana abilties will still work just without a mana cost, the Absorption and Charged Shot mana abilities will be disabled because their mechanics fully depend on mana.

2. In the messages/global.yml file, edit the action_bar.idle message by removing the {{action_bar.mana_display}} part and extra spaces. Since the idle action would just display health, you probably want to disable it completely by setting action_bar.idle to false in config.yml.

3. Up to this step, mana has already been functionally disabled. But to fully remove mentions of mana in menus, replace mentions of the word "Mana" in the messages file of your language to something else, like "Active Ability" for example.

The messages/ folder contains messages and translation files for many languages. All content is translatable, including commands, menus, and chat.

The default language of the server can be set using the default_language option in config.yml. If this does not set everyone to your preferred server language, players can run /skills lang [language] to set their own language, where [language] is a valid two-letter code that is in the languages list in the config (and the file name after messages_).

Editing messages

When editing messages, keep the following in mind:

• Color and formatting is done using the format. Legacy Bukkit color codes using & will still work.

• Do not change any message placeholders that use {this} format. These are replaced by the plugin with contextual data or other messages when shown.

• Do not use the messages file to edit the color or formatting of menus. These can now be done entirely in the config for . Menu messages only need to be editing if you want to change the actual text content of the message.

• Newlines are automatically inserted into menus messages, ability descriptions, and other messages that appear in menus. You do not need to manually add \n anymore.

• Do not touch the file_version field. It is used to automatically update message files when a new version is available.

YAML syntax tips

• Never use tab characters, only spaces are allowed for indentation. You should use a consistent indentation size (2 spaces) for the entire file.

• If your message starts with the characters "&", "{", or "}", wrap the entire message in double quotes. (Ex: "Message"). When in doubt, put it in quotes.

Units

Any instances of the placeholders {xp_unit}, {mana_unit}, and {hp_unit} are replaced by the values in the units section. These placeholders can be added arbitrarily to any message if needed.

Adding translations

To upload a messages file, click "Upload Translations". To download messages, click "Download".

If you see blue in the progress bar, it means translations have yet to be approved by a developer/proofreader. These translations will still be included in the downloaded file.

Translation guidelines

Keep the following guidelines in mind when submitting community translations on Crowdin:

• Do not change or remove colors and formatting tags for messages that have color codes. The style should look the same as the default messages_en.yml no matter the language.

• Do not remove any placeholders in the default messages

• Try to keep translations as accurate as possible. Translations should not affect the meaning of descriptions and names.

• Don't translate a language if the translation already exists; add to the existing file if it needs to be updated.

• Keep formats as much as possible, such as punctuation, colors, caps, etc. You may need to move around color tags to get the contexts/parameters to match.

Adding a file

To add a messages file that doesn't already exist, or isn't being loaded, you must add it to the languages list or the default_language option in config.yml. The code must be a valid language code and the same as the suffix in the file name, aka the part after messages_ but before .yml. Some languages have a country code specifier after the language code, which is formatted with a - followed by the country code in caps. For example, Brazilian Portuguese has the code pt-BR.

Permissions are used to grant or restrict access to commands, skills, and other plugin features. They can also be used to add XP multipliers.

List

Default column key:

• true - All players have the permission by default

• op - Only operators have the permission by default

• false - No players have the permission by default

A command with | separating arguments means the permission controls all the listed sub-commands.

Introduction

This is a quick overview about the plugins that are compatible with AuraSkills. There are three main categories:

• Plugins that are supported by AuraSkills itself

• Plugins that hook into AuraSkills through its API

• Add-ons that are made specifically to work AuraSkills or extend its functionality

Plugins that AuraSkills hooks into

Vault

Enables and the feature. You will need an economy provider as well that hooks into Vault, like EssentialsX or CMI (or any other economy plugin).

WorldGuard

Custom flags to control where can players gain XP. Also used to check whether a player can break/place blocks at a given location or not. You can setup regions to be ignored by the block tracker and/or you can tell the plugin in what regions should XP gaining totally prevented.

See the for a list of options.

LuckPerms

PlaceholderAPI

DecentHolograms and HolographicDisplays

ProtocolLib

Allows the plugin to detect when other plugins try to use the action bar. When this happens, AuraSkills will pause its own action bar so other plugins can show messages there is well.

Towny

Terraform ability won't break blocks in other people's towns.

MythicMobs

Experience can be given with the giveSkillXP mechanic that AuraSkills provides. Lets say you have boss and you want to give fighting skill XP for the player who kills the boss. You can do something like this in your mob Skills config section:

You can create insanely powerful things with this using MythicMobs' scripting language.

MythicCrucible

When you are using MythicCrucible as your primary item plugin, you could use the takeMana mechanic and the hasMana condition, that AuraSkills provides to use in mythic scripting language.

Example of creating a damage skill that uses mana:

With this skill the player will damage 20 if the player has 20 mana. 20 mana will be taken from the player.

You can use this skill on an item like this:

This skill will damage the current target when the player right clicks with the item.

Oraxen

You can augment Oraxen custom blocks with the Luck stat/trait as well as regular blocks. You can also specify how much XP should Oraxen blocks give (oraxen:block_id). Oraxen items can also be used directly for XP source menu items.

Slimefun

Detect and add block to placed blocks from Slimefuns Block placer to prevent XP dupes.

Known plugins that hook into AuraSkills

You can give skill xp when fishing up something in CustomFishing and you can buff fishing rods and minigames based on skill levels or by using other AuraSkills placeholders.

Here is a minimal example how to give fishing skill XP when you catch a fish:

For additional information check out CustomFishings wiki and their Discord support.

Eco plugins are using the Libreforge yaml scripting language to create effects, conditions and other thing in every Eco plugin like EcoItems, EcoPets, Talismans etc.

Eco provides some useful effects and conditions to integrate with AuraSkills:

These minions can give skill XP after they produced some products. There isn't really any documentation about it at the time of writing but you should look around filters.

Aurora plugins, like AuroraLevels, AuroraCollections, and AuroraQuests are hooking into AuraSkills to provide auto-correcting stat rewards. This is useful if you want to spice up your RPG experience while you don't have to worry about nerfing/buffing the stat rewards later on.

Can give AuraSkills foraging skill XP when chopping down trees.

Earn AuraSkills XP when killing mobs with a boomerang.

Official add-ons

Level your mobs based on player sum/average skill levels to make them harder to defeat. Increase their health and attack damage to complete the true RPG experience AuraSkills can provide. Fully integrated with AuraSkills XP gain and mob drop tables.

Unofficial add-ons

By using this addon, you can prevent block breaking until the player reaches a specific skill level. This behavior is highly configurable.

A Cannons and AuraSkills addon that allows players to level up and unlock skills related to firing cannons.

Rewards players with randomly enchanted items as they level up their skills.

Define time ranges in which some skills will earn more/less XP.

Menus are inventory GUIs that display information about skills to players in-game. The main skills menu is opened with the command /skills, with others accessible by clicking buttons in certain menus. The look and style of menus can be configured in the files in the menus/ folder, while the plain text content is configured through messages.

List of menus

The following is a list of menus in the plugin:

File structure

The files for configuring menus are located in the AuraSkills/menus folder. Each menu has its own corresponding file used to configure that menu.

The following is an overview of keys and sections that are at left-most indent of the menu file:

• title - The text that will show up at the top of the menu when it is opened

• size - The number of rows the menu has, from 1-6 (each row has 9 slots)

• fill - A section used to define the menu background item to fill empty slots

• items - The main items section used for singular items

• templates - The section used to define items with custom contexts and multiple instances

• components - Lore snippets used inside some templates/items

• formats - Key-value pairs of formats used in some items

• options - A section found in some menu files that contains custom options and settings

Fill

The fill section defines a background item to fill empty slots not used by other items. There are two required keys in the fill section:

• enabled - A true/false value of whether the fill item should be used

• material - The material of the fill item

The display name of a fill item is automatically turned into a space, so the name of the item is invisible. Additional keys can be added to customize item meta using the same format as other items.

Items

Templates

Components

Formats

The formats section are key-value pairs used as formatting for lore in other items or templates. Usually, placeholders in items/templates that have square brackets denoting an array like {entries[]} use strings from the formats section to populate the array entries. Though the names of the formats don't necessarily match the placeholder, it's name should reflect the item or context it's being used in.

Options

skills:

• bar_length - The total number of characters displayed in the XP bar. Also applies to XP bars in the level progression menu.

level_progression:

• use_level_as_amount - When true, the level templates (unlocked, in_progress, and locked) will have their item amount set to the level number they represent (at level 30 the item amount willl be 30). Above the max stack size of the item (usually 64), the value of over_max_stack_amount is used.

• over_max_stack_amount - The item amount to use for skill level items for levels above the item's maximum stack size. Only applies when use_level_as_amount is true.

• items_per_page - The number of skill level items (unlocked/in_progress/locked) to show per menu page.

• start_level - The level shown on the first skill level item.

• track - A list of slot numbers ranged 0-54 for positioning skill level items. The index of the track matches the index of the skill level item within a specific page, so the length of track should match items_per_page.

sources:

• source_start - The upper left slot position of the rectangle formed by source items.

• source_end - The lower right slot position of source items.

• items_per_page - The number of source items to show per menu page.

• use_track - Whether to use the track list to determine source item positions instead of source_start and source_end.

• track - A list of slot numbers ranged 0-54 for positioning source items.

Colors and formatting

The available color constant names are black, dark_blue, dark_green, dark_aqua, dark_red, dark_purple, gold, gray, dark_gray, blue, green, aqua, red, light_purple, yellow, or white.

Placeholders

Placeholders are used in the menu configuration to allow the plugin to insert context-dependent messages and data. There are three general types of placeholders that serve different purposes:

• Single curly braces ({example}) - Replaced internally by the plugin for variable data such as player levels and XP. They only work within the same item they were originally defined in (or a component attached to the item), so it should not be moved outside the item.

• Double curly braces ({{example}}) - Message placeholders replaced by the message key defined in the messages file by the key menus.[menu_name].[placeholder] where [menu_name] is the name of the menu and [placeholder] is the text within the double curly braces. If this key doesn't exist, it will look at the key menus.common.[placeholder] for the message. The player's set language determines which message file the message will come from, allowing the single menu configuration to work with any language.

• PlaceholderAPI placeholders (%example%) - Placeholders within percent symbols are PlaceholderAPI placeholders. They can either be AuraSkills placeholders or for any other plugin. The PlaceholderAPI plugin must be installed for them to work (and necessary ecloud expansions for other plugins).

Custom menus

Custom menus can be created by creating a file in the menus folder with a .yml extension. The name of the file is the name used to refer to it in commands and other menus. Custom menus use the same file format as the default menus, though the templates, components, formats, and options sections will not work. PlaceholderAPI placeholders and click actions are supported like existing menus.

Custom menus can be opened using the /sk openmenu command or through menu open click actions from other menus.

An example custom menu named test created at menus/test.yml:

This menu can be opened from an existing menu by adding click actions, such as the your_skills item in the skills menu:

Syntax: <this> indicates a required argument, [this] is an optional argument. See for more details about permissions.

Player commands

The following commands are accessible to all players by default.

Admin commands

The following commands are only accessible to players with op by default.