SkillTrees Docs
AI Written DocumentaryThis documentation was written by AI (Claude) from the plugin's source and config files. Check values against your own server before relying on them.
SkillTrees Docs Get in touch
AI Written Documentary

SkillTrees, fully documented

Combatant and Voyager skill trees for Paper servers. Every in-game feature and every yaml option, explained with the real defaults.

Start reading Search every option
Paper 26.3Java 255 yaml files275 documented options and messages3 commandsMiniMessage + hex colours
Getting started

What SkillTrees does

SkillTrees gives every player two skill trees. Combatant grows from fighting. Voyager grows from exploring. Points turn into levels, levels pay out rewards, and a /profile menu shows all of it.

Tree 1

Combatant

Points for hits, kills, shield blocks, boss fights and fighting with a variety of weapons. Hit strength, target type and farm protection all change the payout.

hitskillsbossesshield blocksweapon variety
Tree 2

Voyager

Points for mining blocks, entering new areas and biomes, visiting new dimensions, holding new items and spotting new mobs. Every block is priced in its own file.

miningareas & biomesdimensionsnew itemsnew mobs

Everything at a glance

  • Levels 1 to 100 per tree, with a curve you set per tree (base, exponent, max level).
  • Action bar feedback while you play. Mining and fighting show a running session total, then a summary when you stop.
  • Level rewards per level: sounds, items (with names, lore, enchantments), money, console commands and LuckPerms permissions. Rewards can be reclaimed on a cooldown.
  • /profile GUI with a configurable size, slot for every item, material for every state, glow per item, titles per window, and automatic paging.
  • Leaderboards with /skilltop and PlaceholderAPI placeholders.
  • Anti-abuse: spawner and egg penalties, a grinder limiter, PvP repeat cooldown, boss repeat decay, a placed-block filter for mining, and creative or world blocking.
  • Storage in YAML files, SQLite or MySQL, with async loading and atomic saves.
  • Every text and look is editable: five yaml files, MiniMessage colours, hex colours and gradients.
  • Integrations: PlaceholderAPI, WorldGuard (region flag), Vault (money rewards), LuckPerms (permission rewards) and Folia-style scheduling.
Getting started

Install and first start

One jar, no required dependencies. Drop it in, start the server and edit the files it creates.

RequirementValue
ServerPaper 26.3 (the plugin declares api-version: 26.3 and folia-supported: true)
Java25
Optional pluginsLuckPerms, PlaceholderAPI, WorldGuard, Vault (declared as softdepend, so they load first when present)
Database driversSQLite and MySQL need the matching JDBC driver on the server. Paper ships common ones; if yours does not, stay on yaml storage.
  1. Stop the server and put SkillTrees.jar in plugins/.
  2. Start the server. The plugin writes its files into plugins/SkillTrees/.
  3. Edit what you want, then run /skilladmin reload. Storage, hook and autosave settings need a restart (see the tables).
  4. Join, mine a block, and open /profile.

Files the plugin creates

FilePurpose
config.ymlPoints, level curves, anti-abuse, sessions, storage, hooks, leaderboard, multipliers.
messages.ymlEvery text the plugin shows: tree names and colours, action bar, chat, titles, GUI names and lore.
rewards.ymlWhat each level gives. Layout is <tree>.<level>.<option>.
gui.ymlSize, slots, materials, glow and window titles of the /profile menus, plus the progress bar style.
voyager-blocks.ymlVoyager points per block for mining and for the first time a block type is used.
playerdata/<uuid>.ymlPlayer data when storage.type is yaml.
data.dbPlayer data when storage.type is sqlite.
Reload

A missing file is recreated from the jar the next time the plugin starts. A missing key inside messages.yml falls back to the jar default, so you can delete lines you do not want to change.

Getting started

Ten-minute tour

A guided path through the settings most servers change first.

Step 1

Pick the pace

Edit levels.combatant and levels.voyager in config.yml. Use the level calculator below to see what a base and exponent mean in points. Lower base for a faster server.

Step 2

Set event multipliers

multipliers.combatant and multipliers.voyager scale every award. Set 2.0 for a double points weekend and /skilladmin reload.

Step 3

Add rewards

Open rewards.yml, copy a level block and change the items, money, commands or permissions. Players who already passed that level get it with /skilladmin claim all.

Step 4

Make it yours

Change colours and wording in messages.yml and the menu layout in gui.yml. Every colour is a MiniMessage tag such as <#38bdf8>.

Step 5

Protect the economy

Leave anti-farm on. Set settings.disabled-worlds for creative or event worlds, and use the WorldGuard flag skilltrees-points for single regions.

Step 6

Check storage

Small servers can stay on yaml. Networks should use mysql so every server reads the same points. Changing the type needs a restart and does not move old data.

Gameplay

Points, levels and the curve

Each tree has its own point total. Your level is worked out from that total, so changing the curve later re-levels everyone on the next calculation without losing points.

The formula

Level 1 is where everyone starts and costs 0 points. To go from level n-1 to level n a player needs:

formula
cost(n) = max(1, round(base * (n - 1) ^ exponent))
total points for level n = cost(2) + cost(3) + ... + cost(n)

With the defaults, Combatant uses base 100 and Voyager uses base 80, both with exponent 1.5 and max-level 100. An exponent of 1 makes every level cost the same. Higher exponents make late levels steeper. Max-level is a hard stop: points keep counting but the level does not rise.

A single award can jump several levels (a boss kill, for example). Every skipped level pays its reward, and the level-up message shows the jump as +N levels.

Level calculator

Type your own curve and see the cost of each level, the total, and what level a point total reaches.

0Cost of that level
0Total for that level
0Total for max level
1Level at my points

What happens on a level up

  • A chat line with the old and new level (level-up.chat) and a hint line (level-up.hint).
  • A title and subtitle (level-up.title, level-up.subtitle), shown for about 2 seconds.
  • A sound: the toast sound when 3 or more levels are gained at once, the classic level-up sound otherwise. Turn this off with settings.default-level-up-sound: false when you only want sounds from rewards.yml.
  • The rewards of every level reached (see Rewards).
  • On milestone levels, a server broadcast (see below).
  • A SkillLevelUpEvent for other plugins (see Developer API).

