SkillsAPI reference

The SkillsAPI interface is located at com.hacklab.minecraft.skills.api.SkillsAPI. Obtain an instance via the Bukkit ServicesManager as described in Getting started.

Skill operations

`getSkill` (by Player)

fun getSkill(player: Player, skillName: String): Double?

Returns the current value of a skill for an online player.

player

Player

required

The online player to query.

skillName

String

required

Skill name in any accepted format (display name, enum name, case-insensitive, spaces or underscores).

return

Double?

Skill value in the range 0.0–100.0, or null if skillName does not match any known skill.

val sword: Double = api.getSkill(player, "Swordsmanship") ?: 0.0

`getSkill` (by UUID)

fun getSkill(uuid: UUID, skillName: String): Double?

Returns the current value of a skill looked up by UUID. Useful when you only have a UUID and the player may be offline in cache.

uuid

UUID

required

The UUID of the player.

skillName

String

required

Skill name in any accepted format.

return

Double?

Skill value 0.0–100.0, or null if the skill name is invalid or the player’s data is not loaded.

val mining: Double = api.getSkill(player.uniqueId, "Mining") ?: 0.0

`setSkill`

fun setSkill(player: Player, skillName: String, value: Double): Boolean

Sets a skill to an explicit value. The value is clamped to 0.0–100.0 before being applied.

player

Player

required

The online player to modify.

skillName

String

required

Skill name in any accepted format.

value

Double

required

Target skill value. Automatically clamped to [0.0, 100.0].

return

Boolean

true if the skill was updated, false if skillName is invalid.

// Ensure a new player starts with at least 10 Mining
if ((api.getSkill(player, "Mining") ?: 0.0) < 10.0) {
    api.setSkill(player, "Mining", 10.0)
}

`addSkill`

fun addSkill(player: Player, skillName: String, amount: Double): Double?

Adds (or subtracts, if amount is negative) a delta to the current skill value. Respects the 0.0–100.0 cap.

player

Player

required

The online player to modify.

skillName

String

required

Skill name in any accepted format.

amount

Double

required

Amount to add. May be negative to reduce the skill.

return

Double?

The new skill value after the delta is applied, or null if skillName is invalid.

// Award 5 points of Crafting as a quest reward
val newValue = api.addSkill(player, "Crafting", 5.0)
player.sendMessage("Crafting is now ${newValue?.toInt()}.")

`hasSkillLevel`

fun hasSkillLevel(player: Player, skillName: String, minLevel: Double): Boolean

Checks whether a player’s skill is at or above a threshold without requiring a null check on the caller side.

player

Player

required

The online player to check.

skillName

String

required

Skill name in any accepted format.

minLevel

Double

required

The minimum required skill value.

return

Boolean

true if the player’s skill value is greater than or equal to minLevel. Returns false if the skill name is invalid.

Use hasSkillLevel() instead of comparing the result of getSkill() directly. It handles the invalid-skill case for you.

if (!api.hasSkillLevel(player, "Archery", 30.0)) {
    event.isCancelled = true
    player.sendMessage("You need 30 Archery to use this bow.")
}

`getAllSkills`

fun getAllSkills(player: Player): Map<String, Double>

Returns a snapshot of all 37 skill values for a player.

player

Player

required

The online player to query.

return

Map<String, Double>

Map keyed by skill display name (e.g. "Swordsmanship") with the current value as the entry. All 37 skills are always present; unlearned skills have a value of 0.0.

val skills = api.getAllSkills(player)
skills.forEach { (name, value) ->
    if (value > 0.0) println("$name: $value")
}

`getTotalSkillPoints`

fun getTotalSkillPoints(player: Player): Double

Returns the sum of all skill values. The in-game cap is 700 points.

player

Player

required

The online player to query.

return

Double

Sum of all 37 skill values. Maximum is 700.0 (7 skills at 100.0).

val total = api.getTotalSkillPoints(player)
player.sendMessage("Total skill points: ${total.toInt()} / 700")

Stat operations

STR, DEX, and INT are derived stats calculated automatically from the player’s skill values. They cannot be set directly; they update whenever the underlying skills change.

