ExcellentEnchants API 文档

概述

ExcellentEnchants 是一个轻量级、现代化的 Minecraft 附魔插件，提供 75+ 类原版附魔。本文档为开发者提供 API 使用指南。

包名和主要类

核心包

• su.nightexpress.excellentenchants – 主包
• su.nightexpress.excellentenchants.api – API 包

主要类

1. EnchantRegistry – 附魔注册表
2. EnchantKeys – 附魔键生成器
3. EnchantId – 附魔ID枚举
4. CustomEnchantment – 自定义附魔类

API 使用方法

1. 通过命名空间键获取附魔

// 总是使用 EnchantKeys 类获取带有效命名空间的键
NamespacedKey key = EnchantKeys.custom(EnchantId.TUNNEL);

// 对于 PaperMC
Enchantment enchantment = RegistryAccess.registryAccess()
    .getRegistry(RegistryKey.ENCHANTMENT)
    .get(key);

// 对于 SpigotMC
Enchantment enchantment = Registry.ENCHANTMENT.get(key);

// 使用 nightcore API
Enchantment enchantment = RegistryType.ENCHANTMENT.getRegistry().get(key);

// 使用 ExcellentEnchants API
CustomEnchantment custom = EnchantRegistry.getByKey(key);
Enchantment enchantment = custom.getBukkitEnchantment();

2. 通过 ID 获取附魔

CustomEnchantment custom = EnchantRegistry.getById(EnchantId.TUNNEL);
Enchantment enchantment = custom.getBukkitEnchantment();

3. 检查附魔是否存在

boolean exists = EnchantRegistry.isRegistered(EnchantId.TUNNEL);

4. 获取所有附魔

Set<CustomEnchantment> customs = EnchantRegistry.getRegistered();

附魔ID列表

工具附魔

• TUNNEL – 穿隧（范围挖掘）
• VEINMINER – 连锁挖掘
• BLAST_MINING – 爆破发掘
• HASTE – 急迫
• SMELTER – 熔炼
• SILK_CHEST – 搬箱
• SILK_SPAWNER – 封魔之触
• TREE_FELLER – 连锁伐树
• GLASS_BREAKER – 玻璃之触
• LUCKY_MINER – 幸运矿工
• REPLANTER – 复种
• TELEKINESIS – 心灵遥感

武器附魔

• BANE_OF_NETHERSPAWN – 下界杀手
• BLINDNESS – 致盲
• CONFUSION – 混乱
• CURE – 治愈
• CURSE_OF_DEATH – 唤死诅咒
• CUTTER – 剥蚀
• DECAPITATOR – 斩首
• DOUBLE_STRIKE – 复击
• EXHAUST – 饥饿
• ICE_ASPECT – 霜寒之刃
• INFERNUS – 淬火之戟
• NIMBLE – 掠夺
• PARALYZE – 瘫痪
• RAGE – 怒气
• ROCKET – 升空
• SWIPER – 知识窃取
• TEMPER – 顽抗
• THRIFTY – 猎捕
• THUNDER – 落雷
• VAMPIRE – 歃血
• VENOM – 淬毒
• VILLAGE_DEFENDER – 村庄卫士
• WISDOM – 智慧
• WITHER – 凋零

弓类附魔

• BOMBER – 爆裂之矢
• CONFUSING_ARROWS – 惑乱之矢
• DARKNESS_ARROWS – 暗黑之矢
• DRAGONFIRE_ARROWS – 龙涎之矢
• ELECTRIFIED_ARROWS – 唤雷之矢
• ENDER_BOW – 末影之矢
• EXPLOSIVE_ARROWS – 爆破之矢
• FLARE – 飞火之矢
• GHAST – 恶魂之矢
• HOVER – 虚浮之矢
• LINGERING – 滞留
• POISONED_ARROWS – 淬毒之矢
• SNIPER – 乘风快矢
• VAMPIRIC_ARROWS – 歃血之矢
• WITHERED_ARROWS – 凋谢之矢

盔甲附魔

• COLD_STEEL – 霜甲
• DARKNESS_CLOAK – 暗御
• ELEMENTAL_PROTECTION – 元素之御
• FIRE_SHIELD – 炽炎之盾
• FLAME_WALKER – 炽炎行者
• HARDENED – 硬化
• ICE_SHIELD – 霜寒之御
• JUMPING – 灵跃
• KAMIKADZE – 自爆
• NIGHT_VISION – 夜视
• REBOUND – 粘弹
• REGROWTH – 再生
• SATURATION – 饱食
• SPEED – 疾步
• STOPPING_FORCE – 坚挺
• WATER_BREATHING – 水下呼吸