Milestones

Every milestones.every levels (default 10) is a milestone. Milestone levels use their own GUI items and a ✦ tag in the title. When milestones.broadcast is true, reaching a milestone at or above milestones.min-level announces it to the whole server. Set every to 0 to switch milestones off.

Global multipliers

multipliers.<tree> multiplies every gameplay award after all other rules, rounded, with a minimum of 1 point. It applies to hits, kills, blocks, exploration and discoveries.

Who can earn points

  • Spectators never earn. Creative players earn only if settings.allow-creative is true.
  • Nobody earns in worlds listed in settings.disabled-worlds (use world folder names).
  • Nobody earns inside a WorldGuard region where the flag skilltrees-points is set to deny.
Gameplay · Combatant

Combatant tree

Every hit, kill and shield block pays points. The payout depends on how you fought, who you fought and whether the target came from a farm.

Hit points

A hit pays the base for its type, multiplied by the target modifiers, then rounded with a minimum of 1. Hits that deal less than combatant.min-damage (1.0) final damage pay nothing, so weak spam swings are ignored. Armor stands and yourself never count. Damage from thorns and other indirect sources is ignored.

Hit typeBase pointsHow it is detected
Sweep hit1The extra targets of a sword sweep (damage cause ENTITY_SWEEP_ATTACK).
Normal hit2A standing melee hit that is not one of the types below.
Sprint hit3A melee hit while sprinting.
Critical hit5The vanilla critical conditions: falling, not on the ground, not sprinting, not climbing, swimming, riding or blinded.
Ranged hit3An arrow, crossbow bolt or trident that you shot or threw. Snowballs, eggs and other projectiles are ignored.
Mace smash8A mace hit after falling more than 1.5 blocks while not gliding. Checked before the critical rule.

Target modifiers

  • Players pay hit.player-multiplier (x1.5).
  • Passive mobs (anything that is not hostile, such as cows and sheep) pay hit.passive-multiplier (x0.25). Hostile means a vanilla Enemy, a boss, or a player.
  • Farm-spawned mobs (spawners, eggs, dispensers) multiply by anti-farm.spawner-multiplier (x0.1). See Anti-abuse.

Weapon variety

The weapon you hold sorts into a style: sword, axe, spear, pickaxe, shovel, hoe, trident, mace, bow, crossbow, fishing rod, fist, or improvised:<item> for anything else (a stick, a fish, a block). Hits add bonus points on top of the hit payout:

  • First use: the first time you ever hit with a style, +25 (weapons.first-use). For an improvised item the bonus is +40 (weapons.improvised-first-use). The action bar names it, for example New Weapon Style: Mace.
  • Switching: using a style that is not among your last weapons.recent-window (3) styles gives +4 (weapons.switch-bonus), at most once every weapons.switch-cooldown-ms (3000 ms).

Kill points

Killing a regular mob pays kill.base (10) plus kill.per-max-health (1.0) times the victim's max health, capped at kill.max-regular (200). Passive mobs multiply by kill.passive-multiplier (0.25). Killing a player pays the flat kill.player (75).

Regular kills are also scaled by the farm multiplier and the grinder limiter (see Anti-abuse). Boss, player and override kills are not.

Bosses

Any entity listed under kill.overrides is a boss and pays its flat value. The defaults are Ender Dragon 6000, Wither 15000 (more than the Dragon), Warden 3000 and Elder Guardian 800. Add any entity type id to make it a boss; remove one to make it a normal mob.

  • Everyone who damaged the boss gets the points, not only the killer. Damage is tracked from the first hit.
  • Boss kills also send a chat line (announce message) as well as the action bar text.
  • Repeat decay: with kill.repeat-decay.enabled, each player's repeat kills of a listed boss pay points / n (1st full, 2nd half, 3rd a third...). The kill count is stored per player. Other players keep their own full first kill. Default bosses: ender_dragon, wither.

Shield blocking

When a shield absorbs an attack that dealt at least block.min-raw-damage (1.0), the defender gets block.base (3) plus block.per-damage-blocked (1.0) per point of damage blocked, capped at block.max (25), at most once per block.cooldown-ms (1000 ms). Partial blocks count. Self damage never counts.

How blocks are detected

Minecraft does not expose a clean "shield blocked this" event. The plugin reads the blocking damage modifier and falls back to "the player is blocking and final damage is 0". It is reliable in normal play, but a future server change could affect it.

Points calculator

Uses the default config values. Change a number in config.yml and the real result changes the same way.

0Hit (before tree x)
0Kill (before tree x)
0Hit with multiplier
0Kill with multiplier
0Boss kill points

Gameplay · Voyager

Voyager tree

Voyager pays for going places and seeing things for the first time, plus steady points for mining. Everything "new" is remembered per player, so each thing pays once.

Exploration

Position, biome and dimension are checked every second (starting 2 seconds after joining). One award combines everything new at that moment, for example New Biome: Cherry Grove + New Area.

  • New area: the world is cut into squares of exploration.region-size blocks (256, minimum 16). The first time you stand in a square, you earn new-region (6). Squares are tracked per dimension.
  • New biome: new-biome (40) the first time you stand in a biome.
  • New dimension: new-dimension (100), or the value in dimension-overrides. Defaults: normal 0, nether 150, the_end 300. Custom worlds use their lower-case world name as the key. A value of 0 pays nothing (the Overworld is free because everyone starts there).

Discoveries

  • New item: the first time an item is anywhere in your inventory, armor, offhand or cursor (scanned every second). It pays item-overrides.<id> or new-item (10). Several items found in the same second combine into 3 New Items.
  • New mob: the first time a mob type is within mob-scan-radius (32) blocks and in your line of sight (scanned every 2 seconds). It pays mob-overrides.<id> or new-mob (20). Players and armor stands never count.
  • Ignored items: ids in ignored-items never count (command blocks, barriers, structure blocks and similar).
