EliteEnchants

插件

· 作者 Partakithware

通过 JSON 定义您自己的自定义附魔。其目标是提供充足的功能与可能性。这是首个版本!附带了一些示例自定义附魔。

0 本站下载 0 关注 更新于 5 个月前

最新 1.0.0a · 26.1.2 · Paper

一键开服(送7天)

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" }
      ]
    }
  ]
}

你是这个资源的作者?登录后可认领此资源。

评论 0

0.0
暂无评分
5 星
0
4 星
0
3 星
0
2 星
0
1 星
0
我的评分

登录后参与评分

还没有评论,来抢沙发吧

评论配图

相似资源