Modifying Skills

This is a step tutorial to configure AuraSkills Correctly.

AuraSkills — Setup, Config, Messages, and Menus

This document is written against the current AuraSkills wiki and fixes the common mistakes people make when copying outdated or half-correct setups.

It covers:

• understanding the real file structure

• configuring config.yml

• changing languages and messages the right way

• customizing menus the right way

---

2. Real file structure

A correct high-level structure looks like this:

plugins/AuraSkills/
├── config.yml
├── skills.yml
├── stats.yml
├── xp_requirements.yml
├── xp_multipliers.yml
├── messages/
├── menus/
├── rewards/
├── loot/

Important notes:

• config.yml is the main config file for general plugin behavior

• skills.yml handles skill setup

• stats.yml exists separately; stat options are not all inside config.yml

• messages are not a single messages.yml file by default — AuraSkills uses a messages/ folder with language files

• menus are configured in menus/

---

3. Main configuration (config.yml)

3.1 What config.yml is actually for

The main config handles general and miscellaneous options such as:

• SQL / storage

• language behavior

• plugin hooks

• action bar

• boss bar

• blocked worlds and regions

• anti-AFK

• jobs / income

• death behavior

• leaderboards

It is not the place for all skill-specific and stat-specific behavior.

---

3.2 SQL setup

AuraSkills uses an sql: section in config.yml.

Typical structure:

sql:
  enabled: false
  type: mysql
  host: 127.0.0.1
  port: 3306
  database: auraskills
  username: root
  password: change_me
  load_delay: 20
  always_load_on_join: false
  ssl: false

What matters

• enabled: turns SQL storage on or off

• type: currently mysql

• host, port, database, username, password: database connection values

• load_delay: useful for networks syncing across servers

When to use SQL

Use MySQL when:

• you run multiple servers sharing one player database

• you need central storage

• you want more robust persistence than local-only storage

If you are on one server only and do not need cross-server syncing, keeping SQL disabled is simpler.

---

3.3 Languages

AuraSkills language behavior is controlled in config.yml, while the actual text lives in the messages/ folder.

Relevant options:

default_language: en
try_detect_client_language: false
languages:
  - en

Meaning

• default_language: the language used by default, matching a file like messages_en.yml

• try_detect_client_language: if true, the plugin tries to use the player client's language when possible

• languages: list of allowed language codes players can switch to using /skills lang <language>

Important rule

If you add a custom language code here, there must be a matching language file inside the messages/ folder.

---

3.4 Hooks

Hooks are under hooks:.

Example structure:

hooks:
  Vault:
    enabled: true
  LuckPerms:
    enabled: true
    use_permission_cache: true
  WorldGuard:
    enabled: true
    blocked_regions: []
    blocked_check_replace_regions: []

Why this matters

• Vault is needed for economy integrations and some reward/income systems

• LuckPerms is useful when rewards or permissions are part of progression

• WorldGuard can block XP gain in selected regions

Do not invent generic one-line hook keys if your file already has named plugin subsections.

---

3.5 Action bar

The action bar config is more detailed than just enabled: true.

Example:

action_bar:
  enabled: true
  idle: true
  ability: true
  xp: true
  maxed: true
  update_period: 20
  round_xp: false
  placeholder_api: false
  use_suffix: true
  format_last: false
  update_async: false

What each important option does

• enabled: master switch for all AuraSkills action bars

• idle: shows the idle action bar, including things like health/mana at the bottom

• ability: sends ability notifications through the action bar; if disabled, those messages go to chat instead

• xp: shows XP gain action bar updates while leveling

• maxed: controls action bar behavior when XP is gained in a maxed skill

• update_period: update rate in ticks

• use_suffix: formats values like 1.2k, 3.5m

Practical recommendation

For most servers:

• leave enabled, ability, and xp on

• disable idle if you dislike constant HUD clutter

• increase update_period if you suspect lag from frequent updates

---

3.6 Boss bar

Boss bars are configured separately from the action bar.

Example:

boss_bar:
  enabled: false
  mode: single
  stay_time: 60
  update_every: 20
  round_xp: false
  use_suffix: true
  animate_progress: true