Reward items

Items handed out by rewards.yml can themselves count as a "new item". If you give diamonds as a reward, add diamond to ignored-items or accept the small bonus.

Mining and blocks

Breaking a block pays its mining value from voyager-blocks.yml (default 1). The first time you break or place a type of block you also earn a first-time bonus (default 8, higher for ores). Both come from one award, shown on the action bar as Mining: Diamond Ore with a ✦ mark when a first-time bonus was included. See voyager-blocks.yml for every rule.

  • Match order for one block: exact id, then wildcard (*_ore), then block tag (logs, leaves), then default. The first match wins.
  • Player-placed blocks pay only player-placed-multiplier of the mining value (default 0, so place-and-break farming gives nothing). The plugin remembers placed blocks inside each chunk's data, so it survives restarts.
  • Placed blocks are tracked even for creative players, so creative-placed blocks do not pay survival players later.
Gameplay · Feedback

Action bar and sessions

The action bar tells players what they earned without flooding the chat. Mining and fighting use sessions: a running total that ends with a short summary.

Sessions on

Running total

While you keep mining or fighting, the action bar shows +184 · Diamond Ore: the points gathered so far in this session, then the block you just broke or the action you just did. Blocks that include a first-time bonus get a marker.

When you stop

Summary line

After timeout-seconds (5) without a new gain, the session ends and shows Congrats! You mined 23 blocks and obtained 312 XP (Combatant: Nice fight! You scored 9 combat actions and obtained 120 XP).

Try a session

Click actions the way a player mines or fights. The bar shows the running total, the thin line shows the idle timeout, and the summary appears when you stop. Values are the shipped defaults.

