EliteEnchants

⚠ Alpha Release — Core systems are functional and stable. APIs and JSON schemas may change between versions. Test thoroughly before deploying on a live server.

EliteEnchants is a fully data-driven custom enchantment engine for Paper servers. Every enchant is defined entirely in a JSON file — no recompilation, no source edits, no restarts required to create new behavior. The engine evaluates a Trigger → Condition → Action pipeline at runtime, with a custom expression parser for dynamic numeric formulas and support for hooking into any Bukkit/Paper event.

---

Requirements

Requirement	Version
Server software	Paper 1.21+
Java	21+

---

How It Works

Each enchant is a single JSON file placed in plugins/EliteEnchants/enchants/. On load (or /ee reload), the engine parses every file and registers its triggers dynamically — no hardcoded listeners required.

The runtime pipeline for every player action looks like this:

Player Action / Event
        ↓
Trigger Dispatcher
        ↓
Condition Evaluation  (short-circuits on first failure)
        ↓
Expression Resolution (level, damage, health, random, ...)
        ↓
Action Execution

Enchant data is stored on items using the PersistentDataContainer (PDC) API, making it fully persistent across server restarts and compatible with vanilla item handling.

---

Getting Started

1. Install

Drop the .jar into your plugins/ folder and start the server. Six example enchants are written automatically to plugins/EliteEnchants/enchants/ on first launch.

2. Apply an Enchant to an Item

Use /ee book <id> <level> to receive an enchant book, then drag and drop it onto any compatible item in your inventory. The book is consumed on application.

3. Create Your Own Enchant

Create a new .json file in plugins/EliteEnchants/enchants/ and run /ee reload. No server restart needed.

---

Commands

Command	Description	Permission
/ee book <id> <level>	Give yourself an enchant book	(default: op)
/ee list	List all loaded enchants	—
/ee info <id>	Show details for a specific enchant	—
/ee reload	Hot-reload all enchant JSON files	eliteenchants.admin
/ee strip	Remove all custom enchants from held item	—

All subcommands support tab completion, including enchant IDs and valid level ranges.

---

Enchant File Structure

A minimal enchant file looks like this:

{
  "id": "LIFESTEAL",
  "display_name": "<red>Lifesteal",
  "description": ["Heal on hit. Chance and heal amount scale with level."],
  "max_level": 5,
  "applicable_to": ["SWORD", "AXE"],
  "conflicts_with": [],
  "triggers": [
    {
      "event": "ON_HIT",
      "cooldown": 0.5,
      "conditions": [
        { "type": "CHANCE", "value": "0.15 + (level * 0.1)" },
        { "type": "TARGET_IS", "value": "LIVING" }
      ],
      "actions": [
        { "type": "HEAL",           "target": "HOLDER", "amount": "level * 1.5" },
        { "type": "SEND_ACTION_BAR","target": "HOLDER", "message": "<red>❤ Lifesteal!" }
      ]
    }
  ]
}

display_name and message fields support full MiniMessage formatting (<red>, <bold>, <gradient:...>, etc.).

---

Expression Engine

Any numeric field in conditions or actions accepts a full math expression. Expressions are evaluated at runtime with per-context variable injection.

Example:

{ "type": "ADD_DAMAGE", "amount": "level * (1.0 - holder_health_pct) * 5" }

Available Variables

Variable	Description
level	Current enchant level
damage	Damage value in the triggering event
holder_health	Holder's current HP
holder_max_health	Holder's maximum HP
holder_health_pct	Holder's HP as a fraction (0.0–1.0)
target_health	Target's current HP
target_max_health	Target's maximum HP
target_health_pct	Target's HP as a fraction (0.0–1.0)
distance	Distance between holder and target
random	Random decimal (0.0–1.0)

Supported Operators

+   -   *   /   %   ^
<   >   <=  >=  ==  !=
&&  ||  !

Built-In Functions

min() max() abs() floor() ceil() round() sqrt() pow() log() sin() cos() clamp() lerp() random()

---

Triggers

Standard Triggers

Trigger	Description
ON_HIT	Holder damages an entity
ON_TAKE_DAMAGE	Holder receives damage
ON_KILL	Holder kills an entity
ON_MINE	Holder breaks a block
ON_SNEAK	Holder begins sneaking
ON_SHOOT	Holder launches a projectile
ON_ARROW_LAND	Projectile hits a target
ON_RIGHT_CLICK	Holder right-clicks
TICK	Fires every server tick (use cooldown to gate frequency)

Dynamic Event Triggers

Any Bukkit/Paper event can be registered at runtime using reflection-safe MethodHandle dispatch. Define the event class and the methods that resolve the holder and target:

{
  "eventClass": "org.bukkit.event.player.PlayerInteractEntityEvent",
  "holderMethod": "getPlayer",
  "targetMethod": "getRightClicked"
}

This opens the door to entity interaction enchants, projectile logic, inventory triggers, movement systems, and anything else the Bukkit API exposes — without touching Java.

---

