Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Guide to setting up and configuring a SQL database for storage
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.
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.
Enabling SQL alone will not migrate player data from the default YAML storage method. To migrate data, a few extra steps are required:
While still on YAML, create a backup of the player data using /skills backup save
Shut down the server
Follow the instructions in the Basic Setup section and switch to MySQL (make sure you restart the server after)
Run /skills backup load [fileName], with fileName being the name of the backup file you saved before (seen in the backups folder)
Guide to skills and the skills.yml file
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
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)
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:
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.
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.
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.
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.
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.
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.
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]
The skills menu is accessed using /skills. The design and format of the menu is configured in menus/skills.yml.
The display names and descriptions of skills can be changed under the skills section of the messages file.
Welcome to the AuraSkills wiki!
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.
There are multiple configuration files in the plugins/AuraSkills directory that are used to configure the plugin.
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.
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
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).
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).
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.
AuraSkills provides an extensive API that allows developers to hook into the plugin and interact with users, listen to events, and add custom content.
Guide to stat 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 are like regular modifiers but stored on items. The modifier will only be applied when the player is holding the item. The commands will by default apply lore displaying the modifier's stat and value. The item modifier itself is independent of lore and is stored as custom NBT data. Therefore, you can modify lore however you want and it will still work. You can add multiple modifiers, but you can only have 1 modifier of each stat type.
The commands used to interact with them are:
/sk item modifier add [stat] [value] (lore) - Adds an item stat modifier to the item held, along with lore by default
/sk item modifier remove [stat] (lore) - Removes an item stat modifier from the item held, and the lore associated with it by default
/sk item modifier list - Lists all item stat modifiers on the item held
/sk item modifier removeall - Removes all item stat modifiers from the item held
Armor modifiers are exactly like item modifiers, except they only apply when the player is wearing the item as armor. You can have both item and armor modifiers on the same item and can have an item with an item and armor modifier of the same stat.
The commands used to interact with them are:
/sk armor modifier add [stat] [value] (lore) - Adds an armor stat modifier to the item held, along with lore by default
/sk armor modifier remove [stat] (lore) - Removes an armor stat modifier from the item held, and the lore associated with it by default
/sk armor modifier list - Lists all item armor modifiers on the item held
/sk armor modifier removeall - Removes all armor stat modifiers from the item held
Guide to customizing XP requirements
The amount of XP required to level up skills can be configured in the xp_requirements.yml file.
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.
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.
As you can see, the numeric values of multiplier and base are specified as keys with the same name as the variable:
You can use any variable name, as long as the value of the variable is defined in a separate key of the same name.
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:
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:
The first value in the list is the XP required to get from level 1 to level 2.
Guide to XP multipliers
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.
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).
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
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.
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:
When removing multipliers, you must use the exact text of the permission you added.
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.
Guide to the config.yml file
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.
Last Updated Version: 2.2.3
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.
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:
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:
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:
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:
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:
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:
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:
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:
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:
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.
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:
correct_over_max_level - If true, the plugin will prevent skill levels being over max level on join.
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:
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:
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:
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:
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:
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:
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)
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:
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.
removal_protection - Enables additional protections against removing items from menus.
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:
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.
Other customizable , including:
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 .
This wiki is for AuraSkills 2.0+ only. For the old wiki (AureliumSkills Beta 1.3.x), click .
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.
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.
Main article:
Main article:
Main article:
Removing or changing the default stats granted by a skill are done in the file.
Main article:
Main article:
Main article:
Modifiers are temporary 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.
The expression can be changed as you wish, but it must be a valid EvalEx expression. You can view the supported operators and functions .
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 .
Jobs income can also be configured per-source in the .
Guide to item and armor requirements
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.
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:
The item/armor below means you only type item for item requirements and only armor for armor requirements.
/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 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:
Guide to stats and the stats.yml file
Stats are values that represent specific gameplay buffs called traits. A player's stat levels and their descriptions can be viewed in the stats menu using /stats or by clicking the stat item (their player head by default) in the main skills menu.
Traits are values for the singular gameplay aspect that a stat affects. Since some stats have multiple effects, such as Wisdom's experience bonus and max mana increase, traits allow these effects to be configured independently as well as swapped between stats. Traits increase in value based on a constant multiplier of the stat level, which allows stat levels to display in a more user-friendly level while the trait is decimal that directly shows its effect.
There are 9 stats by default, with the trait(s) they level up also shown:
Strength -> Attack Damage
Health -> Hp
Regeneration -> Saturated Regen, Hunger Regen, Mana Regen
Luck -> Farming Luck, Foraging Luck, Mining Luck, Excavation Luck, Fishing Luck
Wisdom -> Experience Bonus, Anvil Discount, Max Mana
Toughness -> Damage Reduction
Crit Chance -> Crit Chance
Crit Damage -> Crit Damage
Speed -> Movement Speed
Stats and traits are configured in the stats.yml file. Each stat has a section named after its full Namespaced ID (prefixed with auraskills/ for all default stats) in the stats section. Each trait has a similar section under traits. Below is an example stat section for Regeneration with comments explaining each option:
The traits section contains configurable options specific to each trait. These options were formerly in their stats' section before 2.0. If the enabled option (common to all traits) is set to false, the trait will have no effect in game and will be hidden from menus.
hand_damage - Whether damage from hitting with an empty hand should be affected.
bow_damage - Whether damage from bows and projectiles should be affected.
display_damage_with_health_scaling - If true, the damage numbers in the menus and damage holograms will be scaled based on the action_bar_scaling option in the auraskills/hp trait section.
use_percent - Whether the attack damage bonus should be applied as a percent increase of the base damage. If false, damage will be added as the flat trait value.
health_scaling - Whether the player's displayed hearts should be scaled, meaning 2 HP = 1 heart does not apply at higher HP levels. This means it requires increasing amounts of HP to get an additional visual heart, which prevents hearts blocking too much of the screen at high HP values. This options is entirely visual and does not affect the real amount of HP of the player, which is what is shown on the action bar. The scaling amounts are configured by the hearts option.
hearts - A map of entries that determine when extra visual hearts are shown if health_scaling is enabled. The key is the index of the heart and the value is the real HP number needed for that heart to be shown. For example, '17': 48 means that the 17th heart (7th extra heart) will be shown when the player has at least 48 HP (number on the action bar).
action_bar_scaling - A number that is multiplied by the player's Minecraft HP to determine the HP number shown on the action bar (and damage numbers if display_damage_with_health_scaling in strength in enabled).
update_delay - The number of ticks to delay recalculating and applying the player's health on join or world change. Set this to 1 if you are having compatibility issues with mini-game plugins where health is too high when switching back to the main world.
force_base_health - If true, the player's base health attribute value will be forced to 20 on every refresh. Only enable if you have compatibility issues with other plugins.
keep_full_on_increase - If true, increases in a player's max health when the player is already at full HP will automatically set them at the new max HP.
ensure_scaling_disabled - Disables health scaling if the trait is disabled in order to remove past health scaling. Set to false if you have another plugin that is handling health scaling.
use_custom_delay - If true, the vanilla system for health regeneration will be replaced by a custom timer with a customizable delay and base value.
delay - The number of ticks between health regen if use_custom_delay is enabled.
base - The base HP to regenerate if use_custom_delay is enabled.
base - The base amount of mana to regenerate per second when the trait is at level 0.
max_percent - The cap for the percent chance to double drop blocks.
allow_overflow - Whether to allow mana amounts higher than max, such as when a player's max mana decreases but their previous mana was higher than the new max.
base - The base amount of max mana players have when the trait is at level 0.
formula - The formula for calculating damage reduction from the trait value. The input variable value is the trait value (which is after the stat value is multiplied by the trait modifier). The expression result is a decimal from 0 to 1 where 0 is no damage reduction and 1 is all damage blocked. For example, an expression result of 0.32 means 32% damage reduction.
base - The base amount of crit chance players have when the trait is at level 0.
base - The base amount of crit damage players have when the trait is at level 0.
max - The maximum movement speed value.
Guide to mana abilities and the mana_abilities.yml file
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.
Replenish
Farming
Replants crops automatically for a certain duration. Right click with a hoe and break a crop to activate. Works with wheat, carrots, potatoes, nether wart, and beetroot.
Treecapitator
Foraging
Breaks entire trees instantly for a certain duration. Right-click with an axe and break a log to activate. The algorithm is not final and will be improved later on to work perfectly with all tree types.
Speed Mine
Mining
Gives Haste 10 for a certain duration. Right-click with a pickaxe and break stone or an ore to activate.
Sharp Hook
Fishing
Deal damage to a hooked entity when left-clicking with a fishing rod.
Terraform
Excavation
When digging, break connected blocks instantly in a 4 block radius horizontally for a duration. Right click shovel and dig block to activate.
Charged Shot
Archery
Arrows you shoot will deal more damage based on how far the bow was pulled back, consuming mana in the process. Does more damage per mana consumed. Left click a bow to toggle charged shot mode.
Absorption
Defense
Incoming damage will decrease mana by 2x Minecraft damage instead of your health. Mana will not regenerate while Absorption is active. Left click shield and take damage to activate.
Lightning Blade
Fighting
Increases attack speed by a percent for a duration. Right click sword and attack entity to activate.
Configuring mana abilities is done in mana_abilities.yml. The format is similar to the normal ability configuration, but with some different 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.
require_sneak
Replenish, Treecapitator, Speed Mine, Terraform, Lightning Blade
If true, players must right click and sneak at the same time to ready the mana ability.
check_offhand
Replenish, Treecapitator, Speed Mine, Terraform, Lightning Blade
If true, right clicking to place a block from the offhand will not ready the mana ability of the tool in the main hand.
sneak_offhand_bypass
Replenish, Treecapitator, Speed Mine, Terraform, Lightning Blade
If true, sneaking while right clicking with a block in the offhand will ready the mana ability of the tool in the main hand.
replant_delay
Replenish
The delay in ticks between when a crop is broken and when Replenish replants the seed.
show_particles
Replenish
Whether to display particles when replanting.
prevent_unripe_break
Replenish
Whether attempting to break an non-fully-grown crop with a hoe while Replenish is active should be prevented.
max_blocks_multiplier
Treecapitator
A multiplier on the maximum number of blocks that can be broken at once by Treecapitator. The base number of blocks depends on the wood type.
give_xp
Treecapitator
Whether to give skill XP for every block broken by Treecapitator.
haste_level
Speed Mine
The level of the haste effect that should be given by Speed Mine. Counts from 1 for the lowest possible level.
display_damage_with_scaling
Sharp Hook
Whether the damage number shown in menus should be multiplied by the action_bar_scaling option of the hp trait in stats.yml.
enable_sound
Sharp Hook, Charged Shot
Whether a sound should be played when the player uses the mana ability.
disable_health_check
Sharp Hook
If true, Sharp Hook will still apply even if the plugin thinks it will do 0 damage. Only enable this if you have compatibility issues.
always_enabled
Charged Shot
If true, all arrows fired will be charged shots if the player has the mana ability unlocked. This disables the left click toggling functionality.
max_blocks
Terraform
The maximum number of blocks that can be broken at once by Terraform.
enable_particles
Absorption
Whether particles should be shown when a player absorbs a hit.
The names and descriptions of mana abilities can be edited in the mana_abilities section of the messages file.
While mana is a core component of the mana abilities system, the mana system can be essentially disabled through a few steps:
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.
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.
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.
Guide to creating to custom rewards
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.
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:
Pay attention to the spacing above. The indent level of the keys (type, stat, value) should be aligned exactly as shown! If you have a loading error, it's probably a spacing/indentation issue.
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.
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:
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:
This command reward will be executed when the player levels up to skill level 5.
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)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)
format - Configures the decimal format for the value displayed in menus and level up messages. Uses the Java DecimalFormat pattern.
Example:
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:
permission)Permission rewards grant a permission node to a player. Permission rewards are better than using command rewards to add permissions because:
Permissions are automatically removed when the player loses the level
Missing permissions are automatically granted if you added the reward to a level below what a player already has (applies on player join)
Keys:
permission - The permission node to give (Required)
value - The value of the permission, either true or false, but defaults to true (Optional)
Example:
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:
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:
Example patterns section in for replacing legacy money rewards:
If you don't use Vault or have special currencies, you can still give money using command rewards. Here is an example:
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:
Example using the message shorthand for both menu and chat 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.
Guide to configuring loot tables
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).
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 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).
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)
(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)
Basic example of an item loot:
Here is a more complex example with display name, lore, and enchantments:
Here is a potion with base potion data and custom effects:
An item with hidden enchants using item flags and custom model data using the nbt section
(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: 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.)
The way loot is selected is fairly straightforward:
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).
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.
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.
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
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:
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).
Guide to configuring XP sources
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.
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:
This is the same as the following source configuration without the default section:
The default section is useful in making the file more concise for skills with sources of mostly one type that also share common options.
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.
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.
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 - 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.
The anvil source (type: anvil) gives XP when combining items in an anvil.
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.
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.
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.
The brewing source (type: brewing) gives XP when brewing potions in a brewing stand.
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.
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.
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.
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).
The enchanting source (type: enchanting) gives XP when enchanting an item in an enchanting table.
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}'
The entity source (type: entity) gives XP for a player killing or damaging an entity.
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.
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.
The fishing source (type: fishing) is used for players fishing.
item - An item filter defining the item the player fishes up.
The grindstone source (type: grindstone) gives XP for disenchanting items in a grindstone.
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.
The item consume source (type: item_consume) gives XP when players consume a potion or eat an item.
item - An item filter defining the item that is consumed. (Required)
The jumping source (type: jumping) gives XP for the player jumping.
interval - The number of jumps required to give XP. The XP given per jump is xp/interval. Defaults to 100.
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.
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.
The potion splash source (type: potion_splash) gives XP when a player uses a splash or lingering potion.
item - An item filter defining the type of potion splashed. (Required)
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).
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)
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.
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.
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:
is equivalent to
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.
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.
Example of an item filter used in an item_consume source:
Example of an item filter used in a brewing source:
Built-in placeholders can be used to reference other keys inside the menu_item.
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'.
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.
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.
In the example above, all farming sources except sugar cane will apply to Farming Luck.
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.
Guide to configuring menus
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.
The following is a list of menus in the plugin:
skills
/skills command.
Overview and player progress in all skills.
stats
/stats command or clicking the stats item (Player Head) in the skills menu.
Overview and player levels in all stats.
level_progression
Clicking a skill item in the skills menu or the command corresponding to the name of the skill (/farming, /mining, etc).
Shows a track of all levels in a skill and their rewards with player progress. Contains items to access other skill-specific menus.
sources
Clicking the sources item (Experience Bottle) in the level_progression menu.
Shows all the ways to earn XP in a certain skill and their XP value.
abilities
Clicking the abilities item (Light Blue Dye) in the level_progression menu.
Shows the abilities and mana abilities of a skill with the player's ability levels.
leaderboard
Clicking the rank item (Paper) in the level_progression menu.
Shows the top 10 players by level in a skill.
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
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.
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.
bar_length - The total number of characters displayed in the XP bar. Also applies to XP bars in the level progression menu.
percent_format - The decimal format for the {percent} placeholder in the progress component. Uses the Java DecimalFormat pattern.
current_xp_format - The decimal format for the {current_xp} placeholder in the progress component. Uses the Java DecimalFormat pattern.
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.
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.
xp_format - The decimal format for the {source_xp} placeholders in the source template and multiplied_xp component. Uses the Java DecimalFormat pattern.
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 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 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:
Guide to abilities and the abilities.yml file
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.
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.
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.
The following table of options only apply to one or a few abilities.
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.
The name, description, and info messages of abilties are configured in the abilities section of the messages file.
List of plugin permissions
Permissions are used to grant or restrict access to commands, skills, and other plugin features. They can also be used to add XP multipliers.
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.
Plugins that AuraSkills supports or support AuraSkills
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
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.
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.
Terraform ability won't break blocks in other people's towns.
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.
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.
You can augment Nexo custom blocks with the Luck stat/trait as well as regular blocks. You can also specify how much XP should Nexo blocks give (nexo:block_id). Nexo items can also be used directly for XP source menu items.
Detect and add block to placed blocks from Slimefuns Block placer to prevent XP dupes.
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.
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.
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.
Guide to the messages files
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_).
When editing messages, keep the following in mind:
Do not change any message placeholders that use {this} format. These are replaced by the plugin with contextual data or other messages when shown.
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.
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.
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.
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.
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.
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.
Frequently-asked questions
Set action_bar.idle to false in config.yml.
This shouldn't happen by default, but make sure the following config options are set properly:
In the sources folder, ensure that in the mining.yml, excavation.yml, and foraging.yml files, the option default.check_replace is set to true.
In config.yml, ensure check_block_replace.enabled is true. Also make sure your world names are not added to the blocked_worlds list.
In config.yml, ensure hooks.WorldGuard.blocked_check_replace_regions does not contain your world name.
Restart the server. You likely reloaded the server, which is not supported and will break things.
No. Too much would have to be re-coded and features would be cut.
To uninstall, put the plugin back and run skills resethealth in the console when no players are online. Then immediately remove the plugin and restart.
Visual hearts are scaled, meaning it takes more HP to get each additional heart. Your actual health matches the HP value on the action bar. This is enabled to prevent hearts from blocking the screen at high health stats. You can disable this by setting health.health-scaling to false in config.yml
You just need to give a player or group the auraskills.multiplier.[percent] permission, where percent is the percentage more XP that should be received. For example, adding a 2x multiplier to everyone using LuckPerms would be /lp group default permission set auraskills.multiplier.100.
Only Spigot and Paper are officially supported, but many Paper forks like Purpur will likely work. CraftBukkit and modded hybrid servers (Arclight, Mohist, etc) are not supported.
How to migrate from AureliumSkills Beta 1.3 to AuraSkills 2.0
With the 2.0 update, the plugin itself has been renamed from AureliumSkills to AuraSkills. This means that the name of the plugin folder is now /AuraSkills instead of /AureliumSkills.
While it is recommended to start fresh to get the improved default configs, you can migrate old config options to the new folder automatically. However, not everything will be migrated, so manual work will still be required depending on how much you modified the configs.
If you want to migrate, keep your /AureliumSkills folder when running the new jar for the first time, so that when the files in /AuraSkills are generated, it can use the files in the old folder to migrate from.
Backup your /AureliumSkills folder and your database (if using MySQL for data storage) before migrating.
If you are planning on starting a new season/world/server, you do not need to migrate. The new default config options are more balanced and recommended. Only migrate if you want to keep the abilities/stats/xp source values exactly the same as before. Messages and menus won't migrate (see below), so if you only changed those, you will still have to manually change them back.
Compatibilty with plugins that hooked into AureliumSkills before, since the plugin renaming means those plugins will no longer enable their hooks. There are many breaking API changes, so these hooks will have to be recoded anyway. Check with any plugins that hooked into AureliumSkills to see if there is an updated version with AuraSkills support.
Your previous permissions for the plugin set into plugins like LuckPerms won't work, since permission nodes have been renamed.
Messages (significant format changes)
Menus (significant format changes)
PlaceholderAPI placeholders for %aureliumskills_...% will still work for now, but you should change them to %auraskills_...% eventually
Custom XP sources added in the custom section of the old sources_config.yml
Items registered in the item registry using /sk item register will be reset. You will have to re-register your items for them to work in rewards/loot because of NBT format changes to modifiers.
Most options in config.yml (skill-specific options have been moved to skills.yml and stat-specific options are in stats.yml)
Rewards and loot tables (format mostly unchanged)
Player data (now in userdata folder for YAML, new tables will be created for MySQL)
XP values in sources_config.yml (moved to sources folder)
xp_requirements.yml (format unchanged)
abilities_config.yml (separated into abilities.yml and mana_abilities.yml)
Item/armor modifiers when held
In the default configs, the number of skills has been reduced from 15 to 11. However, if you migrate from Beta, you will still have the existing 15 skills and their abilities. But if you want to migrate user data and merge the skills like the new default configs, you will need to do some manual work:
Delete the skills.yml, abilities.yml, menus folder, rewards folder, and sources folder to let them regenerate. If you modified rewards, abilities_config.yml, or the sources_config.yml in Beta, you will have to manually add your changes back.
Run the following commands in the console which set every user's skill level for the merged skills to the higher out of the two previous skills. Make sure no players are online when you run this.
skills storage mergeskills auraskills/endurance auraskills/agility
skills storage mergeskills auraskills/healing auraskills/alchemy
skills storage mergeskills auraskills/forging auraskills/enchanting
Guide to the AuraSkills API
The AuraSkills API allows developers to interact with the plugin, integrate with an existing plugin, or register content (custom skills, stats, abilities).
The API consists of just the api and api-bukkit sub-modules. This allows API methods to be stable across versions and prevents the use of unstable internal methods.
Release versions are published to the Maven central repository.
Groovy DSL:
Kotlin DSL:
Most API classes are accessible through the AuraSkillsApi interface accessed using the following static method.
In very limited situations where the API requires Bukkit classes, such as the ItemManager and Regions API, you will have to obtain an instance of the AuraSkillsBukkit interface:
Any use of the auraSkills variable name below refers to the AuraSkillsApi instance.
Player skill information is available through the SkillsUser interface, which is obtained from the API instance:
While the method accepts a uuid, only online players will have their skill data loaded. Offline players will still return a SkillsUser object, but will have all values set to default ones and modifying values will not work.
You can get and set a user's skill level using the user methods and the Skills enum for default skills. For example:
Getting and adding skill XP is very similar:
Getting a player's stat level is simple using the method and the Stats enum.
Adding stat levels is more complex, since stat levels aren't stored directly. Instead, there a system of stat modifiers which associates a unique name to a stat increase so it can be tracked and removed later.
Getting and setting mana is very simple:
An easier way to consume mana for things like activating mana abilities or casting spells is using the consumeMana method. This returns true if the user has enough mana and mana was successfully removed, and false if mana could not be removed. It also automatically sends a "Not enough mana" message to the action bar.
The API has many events to interact with the plugin. These are registered just like regular Bukkit events.
The following is a list of available events. This may not always be up-to-date, so see the source code for all the events.
LootDropEvent - Calls when the plugin drops/modifies item loot. Includes both multiplier abilities and Fishing/Excavation loot tables. Use getCause() to get the reason for the drop.
SkillsLoadEvent - Calls when the plugin has fully finished loading, usually on the first tick of the server. Use this event when accessing anything related to skills, stats, etc on server startup instead of in onEnable, since skills won't be loaded yet then.
ManaAbilityActivateEvent - Calls when a player activates a mana ability.
ManaAbilityRefreshEvent - Calls when a player is able to use a mana ability again (cooldown reaches 0)
ManaRegenerateEvent - Calls when a player regenerates mana naturally.
SkillLevelUpEvent - Calls when a player levels up a skill.
XpGainEvent - Calls when a player gains skill XP.
CustomRegenEvent - Calls when a player regenerates health if custom regen mechanics are enabled.
To register custom content, you must first obtain a NamespacedRegistry that identifies your plugin and the directory from which to load content files (including skills.yml, rewards, sources, etc).
The first argument of useRegistry is the name of your plugin registering the custom content (it will be forced to lowercase). This is the namespace part of all content that is identified by a NamespacedId, and is used in config files like skills.yml, abilities.yml, etc.
The second argument of useRegistry is a Java File object representing the content directory. Some things like sources and rewards cannot be registered through code alone and must be done through config files that are automatically detected and loaded from the content directory. A good choice is just the plugin's data folder, which is accessed from Plugin#getDataFolder().
The format for content files is the same as the main AuraSkills plugin, as your content files are merged together with the main plugin's config files when loading skills, stats, and abilities. For example, you can reference auraskills/ namespaced abilities in your skills.yml file, and yourplugin/ namespaced abilities can be used in the AuraSkills skills.yml file.
To create a custom stat, use the CustomStat.builder static method to get an instance of CustomStatBuilder. You must pass in a NamespacedId using NamespacedId.of to identify the stat. Then register the stat with the NamespacedRegistry.
Stats on their own don't represent any game mechanics or attributes. Every stat must also have at least one trait that actually implements functionality. Use the CustomTrait.builder to get a CustomTraitBuilder to create a trait. This CustomTrait is then passed into CustomStatBuilder#trait to link it to the stat. You can also pass in a default trait from the Traits enum if you want to simply split up stats.
The example below shows creating a new dexterity stat with a dodge chance trait adding functionality to evade attacks. We create new classes and assign the trait and stat to static constants for easier access.
You must then register the CustomTrait and CustomStat in your plugin's onEnable:
Replace "pluginname" with the name of your plugin in lowercase. The name passed into NamespacedId.of must match the one passed in AuraSkillsApi#useRegistry.
The above code only registers the existence and display elements of the stat without any gameplay functionality. If your stat only uses existing traits, this is all you need. However, if are creating a new trait like the example above, you must add additional code to actually implement your trait's functionality.
To implement your trait functionality, create a new class that implements BukkitTraitHandler:
Finally, register your BukkitTraitHandler in onEnable:
Here is an example stats.yml for the Dexterity/Dodge Chance example above:
You are responsible for generating the stats.yml file in the user's folder using Plugin#saveResource.
To create a custom skill, get an instance of the builder using CustomSkill.builder and pass in a NamespacedId using NamespacedId.of. Then register the skill with the NamspacedRegistry.
The following is an example for creating a Trading skill that gives XP when trading with villagers. We create a new CustomSkills class with a static constant to hold the reference to the skill instance for easier access.
Then, register the skill in your plugin's onEnable:
To add ways to gain XP for a custom skill, create a sources file with the same format as the AuraSkills sources files. For our example, create a file at sources/trading.yml.
In our case, there is no existing source type that handles trading with villagers, so we will need to create our own using the API.
First, create a class that extends CustomSource to hold the configurable data of your source. In this case for simplicty, our only parameter will be the number of emeralds transacted in the trade, so we just need to add a configurable multiplier for this value. Keep the SourceValues constructor argument in your constructor and add your parameters to the end of it.
Then, you need to register your source type and create a parser to deserialize the source from configuration. Use NamespacedRegistry#registerSourceType to register the name and parser of your source.
The first argument, name, is a lowercase name for your source used to construct its NamspacedId used as the type key in the sources config. If you pass in trading as the name, you would use type: pluginname/trading in the sources config.
The second argument accepts an instance of XpSourceParser where the type parameter is your CustomSource class. You can create a new class, or use a lambda like in this example:
To make your source actually give XP, you need to implement a leveler that listens to the proper Bukkit events or implements some other mechanism for gaining XP. You can create an instance of the LevelerContext class to help you create a leveler. It contains useful methods like checking blocked locations and players. To create an instance, you need to pass an instance of the API and the SourceType returned when you registered it.
After you register the source type, you still have to create a sources file for your skill to actually define the XP source. In this example, we create a sources/trading.yml file:
You are responsible for generating the sources file in the user's folder using Plugin#saveResource.
Rewards are added by creating a rewards file in the same format as the AuraSkills rewards files. For this example, create a file at rewards/trading.yml. We make Trading give the Luck stat every skill level and the Dexterity stat created above every two levels:
To add a custom ability, use the CustomAbility.builder static method to get an instance of CustomAbilityBuilder. This example creates an ability called Magic Archer that gives additional Archery XP when using spectral or tipped arrows. We create a new class to hold static constant references to our abilities for easier access.
Then, register your CustomAbility using the NamespacedRegistry in your plugin's onEnable.
You now need to actually implement your ability's functionality. This will vary depending on the mechanics of your ability, but will typically follow this general flow:
Listen to some Bukkit event
Perform some checks confirming the ability can actually be used. You can create an instance of theAbilityContext class and use methods like isDisabled and failsChecks to return early.
Get the player's ability value using Ability#getValue(SkillsUser#getAbilityLevel)
Use the value to modify gameplay mechanics
The implementation of the example ability won't be shown, but it would be done by listening to the EntityXpGainEvent and using setAmount to change the XP gained.
For your ability to work, it must be linked to a skill. You can do this by calling the ability or abilities methods on CustomSkillBuilder when building your CustomSkill. You can also add it to the abilities list of a skill in any skills.yml configuration file, including for existing default skills. Make sure to use the full NamespacedId to reference your ability in the config in the format pluginname/abilityname.
The example above hardcoded the values for baseValue, unlock, levelUp, etc. If you want to make these values configurable by the user, create an abilities.yml file in your content directory. The format is the same as the AuraSkills file.
You are responsible for generating abilities.yml in your user's plugin folder using Plugin#saveResource.
Adding a custom mana ability is similar to creating a normal ability. Use the builder to create a CustomManaAbility instance. This example creates a mana ability called Leap for Agility that launches the player forward when right clicking a feather. We create a new class to hold a static constant reference to our mana abillity for easier access.
To define the values for your mana ability like base_value, value_per_level, base_cooldown, base_mana_cost, etc., you can either set them directly using the builder methods or create a mana_abilities.yml file in your content directory in the same format as the AuraSkills file, but with the mana ability name being your mana ability's NamespacedId of course. You should define all the necessary options using one of the two methods, otherwise they will use arbitrary default values.
Make sure to register your CustomManaAbility in your plugin's onEnable.
You must then implement the functionality for your mana ability yourself using Bukkit events and other API calls to get the mana ability values. For example, to get the value for a user, get the mana ability level using SkillsUser#getManaAbilityLevel and pass it into ManaAbility#getValue:
AuraSkills 2.2 Release Notes
Add anti-AFK system for preventing AFK XP gain
This is an optional feature that detects and blocks repetitive AFK skill XP gain, encouraging active play
Must be manually enabled with the anti_afk.enabled option in the main config
There are 8 types of checks that can block AFK XP gain in the following skills: Farming, Foraging, Mining, Fishing, Excavation, Fighting, Archery, and Defense
The checks work in one of three ways: detecting identical player coordinates, facing direction (pitch/yaw), or the entity being involved
Checks are configured in the anti_afk.checks section
Specific checks can be toggled with the enabled option
The min_count option is the number of identical XP gain conditions in a row for the player to be blocked from gaining XP
The max_distance option for some checks is the threshold for which movement below that value is still considered identical
Logging for failing anti-AFK checks can be enabled with the anti_afk.logging_enabled option
The log_threshold is 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.
Logs will be sent to any online player with the auraskills.antiafk.notify permission (op by default)
Logs are saved to storage can can be viewed for any player with the /skills antiafk logs <player> [page] [perPage] command (auraskills.command.antiafk.logs permission)
Important disclaimer: A player failing checks and being logged does not necessarily mean they are cheating or using a macro, as false positives can be common for legitmate players, especially if min_count is low. An example is a player using a mob farm manually can still trigger anti-AFK checks. Always check logged players manually before taking any action.
Add entity loot for fishing loot tables
The new entity loot type adds the ability to catch entity with fishing
Defined by a loot entry with type: entity
The entity key 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)
The health key overrides the entity max health attribute
The damage key overrides the entity attack damage attribute
The level key can be used to define the AuraMobs or MythicMobs level
The default vertical and horizontal velocities when caught can be overridden with velocity.horizontal and velocity.vertical
The keys hand, off_hand, feet, legs, chest, and head are used to define equipment on the spawned entity
The value is a mapping in the same item format as regular item loot (Using keys material, enchantments, etc.)
Add boss bar animation using delay when upgrading progress
This allows players to visually see the change in progress when a new boss bar is shown
Can be toggled with the boss_bar.animate_progress option in the main config
Add support for multiple commands on one loot entry
Use a commands list of strings on a command loot entry instead of command
Optimize leaderboard updating for SQL
Optimize SQL user loading and saving
A user is now loaded in a single statement with subqueries
Saving key_values will now utilize batched statements
Fix disabled abilities still showing in abilities menu
Fix level up title not working in 1.20.5+
Fix XP Convert giving extremely high experience values
Fix boss bar income showing for jobs enabled without economy
Relocate and create Configurate API wrapper (breaking change)
ConfigurationNode has been replaced with the ConfigNode wrapper class in api and api-bukkit
Configurate is no longer included in the api module as a dependency
Any plugins working with ConfigurationNode in the API will break and must be updated (such as using LootParser, creating custom source types, or ItemManager#parseItem)
Updating is done by simply renaming ConfigurationNode mentions to ConfigNode, as most methods are copied over exactly
This change was made to fix critical loading errors with plugins like Nova
Add trait modifier methods to ItemManager
Deprecate addModifier, getModifiers, and removeModifier to be replaced by addStatModifier, getStatModifiers, and removeStatModifier
Add action bar methods to SkillsUser for sending and pausing action bars
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 . Stats can also be increased through modifiers created with commands or on items.
Not to be confused with passive .
Permission rewards currently only work if you use as your permissions plugin.
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 .
Each source has a name, which is simply the name of the section it is defined in. This name can be used in the section to reference the source. Sources must have unique names within a single skill.
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 for details.
income_per_xp - Gives money based on the value times the XP gained. Only works if jobs are enabled in the . 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_expression - An expression to calculate the income, works the same as the jobs.income.default.expression in the . Only works if jobs are enabled. Mutually exclusive with income_per_xp and income.
left_item - An defining valid items in in the left slot. (Required)
block - The block type/material. This must be a valid Bukkit in all lowercase. (Required)
cause - The cause of the damage that is required for the source. Must be a valid Bukkit in all lowercase.
damager - A specific entity type that the player must be damaged from. Can be either mob, player, or any Bukkit in all lowercase. Specifying a damager automatically excludes the source from non-entity damage, like fall damage.
entity - A valid Bukkit that specifies the type of entity the player kills/damages. (Required)
cause - The cause of the damage that is required for the source. Must be a valid Bukkit in all lowercase.
statistic - The name of the statistic to track increases and give XP for. Must be a valid Bukkit in all lowercase. (Required)
material - A single specific material the item must be. This should be a valid Bukkit in all lowercase.
type - A valid Bukkit to match in all lowercase.
As mentioned above, the menu_item option is a section that defines the item used in the sources menu to represent the source. The format for this section is explained in the .
The plugin uses the library for menus; most of the information on configuring items, templates, and lore can be found there.
Main article:
The items section defines single items in a menu. See the for how to configure an item's material, nbt, lore, etc.
Main article:
The templates section is used for items with a similar layout that appear multiple times in the same menu. See the for how to configure templates.
Main article:
The components section is used to configure sections of lore used in some templates. See the for a full explanation.
The menu files use the format by default. Styles are defined using tags with angle brackets (<tag>) with optional closing tag (</tag). The old Bukkit method of styling (such as &a) is also supported if you want to use it, though MiniMessage is preferred due to its greater features.
Hex colors can be defined using <#00ff00>. See the for the full format. However, some MiniMessage features like hover and click may not work.
Not to be confused with .
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).
See the for a list of options.
Grant . Optionally it can improve permission multiplier lookup performance which is enabled by default and in most cases you shouldn't disable it. If you are having issues like incorrect multiplier calculations, then turn this off by setting hooks.LuckPerms.use_permission_cache to false in the main config file.
AuraSkills provides a lot of placeholders through PlaceholderAPI. You can view the full list .
when you hit an entity.
We can't provide more support than this. If you are not sure about how Mythic triggers/targeters or conditions work, please learn about them in their or ask for support on their Discord server.
We can't provide more support than this. If you are not sure about how Mythic triggers/targeters or conditions work, please learn about them in their or ask for support on their Discord server.
You can set your preferred_rpg_provder in MMOItems to AURA_SKILLS. This way you can create items that are using mana from this plugin. You can also make your items give AuraSkills stats and mana to players, or restrict their usage by skill levels. For a more detailed guide on how to set this up please refer to the official .
Can require mana to let players use the items. Use for this to work.
Color and formatting is done using the format. Legacy Bukkit color codes using & will still work.
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.
If there isn't a message file for your language, or messages in your language are incomplete, check if it exists on . You can directly translate messages one-by-one there or uploading your completed messages files. If your language isn't listed there, ask on for it to be added.
See or .
Yes, see .
See the for migration steps.
See the for more details.
Don't know what's new in 2.0? Read the .
Javadocs are available .
The global registry is used to get any Skill, Stat, Ability, etc instance by its NamespacedId. This allows you to parse content from a name that supports custom content. Use AuraSkillsApi#getGlobalRegistry to get the registry. This is a read-only interface, to register your own custom content, see .
To make your stat and trait configurable by users of your plugin, create a stats.yml file in your plugin's that you linked to the NamespacedRegistry used to register your traits/stats.
If your custom skill's XP sources use existing source types available in default skills (such as breaking blocks, killing a mob, tracking a statistic, etc), then you just need to add configured sources of the existing types to the file. See for how to add existing source types.
The source argument of the lambda is a ConfigurationNode from that contains the keys and values from the configuration section of the source to load. The context argument is a SourceContext that contains useful parsing methods for enforcing required keys or getting pluralized values. You also need to use context.parseValues(source) to get the SourceValues object to pass as the first argument of your source type constructor. This parses things like the name, xp, and display_name of the source for you, so you only need to implement parsing of your custom options.
AuraSkills 2.2 adds the anti-AFK system for detecting and stopping AFK XP gain and macros. Also added is the entity loot type for catching entities while fishing. Additionally, a breaking was made.
scale_base_value_chance
treasure_hunter, epic_catch, metal_detector, lucky_spades
If true, the value of the ability will scale the loot table base_chance instead of adding. The chance is multiplied by 1 + value/100.
enable_message
first_strike, revival
Whether the player should be sent an action bar message when the ability activates.
cooldown_ticks
first_strike
The number of ticks required for First Strike to refresh. Defaults to 6000 (5 minutes).
enable_enemy_message
bleed
Whether to send an action bar message when a player makes an enemy bleed.
enable_self_message
bleed
Whether to send an action bar message when yourself is bleeding.
enable_stop_message
bleed
Whether to send an action bar message when your own bleeding stops.
base_ticks
bleed
The number of bleed ticks to add when the player is not already bleeding.
added_ticks
bleed
The number of bleed ticks to add when the player is already bleeding.
tick_period
bleed
The number of Minecraft ticks between each time a bleed tick applies.
show_particles
bleed
Whether to spawn particles when bleeding.
health_percent_required
fleeting
The maximum percent health a player can be for Fleeting to apply.
add_item_lore
alchemist
Whether to add lore to potions brewed to display the duration bonus.
speed_reduction
stun
The speed reduction factor when stunned. 0.2 = 20% reduction in speed.
auraskills.multiplier.[percent]
Format for skill XP multipliers. Replace [percent] with the percent more XP the player should get. Ex: auraskills.multiplier.100 = 100% more XP = 2x XP.
false
auraskills.multiplier.[skill].[percent]
Format for skill XP multipliers for a specific skill only. Replace [skill] with the name of the skill the multiplier applies to. Otherwise works the same as above. Ex: auraskills.multiplier.farming.50.
false
auraskills.skill.[skill]
Permissions that control access to a specific skill. Replace [skill] with the name of a skill. If the permission is set to false, players will not be able to gain XP, use abilities, or gain stats from that skill. Ex: auraskills.skill.mining
true
auraskills.command.skills
/skills
true
auraskills.command.stats
/stats
true
auraskills.command.sources
/sources
true
auraskills.command.help
/sk help (only lists commands player has access to)
true
auraskills.command.mana
/mana (only for viewing own mana)
true
auraskills.command.top
/sk top and /skilltop
true
auraskills.command.rank
/sk rank and /skillrank
true
auraskills.command.lang
/sk lang
true
auraskills.command.abtoggle
/abtoggle and /sk toggle
true
auraskills.command.save
/sk save
op
auraskills.command.claimitems
/sk claimitems
true
auraskills.command.version
/sk version
op
auraskills.command.multiplier
/sk multiplier
op
auraskills.command.updateleaderboards
/sk updateleaderboards
op
auraskills.command.transfer
/sk transfer
op
auraskills.command.mana.add
/mana add
op
auraskills.command.mana.remove
/mana remove
op
auraskills.command.mana.set
/mana set
op
auraskills.command.mana.other
/mana <player> (Viewing mana of other players)
op
auraskills.command.reload
/sk reload
op
auraskills.command.backup.save
/sk backup save
op
auraskills.command.backup.load
/sk backup load
op
auraskills.command.skill.setlevel
/sk skill setlevel and /sk skill setall
op
auraskills.command.skill.reset
/sk skill reset
op
auraskills.command.xp.add
/sk xp add
op
auraskills.command.xp.set
/sk xp set
op
auraskills.command.xp.remove
/sk xp remove
op
auraskills.command.preset
/sk preset load
op
auraskills.command.profile
/sk profile skills|stats
op
auraskills.command.modifier
/sk modifier add|remove|list|removeall
op
auraskills.command.armor.modifier
/sk armor modifier add|remove|list|removeall
op
auraskills.command.armor.requirement
/sk armor requirement add|remove|list|removeall
op
auraskills.command.armor.multiplier
/sk armor multiplier add|remove|list|removeall
op
auraskills.command.item.modifier
/sk item modifier add|remove|list|removeall
op
auraskills.command.item.requirement
/sk item requirement add|remove|list|removeall
op
auraskills.command.item.multiplier
/sk item multiplier add|remove|list|removeall
op
auraskills.command.item.register
/sk item register|unregister
op
auraskills.command.item.give
/sk item give
op
auraskills.command.item.ignore
/sk item ignore add|remove
op
auraskills.command.openmenu
/sk openmenu
op
auraskills.command.jobs
/sk jobs add|remove|removeall
op
auraskills.command.jobs.other
/sk jobs add|remove|removeall when other user is specified
op
auraskills.jobs.limit.[number]
Max active jobs a player can have at once. Ex: auraskills.jobs.limit.4
false
auraskills.jobs.block.[skill]
Prevents a skill from being selected as a job if set to true. Ex: auraskills.jobs.block.mining
false
auraskills.checkupdates
Whether plugin update messages on join should be sent to the player.
op
auraskills.*
Permissions for all commands
false
auraskills.command.user
Permissions users have by default
true
auraskills.skill.*
Permissions to use all skills
true
auraskills.command.item.*
Permissions related to item modifier creation
false
auraskills.command.armor.*
Permissions related to armor modifier creation
false
auraskills.command.admin
Permissions for all admin/op commands
false
AuraSkills 2.3 Release Notes
AuraSkills 2.3 adds new customization features for the stats and requirements systems. The new stat info menu shows players exactly how stat and trait levels are calculated, while percentage-based and temporary modifiers create new ways to use stats. Block requirements add a flexible way to restrict breaking blocks based on skills.
The plugin now requires at least Java 21
Drop support for Minecraft 1.18.x and 1.19.x
Add 1.21.5 support
Add stat_info menu
This allows players to see exactly how their stat and trait levels are calculated
Accessed by clicking any of the stat items (glass panes) in the stats menu (/stats)
The menu is tab-based and shows stat modifiers by default. Trait modifiers can be viewed by clicking on the tab buttons on the right.
Each tab shows any base value, value from skill rewards, and custom modifiers
Add percentage-based stat and trait modifiers
Modifiers now have an operation value that defines how they are applied
The add_percent operation multiplies the stat level by 1+value/100
For example, a modifier with value 50 multiplies the stat by 1.5
The values for all add_percent modifiers for a stat are added together before multiplying the stat (additive multiplier)
The multiply operation directly multiplies the stat level by the value
For example, a modifier with value 2 doubles the stat level
Each multiply modifier is applied separately (multiplicative modifier)
All existing modifiers use the add operation, which is the basic addition to the stat level
All add modifiers are applied before any add_percent or multiply modifiers
The following existing commands have been modified to add an operation argument:
/skills modifier add <player> <stat> <name> <value> [operation] [silent] [stack]
/skills trait add <player> <trait> <name> <value> [operation] [silent] [stack]
/skills item modifier add <player> <stat> <value> [operation] [lore]
/skills item trait add <player> <trait> <value> [operation] [lore]
/skills armor modifier add <player> <stat> <value> [operation] [lore]
/skills armor trait add <player> <trait> <value> [operation] [lore]
The operation argument is optional and defaults to add
Add temporary modifiers
Temporary modifiers are automatically removed after certain amount of time
Use the following commands to add temporary stat and trait modifiers:
/skills modifier addtemp <player> <stat> <name> <value> <duration> [pauseOffline] [operation] [silent] [stack]
/skills trait addtemp <player> <trait> <name> <value> <duration> [pauseOffline] [operation] [silent] [stack]
The duration argument is in the format [years]y[months]mo[days]d[hours]h[minutes]m[seconds]s
Examples of valid durations are 5s, 10m, and 4d2m1s
The pauseOffline argument defines whether the remaining duration should stop counting down when the player is offline (defaults to false)
Add block requirements
Block requirements are customizable restrictions on breaking, placing, or harvesting blocks
Requirements are defined in requirement.blocks.list in config.yml
Each element in the list can have the following keys:
material - The name of the block to add requirements for (required)
allow_break - Whether to ignore requirements on block break (defaults to false)
allow_place - Whether to ignore requirements on block place (defaults to false)
allow_harvest - Whether to ignore requirements on block harvest (defaults to false)
When none of the above allow options are defined, the block cannot be broken, placed, or harvested when requirements are not met
requirements - A map list of the requirement nodes for this block. Each element in the list can have the following keys:
type - The type of requirement, which can be skill_level, permission, excluded_world, or stat
message - The error message to send to the player when the requirement is not met. Supports MiniMessage and PlaceholderAPI (optional).
Each type has specific keys below that must be added to define type behavior. These keys are added in the same indent level as type.
The skill_level type requires the player to be at least a specific level in a skill. Keys:
skill - The name of the skill to add a level requirement for
level - The minimum skill level the player must be
The permission type requires the player to have a specific permission node. Keys:
permission - The permission node required
The excluded_world type defines a list of worlds that will make the requirement fail if the player is in one of them. Keys:
worlds - The list of worlds to not allow the player to be in
The stat type requires the player to be at least a specific stat level. Keys:
stat - The name of the stat to add a level requirement for
value - The minimum stat value that the player must be
General options related to the block requirement system are in requirement.blocks:
enabled - Whether block requirements are checked at all
bypass_in_creative_mode - Whether to ignore block requirements for players in creative mode (defaults to true)
bypass_if_op - Whether to ignore block requirements for players that are op (defaults to false)
Add addition protections against removing items from menus
Enable by setting menus.removal_protection in config.yml to true (false by default)
Add speed_reduction option to Stun ability
Add translatable messages for command descriptions and update notification
Add item_model support in menu and loot items
Add percent_format and current_xp_format options to skills menu
Add xp_format option to sources menu
Add format option to stat reward to configure decimals
Add Nexo support
Storing modifiers with SQL has been moved from the key_values table to a new modifiers table
Existing modifiers will be migrated automatically
A new schema_migrations table stores previously applied migrations
Remove Oraxen support
Fix default item options like glow being saved when updating files
Fix errors when Anvil Discount is not loaded
List of incompatible software
The following server software will not receive support. Although the plugin may work, it is prone to issues and deviates from the mechanics of Spigot/Paper.
CraftBukkit - Action bar will not work
Modded hybrid servers (Arclight, Mohist, Magma, CatServer) - Modded environments do not work well with Bukkit plugins in general, some features are reported to be broken especially around health.
Offline Mode - We do not provide support for offline mode on Discord due to terms of service and the EULA. Certain features around player data saving may not work. Use at your own risk.
LoreAttributesRecoded - Will reset health when doing certain actions. Can be fixed by disabling the health in that plugin.
CustomEnchants (not all enchant plugins, just the one specifically named this) - Will reset health when doing certain actions.
AuraSkills 2.1 Release Notes
AuraSkills 2.1 adds the jobs system, an optional feature that allows players to earn money while gaining XP. New commands have also been added to add trait modifiers to players, items, and armor.
Jobs must be manually enabled in config.yml and requires Vault plus an economy plugin to be installed to work.
Add jobs system
Jobs is an optional feature that allows players to select skills as jobs to earn money while gaining XP.
To use jobs, the jobs.enabled option must be set to true in config.yml
Income for all XP sources is configured under jobs.income
If use_xp is true, sources will give a multiple of the XP gained based on default.income_per_xp
If use_expression is true, sources will give XP based on the result of default.expression
The available variables include xp, base_xp (value without multipliers), level (skill level), power, and skill_average
If use_final_xp is set to false, the calculation for income_per_xp will exclude all XP multipliers
Job selection is configured under jobs.selection
Players select a skill as a job using a new item in the level progression menu of a skill (gold_ingot by default)
If require_selection is set to false, players will gain income for all skills and selection will be hidden
The default_job_limit is the maximum number of skills that can be selected as jobs at the same time
The limit can be changed per-player using the auraskills.jobs.limit.[number] permission node (ex: auraskills.jobs.limit.4)
The disable_unselected_xp option will block gaining XP in all skills that are not active jobs if set to true
Income can also be configured per-source inside the sources files
Keys can be added to both the default section or an individual source
The following keys can be added to a source:
income_per_xp - The income to give per XP gained, works the same as the value in config.yml
income - A fixed decimal value for the money to give
income_expression - An expression to calculate the income, works the same as the expression in config.yml
Menu files will automatically update to add the new items and components to show job selection
However, you must manually add a new line - component: skill_job_active to the lore of the skill template in menus/skills.yml under - component: max_level
Everything will still work if this line isn't manually added, players just won't see the "Active Job" displayed in the skills menu
New jobs commands:
/skills jobs add <job> [user] - Joins a specific job for yourself or a different player
/skills jobs remove <job> [user] - Quits a specific job for yourself or a different player
/skills jobs removeall [user] - Quits all jobs for yourself or a different player
When user is not specified, these commands use the auraskills.command.jobs permission (op by default)
To specify a different user, the sender must also have the auraskills.command.jobs.other permission (op by default)
New jobs PlaceholderAPI placeholders:
%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
Add trait commands for adding trait modifiers directly to players
/skills trait add <player> <trait> <name> <value> [silent] [stack] - Adds a trait modifier to a player with the given name
/skills trait remove <player> <name> [silent] - Removes a trait modifier from a player with the given name
/skills trait list [player] [trait] - Lists trait modifiers of a player
/skills trait removeall [player] [trait] [silent] - Removes all trait modifiers from a player
The functionality of these commands is almost identical to the modifier commands for stat modifiers
These commands use the existing auraskills.command.modifier permission
Add item and armor trait commands for adding trait modifiers to items
/skills item|armor trait add <trait> <value> [lore] - Adds a trait modifier to the held item, with lore by default
/skills item|armor trait remove <trait> - Removes a trait modifier from the item held
/skills item|armor trait list - Lists all trait modifiers on the item held
/skills item|armor trait removeall - Removes all trait modifiers from the item held
Where item|armor is shown above, only item or armor should be specified, not both
These commands use the existing auraskills.command.item.modifier or auraskills.command.armor.modifier permissions
Like stat modifiers, trait modifiers use PDC and do not depend on lore to function
Add item ignore commands to ignore interactions on specific items
This allows you to disable mana abilities on custom items to allow separate right-click functionality
/skills item ignore add - Adds the tag that ignores the held item from mana ability interactions
/skills item ignore remove - Removes the tag that ignores the held item from mana ability interactions
Add format_title option to menus to allow disabling color and MiniMessage parsing of menu titles
To use, manually add it to the options section of a menu file (create it if it doesn't exist)
Add PlaceholderAPI support to level up chat message
Add %auraskills_xp_bar_[skill]% placeholder that gets the XP progress bar shown in the menus
Optimize menus to significantly improve performance for idle open menus
Change the default skills and level_progression menu files to fully use block style YAML syntax
The default contexts materials of the skill template in the level_progression menu now match the materials in the skills menu
Add symbol placeholder support to item modifier lore message
Automatic backups will now be skipped if the server has too many users (uses new max_users config option)
Add ensure_scaling_disabled option to hp trait in stats.yml to disable health scaling if the trait is disabled (true by default)
Update Japanese, Polish, and Chinese Simplified messages
Fix Bleed and Absorption particle errors on 1.20.5+
Fix mana add command always setting mana to max
Fix hex colors in ability messages not working
Fix added contexts sections breaking some level_progression templates
Fix hp action_bar_scaling not applying to menus and chat
Fix multiplier permissions set to false not being ignored
Fix Disenchanter not working when shift clicking to remove an item with a different item on the cursor
Fix hide_attributes flag not working in 1.20.5+
Fix Alchemist duration lore stacking on the same potion
Add job methods to SkillsUser
Add Trait#getMenuDisplay to get the trait value formatted as shown in the stats menu
Fix MenuManager#buildMenu not working when called multiple times to extend the same menu
List of PlaceholderAPI placeholders
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.
%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%)
List of plugin commands
The following commands are accessible to all players by default.
/skills
Opens the skills menu, which shows an overview and player progress in all skills.
auraskills.command.skills
/stats
Opens the stats menu, which shows an overview and player levels in all stats.
auraskills.command.stats
/[skill]
Opens the level progression menu of a specific skill directly, where [skill] is the name of the skill (e.g. /farming, /archery, /healing). These commands can be disabled in config.yml at enable_skill_commands
auraskills.skill.[skill] (Controls access to all skill features)
/sk lang [language]
Changes your personal language used for messages and menus. Must be a valid language code (see tab completion).
auraskills.command.lang
/abtoggle or /sk toggle
Toggles your personal action bar.
auraskills.command.abtoggle
/sk top [page] or /skilltop [page]
Shows the leaderboard of top players in all skills (sum of skill levels).
auraskills.command.top
/sk top <skill> [page] or /skilltop <skill> [page]
Shows the leaderboard of top players in a specific skill.
auraskills.command.top
/sk top average [page] or /skilltop average [page]
Shows the leaderboard of the average of a player's skill levels.
auraskills.command.top
/sk rank or /skillrank
Shows your skill rankings.
auraskills.command.rank
/mana
Shows your current mana.
auraskills.command.mana
/sk claimitems
Opens the menu to claim items (from item rewards or /sk item give) that did not fit into the player's inventory initially.
auraskills.command.claimitems
/sk sources <skill> [sortType]
Opens the sources menu for a skill, which displays the ways to gain XP.
auraskills.command.sources
/sk help
Shows the command help page.
auraskills.command.help
The following commands are only accessible to players with op by default.
/sk reload
Reloads the plugin config, messages, menus, loot tables, etc. Some options may require a restart.
auraskills.command.reload
/sk version
Shows the current version of the plugin.
auraskills.command.version
/sk skill setlevel <player> <skill> <level>
Sets a skill to a level for a player.
auraskills.command.skill.setlevel
/sk skill setall <player> <level>
Sets all skills to a level for a player.
auraskills.command.skill.setlevel
/sk skill reset <player> [skill]
Resets all skill to the starting level (0 or 1 depending on start_level in config.yml) for a player, or a specific skill if skill is provided.
auraskills.command.skill.reset
/sk xp add <player> <skill> <amount> [silent]
Gives skill XP to a player in a skill.
auraskills.command.xp.add
/sk xp set <player> <skill> <amount> [silent]
Sets a player's skill XP to an amount in a skill.
auraskills.command.xp.set
/sk xp remove <player> <skill> <amount> [silent]
Removes skill XP from a player in a skill. Does not decrease a player's skill level, only the XP progress of the current level.
auraskills.command.xp.remove
/sk multiplier [player]
Shows a player's current XP multiplier based on their cummulative auraskills.multiplier.* permissions.
auraskills.command.multiplier
/sk backup save
Saves a backup of the current skill data to the backups folder.
auraskills.command.backup.save
/sk backup load <file>
Loads a backup from the backups folder. You must specify the exact file name, including the file extension. This will override the current skill data, so it is advised to take a backup before loading one.
auraskills.command.backup.load
/sk save
Saves skill data.
auraskills.command.save
/sk updateleaderboards
Sorts and updates skill leadeboards.
auraskills.command.updateleaderboards
/sk transfer <playerFrom> <playerTo>
Copies the player data from one player to another. playerFrom and playerTo must be valid UUIDs. The player data from playerFrom is not reset. Players do not have to be online for this to work.
auraskills.command.transfer
sk resethealth
Removes all AureliumSkills player health and luck attributes. Useful if you want to uninstall the plugin. This command can only be run through console and there should be no players online to work properly.
N/A
/sk preset load <file>
Loads a config preset from the presets folder, replacing and modifying the current configuration. The file must be the full file name and end in .zip. Requires to be typed twice for confirmation.
auraskills.command.preset
/sk profile skills <player>
Views the skill levels of another player. player is the username of the player you want to view skills for. This player does not have to be online.
auraskills.command.profile
/sk profile stats <player>
Views the stat levels of another player. player is the username of the player you want to view skills for. This player does not have to be online.
auraskills.command.profile
/mana <player>
Shows how much mana a player has.
auraskills.command.mana.other
/mana add <player> <amount> [allowOverMax] [silent]
Adds mana to a player. If allowOverMax is true, added mana can go over max mana. By default, mana will be capped at max mana.
auraskills.command.mana.add
/mana remove <player> <amount> [silent]
Removes mana from a player. Mana cannot go below 0, any extra is ignored.
auraskills.command.mana.remove
/mana set <player> <amount> [allowOverMax] [silent]
Sets the mana of a player.
auraskills.command.mana.set
/sk modifier add <player> <stat> <name> <value> [operation] [silent] [stack]
Adds a stat modifier to a player. Setting silent to true will not send a feedback message. Setting stack to true will add the stat modifier even if the name is already used by appending a number to the end.
auraskills.command.modifier
/sk modifier addtemp <player> <stat> <name> <value> <duration> [pauseOffline] [operation] [silent] [stack]
Adds a temporary stat modifier to a player with the given name. The duration argument is in the format [years]y[months]mo[days]d[hours]h[minutes]m[seconds]s. Examples of valid durations are 5s, 10m, and 4d2m1s. The pauseOffline argument defines whether the remaining duration should stop counting down when the player is offline (defaults to false).
auraskills.command.modifier
/sk modifier remove <player> <name> [silent]
Removes a specific stat modifier from a player.
auraskills.command.modifier
/sk modifier list [player] [stat]
Lists all stat modifiers. If player is not specified, modifiers for yourself will be listed. Specifying stat only shows that stat's modifiers.
auraskills.command.modifier
/sk modifier removeall [player] [stat] [silent]
Removes all stat modifiers. If player is not specified, all modifiers for yourself will be removed. Specifying stat only removes that stat's modifiers.
auraskills.command.modifier
/sk item modifier add <stat> <value> [operation] [lore]
Adds an item stat modifier to the item held, along with lore by default.
auraskills.command.item.modifier
/sk item modifier remove <stat> [lore]
Removes an item stat modifier from the item held, and the lore associated with it by default.
auraskills.command.item.modifier
/sk item modifier list
Lists all item stat modifiers on the item held.
auraskills.command.item.modifier
/sk item modifier removeall
Removes all item stat modifiers from the item held.
auraskills.command.item.modifier
/sk armor modifier add <stat> <value> operation] [lore]
Adds an armor stat modifier to the item held, along with lore by default.
auraskills.command.armor.modifier
/sk armor modifier remove <stat> [lore]
Removes an armor stat modifier from the item held, and the lore associated with it by default.
auraskills.command.armor.modifier
/sk armor modifier list
Lists all armor stat modifiers on the item held.
auraskills.command.armor.modifier
/sk armor modifier removeall
Removes all armor stat modifiers from the item held.
auraskills.command.armor.modifier
/sk item requirement add <skill> <level> [lore]
Adds an item requirement to the item held, along with lore by default.
auraskills.command.item.requirement
/sk item requirement remove <skill> [lore]
Removes an item requirement from the item held, and the lore associated with it by default.
auraskills.command.item.requirement
/sk item requirement list
Lists the item requirements on the item held.
auraskills.command.item.requirement
/sk item requirement removeall
Removes all item requirements from the item held.
auraskills.command.item.requirement
/sk armor requirement add <skill> <level> [lore]
Adds an armor requirement to the item held, along with lore by default.
auraskills.command.armor.requirement
/sk armor requirement remove <skill> [lore]
Removes an armor requirement from the item held, and the lore associated with it by default.
auraskills.command.armor.requirement
/sk armor requirement list
Lists the armor requirements on the item held.
auraskills.command.armor.requirement
/sk armor requirement removeall
Removes all armor requirements from the item held.
auraskills.command.armor.requirement
/sk item multiplier add <target> <value> [lore]
Adds an item multiplier to the item held, which multiplies XP when held. target is either the name of a skill, or global to add a multiplier for all skills. value is the percent more XP gained (100 = 2x XP).
auraskills.command.item.multiplier
/sk item multiplier remove <target>
Removes an item multiplier from the item held.
auraskills.command.item.multiplier
/sk item multiplier list
Lists the item multipliers on the item held.
auraskills.command.item.multiplier
/sk item multiplier removeall
Removes all item multipliers from the item held.
auraskills.command.item.multiplier
/sk armor multiplier add <target> <value> [lore]
Adds an armor multiplier to the item held, which multiplies XP when worn. target is either the name of a skill, or global to add a multiplier for all skills. value is the percent more XP gained (100 = 2x XP).
auraskills.command.armor.multiplier
/sk armor multiplier remove <target>
Removes an armor multiplier from the item held.
auraskills.command.armor.multiplier
/sk armor multiplier list
Lists the armor multipliers on the item held.
auraskills.command.armor.multiplier
/sk armor multiplier removeall
Removes all armor multipliers from the item held.
auraskills.command.armor.multiplier
/sk item register <key>
Registers the held item to a unique key. This key can be used to represent the exact item in configs like rewards and loot.
auraskills.command.item.register
/sk item unregister <key>
Unregisters an item from the item registry.
auraskills.command.item.register
/sk item give <player> <key> [amount]
Gives a registered item to a player. If the player does not have enough inventory space, the item will be added to the player's unclaimed items, which is claimed using /sk claimitems.
auraskills.command.item.give
/sk openmenu <menuName> [player] [properties] [page]
Opens a menu for a player. If player is not specified, it opens for the sender. The properties argument is a JSON string required to open some menus. For example, {"skill":"Skill:mining"} should be passed when opening the level_progression, abilities, sources, and leaderboard menu. The page argument starts at 0 for the first page.
auraskills.command.openmenu
/sk jobs add <job> [user]
Joins a specific job for yourself or a different player.
auraskills.command.jobs (auraskills.command.jobs.other when user is specified)
/sk jobs remove <job> [user]
Quits a specific job for yourself or a different player.
auraskills.command.jobs (auraskills.command.jobs.other when user is specified)
/sk jobs removeall [user]
Quits all jobs for yourself or a different player.
auraskills.command.jobs (auraskills.command.jobs.other when user is specified)
/sk trait add <player> <trait> <name> <value> [operation] [silent] [stack]
Adds a trait modifier to a player with the given name.
auraskills.command.modifier
/sk trait addtemp <player> <trait> <name> <value> <duration> [pauseOffline] [operation] [silent] [stack]
Adds a temporary trait modifier to a player with the given name. The duration argument is in the format [years]y[months]mo[days]d[hours]h[minutes]m[seconds]s. Examples of valid durations are 5s, 10m, and 4d2m1s. The pauseOffline argument defines whether the remaining duration should stop counting down when the player is offline (defaults to false).
auraskills.command.modifier
/sk trait remove <player> <name> [silent]
Removes a trait modifier from a player with the given name.
auraskills.command.modifier
/sk trait list [player] [trait]
Lists trait modifiers of a player.
auraskills.command.modifier
/sk trait removeall [player] [trait] [silent]
Removes all trait modifiers from a player.
auraskills.command.modifier
/sk item trait add <trait> <value> [operation] [lore]
Adds an item trait modifier to the held item, along with lore by default.
auraskills.command.item.modifier
/sk item trait remove <trait>
Removes an item trait modifier from the item held.
auraskills.command.item.modifier
/sk item trait list
Lists all item trait modifiers on the item held.
auraskills.command.item.modifier
/sk item trait removeall
Removes all item trait modifiers from the item held.
auraskills.command.item.modifier
/sk armor trait add <trait> <value> [operation] [lore]
Adds an armor trait modifier to the held item, along with lore by default.
auraskills.command.armor.modifier
/sk armor trait remove <trait>
Removes an armor trait modifier from the item held.
auraskills.command.armor.modifier
/sk armor trait list
Lists all armor trait modifiers on the item held.
auraskills.command.armor.modifier
/sk armor trait removeall
Removes all armor trait modifiers from the item held.
auraskills.command.armor.modifier
/sk item ignore add
Adds the tag that ignores the held item from mana ability interactions.
auraskills.command.item.ignore
/sk item ignore remove
Removes the tag that ignores the held item from mana ability interactions.
auraskills.command.item.ignore
List of requirements for using AuraSkills
AuraSkills requires the following server environment to run, as of version 2.2.x:
Paper, Purpur, or Spigot server
Minecraft 1.17 or newer (latest is always recommended)
Java 17 or newer (Java 21 recommended)
Syntax: <this> indicates a required argument, [this] is an optional argument. See for more details about permissions.
You can view the most up-to-date list of supported Minecraft versions on .
Additionally, ensure your server and other plugins aren't in the list of .
AuraSkills 2.0 Release Notes
New config files for configuring sources of each skill in the sources folder.
Each source now has a specific type and options that fully define when XP is gained. For example, all sources for breaking blocks have type block.
New sources can be added just like default ones, with the type options allowing much more customization and control.
Examples of what is possible:
Gaining XP when a player breaks a block matching any specific block state (allows custom blocks).
Gaining XP for increasing any Minecraft statistic, like the existing running and walking sources.
Gaining XP for consuming a specific item.
Gaining XP for enchanting or brewing a custom item.
Gaining XP for fishing up a custom item.
Sources are no longer tied to their default skill, they can be switched around to any skill.
The new skills.yml file is where individual skills are now configured.
Abilities and mana abilities are no longer tied to their default skill, they can be moved between skills.
New Farming ability: Growth Aura
Crops with growth stages within 30 blocks of you grow {value}% faster.
Unlocks at Farming 5 by default.
New Archery ability: Retrieval
Arrows you miss will be instantly retrieved after 3s up to {value} blocks away.
Unlocks at Archery 1 by default.
New Fighting ability: Parry
Missing a sword swing within 0.25s before being hit reduces damage by {value}% and cancels knockback.
Unlocks at Fighting 1 by default.
Crit Damage, Crit Chance, and Speed have been added as individual stats.
The old Crit Chance Archery ability and Crit Chance Fighting ability have been replaced with normal stat rewards, allowing a new ability to be added for each.
The Speed stat always shows the player's accurate speed, where 100 = 100% (normal) speed. While skills don't directly increase speed by default, you can use it in rewards or modifiers.
Traits are a new system that makes stats more modular and configurable.
A trait represents a single mechanic that a stat changes/improves. For example, the Wisdom stat increases experience gain, reduces anvil costs, and increases max mana. These aspects are now represented as the individual traits experience_bonus, anvil_discount, and max_mana.
Traits can be moved between stats.
Both stats and traits can be easily disabled with one option, instead of having to remove every stat reward.
When linking a trait to a stat, the modifier option determines how much of the trait you gain for each stat level.
When a trait has a modifier of 1 (meaning it's the same number of the stat), it can be displayed instead of the stat value. This allows the health stat to always display the accurate HP amount you have in menus, including the default 20 HP and HP from other plugins.
The Luck stat has been fully reworked to make it more useful. Instead of increasing the Minecraft Luck attribute, which most players don't understand, Luck now increases the new traits Farming Luck, Foraging Luck, Mining Luck, Fishing Luck, and Excavation Luck.
These traits increase the chance for extra item drops of any XP source of those skills.
When a player's luck trait is 150 for example, they have a guaranteed +1 drop and a 50% chance for +2 drops.
Luck traits are also increased by the specific ability in each gathering skill, such as Bountiful Harvest.
The Triple Harvest Farming ability has been removed, since Bountiful Harvest just increases Farming Luck, doing the same thing.
Create the loot/mob.yml file to add mob loot tables and specify specific mob types with the mobs pool option.
Any skill with block sources can now have their own custom loot tables, including farming. Create a file named after the skill, such as loot/farming.yml.
The plugin has been renamed from AureliumSkills to AuraSkills. This means the data folder is now plugins/AuraSkills.
Why? The new name is shorter, simpler, and more meaningful. The original plugin name didn't have a meaning when first made, and was pretty long to say and type.
The new data folder allows migration to be implemented more easily, without overriding existing files. This means any problems from migration can be reverted.
PlaceholderAPI placeholders now use the prefix %auraskills_. Old placeholders using %aureliumskills_ will still work, but you should gradually convert your placeholders over to the new prefix.
Because some skills were too slow to level up and had abilities that weren't very useful, some skills have been merged/removed by default. This brings the total skill count from 15 to 11. The existing 15 skills can still be used by applying the legacy config preset using /skills preset load legacy.zip.
If you migrated from Beta, the legacy preset will be automatically applied and you will still have 15 skills. The points below will not apply.
Endurance has been merged into Agility.
Healing has been merged into Alchemy.
Forging has been merged into Enchanting.
The XP sources from the removed skills (Endurance, Healing, and Forging) have been added to the skills they merged with, so you can still gain XP in the same way.
The abilities deemed most useful out of the two skills have been kept, the rest have been not included in default configs.
No abilities have been deleted, you can still add them back in skills.yml.
Sorcery has been removed from defaults since it never had any abilities.
The format and location of config files has signifcantly changed.
Messages in the menus section, as well as skill, stat, and ability descriptions no longer contain formatting. Formatting is now fully done in the menus configuration.
Newlines (\n) have been removed from most messages since menus will insert them automatically through lore wrapping.
Messages that were the same for every language have been moved to a new messages/global.yml file.
The section for each ability is now directly under abilities instead of a section for each skill. This accounts for the fact that abilities can be moved between skills.
The messages for block and mob names have been removed, as these messages are now replaced on the client-side depending on the language the client is using. This reduces the overall message file size by almost 200 lines.
Added menu components, which are lines for certain templates that are inserted into the lore. This allows elements to be hidden/shown when needed while keeping the lore format of the main template clean without a bunch of newline characters.
Added a formats section that defines formats for some items. Most of these were moved from the messages file.
Added different lore line types, with options for automatically wrapping to new lines if the current line is too long. The style/color of the current line can be maintained for the wrapped line.
Added groups, which allow contexts to be defined by an order within an area of the menu, instead of a static position. This allows items to be shifted when one is removed/added without changing all the positions. Groups can be set to align at the center, left, or right or their bounding box.
Placeholders that replace directly from the messages file are now in double curly braces like {{this}}. The format indicates that the message is found directly at the message path menus.menu_name.this or menus.common.this, where menu_name is the name of the menu the placeholder is in and this is the text inside the double curly braces. The change means you can add arbitrary message placeholders in the menu files, including message keys you added yourself.
Placeholders in single curly braces are data placeholders replaced by the plugin directly, usually numbers.
Context sections for templates are now under a contexts section instead of directly under the template.
The unlocked, locked, and in_progress templates in the level_progression menu now have their context from 1-max_level of the skill instead of 1-items_per_page. This allows changing the material of a specific level to signify a special reward.
The appearance of the default menus has been slightly changed.
A progress bar for XP has been added to the skill template and in_progress level_progression item.
In the default 11 skill configuration, the 3 combat skills are now on the first row while the 5 gathering skills are on the second. Agility has been moved to the third row.
The material of loots/amor for each skill item is now all iron.
The your_skills item is now a textured information player head.
The following is a list of changes to the default configuration, most of these will not apply if you migrated from Beta.
Added a start_level option to the main config to define what skill levels players start at by default. Players now start at skill level 0, instead of 1.
boss_bar.mode has been changed to single.
enable_roman_numerals is now false.
Added options to configure the critical hologram colors; the default damage_holograms.colors.critical.digits now start at white instead of gray.
auto_save.enabled is now true.
The max level of all skills is now 100 instead of 97.
Abilities of some skills have been changed due to the skill merging.
The modifier for health and hp is now 1, so the health stat matches the Minecraft HP value. The health stat reward values in the rewards files have been changed to 0.4 to account for this. This means players will see +0.4 Health when leveling, which is accurate to the action bar.
The hearts option in the hp trait has been changed to show more visual hearts earlier to account for less overall possible HP.
Mana regeneration has been heavily reduced to make mana an actual relevant cost (0.1 to 0.02).
The modifier for Strength has been decreased from 0.5 to 0.4
Modifiers for some traits have been scaled differently from the existing stat modifier values.
Base mana regen is now 0.1 per second instead of 1.
Overflow mana (over max mana) is no longer allowed.
The way item/armor modifiers, requirements, and multipliers are stored on items has changed.
The new format uses the built-in PersistentDataContainer API instead of an external library dependent on NMS code.
Old items should be automatically converted to the new format when held.
Most damage modifiers, except Strength, are now additive instead of multiplicative.
This means the percent increases for Crit Damage, tool master abilities, and First Strike will be added together before multiplying the damage.
The codebase has been split into multiple modules to allow the api to be independent from implementation, and opening the possibility for ports to other platforms like Folia or Fabric in the future (not a guarantee).
api - Contains API code not dependent on the Bukkit API
api-bukkit - Contains API code dependent on the Bukkit API, like events. When using the api-bukkit dependency, all the code in the api module is bundled in.
bukkit - Contains implementation code that requires the Bukkit API, such as implementations for sources, abilities, traits, loot, commands, and menus.
common - Contains the core skills systems not dependent on the Bukkit API, including the registries, most configuration loading, messages, rewards, migration, user management, and storage.
The package for the plugin classes is now dev.aurelium.auraskills instead of com.archyx.aureliumskills.
The 2.0 releases adds a brand-new API that is much more capable and extensive than before. It also supports adding custom content (skills, stats, abilities).
AuraSkills 2.0 is a complete recode of the plugin codebase, overhauling existing systems to make everything more modular and customizable. While many of the changes are behind the scenes stuff like changes to configuration and a , there is still some new content that players can enjoy. The default configs have also been simplified and rebalanced through rigorous playtesting, making it fit more seamlessly into the vanilla survival experience.
You must read the guide if updating from Beta, there are major breaking changes!
A completely new and fully customizable has been added for XP sources.
Custom skills, stats, abilities, and mana abilities can be added using the in a seamless way.
Custom can now be created for killing mobs and harvesting farming crops.
For plugins that hook into AureliumSkills, the renaming means compatibility with Beta versions won't break, and a new hook system can be implemented by developers with the brand new and improved . Plugins will be able to support both Beta and 2.0 at the same time easily.
All permissions have been renamed and reorganized. Old ones will not work. See the for the up-to-date list.
All keys in config.yml () now use underscores instead of hyphens.
has been moved to skills.yml.
has been moved to stats.yml.
has been moved to abilities.yml.
has been moved to mana_abilities.yml.
has been moved to the sources folder.
Legacy color codes with & have been replaced with tags. Legacy codes will still work if you want to use them.
Legacy color codes with & have been replaced with tags. Legacy codes will still work if you want to use them.
Main article:
The plugin is now licensed under . For one, this means that forks or modifications to the plugin that you distribute must also have their source-code available.