Action bar is empty. Pick an action.

    Session rules

    • One session per player and tree. Mining belongs to Voyager and combat (hits, kills, blocks, weapon bonuses) belongs to Combatant. Exploration and discoveries are not part of a session.
    • Switch parts off independently with session.mining and session.combat, or everything with session.enabled.
    • session.summary chooses where the summary goes: actionbar, chat, both or none.
    • Sessions need settings.actionbar-feedback: true.
    • If a player leaves mid session, the session is dropped without a summary. The points are already saved.

    Gains outside a session

    • Shown as +12 · Critical Hit (actionbar message).
    • Repeating the same thing shows only +12 (actionbar-compact). After actionbar-compact-reset-seconds without it the full text returns. The default is 0: never go back.
    • actionbar-min-gain hides awards below that many points (0 shows everything). Session gains always show the running total.
    • Boss kills additionally send a chat line (announce message) because they are rare.
    Gameplay · Protection

    Anti-abuse

    Every shortcut a player might try has a rule. All of them are configurable, and most can be switched off.

    AbuseRuleWhere to change it
    Spawner and egg farmsMobs from the listed spawn reasons are tagged when they appear. Hits and regular kills on them pay x0.1. Bosses and players are not scaled.anti-farm.reduced-spawn-reasons, anti-farm.spawner-multiplier
    Mob grindersAfter free-kills (20) regular kills inside window-seconds (60), further kills pay x0.25 until the window clears.anti-farm.kill-rate.*
    PvP boostingKilling the same player again within victim-cooldown-seconds (600) pays nothing and sends anti-farm.pvp-cooldown.anti-farm.pvp.victim-cooldown-seconds
    Farming the same bossA player's repeat kills of a listed boss pay points / n.combatant.kill.repeat-decay.*
    Weak swing spamHits under the minimum damage pay nothing.combatant.min-damage
    Shield spamBlock points have a cooldown and a cap.combatant.block.*
    Place and break miningPlayer-placed blocks pay a fraction (default none).voyager-blocks.yml player-placed-multiplier
    Creative and test worldsCreative and spectator do not earn, listed worlds do not earn.settings.allow-creative, settings.disabled-worlds
    Single regionsA WorldGuard region with skilltrees-points deny pays nothing.WorldGuard flag
    Spawn reasons

    Valid values for reduced-spawn-reasons are the names of Bukkit's CreatureSpawnEvent.SpawnReason, for example SPAWNER, TRIAL_SPAWNER, SPAWNER_EGG, DISPENSE_EGG, BREEDING, RAID. The tag is stored on the mob, so it survives restarts.

    Players

    The /profile menu

    Two screens. The main menu shows both trees. A tree view shows one item per level, with pages when there are more levels than slots.

    Screen 1

    Main menu

    One item per tree (Combatant and Voyager) with level, points and a progress bar. Click one to open its levels. The title changes when you look at someone else: menu.title.own or menu.title.other.

    Screen 2

    Tree view

    One item per level, in the order the slots are written. The tree opens on the page that holds your current level. Previous and next buttons appear only when there is another page.

    Level states

    Each level item is in one of four states, each with its own material, glow, title and lore. Milestone levels have a second set of four materials.

    StateMeaningDefault materialLore shows
    lockedNot reached yet, and not the next level.GRAY_DYERequired total, points still missing, rewards.
    reachedYou are past this level.LIME_DYECost of the level, rewards, and reclaim status when the reward is reclaimable.
    currentThe level you are on.tree-icon (a diamond sword or compass)Your points, a progress bar to the next level, rewards.
    nextThe next level to reach.YELLOW_DYEPoints to go, percent bar, rewards.

    Buttons

    • prev / next: page arrows. Hidden when there is no such page.
    • back: returns to the main menu.
    • summary: the tree item again, with extra counters. Combatant shows how many weapon styles you used. Voyager shows items, mobs, blocks, biomes and areas discovered.

    Clicking a level

    Clicking one of your own reached levels claims its reward again when that reward is reclaimable and off cooldown. Otherwise the plugin answers with the matching message (can only be claimed once, claim again in 1h 12m, reach this level first, this level has no reward). Viewing another player's profile never claims anything.

    Looking at other players

    /profile <player> works for online players and for offline players the server has seen before. Their data loads from storage in the background, so a short Loading profile... line may show first. Needs skilltrees.profile.others.

    Live content and safety

    • Menus cannot be taken from. Clicks, drags and shift-clicks are cancelled.
    • After /skilladmin reload, a menu that is already open keeps the old layout until it is reopened.

    Slot map

    Preview how tree.rows, tree.level-slots and the button slots fit together. Type the same values you would write in gui.yml. Slots are 0 (top-left) to 8, then 9 to 17 for row two, and so on.

    54Inventory slots
    45Levels per page
    3Pages for 100 levels
    level (L1 is the first level of the page)prev / nextbacksummary
    Slot rules

    A single slot accepts a number, a range (10-16), a descending range (17-9) or a list mixing them. auto uses the default. A button always wins over a level on the same slot. Slots outside the inventory are skipped with a console warning. If no level slot is left, slot 0 is used.

    Players

    Level rewards

    A level can give a sound, items, money, console commands and permissions. Each level pays once per player, and can optionally be claimed again on a cooldown.

    How rewards are paid

    • Rewards are given when the level is reached. A multi-level jump pays every skipped level, but only the highest level's sound plays.
    • If the inventory is full, extra items drop at the player's feet and rewards.inventory-full is sent.
    • Players who passed levels before a reward existed are paid with /skilladmin claim <player|all>, or automatically on join with settings.auto-claim-on-join: true.
    • Chat feedback per reward (rewards.item-received, rewards.money-received) can be turned off with settings.reward-messages: false.
    • Rewards are shown in the GUI lore automatically: items and money are listed by the plugin, and display adds your own lines for permissions or commands.

    Reclaiming

    With reclaimable: true, the player clicks that level in /profile and gets the items, money, commands and sound again. Permissions are never given twice. The first claim is the normal level-up payout and starts the cooldown clock for later claims.

    • cooldown sets how long the player waits between claims. The clock starts at the player's last claim.
    • The GUI lore shows Reclaimable every 12h, then Click to claim again or Claim again in 3h 20m.

    Cooldown converter

    Type a cooldown exactly as you would in rewards.yml.

    ValidStatus
    40mReal time
    2 Minecraft daysMinecraft days
    UnitMeaningExample
    XsSeconds30s
    XmMinutes15m
    XhHours12h
    XdReal days7d
    XmdMinecraft days (1 day = 20 real minutes)2md = 40 real minutes

    Decimals work (1.5h). none or 0 means no cooldown. An unreadable value disables reclaiming for that level and prints a warning in the console.

    Reference

    Commands and permissions

    Three commands. Tab completion offers trees, online players and sub-commands.

    CommandAliasesPermissionWhat it does
    /profile/skillsskilltrees.profileOpens your main menu.
    /profile <combatant|voyager>skilltrees.profileOpens that tree directly, on the page of your current level.
    /profile <player> [tree]skilltrees.profile.othersOpens another player's menu, or one of their trees. Works for offline players the server has cached.
    /skilltop [tree]/sktopskilltrees.topShows the leaderboard of both trees, or one tree. Shows a loading line until the first refresh finishes.
    /skilladmin reloadskilltrees.adminReloads config, messages, rewards, block points and the GUI layout.
    /skilladmin add <player> <tree> <points>skilltrees.adminAdds points to an online player, as an Admin award (levels and rewards trigger).
    /skilladmin set <player> <tree> <points>skilltrees.adminSets the point total of an online player. Points must be a whole number, 0 or higher.
    /skilladmin reset <player>skilltrees.adminDeletes all skill data of an online player: points, discoveries, boss kills and claim times.
    /skilladmin claim <player|all>skilltrees.adminPays every reward the player has reached but never received. all means everyone online.

    Permissions

    PermissionDefaultGives
    skilltrees.profileeveryone/profile
    skilltrees.profile.otherseveryoneViewing other players with /profile <player>
    skilltrees.topeveryone/skilltop
    skilltrees.adminoperators/skilladmin, all sub-commands
    Tip

    Take away skilltrees.profile.others in your permissions plugin if you want profiles to stay private.

    Configuration

    Every yaml option

    Five files, every key. Defaults come straight from the files that ship with the plugin. Type in the box to search across all five.

    Type to search every option in all five files

    The main file. /skilladmin reload applies everything except the options marked needs a restart. Points are whole numbers; decimals are rounded.

    OptionTypeDefaultWhat it does
    settings
    settings.allow-creativebooleanfalseCreative players earn points only when true. Spectators never earn.
    settings.disabled-worldslist of world names[]No points in these worlds. Use the world folder names, case-insensitive.
    settings.actionbar-feedbackbooleantrueShow the action bar on gains. Sessions need this on.
    settings.actionbar-min-gainwhole number0Hide non-session awards below this many points. 0 shows all.
    settings.actionbar-compact-reset-secondsseconds0Repeats show only +N. After this many quiet seconds the full text shows again. 0 = never.
    settings.session.enabledbooleantrueMaster switch for mining and combat sessions.
    settings.session.timeout-secondsseconds5Seconds without a gain before a session ends and the summary shows.
    settings.session.miningbooleantrueVoyager block mining uses sessions.
    settings.session.combatbooleantrueCombatant hits, kills and blocks use sessions.
    settings.session.summary<code>actionbar</code> | <code>chat</code> | <code>both</code> | <code>none</code>actionbarWhere the end-of-session summary is shown.
    settings.autosave-minutesminutes5How often online players are saved. Players are also saved on quit and on shutdown. needs a restart
    settings.default-level-up-soundbooleantruePlay the built-in level-up sound. Set false if you only want reward sounds.
    settings.reward-messagesbooleantrueSend a chat line for each reward received.
    settings.auto-claim-on-joinbooleanfalseOn join, pay rewards for levels passed before those rewards existed.
    hooks
    hooks.worldguardbooleantrueRegisters the region flag skilltrees-points. Set it to deny in a region to stop points there. needs a restart
    hooks.placeholderapibooleantrueRegisters the %skilltrees_...% placeholders. needs a restart
    hooks.vaultbooleantrueLets money rewards pay through your economy plugin. needs a restart
    storage
    storage.type<code>yaml</code> | <code>sqlite</code> | <code>mysql</code>yamlWhere player data lives. Existing data is not converted when you change it. If the chosen backend cannot start, the plugin falls back to YAML and logs an error. needs a restart
    storage.table-prefixtextskilltrees_Prefix for the SQL table. The table is <prefix>players. needs a restart
    storage.mysql.hosttextlocalhostMySQL host. needs a restart
    storage.mysql.portnumber3306MySQL port. needs a restart
    storage.mysql.databasetextminecraftDatabase name. needs a restart
    storage.mysql.usernametextrootDatabase user. needs a restart
    storage.mysql.passwordtext""Database password. needs a restart
    storage.mysql.use-sslbooleanfalseUse SSL for the connection. needs a restart
    leaderboard
    leaderboard.top-sizewhole number10How many players /skilltop and the top placeholders list (minimum 1).
    leaderboard.refresh-secondsseconds120How often the leaderboard is rebuilt from storage (minimum 10). needs a restart
    milestones
    milestones.everywhole number10Every Nth level is a milestone with special GUI items. 0 = off.
    milestones.broadcastbooleantrueAnnounce milestone levels to the whole server.
    milestones.min-levellevel10Do not broadcast milestones below this level.
    multipliers
    multipliers.combatantdecimal1.0Multiplies every Combatant award. 2.0 = double points.
    multipliers.voyagerdecimal1.0Multiplies every Voyager award.
    levels
    levels.combatant.max-levellevel100Highest Combatant level. Points still count after it.
    levels.combatant.basenumber100Curve scale for Combatant: points for level 2 equal base.
    levels.combatant.exponentdecimal1.5Curve steepness for Combatant. 1 = every level costs the same.
    levels.voyager.max-levellevel100Highest Voyager level. Points still count after it.
    levels.voyager.basenumber80Curve scale for Voyager: points for level 2 equal base.
    levels.voyager.exponentdecimal1.5Curve steepness for Voyager. 1 = every level costs the same.
    anti-farm
    anti-farm.reduced-spawn-reasonslist of spawn reasons[SPAWNER, TRIAL_SPAWNER, SPAWNER_EGG, DISPENSE_EGG]Mobs that appear through these reasons are tagged and pay reduced points.
    anti-farm.spawner-multiplierdecimal0.1Multiplier for hits and regular kills on tagged mobs.
    anti-farm.kill-rate.enabledbooleantrueSwitch the grinder limiter on or off.
    anti-farm.kill-rate.window-secondsseconds60Length of the rolling window.
    anti-farm.kill-rate.free-killswhole number20Kills inside the window that pay full points.
    anti-farm.kill-rate.over-limit-multiplierdecimal0.25Multiplier for kills beyond the free kills.
    anti-farm.pvp.victim-cooldown-secondsseconds600Killing the same player again within this time pays nothing.
    combatant
    combatant.min-damagedecimal1.0Hits that deal less final damage than this pay nothing.
    combatant.hit.sweeppoints1Sword sweep hit.
    combatant.hit.normalpoints2Standing melee hit.
    combatant.hit.sprintpoints3Melee hit while sprinting.
    combatant.hit.criticalpoints5Vanilla critical hit.
    combatant.hit.rangedpoints3Arrow, crossbow or trident hit.
    combatant.hit.mace-smashpoints8Mace hit after a real fall.
    combatant.hit.player-multiplierdecimal1.5Multiplier when the target is a player.
    combatant.hit.passive-multiplierdecimal0.25Multiplier when the target is not hostile (cows, sheep and so on).
    combatant.kill.basepoints10Flat part of a regular kill.
    combatant.kill.per-max-healthdecimal1.0Added per point of victim max health.
    combatant.kill.max-regularpoints200Cap for non-boss kills before multipliers.
    combatant.kill.playerpoints75Flat points for killing a player.
    combatant.kill.passive-multiplierdecimal0.25Multiplier for killing a non-hostile mob.
    combatant.kill.overridesmap: entity id to points{ender_dragon: 6000, wither: 15000, warden: 3000, elder_guardian: 800}Flat kill points per entity type. Every entry is also a boss: all players who damaged it are paid. Remove an entry to make the mob normal again.
    combatant.kill.repeat-decay.enabledbooleantrueRepeat kills of listed bosses by the same player pay points / n.
    combatant.kill.repeat-decay.bosseslist of entity ids[ender_dragon, wither]Bosses the decay applies to.
    combatant.block.basepoints3Flat part of a shield block.
    combatant.block.per-damage-blockeddecimal1.0Added per point of damage the shield absorbed.
    combatant.block.maxpoints25Cap for one block award.
    combatant.block.min-raw-damagedecimal1.0Attacks absorbing less than this pay nothing.
    combatant.block.cooldown-msmilliseconds1000Minimum time between block awards per player.
    combatant.weapons.first-usepoints25Bonus the first time you hit with a weapon style.
    combatant.weapons.improvised-first-usepoints40Bonus the first time you hit with a non-weapon item.
    combatant.weapons.switch-bonuspoints4Bonus for switching to a style not used recently.
    combatant.weapons.recent-windowwhole number3How many of your latest styles count as "recent".
    combatant.weapons.switch-cooldown-msmilliseconds3000Minimum time between switch bonuses.
    voyager
    voyager.exploration.region-sizeblocks256Side length of an exploration square (minimum 16).
    voyager.exploration.new-regionpoints6Points for the first visit to a square.
    voyager.exploration.new-biomepoints40Points for the first visit to a biome.
    voyager.exploration.new-dimensionpoints100Default points for a new dimension.
    voyager.exploration.dimension-overridesmap: dimension to points{normal: 0, nether: 150, the_end: 300}Per dimension. Keys: normal, nether, the_end, or a custom world's lower-case name. 0 pays nothing.
    voyager.discovery.new-itempoints10Default points for holding an item for the first time.
    voyager.discovery.new-mobpoints20Default points for seeing a mob type for the first time.
    voyager.discovery.mob-scan-radiusblocks32How close, and in line of sight, a mob must be to be discovered.
    voyager.discovery.item-overridesmap: item id to points{diamond: 40, emerald: 30, netherite_ingot: 100, netherite_scrap: 60, elytra: 150, nether_star: 200, totem_of_undying: 80, enchanted_golden_apple: 120, heart_of_the_sea: 100, dragon_egg: 500, dragon_head: 150, trident: 80, mace: 120, beacon: 150}Points for specific items. Ids are Minecraft ids without the namespace.
    voyager.discovery.mob-overridesmap: entity id to points{ender_dragon: 300, wither: 400, warden: 250, elder_guardian: 150, evoker: 60, ravager: 60}Points for specific mobs.
    voyager.discovery.ignored-itemslist of item ids[command_block, chain_command_block, repeating_command_block, command_block_minecart, barrier, light, structure_block, structure_void, jigsaw, debug_stick, knowledge_book, test_block, test_instance_block]Items that never count as discoveries.
    config.yml (shipped with the plugin)
    # ---------------------------------------------------------------
