SkillsAPI reference

Complete reference for all 19 methods in the SkillsAPI interface.

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