Conditions

All conditions in a trigger must pass before any actions execute. Evaluation short-circuits on the first failure.

Condition	Description
CHANCE	Probabilistic check — e.g. "0.05 * level"
HEALTH_ABOVE / HEALTH_BELOW	Holder HP threshold
HEALTH_PERCENT_ABOVE / HEALTH_PERCENT_BELOW	Holder HP as fraction
TARGET_HEALTH_ABOVE / TARGET_HEALTH_BELOW	Target HP threshold
IS_SNEAKING / IS_SPRINTING / IS_FLYING	Movement state
IS_ON_GROUND / IS_ON_FIRE / IS_FROZEN	Physical state
TARGET_IS / TARGET_NOT	Entity category (LIVING, UNDEAD, CREATURE, etc.)
DAMAGE_ABOVE / DAMAGE_BELOW / DAMAGE_CAUSE	Damage event filtering
BIOME_IS / WORLD_IS / TIME_IS / WEATHER_IS	Environmental checks
HAS_EFFECT / TARGET_HAS_EFFECT	Potion effect checks
EXPR / EXPRESSION	Arbitrary boolean expression

---

Actions

Action	Description
HEAL	Restore HP to target
DAMAGE	Deal damage to target
ADD_DAMAGE	Add flat bonus to current event damage
MULTIPLY_DAMAGE	Multiply current event damage by a factor
SET_HEALTH	Set target HP to a specific value
SET_ON_FIRE / EXTINGUISH	Ignite or extinguish target
FREEZE / UNFREEZE	Apply or remove powder snow freeze
APPLY_POTION / REMOVE_POTION / CLEAR_POTIONS	Manage potion effects
PLAY_SOUND	Play a sound at the target's location
SPAWN_PARTICLE	Spawn a particle effect
SEND_MESSAGE / SEND_ACTION_BAR / SEND_TITLE	Send text to the holder
STRIKE_LIGHTNING / STRIKE_LIGHTNING_EFFECT	Real or visual lightning
TELEPORT / TELEPORT_BEHIND	Teleport an entity
LAUNCH / KNOCKBACK / PULL	Apply velocity
EXPLOSION	Create an explosion
BREAK_BLOCK	Break blocks in a radius
SPAWN_MOB	Spawn an entity
GIVE_EXP / RESTORE_HUNGER / RESTORE_SATURATION	Player resource management
CANCEL_EVENT	Cancel the triggering Bukkit event
RUN_COMMAND	Execute a console or player command

Dynamic Action Registry (Java API)

Addons and soft-dependencies can register entirely custom actions at runtime without modifying the plugin:

actionRegistry.put("SPAWN_EGG", (def, ctx) -> {
    if (ctx.target instanceof Creature creature) {
        ItemStack egg = new ItemStack(
            Material.valueOf(creature.getType().name() + "_SPAWN_EGG")
        );
        ctx.holder.getWorld().dropItemNaturally(ctx.holder.getLocation(), egg);
    }
});

---

Included Example Enchants

Six fully-configured enchants are written to disk on first launch as ready-to-use references:

ID	Slot	Description
LIFESTEAL	Sword, Axe	Heals on hit; chance and amount scale with level
LIGHTNING	Sword, Axe, Trident	Chance to strike lightning; adds bonus damage and slowness
BERSERKER	Sword, Axe	Bonus damage scales with missing health percentage
FEATHERFALL_ELITE	Boots	Reduces fall damage by 25% per level; eliminated at max level
EXCAVATOR	Pickaxe, Shovel	Area block-break while sneaking; radius scales with level
FROSTBITE	Sword, Axe	Freezes and slows on hit; conflicts with LIGHTNING

---

Performance Notes

The engine is designed with throughput in mind:

• Cached MethodHandles — dynamic event resolution avoids repeated reflection lookups
• Cooldown gating — per-trigger, per-player cooldowns are checked before any evaluation
• Short-circuit conditions — the condition chain aborts on the first failure; expensive checks should go last
• Filtered dispatch — only enchants relevant to the triggered event and the holder's equipped items are evaluated

---

Advanced Example

{
  "id": "VOIDSTEP",
  "display_name": "<dark_purple>Voidstep",
  "description": ["Teleport behind your target on hit."],
  "max_level": 3,
  "applicable_to": ["SWORD"],
  "conflicts_with": [],
  "triggers": [
    {
      "event": "ON_HIT",
      "cooldown": 4.0,
      "conditions": [
        { "type": "CHANCE", "value": "0.08 * level" },
        { "type": "TARGET_IS", "value": "LIVING" }
      ],
      "actions": [
        { "type": "TELEPORT_BEHIND", "target": "TARGET" },
        { "type": "PLAY_SOUND", "target": "HOLDER", "sound": "ENTITY_ENDERMAN_TELEPORT" },
        { "type": "SPAWN_PARTICLE", "location": "TARGET", "particle": "PORTAL", "count": "20", "spread": "0.5" }
      ]
    }
  ]
}