# SkillTrees configuration  (/skilladmin reload applies most changes)
# Texts live in messages.yml, level rewards in rewards.yml, block points in voyager-blocks.yml,
# the /profile GUI layout in gui.yml.
# ---------------------------------------------------------------

settings:
  # Creative players never earn points unless this is true. Spectators never earn.
  allow-creative: false
  # No points are earned in these worlds (world folder names)
  disabled-worlds: []
  # Show "+X points | reason" on the action bar
  actionbar-feedback: true
  # Only show the action bar for awards of at least this many points (0 = show every gain).
  # (Not used for session gains, they always show the running total.)
  actionbar-min-gain: 0
  # For gains that are not part of a session (exploration, discoveries, or everything when sessions are off):
  # repeating the same thing shows just "+N". After this many seconds without it, the full text
  # is shown again (0 = never go back to the full text)
  actionbar-compact-reset-seconds: 0
  # SESSIONS: while you keep mining (Voyager) or fighting (Combatant), the action bar shows the running
  # total of the session plus the block / action you just did, instead of "+N" every time.
  # When you stop, a summary ("Congrats! You mined n blocks and obtained r XP") is shown.
  # Texts are in messages.yml (session.*). Needs actionbar-feedback: true.
  session:
    enabled: true
    timeout-seconds: 5        # stop for this long and the session ends (1 mined dirt every 2s = one session)
    mining: true              # Voyager: block mining sessions
    combat: true              # Combatant: hits, kills, blocks...
    summary: actionbar        # actionbar | chat | both | none
  autosave-minutes: 5
  # Play the built-in level-up sound (set false if you only want sounds from rewards.yml)
  default-level-up-sound: true
  # Chat line for each reward received
  reward-messages: true
  # On join, hand out rewards for levels the player passed before rewards existed
  auto-claim-on-join: false