鱼竿附魔

• AUTO_REEL – 自动收杆
• CURSE_OF_DROWNED – 溺尸诅咒
• DOUBLE_CATCH – 二重钓
• RIVER_MASTER – 抛钩大师
• SEASONED_ANGLER – 捕鱼大师
• SURVIVALIST – 烈焰鱼钩

通用附魔

• CURSE_OF_BREAKING – 锈斑诅咒
• CURSE_OF_FRAGILITY – 脆弱诅咒
• CURSE_OF_MEDIOCRITY – 祛魔诅咒
• CURSE_OF_MISFORTUNE – 厄运诅咒
• RESTORE – 传承
• SOULBOUND – 归魂

内部变量（配置文件使用）

附魔变量

• %enchantment_id% – 附魔的唯一标识符
• %enchantment_name% – 附魔的显示名称
• %enchantment_description% – 附魔描述
• %enchantment_level% – 附魔等级
• %enchantment_level_min% – 附魔最小等级
• %enchantment_level_max% – 附魔最大等级
• %enchantment_trigger_chance% – 触发附魔效果的几率
• %enchantment_trigger_interval% – 被动附魔效果的时间间隔
• %enchantment_fit_item_types% – 附魔能够施加的物品类型列表
• %enchantment_charges_max_amount% – 附魔的最大充能数量
• %enchantment_charges_consume_amount% – 单次使用消耗的充能数量
• %enchantment_charges_recharge_amount% – 单个充能物品所回复的充能数量
• %enchantment_charges_fuel_item% – 充能物品的显示名称

PlaceholderAPI 集成

变量格式

将 [enchantment] 替换为附魔标识符（等于附魔的配置文件名称）。

可用变量

1. %excellentenchants_charges_remaining_[slot]_[enchantment]%

   • 物品剩余充能次数
   • [slot] 为装备格子（EquipmentSlot）

2. %excellentenchants_charges_maximum_[enchantment]_[level]%

   • 物品最大充能次数
   • [level] 为附魔等级

附魔属性说明

通用属性

• Max Level: 附魔的最大等级
• Primary Items: 在生存模式下，可以通过附魔台获得该附魔的物品类型
• Secondary Items: 在生存模式下，可以通过附魔书与铁砧获得该附魔的物品类型
• Weight: 附魔出现的相对概率

附魔类型分类

1. 箭类附魔 – 效果只能作用在箭上的附魔
2. 非箭类附魔 – 替换弹射物的附魔（如：爆炸箭矢、末影之矢、恶魂之矢等）

注意事项

1. 命名空间键: 总是使用 EnchantKeys.custom() 方法获取有效的命名空间键
2. 兼容性: API 适配了 Paper Registry API，兼容所有新版 PaperMC
3. 版本: 确保使用最新版本的 ExcellentEnchants API
4. 依赖: 插件需要 PlaceholderAPI 支持全局变量功能

示例代码

获取所有注册的附魔

Set<CustomEnchantment> allEnchants = EnchantRegistry.getRegistered();
for (CustomEnchantment enchant : allEnchants) {
    String id = enchant.getId();
    String name = enchant.getDisplayName();
    int maxLevel = enchant.getMaxLevel();
    // 处理附魔...
}

检查特定附魔是否存在

if (EnchantRegistry.isRegistered(EnchantId.TUNNEL)) {
    CustomEnchantment tunnel = EnchantRegistry.getById(EnchantId.TUNNEL);
    // 使用隧道附魔...
}

通过键获取附魔

NamespacedKey key = EnchantKeys.custom(EnchantId.VEINMINER);
CustomEnchantment veinminer = EnchantRegistry.getByKey(key);
if (veinminer != null) {
    Enchantment bukkitEnchant = veinminer.getBukkitEnchantment();
    // 使用连锁挖掘附魔...
}

开发建议

1. 错误处理: 总是检查 getByKey() 和 getById() 的返回值是否为 null
2. 性能: 缓存频繁使用的附魔对象以提高性能
3. 兼容性: 考虑不同服务器平台（PaperMC/SpigotMC）的差异
4. 版本控制: 注意 API 版本变化，及时更新代码

---

文档最后更新: 2025年11月
来源: ExcellentEnchants 官方文档