Key options

• enabled: enable boss bar XP display

• mode: single or multi

• stay_time: how long the bar stays after XP gain stops

• update_every: update interval

• animate_progress: enables progress animation

When to use it

Use the boss bar only if you want large, obvious feedback. For cleaner UI, many servers keep it off and rely on the action bar instead.

---

3.7 Jobs and income

AuraSkills includes a jobs system in config.yml.

Important structure:

jobs:
  enabled: false
  selection:
    require_selection: false
    default_job_limit: 3
    disable_unselected_xp: false
    cooldown_sec: 0
  income:
    use_xp: true
    use_expression: false
    default:
      income_per_xp: 0.1
      expression: xp * 0.1
    batching:
      enabled: false
      interval_ms: 2000
      display_individual: true
    use_final_xp: true

What this is for

• lets players earn money from XP gain

• optionally forces players to select which skills count as active jobs

• can batch Vault payments to reduce performance cost

If you are not building a jobs/economy system, leave this disabled.

---

3.8 World and gameplay restrictions

Important global controls include:

enable_roman_numerals: false
start_level: 0
enable_skill_commands: true
blocked_worlds: []
disabled_worlds: []
disable_in_creative_mode: true
check_block_replace:
  enabled: true
  blocked_worlds: []

What these do

• start_level: starting skill level; default is usually 0

• enable_skill_commands: enables commands like /farming and /mining

• blocked_worlds: blocks natural XP gain in listed worlds

• disabled_worlds: disables most gameplay features in listed worlds

• disable_in_creative_mode: blocks XP gain in creative mode

• check_block_replace.enabled: prevents player-placed blocks from giving XP when broken

Strong recommendation

Keep block-replace checks enabled unless you have a specific compatibility problem. Turning this off makes XP farming exploits much easier.

---

3.9 Anti-AFK

AuraSkills has built-in anti-AFK controls.

Relevant structure:

anti_afk:
  enabled: true
  logging_enabled: false
  log_threshold: min_count
  checks:
    position:
      enabled: true
      min_count: 5
      max_distance: 1.0

The exact checks can vary, but the system is there to block repetitive stationary XP farming.

---

4. Messages system

4.1 Where messages actually are

AuraSkills uses a messages/ folder, not just one messages.yml file.

Typical language file pattern:

plugins/AuraSkills/messages/messages_en.yml

If your server language is English and default_language: en, that file is the main one you edit.

---

4.2 What messages files control

The messages files control translatable text for:

• chat messages

• command messages

• menu text content

• other plugin text output

Important distinction:

• messages files change the text itself

• menus files control GUI structure and most menu styling

That distinction matters because many broken guides mix them together.

---

4.3 Formatting rules for messages

AuraSkills uses MiniMessage formatting by default.

Examples:

<green>Hello
<gold><bold>Level Up!
<#00ff00>Custom hex color

Legacy Bukkit codes like &a still work, but MiniMessage is preferred.

Important warning

Do not alter placeholders in {placeholder} format unless you know exactly what they are for. Those are replaced by the plugin with runtime values or linked message content.

---

4.4 Language switching

Server-wide default language comes from config.yml, but players can also use:

/skills lang <language>

That only works for languages listed in the languages: array and backed by actual message files.

---

4.5 Editing messages safely

When changing a message file:

1. keep the YAML indentation intact

2. do not rename keys unless you know the plugin expects a different key

3. do not remove placeholders inside {} unless you want to break the output

4. only edit menu text here if you want different wording, not different menu styling

---

5. Menus system

5.1 What menus are

Menus are inventory GUIs used by commands like /skills, /stats, and the skill-specific progression views.

The wiki lists these built-in menu types:

• skills

• stats

• level_progression

• sources

• abilities

• leaderboard

Each has its own file in the menus/ folder.

---

5.2 Where menu files are

Menu config files are stored in:

plugins/AuraSkills/menus/

Each menu has its own file.

---

5.3 Top-level sections in a menu file

The main top-level sections you can see in a menu file are:

• title