hooks:
  # Registers the region flag "skilltrees-points" (set it to deny in a region = no points there)
  worldguard: true
  placeholderapi: true
  vault: true

storage:
  type: yaml            # yaml | sqlite | mysql   (needs a restart to change)
  table-prefix: skilltrees_
  mysql:
    host: localhost
    port: 3306
    database: minecraft
    username: root
    password: ""
    use-ssl: false

leaderboard:
  top-size: 10
  refresh-seconds: 120

milestones:
  every: 10             # every Nth level gets special GUI items (0 = off)
  broadcast: true       # announce milestone levels to the whole server
  min-level: 10         # don't broadcast below this level

# Global multipliers per tree (handy for events: 2.0 = double points)
multipliers:
  combatant: 1.0
  voyager: 1.0

# Level curve. Level 1 is the starting level (0 points).
# Points needed to go from level (n-1) to level n = round(base * (n-1) ^ exponent)
levels:
  combatant:
    max-level: 100
    base: 100
    exponent: 1.5
  voyager:
    max-level: 100
    base: 80
    exponent: 1.5

# GUI size, slots, materials and glow are in gui.yml

# ---------------------------------------------------------------
# ANTI-ABUSE
# ---------------------------------------------------------------
anti-farm:
  # Mobs that appeared via these spawn reasons give reduced points (hits and kills)
  reduced-spawn-reasons: [SPAWNER, TRIAL_SPAWNER, SPAWNER_EGG, DISPENSE_EGG]
  spawner-multiplier: 0.1
  # Grinder limiter: after "free-kills" kills inside the window, further kills are scaled down
  kill-rate:
    enabled: true
    window-seconds: 60
    free-kills: 20
    over-limit-multiplier: 0.25
  pvp:
    # The same player killing the same victim again within this time gives no points
    victim-cooldown-seconds: 600

# ---------------------------------------------------------------
# COMBATANT
# ---------------------------------------------------------------
combatant:
  # Hits dealing less final damage than this give nothing (stops weak spam swings)
  min-damage: 1.0

  hit:
    sweep: 1          # least
    normal: 2
    sprint: 3         # medium
    critical: 5       # most
    ranged: 3         # arrow / crossbow / trident hits
    mace-smash: 8     # mace hit after a real fall
    player-multiplier: 1.5     # hitting another player
    passive-multiplier: 0.25   # hitting non-hostile mobs (cows, sheep...)

  kill:
    base: 10
    per-max-health: 1.0        # + this * victim max health
    max-regular: 200           # cap for non-boss mobs
    player: 75
    passive-multiplier: 0.25
    # Entity type -> flat points. Presence of an entry marks it as a boss:
    # every player who damaged it receives the points, not just the killer.
    overrides:
      ender_dragon: 6000
      wither: 15000            # larger than the Ender Dragon
      warden: 3000
      elder_guardian: 800
    # Repeat kills by the SAME player: 1st kill = full, 2nd = x/2, 3rd = x/3, 4th = x/4 ...
    # Other players fighting the same boss still get their own full first-kill points.
    repeat-decay:
      enabled: true
      bosses: [ender_dragon, wither]

  block:                       # shield blocking
    base: 3
    per-damage-blocked: 1.0
    max: 25
    min-raw-damage: 1.0
    cooldown-ms: 1000

  weapons:                     # being creative with weapons
    first-use: 25              # first time you hit with a new weapon style (sword, axe, mace, trident, bow...)
    improvised-first-use: 40   # first time you hit with a non-weapon item (stick, fish, etc.)
    switch-bonus: 4            # switching to a style not used in your last N styles
    recent-window: 3
    switch-cooldown-ms: 3000

