EliteEnchants
⚠ Alpha Release — 核心系统功能完善且稳定。API 和 JSON 模式在不同版本间可能会发生变化。在部署到正式服务器之前,请进行充分测试。
EliteEnchants 是一个完全数据驱动的自定义附魔引擎,适用于 Paper 服务器。每个附魔都完全由 JSON 文件定义——无需重新编译、无需修改源码、无需重启服务器即可创建新行为。引擎在运行时评估 触发器 → 条件 → 动作 管道,并配有自定义表达式解析器以支持动态数值公式,同时支持挂钩任何 Bukkit/Paper 事件。
要求
| 要求 |
版本 |
| 服务端软件 |
Paper 1.21+ |
| Java |
21+ |
工作原理
每个附魔都是一个单独的 JSON 文件,放置在 plugins/EliteEnchants/enchants/ 中。在加载时(或执行 /ee reload),引擎会解析每个文件并动态注册其触发器——无需硬编码监听器。
每次玩家操作的运行时管道如下所示:
玩家操作 / 事件
↓
触发器分发器
↓
条件评估 (首次失败时短路)
↓
表达式解析(等级、伤害、生命值、随机数等)
↓
动作执行
附魔数据使用 PersistentDataContainer (PDC) API 存储在物品上,使其在服务器重启后完全持久化,并与原版物品处理兼容。
快速开始
1. 安装
将 .jar 放入你的 plugins/ 文件夹并启动服务器。首次启动时会自动在 plugins/EliteEnchants/enchants/ 中写入六个示例附魔。
2. 将附魔应用到物品
使用 /ee book <id> <level> 获取附魔书,然后将其拖放到库存中的任何兼容物品上。应用后书本会被消耗。
3. 创建你自己的附魔
在 plugins/EliteEnchants/enchants/ 中创建一个新的 .json 文件并运行 /ee reload。无需重启服务器。
命令
| 命令 |
描述 |
权限 |
/ee book <id> <level> |
给自己一本附魔书 |
(默认:op) |
/ee list |
列出所有已加载的附魔 |
— |
/ee info <id> |
显示特定附魔的详细信息 |
— |
/ee reload |
热重载所有附魔 JSON 文件 |
eliteenchants.admin |
/ee strip |
移除手持物品上的所有自定义附魔 |
— |
所有子命令均支持自动补全,包括附魔 ID 和有效的等级范围。
附魔文件结构
一个最小的附魔文件如下所示:
{
"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 和 message 字段支持完整的 MiniMessage 格式(<red>、<bold>、<gradient:...> 等)。
表达式引擎
条件和动作中的任何数值字段都接受完整的数学表达式。表达式在运行时进行评估,并注入每上下文变量。
示例:
{ "type": "ADD_DAMAGE", "amount": "level * (1.0 - holder_health_pct) * 5" }
可用变量
| 变量 |
描述 |
level |
当前附魔等级 |
damage |
触发事件中的伤害值 |
holder_health |
持有者当前生命值 |
holder_max_health |
持有者最大生命值 |
holder_health_pct |
持有者生命值比例(0.0–1.0) |
target_health |
目标当前生命值 |
target_max_health |
目标最大生命值 |
target_health_pct |
目标生命值比例(0.0–1.0) |
distance |
持有者与目标之间的距离 |
random |
随机小数(0.0–1.0) |
支持的运算符
+ - * / % ^
< > <= >= == !=
&& || !
内置函数
min() max() abs() floor() ceil() round() sqrt() pow() log() sin() cos() clamp() lerp() random()
触发器
标准触发器
| 触发器 |
描述 |
ON_HIT |
持有者对实体造成伤害 |
ON_TAKE_DAMAGE |
持有者受到伤害 |
ON_KILL |
持有者击杀实体 |
ON_MINE |
持有者破坏方块 |
ON_SNEAK |
持有者开始潜行 |
ON_SHOOT |
持有者发射投射物 |
ON_ARROW_LAND |
投射物击中目标 |
ON_RIGHT_CLICK |
持有者右键点击 |
TICK |
每个服务器刻触发一次(使用冷却时间来限制频率) |
动态事件触发器
任何 Bukkit/Paper 事件都可以通过反射安全的 MethodHandle 分发在运行时注册。定义事件类以及解析持有者和目标的方法:
{
"eventClass": "org.bukkit.event.player.PlayerInteractEntityEvent",
"holderMethod": "getPlayer",
"targetMethod": "getRightClicked"
}
这为实体交互附魔、投射物逻辑、库存触发器、移动系统以及 Bukkit API 暴露的任何其他内容打开了大门——无需接触 Java。
条件
触发器中的所有条件都必须通过,才能执行任何动作。评估在首次失败时短路。
| 条件 |
描述 |
CHANCE |
概率检查 — 例如 "0.05 * level" |
HEALTH_ABOVE / HEALTH_BELOW |
持有者生命值阈值 |
HEALTH_PERCENT_ABOVE / HEALTH_PERCENT_BELOW |
持有者生命值比例 |
TARGET_HEALTH_ABOVE / TARGET_HEALTH_BELOW |
目标生命值阈值 |
IS_SNEAKING / IS_SPRINTING / IS_FLYING |
移动状态 |
IS_ON_GROUND / IS_ON_FIRE / IS_FROZEN |
物理状态 |
TARGET_IS / TARGET_NOT |
实体类别(LIVING、UNDEAD、CREATURE 等) |
DAMAGE_ABOVE / DAMAGE_BELOW / DAMAGE_CAUSE |
伤害事件过滤 |
BIOME_IS / WORLD_IS / TIME_IS / WEATHER_IS |
环境检查 |
HAS_EFFECT / TARGET_HAS_EFFECT |
药水效果检查 |
EXPR / EXPRESSION |
任意布尔表达式 |
动作
| 动作 |
描述 |
HEAL |
为目标恢复生命值 |
DAMAGE |
对目标造成伤害 |
ADD_DAMAGE |
为当前事件伤害增加固定额外值 |
MULTIPLY_DAMAGE |
将当前事件伤害乘以系数 |
SET_HEALTH |
将目标生命值设置为特定值 |
SET_ON_FIRE / EXTINGUISH |
点燃或熄灭目标 |
FREEZE / UNFREEZE |
施加或移除粉末雪冻结效果 |
APPLY_POTION / REMOVE_POTION / CLEAR_POTIONS |
管理药水效果 |
PLAY_SOUND |
在目标位置播放声音 |
SPAWN_PARTICLE |
生成粒子效果 |
SEND_MESSAGE / SEND_ACTION_BAR / SEND_TITLE |
向持有者发送文本 |
STRIKE_LIGHTNING / STRIKE_LIGHTNING_EFFECT |
真实闪电或视觉闪电效果 |
TELEPORT / TELEPORT_BEHIND |
传送实体 |
LAUNCH / KNOCKBACK / PULL |
施加速度 |
EXPLOSION |
创建爆炸 |
BREAK_BLOCK |
破坏半径内的方块 |
SPAWN_MOB |
生成实体 |
GIVE_EXP / RESTORE_HUNGER / RESTORE_SATURATION |
玩家资源管理 |
CANCEL_EVENT |
取消触发的 Bukkit 事件 |
RUN_COMMAND |
执行控制台或玩家命令 |
动态动作注册表 (Java API)
插件和软依赖可以在运行时注册完全自定义的动作,而无需修改插件本身:
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);
}
});
内置示例附魔
首次启动时,六个完整配置的附魔会被写入磁盘,作为即用型参考:
| ID |
适用部位 |
描述 |
LIFESTEAL |
剑,斧 |
命中时治疗;几率和数值随等级提升 |
LIGHTNING |
剑,斧,三叉戟 |
有几率召唤闪电;附加额外伤害和缓慢效果 |
BERSERKER |
剑,斧 |
额外伤害随缺失生命值的百分比提升 |
FEATHERFALL_ELITE |
靴子 |
每级减少 25% 摔落伤害;满级时完全消除 |
EXCAVATOR |
镐,锹 |
潜行时范围破坏方块;半径随等级提升 |
FROSTBITE |
剑,斧 |
命中时冻结并减速;与 LIGHTNING 冲突 |
性能说明
引擎设计注重吞吐量:
- 缓存的 MethodHandles — 动态事件解析避免了重复的反射查找
- 冷却门控 — 在每个触发器、每个玩家的冷却时间在任何评估之前进行检查
- 短路条件 — 条件链在第一次失败时中止;昂贵的检查应放在最后
- 过滤分发 — 仅评估与触发事件相关且持有者装备物品相关的附魔
高级示例
{
"id": "VOIDSTEP",
"display_name": "<dark_purple>Voidstep",
"description": ["命中后传送到目标身后。"],
"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" }
]
}
]
}
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" }
]
}
]
}
评论 0
登录后参与评分
还没有评论,来抢沙发吧