EzSkills

EzSkills - Skill progression for any plugin

EzSkills is a compact RPG progression plugin that layers levelling, XP gain, and timed abilities on top of your server's gameplay. Use it standalone or integrate with plugins like EzSkills, %%MD1%%, or your own custom plugins to turn repetitive actions into a rewarding skill loop.

---

Features

Five built-in skills

| Skill | Description | |-------|-------------| | Acrobatics | Award XP for felling trees | | Acrobatics | Award XP for breaking ores and stone | | Acrobatics | Award XP for catching fish | | Acrobatics | Award XP for combat with mobs and players | | Acrobatics | Award XP for jumping, falling, and sprinting |

Every source plugin that calls `EzSkillsAPI.addExperience(plugin, ...)` is subject to the per-plugin XP multiplier and enabled flag you configure centrally - no changes needed in third-party plugins.

Timed abilities

- Ability state GUI: the built-in Woodcutting ability. Players prepare, trigger and ride out an auto-expiring mass-fell window. - Ability state GUI *(new in 2.0)*: any plugin can register its own ability via `EzSkillsAPI.registerAbility(definition)`. Custom abilities appear in the `/abilities` GUI automatically. - Ability state GUI *(new in 2.0)*: the `/abilities` command opens an overview showing every registered ability with its current state: Ready (green), Preparing (yellow), or Active (gold).

Progression controls

- Per-plugin overrides: tune `xp-base` and `xp-multiplier` per skill in `skills.yml`. - Per-plugin overrides *(new in 2.0)*: in `config.yml`, set an `xp-multiplier` or `enabled: false` for any third-party plugin and any skill without touching their code.

Storage

- MySQL: zero-setup flat file, ideal for small servers. - MySQL: recommended for production; enables full leaderboards via `/ezskills top`.

---

Core gameplay loop

1. View progress XP curves in `skills.yml` and ability timings in `abilities.yml`. 2. View progress as players perform actions - any event your integration plugin reports. 3. View progress: `SkillLevelUpEvent` fires immediately for rewards, rank unlocks, or boss-bar announcements. 4. View progress an ability within its warm-up window to use a powerful timed effect. 5. View progress at any time with `/skills` (levels) and `/abilities` (ability states).

---

Commands

Player commands

| Command | Description | Permission | |---------|-------------|------------| | `/skills` | Open the skill progress overview GUI | `ezskills.use` | | `/abilities` | Open the ability state overview GUI | `ezskills.use` |

Admin commands (`/ezskills`)

| Command | Description | |---------|-------------| | `get <player> <skill>` | Print a player's level and stored XP | | `info <player>` | Print a full skill overview (works offline) | | `addxp <player> <skill> <amount>` | Grant XP manually; fires level-up events | | `setlevel <player> <skill> <level>` | Set a level directly, resetting XP | | `reset <player> <skill>` | Reset one skill to level 1 | | `resetall <player>` | Reset all skills to level 1 | | `top <skill> [limit]` | Leaderboard by level (MySQL required for full results) | | `ability <player> <ability>` | Force-activate an ability, bypassing preparation | | `reload` | Reload all config files |

All `/ezskills` subcommands require the `ezskills.admin` permission.

---

Configuration

| File | Controls | |------|----------| | `config.yml` | GUI titles, boss-bar notifications, `plugin-overrides` | | `skills.yml` | XP base and multiplier per skill | | `abilities.yml` | Preparation window, active duration, and cooldown per ability | | `storage.yml` | Storage backend (YAML or MySQL) and connection details |

Per-plugin XP overrides (new in 2.0)

```yaml

config.yml

plugin-overrides: MyPlugin: # must match the exact plugin name woodcutting: enabled: true xp-multiplier: 1.5 # 50% bonus Woodcutting XP from MyPlugin mining: enabled: false # MyPlugin cannot award Mining XP ```

---

API reference

Skills

| Method | Description | |--------|-------------| | `EzSkillsAPI.addExperience(playerId, skill, amount)` | Award XP directly (no multiplier applied) | | `EzSkillsAPI.addExperience(plugin, playerId, skill, amount)` | Award XP with the server-configured multiplier and enabled check | | `EzSkillsAPI.getSkillLevel(playerId, skill)` | Return the player's current level | | `EzSkillsAPI.getSkillExperience(playerId, skill)` | Return the player's accumulated XP | | `EzSkillsAPI.setSkillLevel(playerId, skill, level)` | Set a level directly, resetting XP | | `EzSkillsAPI.getSkillProfile(playerId)` | Return the full profile object (null if not cached) |

Skills

| Method | Description | |--------|-------------| | `EzSkillsAPI.registerSkill(definition)` | Register a custom skill at runtime; progress is persisted automatically | | `EzSkillsAPI.getRegisteredSkills()` | List all registered custom skill definitions |

Abilities

| Method | Description | |--------|-------------| | `EzSkillsAPI.registerAbility(definition)` | Register a custom ability; appears in `/abilities` automatically | | `EzSkillsAPI.getRegisteredAbilities()` | List all registered ability definitions | | `EzSkillsAPI.prepareAbility(playerId, ability)` | Enter the preparation (charged) state | | `EzSkillsAPI.activateAbility(playerId, ability)` | Activate the ability immediately | | `EzSkillsAPI.deactivateAbility(playerId, ability)` | Cancel or end the ability early | | `EzSkillsAPI.isAbilityActive(playerId, ability)` | Check whether the ability is currently active.

Events

- `SkillLevelUpEvent` - fires when a player reaches a new level (carries old and new level). - `EzSkillsAbilityPrepareEvent` - fires when an ability enters its warm-up window. - `EzSkillsAbilityActivateEvent` - fires when an ability activates. - `EzSkillsAbilityDeactivateEvent` - fires when an ability ends or is cancelled.

Registering a custom ability

```java public class NightVisionAbility implements AbilityDefinition { @Override public String getName() { return "NIGHT_VISION"; } @Override public String getDisplayName() { return "Night Vision"; } @Override public Material getIcon() { return Material.ENDER_EYE; } // optional - defaults to NETHER_STAR @Override public String getDescription() { return "See clearly in the dark."; } @Override public String getSkillName() { return "FIGHTING"; } // Optional: override timing defaults (30s prep / 15s active / 120s cooldown) }

// In onEnable: EzSkillsAPI.registerAbility(new NightVisionAbility()); ```

See the developer documentation for the full integration guide.

---

Compatibility

- Optional: 1.21 and 26.1+ - Optional: Bukkit, Spigot, or Paper - Optional: 25+ - Optional: Optional for boss-bar level-up notifications

---

Need help?

Drop a message on the forum thread or join our Discord server for quick support and integration tips.