# ---------------------------------------------------------------
# VOYAGER
# ---------------------------------------------------------------
voyager:
  exploration:
    region-size: 256           # blocks; entering an unvisited square area gives points
    new-region: 6
    new-biome: 40
    new-dimension: 100
    dimension-overrides:       # keys: normal, nether, the_end (or custom world name)
      normal: 0
      nether: 150
      the_end: 300

  discovery:
    new-item: 10
    new-mob: 20
    mob-scan-radius: 32        # a mob is "discovered" when you see it within this range
    item-overrides:            # item id -> points for the first time you hold it
      diamond: 40
      emerald: 30
      netherite_ingot: 100
      netherite_scrap: 60
      elytra: 150
      nether_star: 200
      totem_of_undying: 80
      enchanted_golden_apple: 120
      heart_of_the_sea: 100
      dragon_egg: 500
      dragon_head: 150
      trident: 80
      mace: 120
      beacon: 150
    mob-overrides:             # mob id -> points for first sighting
      ender_dragon: 300
      wither: 400
      warden: 250
      elder_guardian: 150
      evoker: 60
      ravager: 60
    ignored-items:             # never count as discoveries
      - command_block
      - chain_command_block
      - repeating_command_block
      - command_block_minecart
      - barrier
      - light
      - structure_block
      - structure_void
      - jigsaw
      - debug_stick
      - knowledge_book
      - test_block
      - test_instance_block
    Integrations

    PlaceholderAPI, WorldGuard, Vault, LuckPerms

    All four are optional. Each hook is checked on start, and a failed hook logs one warning and never stops the plugin.

    PlaceholderAPI

    Registered when hooks.placeholderapi is true. The expansion identifier is skilltrees and it stays registered across /papi reload. Trees are combatant and voyager. Data comes from the online player cache; an unknown player returns zeros.

    PlaceholderReturns
    %skilltrees_<tree>_level%Current level
    %skilltrees_<tree>_points%Total points
    %skilltrees_<tree>_max_level%Max level of that tree
    %skilltrees_<tree>_next_required%Total points needed for the next level (the current requirement at max level)
    %skilltrees_<tree>_points_to_next%Points still missing for the next level, 0 at max
    %skilltrees_<tree>_percent%Whole-number progress to the next level, 100 at max
    %skilltrees_total_level%Combatant level plus Voyager level
    %skilltrees_top_<tree>_<rank>_name%Name at that leaderboard rank
    %skilltrees_top_<tree>_<rank>_points%Points at that rank
    %skilltrees_top_<tree>_<rank>_level%Level at that rank. A rank beyond the list returns -.
    Examples
    %skilltrees_combatant_level%        -> 27
%skilltrees_voyager_percent%         -> 62
%skilltrees_top_combatant_1_name%    -> Steve
%skilltrees_top_voyager_3_points%    -> 18240

    WorldGuard

    When hooks.worldguard is true, the plugin registers a state flag named skilltrees-points when it loads. Set it to deny in a region to stop all point gains for players standing there.

    In game
    /rg flag spawn skilltrees-points deny

    If another plugin already uses that flag name, the plugin logs a warning and continues without the flag.

    Vault

    Needed only for money rewards. Without an economy the plugin logs rewards.yml gives money, but no Vault economy was found and skips the money. The economy may load after SkillTrees; the plugin looks again when rewards are paid.

    LuckPerms

    Needed only for permissions and remove-permissions. Nodes are added and removed through the LuckPerms API as permanent nodes. Without LuckPerms the plugin logs a warning on reload and the permission rewards do nothing. For other permission plugins use the commands option instead.

    Folia

    The plugin declares folia-supported: true and schedules work on the entity, region, global or async scheduler as appropriate: each player's scans and awards run on that player's own thread. Folia support is built to the documented rules but has had less real-world testing than Paper, so test on a copy of your server first.

    Integrations

    Storage

    Player data is loaded asynchronously when a player joins and saved when they leave, on the autosave timer, and on shutdown.

    TypeWhereGood for
    yamlplugins/SkillTrees/playerdata/<uuid>.yml, written atomically (temp file, then move)Small servers, no setup
    sqliteplugins/SkillTrees/data.dbOne server, faster leaderboards
    mysqlYour database, table <prefix>playersSeveral servers sharing one profile

    What is stored

    • Points for each tree and the highest level whose reward was paid.
    • Everything discovered: items, mobs, blocks, biomes, exploration squares, weapon styles and dimensions.
    • Boss kill counts per boss, and the last claim time per reclaimable reward.
    • SQL tables hold uuid, name, combatant_points, voyager_points (for fast leaderboards) and a data text column with the rest.
    • Placed-block memory is stored separately, inside each chunk's own data.

    Behaviour to know

    • All disk and database work runs on one background thread, so the game thread never waits for storage.
    • If the chosen backend cannot start, the plugin logs an error and falls back to YAML so players keep earning points.
    • Changing storage.type needs a restart, and existing data is not converted automatically.
    • On shutdown the plugin waits for pending saves, and warns if they time out.
    Integrations

    Developer API

    One public event, fired on every level up. It is a plain Bukkit event, so any plugin can listen to it.

    MethodReturns
    getPlayer()The player who levelled up
    getTree()SkillTree.COMBATANT or SkillTree.VOYAGER
    getOldLevel()Level before the award
    getNewLevel()Level after the award. More than old + 1 when levels were skipped.
    Listener example
    @EventHandler