Stat	Range	Effect
STR	0–100	Max HP = 100 + STR; mining/lumberjacking speed bonus
DEX	0–100	Attack speed +DEX/2%; movement speed +DEX/10%
INT	0–100	Mana cost −INT/2%; cast success rate +INT/5%

`getStat`

fun getStat(player: Player, statName: String): Int?

Returns the current value of a single derived stat.

player

Player

required

The online player to query.

statName

String

required

One of "STR", "DEX", or "INT" (also accepts the long forms "STRENGTH", "DEXTERITY", "INTELLIGENCE").

return

Int?

Stat value 0–100, or null if statName is not recognised.

val str = api.getStat(player, "STR") ?: 0
val maxHp = 100 + str

`getAllStats`

fun getAllStats(player: Player): Map<String, Int>

Returns all three derived stats in a single call.

player

Player

required

The online player to query.

return

Map<String, Int>

Map with keys "STR", "DEX", and "INT" mapped to their current integer values.

val stats = api.getAllStats(player)
val str = stats["STR"] ?: 0
val dex = stats["DEX"] ?: 0
val int = stats["INT"] ?: 0

HP, mana, and stamina

Skills maintains internal HP, mana, and stamina values that are separate from vanilla Minecraft hunger and hearts. HP is synchronised to vanilla hearts as a percentage.

`getCurrentHp`

fun getCurrentHp(player: Player): Double

Returns the player’s current internal HP.

player

Player

required

The online player to query.

return

Double

Current internal HP. Minimum 0.0; maximum equals getMaxHp().

val hp = api.getCurrentHp(player)

`getMaxHp`

fun getMaxHp(player: Player): Double

Returns the player’s maximum internal HP. Calculated as 100 + STR, giving a range of 100–200.

player

Player

required

The online player to query.

return

Double

Maximum HP in the range 100.0–200.0 based on the player’s STR stat.

val pct = api.getCurrentHp(player) / api.getMaxHp(player)

`getCurrentMana`

fun getCurrentMana(player: Player): Double

Returns the player’s current mana. Mana is consumed by spell casting and is independent of the vanilla hunger bar.

player

Player

required

The online player to query.

return

Double

Current mana. Minimum 0.0; maximum 20.0.

val mana = api.getCurrentMana(player)

`getMaxMana`

fun getMaxMana(player: Player): Double

Returns the player’s maximum mana. The maximum is always 20.0. INT reduces the cost of spells rather than increasing the pool.

player

Player

required

The online player to query.

return

Double

Maximum mana. Always 20.0.

val maxMana = api.getMaxMana(player) // always 20.0

`getCurrentStamina`

fun getCurrentStamina(player: Player): Double

Returns the player’s current stamina. Stamina is consumed while sprinting.

player

Player

required

The online player to query.

return

Double

Current stamina. Minimum 0.0; maximum equals getMaxStamina().

val stamina = api.getCurrentStamina(player)

`getMaxStamina`

fun getMaxStamina(player: Player): Double

Returns the player’s maximum stamina. Calculated as 100 + DEX + (Focus / 2), giving a maximum of 250.0 when DEX and Focus are both 100.

player

Player

required

The online player to query.

return

Double

Maximum stamina. Range 100.0–250.0 depending on DEX stat and Focus skill.

val staminaPct = api.getCurrentStamina(player) / api.getMaxStamina(player)

`restoreMana`

fun restoreMana(player: Player, amount: Double)

Adds mana to the player, capped at the maximum.

player

Player

required

The online player to restore mana for.

amount

Double

required

Amount of mana to restore. Excess is discarded.

// Simulate a mana potion
api.restoreMana(player, 5.0)

`restoreStamina`

fun restoreStamina(player: Player, amount: Double)

Adds stamina to the player, capped at the maximum.

player

Player

required

The online player to restore stamina for.

amount

Double

required

Amount of stamina to restore. Excess is discarded.

// Give a brief stamina burst on a specific event
api.restoreStamina(player, 20.0)

Utility

`getAvailableSkillNames`

fun getAvailableSkillNames(): List<String>

Returns the display names of all 37 skills registered by the plugin.

return

List<String>

Ordered list of skill display names (e.g. ["Swordsmanship", "Axe", ...]). Use these as inputs to other skill methods.

