LyCharging
LyCharging 是一款装备充能与成长插件。玩家可以通过击杀怪物、击杀玩家、保持在线、消耗自定义物品、消耗原版物品，或将等级插件获得的经验按比例转化为充能经验。
充能物品升级后会刷新指定 lore。达到特定等级时，还可以抽取永久词条、写入 NBT、执行控制台指令、替换物品或删除物品。插件也支持满级经验保留和循环充能，可用于成长型武器、饰品养成、赛季装备与副本培养系统。
插件信息
| 项目 | 内容 |
|---|---|
| 插件名 | LyCharging |
| 当前版本 | 2.1.8 |
| 作者 | Liyuan |
| 主命令 | /lycn |
| 服务端平台 | Bukkit / Spigot 体系服务端 |
| Java 要求 | Minecraft 1.7.10 至 1.16.5 模块使用 Java 8；Minecraft 1.17.1 及以上模块使用 Java 17 |
支持版本
项目内提供了以下 Minecraft 版本的独立 NMS 实现：
| Minecraft 版本 | NMS 版本 |
|---|---|
1.7.10 | v1_7_R4 |
1.8.8 | v1_8_R3 |
1.11.2 | v1_11_R1 |
1.12.2 | v1_12_R1 |
1.13.2 | v1_13_R2 |
1.14.4 | v1_14_R1 |
1.15.2 | v1_15_R1 |
1.16.5 | v1_16_R3 |
1.17.1 | v1_17_R1 |
1.18.2 | v1_18_R2 |
1.19.2 | v1_19_R1 |
1.19.4 | v1_19_R3 |
1.20.1 | v1_20_R1 |
1.20.2 | v1_20_R2 |
1.20.3 | v1_20_R3 |
版本说明
仅建议在表格明确列出的服务端版本上使用。项目没有提供 1.9、1.10、1.20.4 及更高版本的对应 NMS 实现。
依赖与兼容插件
插件本体没有声明必须安装的硬依赖。以下插件在 plugin.yml 中被声明为软依赖，安装后会启用对应功能：
| 插件 | 用途 |
|---|---|
PlaceholderAPI | 解析条件、经验公式、等级 lore、永久词条、NBT 内容和指令中的外部变量。 |
MythicMobs | 监听 MythicMobs 4 或 5 的怪物死亡事件；等级奖励也可替换为 MythicMobs 物品。 |
DragonCore | 读取和写入龙核槽位，并可由 LyCharging 接管龙核槽位点击。 |
LyGalaxyLevel | 将玩家获得的 LyGalaxyLevel 有效经验按配置比例转化为充能经验。 |
LyLevelPlus | 将玩家获得的 LyLevelPlus 经验按配置比例转化为充能经验。 |
代码中还包含以下槽位或物品接口适配。只有实际使用对应配置格式时，才需要安装相关插件：
| 接口 | 支持内容 |
|---|---|
GermPlugin | 萌芽槽位读取与写入接口；当前核心启动流程没有注册萌芽点击消耗物品监听。 |
APInventory | 按背包分页和槽位编号读写物品。 |
LyInventory | 按背包 ID 与类型读写物品。 |
LyInventoryReload | 按背包 ID 与类型读写物品。 |
YeeJewelry | 按背包 ID 与槽位 ID 读写饰品。 |
NeigeItems | 等级奖励可替换为 NeigeItems 物品。 |
SX-Item | 等级奖励包含 SX-Item 物品接口。 |
玩法流程
- 管理员在
plugins/LyCharging/charge下创建充能方案。 - 充能方案通过物品名称、初始 lore、条件和槽位识别目标物品。
- 玩家通过方案允许的经验来源获得充能经验。
- 物品首次获得有效经验后，初始 lore 会被当前等级的充能 lore 替换。
- 当前经验达到升级需求后，物品自动升级，并结转多余经验。
- 达到配置等级时，可生成永久词条、写入 NBT、执行指令或替换物品。
- 开启循环充能后，物品满级且未被替换或删除时，可以重置为 1 级并继续结算剩余经验。
充能等级、当前经验、下一级经验、绑定的充能方案 ID 和循环次数会记录在物品 NBT 中。物品首次匹配方案后会绑定该方案 ID，避免多个同名方案在后续充能时串用配置。
核心功能
| 功能 | 说明 |
|---|---|
| 多种经验来源 | 支持击杀怪物、击杀玩家、在线、自定义名称物品、原版物品、LyLevelPlus 和 LyGalaxyLevel 经验转化。 |
| 分等级经验来源 | gain-exp 可按单个等级或等级区间设置，不同成长阶段可以使用不同的经验来源和数值。 |
| 正负经验 | 已初始化的充能物品可以通过负数经验配置扣除经验和等级；首次初始化只接受正数经验。 |
| 随机经验值 | 经验配置和管理指令支持固定数值或范围数值。 |
| 怪物组 | 可在 怪物组配置.yml 中将多个怪物内部名称归入同一组，也可以使用 * 匹配任意怪物、使用 player 匹配玩家。 |
| 物品匹配 | 支持按显示名模糊匹配或完全匹配，并通过指定初始 lore 确认尚未初始化的物品。 |
| 方案绑定 | 首次充能后在 NBT 中记录充能方案 ID，后续优先按已绑定方案处理。 |
| 条件限制 | 支持必须拥有权限、必须没有权限和 PlaceholderAPI 条件表达式。 |
| lore 黑名单 | 物品包含指定 lore 时，不会被自动经验来源匹配，也不能进入下一轮循环充能。 |
| 槽位限制 | 自动充能只处理方案 slot 中登记的槽位。消耗物品升级不受该列表限制。 |
| 原版槽位 | 支持主手、副手、盔甲槽位和玩家背包编号槽位。 |
| 外部槽位 | 包含 DragonCore、GermPlugin、APInventory、LyInventory、LyInventoryReload 和 YeeJewelry 的槽位接口。 |
| 等级经验公式 | 每级所需经验支持 +、-、*、/、括号、等级变量、循环变量和 PlaceholderAPI 变量。 |
| 动态等级 lore | 升级后自动刷新等级、当前经验、下一级经验、最高等级和循环次数等内容。 |
| lore 数值读取 | 可从物品已有固定 lore 中提取数字，并通过自定义变量参与公式和文本生成。 |
| 经验加成 | 每个充能方案可通过 PlaceholderAPI 或 lore 数值变量计算百分比经验加成，加成经验向下取整。 |
| 自定义消息 | 可全局设置获得经验与升级消息，也可为单个充能方案覆盖消息。 |
| 消息开关 | 每个方案可以关闭获得充能经验消息，升级消息不受该开关影响。 |
| 永久词条 | 达到指定等级时，可按权重抽取 lore，并放在定位 lore 的上一行、下一行、原位替换或直接删除定位行。 |
| 多次词条抽取 | 单个等级支持固定次数或范围次数抽取，并可设置本次多次抽取不重复。 |
| 随机数变量 | 永久 lore 和 NBT 内容支持 {random:最小值-最大值}，生成结果保留两位小数。 |
| NBT 写入 | 抽中永久词条时可以向物品写入一个或多个字符串 NBT 节点。 |
| 等级奖励 | 达到指定等级或等级区间时，可执行控制台指令、替换为插件物品或删除物品。 |
| 满级经验控制 | 可选择满级后将当前经验固定为 0，或继续保留溢出经验。保留值最高为 Java long 上限。 |
| 循环充能 | 满级后可恢复为 1 级继续升级，并记录已完成循环次数和最大循环次数。 |
| 溢出经验结转 | 升级后剩余经验会继续结算后续等级；如果新等级不再支持本次经验来源，则停止本次结算。 |
| DragonCore 槽位保护 | 可接管 DragonCore 槽位的左键、右键和中键操作，降低槽位点击过程中物品状态互相覆盖的风险。 |
| Java API | 提供 tryCharge(Player, ItemStack, long)，可对传入物品尝试增加或扣除充能经验。 |
物品数量限制
自动充能、管理指令和 API 均会跳过数量大于 1 的目标物品。建议所有可充能装备保持不可堆叠状态。
经验来源
| 配置格式 | 触发方式 | 说明 |
|---|---|---|
kill:怪物组:经验 | 击杀怪物 | 怪物内部名称需要存在于对应怪物组中。使用 * 可匹配任意怪物。 |
kill:player:经验 | 击杀玩家 | 击杀任意玩家时触发。 |
online:经验 | 在线计时 | 按 online-gain-exp-interval 设置的秒数周期结算。 |
llexp:比例 | 获得等级经验 | 同时用于 LyLevelPlus 与 LyGalaxyLevel，最终充能经验为原经验乘以配置比例并取整。 |
item:物品名:经验 | 消耗自定义名称物品 | 在玩家背包界面中，用光标上的物品左键点击充能物品，每次消耗一个。 |
mcitem:数字ID:子ID:经验 | 消耗 1.12.2 及以下原版物品 | 使用旧版数字物品 ID 与子 ID 匹配。 |
mcitem:材料枚举名:经验 | 消耗 1.13.2 及以上原版物品 | 使用 Bukkit 材料枚举名匹配，例如 DIAMOND。 |
同一经验来源在不同等级区间可以配置不同数值。经验值为正数时增加经验，为负数时扣除经验；尚未初始化的物品不会通过负数经验完成初始化。
支持槽位
| 槽位格式 | 说明 |
|---|---|
DragonCore#槽位名 | DragonCore 注册槽位。 |
GermPlugin#槽位名 | GermPlugin 槽位标识。 |
APInventory#分页ID#槽位ID | APInventory 指定分页中的槽位，示例配置说明的槽位范围为 0 至 53。 |
LyInventory#背包ID#类型 | LyInventory 指定背包与物品类型。 |
LyInventoryReload#背包ID#类型 | LyInventory 重置版指定背包与物品类型。 |
YeeJewelry#背包ID#槽位ID | YeeJewelry 饰品槽位。 |
Origin#MainHand | 玩家主手。 |
Origin#OffHand | 玩家副手。 |
Origin#Helmet | 头盔槽位。 |
Origin#ChestPlate | 胸甲槽位。 |
Origin#Legging | 护腿槽位。 |
Origin#Boots | 靴子槽位。 |
Minecraft#槽位ID | 玩家背包编号槽位。 |
指令
| 指令 | 说明 |
|---|---|
/lycn | 查看插件提供的管理指令。 |
/lycn reload | 重载主配置、怪物组、全部充能方案和在线经验任务。 |
/lycn give [玩家] [充能ID] [经验] | 给在线玩家指定充能方案所登记槽位中的匹配物品增加经验。 |
/lycn giveslot [玩家] [槽位ID] [经验] | 给在线玩家指定槽位中的匹配物品增加经验。 |
/lycn take [玩家] [充能ID] [经验] | 扣除在线玩家指定充能方案所登记槽位中已初始化物品的经验。 |
/lycn takeslot [玩家] [槽位ID] [经验] | 扣除在线玩家指定槽位中已初始化物品的经验。 |
[经验] 可以填写固定数字，也可以填写范围，例如 10-20。执行范围数值时会随机取得本次经验。
指令权限
项目没有声明独立权限节点。上述指令均通过是否为 OP 判断，只有 OP 可以使用。
重要机制
- 充能方案必须正确设置
max-level、gain-exp、level-exp和level-lore。 - 首次充能要求物品名称匹配，并存在符合
init-lore规则的 lore。 - 物品初始化后，插件使用 NBT 中记录的充能方案 ID、等级和经验继续处理。
- 充能 lore 会附加内部识别字符。不要随意修改
match-key，否则旧物品的充能 lore 可能无法被正确替换。 - 未配置下一级经验时，插件会将物品视为没有可继续升级的等级；只有开启满级经验保留或满足循环充能条件时才能继续接收经验。
- 等级奖励替换或删除物品后，本次升级流程会直接返回新物品，不会继续进入下一轮循环。
- 循环次数会参与后续等级经验、等级 lore、永久词条、NBT、指令和消息变量计算。
- 条件会在物品匹配时频繁检查。大量充能方案同时使用复杂 PlaceholderAPI 条件可能增加服务器负载。
页面导航
| 页面 | 内容 |
|---|---|
| 配置说明 | 主配置、怪物组、充能方案、经验来源、词条和等级奖励配置。 |
| 常见问题 | 物品匹配、槽位、升级、循环、词条和经验来源排查。 |
| 更新日志 | 版本与文档更新记录。 |