public void onLevelUp(SkillLevelUpEvent e) {
    if (e.getTree() == SkillTree.COMBATANT && e.getNewLevel() >= 50) {
        e.getPlayer().sendMessage("You reached the Combatant elite.");
    }
}

    The event is informational and cannot be cancelled. The class is me.arx160.skilltrees.event.SkillLevelUpEvent. For anything else (leaderboards, scoreboards, tab lists), use the placeholders above.

    Reference

    Troubleshooting

    Start with the console. Almost every config mistake prints one line naming the file, the path and what was skipped.

    I mine blocks but get no points
    • Creative mode earns nothing unless settings.allow-creative is true. Spectators never earn.
    • Check settings.disabled-worlds and any WorldGuard region with skilltrees-points deny.
    • Blocks you placed pay player-placed-multiplier (default 0).
    • A block can be set to 0 in voyager-blocks.yml.
    • Run /skilladmin add <you> voyager 10. If that shows the action bar, the earning rules are the cause.
    The action bar shows nothing

    Check settings.actionbar-feedback and settings.actionbar-min-gain. Session gains always show the running total, but only when settings.session.enabled and the matching mining or combat switch are on.

    The action bar shows only +N

    That is the compact form for repeats outside sessions. Raise actionbar-compact-reset-seconds so the full text returns after a pause, or use sessions.

    A reward did not arrive
    • Read the console for rewards.yml ... warnings: unknown item, unknown enchantment, bad money amount, invalid sound.
    • Money needs Vault and an economy plugin. Permissions need LuckPerms.
    • For a level reached before the reward existed, run /skilladmin claim <player|all> or turn on auto-claim-on-join.
    • Rewards pay once per level. Use reclaimable to allow repeats.
    Level rewards after I changed the level curve

    Points are kept, so levels are recalculated from them. Run /skilladmin claim all to pay rewards for levels that players now count as having reached.

    Reclaiming does not work for one level

    An unreadable cooldown disables reclaiming for that level, with a console warning. Use the units s, m, h, d or md with a number, like 12h.

    My GUI layout looks wrong
    • Run /skilladmin reload and reopen the menu. Open menus keep the old layout.
    • A button wins over a level on the same slot. Move one of them.
    • Slots are numbered from 0. A 3-row menu has slots 0 to 26.
    • The console tells you about unknown materials and out-of-range slots.
    /skilltop says the leaderboard is loading

    The first build runs right after startup. Wait a moment and try again. The list refreshes every leaderboard.refresh-seconds.

    Storage did not start

    The console says Could not start 'mysql' storage with the reason, and the plugin runs on YAML instead. Check host, port, user, password and that the JDBC driver is available, then restart. Data saved in the YAML fallback is not moved to MySQL automatically.

    Placeholders show as text

    PlaceholderAPI must be installed and hooks.placeholderapi true. The log line PlaceholderAPI expansion registered confirms it.

    Console messages

    Message starts withMeaning
    gui.yml tree.level-slots: slot N ...A level slot is invalid or outside the inventory, skipped.
    gui.yml: no free slot for levels, using slot 0Every level slot is used by buttons or out of range.
    gui.yml ... unknown itemA material name was not recognised. The default is used.
    rewards.yml ... bad cooldownCooldown text could not be read. That level cannot be reclaimed.
    rewards.yml ... unknown item / enchantment / invalid soundThat one entry is skipped, the rest of the reward still pays.
    rewards.yml changes permissions, but LuckPerms was not foundPermission rewards do nothing until LuckPerms is installed.
    rewards.yml gives money, but no Vault economy was foundMoney rewards are skipped until an economy exists.
    voyager-blocks.yml ...An unknown block, unknown tag or non-number was skipped.
    Could not load / save data for ...A storage read or write failed for that player. Check disk space and database access.
    Another plugin already uses the WorldGuard flagThe flag name is taken, so region control is off.
    Reference

    Good to know

    The behaviours below are intentional or unavoidable. Reading them now saves a support question later.

    Compatibility

    Built for Paper 26.3

    The plugin targets the Paper 26.3 API on Java 25. It has not been run on Spigot or older Paper versions.

    Shields

    Block detection is indirect

    Shield blocks are found by reading the blocking damage modifier, with a fallback for fully blocked hits. A server change to damage handling could affect it.

    Placed blocks

    Doors and beds

    Only the placed position of a block is remembered. For two-part blocks such as doors and beds, only the main half reported by the placement is tracked, so breaking the other half can pay normal mining points.

    Discoveries

    Reward items count

    Items from rewards.yml can trigger the "new item" bonus. Add them to ignored-items if you do not want that.

    Storage

    No automatic migration

    Changing storage type starts a new data set. Copy data yourself if you need to keep it.

    Admin commands

    Online players only

    add, set, reset and claim work on online players. /profile can still view offline players.

    Frequently asked

    Can I change every value?

    Yes. Every number, text, material, slot and colour listed on this page is in a yaml file. Keys the plugin does not recognise are ignored.

    Can I add more bosses?

    Add any entity id to combatant.kill.overrides with its points. It becomes a boss: everyone who hurt it is paid. Add it to repeat-decay.bosses too if repeat kills should decay.

    Can I make a point-less world?

    Yes: add the world folder name to settings.disabled-worlds, or use the WorldGuard flag for a single region.

    How do I run a double points event?

    Set multipliers.combatant and multipliers.voyager to 2.0 and run /skilladmin reload. Set them back to 1.0 afterwards.

    How do I give a prize every few days?

    Give that level reclaimable: true and a cooldown such as 3d. Players click the level in /profile to claim it again.

    Can I use a custom item as a menu button?

    Any Minecraft item name works for material. Menus use plain items, so custom model data on GUI items is not supported. Reward items do support custom-model-data.

    How do I reset one player?

    /skilladmin reset <player> deletes all of their skill data. To only change points use /skilladmin set.

    Questions about SkillTrees?

    Tell me what you are trying to set up and what you see on your server.

    GitHub

    prashantsharma0720@gmail.com