API Reference

Table of contents

1. Dependency setup
2. EzSkillsAPI
   1. Obtaining the instance
   2. Reading skill data
   3. Modifying skill data
3. Events
   1. SkillLevelUpEvent
   2. EzSkillsAbilityPrepareEvent
   3. EzSkillsAbilityActivateEvent
   4. EzSkillsAbilityDeactivateEvent
4. SkillType enum
5. AbilityType enum
6. Thread safety

---

Dependency setup

Add the ezskills-api artifact to your project; see Installation for Maven and Gradle snippets.

Declare EzSkills as a (soft) dependency in plugin.yml so the API is available when your plugin loads:

depend:
  - EzSkills

---

EzSkillsAPI

The EzSkillsAPI class is a static facade that delegates to EzSkillsService, the interface implemented by the main plugin class.

Obtaining the instance

// Throws IllegalStateException if EzSkills is not loaded
EzSkillsService api = EzSkillsAPI.get();

Reading skill data

UUID id = player.getUniqueId();

int level = api.getSkillLevel(id, "WOODCUTTING");
double xp  = api.getSkillExperience(id, "MINING");

Both methods accept either a UUID or an OfflinePlayer.

Modifying skill data

// These operate on the in-memory cache and queue an async save.
// They are safe to call from the main thread.
api.addExperience(id, "FISHING", 50.0);
api.setSkillLevel(id, "FIGHTING", 10);

---

Events

All events extend org.bukkit.event.Event and are fired on the main thread.

SkillLevelUpEvent

Fired when a player’s skill advances to a new level.

import com.github.ezplugins.ezskills.api.event.SkillLevelUpEvent;

@EventHandler
public void onLevelUp(SkillLevelUpEvent event) {
    Player player   = event.getPlayer();
    SkillType skill = event.getSkillType();
    int oldLevel    = event.getOldLevel();
    int newLevel    = event.getNewLevel();
}

EzSkillsAbilityPrepareEvent

Fired when an ability enters the preparing state.

import com.github.ezplugins.ezskills.api.event.EzSkillsAbilityPrepareEvent;

@EventHandler
public void onPrepare(EzSkillsAbilityPrepareEvent event) {
    Player player       = event.getPlayer();
    AbilityType ability = event.getAbilityType();
    // event.setCancelled(true) to prevent preparation
}

EzSkillsAbilityActivateEvent

Fired when an ability becomes active.

import com.github.ezplugins.ezskills.api.event.EzSkillsAbilityActivateEvent;

@EventHandler
public void onActivate(EzSkillsAbilityActivateEvent event) {
    // Apply custom buff logic here
}

EzSkillsAbilityDeactivateEvent

Fired when an ability leaves the active state (expired or cancelled).

import com.github.ezplugins.ezskills.api.event.EzSkillsAbilityDeactivateEvent;

@EventHandler
public void onDeactivate(EzSkillsAbilityDeactivateEvent event) {
    // Remove custom buff logic here
}

---

SkillType enum

import com.github.ezplugins.ezskills.skill.SkillType;

SkillType type = SkillType.fromString("woodcutting"); // null-safe, case-insensitive

Constants: WOODCUTTING, MINING, FISHING, FIGHTING

---

AbilityType enum

import com.github.ezplugins.ezskills.ability.AbilityType;

AbilityType ability = AbilityType.fromString("lumberjack");

Constants: LUMBERJACK, SPELUNKER, ANGLER, WARRIOR

---

Thread safety

• EzSkillsAPI methods that read or mutate skill data are safe to call from the main thread.
• All actual storage I/O happens on the dedicated EzSkills-StorageWorker thread.
• Do not call EzSkills API methods from asynchronous Bukkit events or other plugin worker threads without synchronising back to the main thread first.