val names: List<String> = api.getAvailableSkillNames()

`isValidSkillName`

fun isValidSkillName(skillName: String): Boolean

Checks whether a string resolves to a known skill, using the same lenient matching as all other skill methods.

skillName

String

required

The string to validate.

return

Boolean

true if the name resolves to a known skill, false otherwise.

if (!api.isValidSkillName(input)) {
    sender.sendMessage("Unknown skill: $input")
    return
}

`getTitle`

fun getTitle(player: Player): String

Returns the player’s current title string, which is derived from their highest-ranked skills (e.g. "Grandmaster Swordsman").

player

Player

required

The online player to query.

return

String

Human-readable title string. The format depends on the player’s skill distribution.

val title = api.getTitle(player)
player.sendMessage("Your title: $title")

Skill name reference

All skill names accepted by any API method. Matching is case-insensitive; spaces and underscores are interchangeable.

Display name	Enum name
Swordsmanship	`SWORDSMANSHIP`
Axe	`AXE`
Mace Fighting	`MACE_FIGHTING`
Spear	`SPEAR`
Archery	`ARCHERY`
Throwing	`THROWING`
Wrestling	`WRESTLING`
Tactics	`TACTICS`
Anatomy	`ANATOMY`
Parrying	`PARRYING`
Focus	`FOCUS`
Magery	`MAGERY`
Evaluating Intelligence	`EVALUATING_INTELLIGENCE`
Meditation	`MEDITATION`
Resisting Spells	`RESISTING_SPELLS`
Inscription	`INSCRIPTION`
Crafting	`CRAFTING`
Cooking	`COOKING`
Mining	`MINING`
Lumberjacking	`LUMBERJACKING`
Fishing	`FISHING`
Farming	`FARMING`
Hiding	`HIDING`
Stealth	`STEALTH`
Detecting Hidden	`DETECTING_HIDDEN`
Snooping	`SNOOPING`
Stealing	`STEALING`
Poisoning	`POISONING`
Animal Taming	`ANIMAL_TAMING`
Animal Lore	`ANIMAL_LORE`
Veterinary	`VETERINARY`
Athletics	`ATHLETICS`
Swimming	`SWIMMING`
Heat Resistance	`HEAT_RESISTANCE`
Cold Resistance	`COLD_RESISTANCE`
Endurance	`ENDURANCE`
Arms Lore	`ARMS_LORE`

Integration

Skill operations

`getSkill` (by Player)

`getSkill` (by UUID)

`setSkill`

`addSkill`

`hasSkillLevel`

`getAllSkills`

`getTotalSkillPoints`

Stat operations

`getStat`

`getAllStats`

HP, mana, and stamina

`getCurrentHp`

`getMaxHp`

`getCurrentMana`

`getMaxMana`

`getCurrentStamina`

`getMaxStamina`

`restoreMana`

`restoreStamina`

Utility

`getAvailableSkillNames`

`isValidSkillName`

`getTitle`

Skill name reference

Build docs developers (and LLMs) love

Integration

​Skill operations

​getSkill (by Player)

​getSkill (by UUID)

​setSkill

​addSkill

​hasSkillLevel

​getAllSkills

​getTotalSkillPoints

​Stat operations

​getStat

​getAllStats

​HP, mana, and stamina

​getCurrentHp

​getMaxHp

​getCurrentMana

​getMaxMana

​getCurrentStamina

​getMaxStamina

​restoreMana

​restoreStamina

​Utility

​getAvailableSkillNames

​isValidSkillName

​getTitle

​Skill name reference

Build docs developers (and LLMs) love

Skill operations

`getSkill` (by Player)

`getSkill` (by UUID)

`setSkill`

`addSkill`

`hasSkillLevel`

`getAllSkills`

`getTotalSkillPoints`

Stat operations

`getStat`

`getAllStats`

HP, mana, and stamina

`getCurrentHp`

`getMaxHp`

`getCurrentMana`

`getMaxMana`

`getCurrentStamina`

`getMaxStamina`

`restoreMana`

`restoreStamina`

Utility

`getAvailableSkillNames`

`isValidSkillName`

`getTitle`

Skill name reference