EliteEnchants

!(https://imgur.com/g8A0j6Y.png) # 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 ` 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 ` | Give yourself an enchant book | (default: op) | | `/ee list` | List all loaded enchants | — | | `/ee info ` | 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:

```json { "id": "LIFESTEAL", "display_name": "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": "❤ Lifesteal!" } ] } ] } ```

`display_name` and `message` fields support full MiniMessage formatting (``, ``, ``, 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: ```json { "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. D