• size

• fill

• items

• templates

• components

• formats

• options

Not every menu uses all of them, but these are the important sections documented by the wiki.

---

5.4 title

title is the inventory title shown at the top.

Example:

title: <dark_gray>Skills

This supports MiniMessage formatting.

---

5.5 size

size is the number of rows, not the raw slot count.

Example:

size: 6

That means 6 rows, with 9 slots per row.

A lot of generic GUI guides incorrectly describe this as 54 directly. AuraSkills menu docs describe size as row count from 1 to 6.

---

5.6 fill

The fill section controls the background item used in empty slots.

Example:

fill:
  enabled: true
  material: black_stained_glass_pane

Required keys:

• enabled

• material

The fill item's display name is automatically made invisible.

---

5.7 items

items are for single fixed items in a menu.

Example:

items:
  your_stats:
    material: player_head
    display_name: <green>Your Stats
    pos: 22

The exact keys inside an item can include material, display name, lore, and click actions.

AuraSkills menus are built on the Slate library, so menu item configuration follows that style.

---

5.8 templates

templates are used for repeating items generated multiple times from a shared layout.

Typical use cases:

• level track items

• source lists

• repeated entries in a progression or sources menu

If you want to redesign repeating generated content cleanly, this section matters more than items.

---

5.9 components

components define reusable lore snippets.

This helps avoid repeating the same lore block inside multiple templates or items.

---

5.10 formats

formats are reusable key-value text formats often used by placeholders that generate arrays or repeated lore entries.

This is especially useful in complex templates.

---

5.11 options

Some menu files include an options section with menu-specific settings.

Examples documented by the wiki include:

skills menu options

• bar_length

• percent_format

• current_xp_format

level_progression options

• use_level_as_amount

• over_max_stack_amount

• items_per_page

• start_level

• track

sources options

• source_start

• source_end

• items_per_page

• use_track

• track

• xp_format

These control generated layout and formatting, not just cosmetics.

---

5.12 Menu formatting rules

AuraSkills menu files use MiniMessage by default.

Examples:

<green>Mining
<gold><bold>Rewards
<#55ff55>XP Progress

Legacy & color codes still work, but MiniMessage is the preferred format.

---

5.13 Menu placeholders

AuraSkills menus support three important placeholder styles.

1. Single curly braces

{example}

These are plugin context placeholders for dynamic data.

2. Double curly braces

The wiki describes these as message placeholders looked up from the messages file under:

• menus.[menu_name].[placeholder]

• fallback: menus.common.[placeholder]

This is what allows one menu config to work across languages while pulling text from message files.

3. PlaceholderAPI placeholders

%player_name%

These require PlaceholderAPI and any needed expansions.

---

5.14 Custom menus

AuraSkills supports custom menu files created manually in the menus/ folder.

Example file path:

plugins/AuraSkills/menus/test.yml

Custom menus can be opened with:

/sk openmenu test

Custom menus support:

• normal item config

• PlaceholderAPI placeholders

• click actions

But according to the docs, custom menus do not support the same advanced templates, components, formats, and options behavior as the built-in menu system.

---

6. Proper setup workflow

6.1 First startup

• install plugin

• start server once

• stop server

6.2 Decide language behavior

• set default_language

• choose whether to use try_detect_client_language

• ensure the correct language files exist

6.3 Configure core behavior in config.yml

At minimum review:

• sql

• hooks

• action_bar

• boss_bar

• jobs

• blocked_worlds

• disabled_worlds

• disable_in_creative_mode

• check_block_replace

• enable_skill_commands

6.4 Edit message text in messages/messages_<lang>.yml

Use this for:

• wording

• translated text

• menu labels only when you want different text

Do not use it to redesign GUI layout.

6.5 Edit menu appearance in menus/*.yml

Use this for:

• inventory titles

• fill background

• item materials

• lore layout

• click actions

• menu navigation

• repeated templates and progression tracks

6.6 Reload carefully

If the plugin supports reload cleanly for your changes, use:

/auraskills reload

If menu/message behavior looks wrong after editing, do a full server restart instead.