常见问题

物品没有开始充能怎么办？

按以下顺序检查：

1. 物品必须拥有自定义显示名和 lore。
2. 物品数量必须为 1，数量大于 1 的物品会被跳过。
3. match-name 必须命中物品显示名。
4. 尚未初始化的物品必须存在 init-lore 指定的 lore。
5. 玩家必须满足 condition 中的全部条件。
6. 物品所在位置必须与 slot 配置完全一致。
7. 当前等级必须存在对应的 gain-exp 经验来源。
8. 物品不能命中 lore-black-list。

match-name 和 init-lore 支持以下匹配方式：

写法	作用
contain@文本	包含指定文本时匹配
equals@文本	与指定文本完全一致时匹配

颜色代码可以使用 &。匹配格式必须包含 @，不要省略匹配方式。

match-name:
  - 'contain@充能道具'
  - 'equals@&6高级充能道具'

init-lore: 'equals@&7充能进度未开启'

物品名称正确，为什么仍然无法匹配？

名称匹配只是第一步。插件还会检查：

• condition 中的权限和 PlaceholderAPI 条件。
• 未初始化物品的 init-lore。
• 已初始化物品记录的充能配置 ID。
• lore-black-list。
• 物品数量是否大于 1。

物品第一次开始充能后，会记录对应的充能配置 ID。此后即使存在名称相同的其他充能方案，也只会继续使用最初绑定的方案，避免不同方案之间串用数据。

如果已经充能的物品突然失效，检查是否修改了充能配置最外层的 ID。重命名配置 ID 后，旧物品记录的 ID 不会自动改变。

配置了 slot，为什么还是找不到物品？

槽位字符串需要与插件支持的格式完全一致。

槽位类型	格式
DragonCore	DragonCore#槽位名
GermPlugin	GermPlugin#槽位名
APInventory	APInventory#分页ID#槽位ID
LyInventory	LyInventory#背包ID#类型
LyInventoryReload	LyInventoryReload#背包ID#类型
YeeJewelry	YeeJewelry#背包ID#槽位ID
原版主手	Origin#MainHand
原版副手	Origin#OffHand
头盔	Origin#Helmet
胸甲	Origin#ChestPlate
护腿	Origin#Legging
靴子	Origin#Boots
原版背包槽位	Minecraft#槽位ID

需要注意：

• 槽位功能依赖对应背包或槽位插件实际存在。
• slot 为空时，击杀、在线、等级经验转化和管理指令没有可遍历的目标位置。
• 使用充能材料直接点击物品时，不受 slot 限制，但只处理玩家原版合成界面或创造模式物品栏中的点击。
• DragonCore 槽位可由 dragoncore-slot-control 接管点击逻辑，默认开启。

为什么一组堆叠物品无法充能？

插件会跳过数量大于 1 的目标充能物品。请先把目标物品拆分为单个物品，再进行充能。

使用充能材料点击目标物品时，作为材料的光标物品可以堆叠。成功结算后，每次消耗光标上的一个材料。

击杀怪物没有获得经验怎么办？

先确认当前等级的 gain-exp 中存在正确的击杀规则：

gain-exp:
  1-10:
    - 'kill:怪物组1:1'

然后检查 怪物组配置.yml 中是否存在对应怪物组，并且列表中的怪物标识与事件取得的怪物标识一致。

当前可确认的击杀来源包括：

来源	匹配方式
MythicMobs 4	MythicMobs 内部怪物 ID
MythicMobs 5	MythicMobs 内部怪物 ID
MOD_CUSTOM 实体	实体自定义名称
CUSTOMNPCS_CUSTOMNPC 实体	实体名称
玩家	使用固定参数 player

MythicMobs 配置应填写内部怪物 ID，不是物品名称或经过颜色处理的显示名。MythicMobs 击杀者可以是玩家，也可以是拥有玩家主人的狼；部分没有直接击杀者的事件会尝试使用怪物的新目标玩家。

普通原版怪物没有对应的通用 EntityDeathEvent 充能处理逻辑，不能仅凭原版实体枚举名认定其会触发。

击杀玩家如何增加经验？

怪物组参数直接填写 player：

gain-exp:
  1-10:
    - 'kill:player:5'

只有玩家被另一名玩家击杀时才会触发。player 不需要写入 怪物组配置.yml。

如何让任意已处理的怪物都提供经验？

击杀规则的怪物组位置可以填写 *：

gain-exp:
  1-10:
    - 'kill:*:1'

该写法只会匹配插件已经监听并取得怪物标识的击杀事件，不会额外为未监听的原版实体类型注册处理逻辑。

在线充能没有生效怎么办？

检查以下内容：

• 当前等级的 gain-exp 是否包含 online:经验。
• slot 是否包含目标物品实际所在位置。
• 物品名称、初始 lore 和条件是否匹配。
• online-gain-exp-interval 是否设置为合理的正数。
• 目标物品是否只有一个。
• 满级物品是否允许保留经验或继续循环。

gain-exp:
  1-10:
    - 'online:1'

online-gain-exp-interval 的单位为秒。默认值为 3，任务首次执行也会等待一个完整间隔。

在线充能太频繁或服务器压力较大怎么办？

增大 online-gain-exp-interval。数值越大，遍历在线玩家和充能槽位的频率越低。

同时建议：

• 减少不必要的在线充能方案。
• 减少每个方案配置的槽位数量。
• 避免在大量充能物品上配置复杂的 PlaceholderAPI 条件。
• 保持 sync-online-task-enable: true。

sync-online-task-enable 为 true 时，在线充能在同步任务中运行。设置为 false 后会改用异步任务，但配置注释明确提示可能存在刷物品风险，不建议仅为降低主线程消耗而关闭。

使用充能材料点击物品没有反应怎么办？

材料充能只处理以下操作：

• 玩家打开的是原版合成界面或创造模式物品栏。
• 使用鼠标左键，将光标物品与目标物品交换。
• 目标充能物品数量不大于 1。
• 光标上存在有效材料。
• 当前等级存在对应的 item 或 mcitem 规则。

有自定义显示名的材料使用 item 匹配，没有自定义显示名的原版材料使用 mcitem 匹配。

服务端版本	mcitem 格式
1.12.2 及以下	mcitem:数字ID:子ID:经验
1.13.2 及以上	mcitem:材料枚举名:经验

gain-exp:
  1-10:
    - 'item:&6充能核心:1'
    - 'mcitem:160:0:1'
    - 'mcitem:DIAMOND:1'

不要在同一服务端版本中混用不对应的原版材料格式。成功充能后会消耗一个光标材料。

为什么 GermPlugin 槽位内不能使用材料点击充能？

项目中存在 GermPlugin 点击充能监听实现，但插件启动流程没有注册该监听。当前能够确认的材料点击充能入口是原版合成界面和创造模式物品栏。

GermPlugin 槽位仍存在读取和写入实现，可用于通过已配置的槽位处理其他经验来源，但不能据此认定 GermPlugin GUI 点击材料功能已经启用。

LyLevelPlus 或 LyGalaxyLevel 经验没有转化怎么办？

两个等级插件都使用 llexp:倍率 规则。只有服务器安装并启用对应插件时，LyCharging 才会注册相应事件监听。

gain-exp:
  1-10:
    - 'llexp:0.01'

实际充能经验按“原等级经验 × 配置倍率”计算，并格式化为整数。倍率太小时，结果可能四舍五入为 0，此时不会开始充能或更新经验。

还需要确认目标物品位于 slot 配置的槽位中，并满足名称、初始 lore、条件和黑名单检查。

等级 lore 没有刷新怎么办？

检查 level-lore 是否覆盖物品可能到达的全部等级。若最大等级为 10，通常需要提供 1-10 的 lore 配置。

max-level: 10

level-lore:
  1-10:
    - '&7当前等级: &e{level} &7/ {level_max}'
    - '&7当前经验: &e{exp_now} &7/ &e{exp_next}'

如果当前等级找不到对应 lore，插件会停止本次物品更新，并向玩家提示该充能道具缺少对应等级的 lore 配置。

level-lore 可以按单级或范围配置。重叠范围的读取顺序不适合作为稳定优先级规则，建议避免为同一等级配置多个范围。

为什么满级时 {exp_next} 显示 Max？

插件会读取下一等级所需经验。当 level-exp 找不到下一等级配置时，结果为 0，level-lore 中的 {exp_next} 会显示为 Max。

这通常表示物品已经到达最高等级。是否还能继续保存经验或进入下一轮充能，由以下配置决定：

• charge-exp-overflow-enable
• charge-loop-enable
• charge-loop-max
• lore-black-list
• level-reward 是否替换或删除物品

满级后的经验为什么变成了 0？

charge-exp-overflow-enable 默认为 false。关闭时，物品达到最高等级后，当前经验会保存为 0。

charge-exp-overflow-enable: false

设置为 true 后，满级物品可以继续保留经验，最多保存到 Java long 上限 9223372036854775807。未达到最高等级时，多余经验仍会正常结转到后续等级，不受此开关影响。

循环充能为什么没有开始？

循环充能需要同时满足以下条件：

条件	要求
charge-loop-enable	必须为 true
charge-loop-max	必须大于 0
当前等级	已达到 max-level
已完成循环次数	小于 charge-loop-max
lore 黑名单	不能命中 lore-black-list
等级奖励	物品没有被 level-reward 替换或删除

charge-loop-enable: true
charge-loop-max: 3

进入下一轮时，物品会恢复为 1 级，并继续结算已有的多余经验。达到最大循环次数后，不再重置等级；剩余经验是否保留由 charge-exp-overflow-enable 决定。

开启循环后，为什么到达满级仍然没有重置？

常见原因包括：

• charge-loop-max 为 0 或负数。
• 已完成循环次数已经达到上限。
• 物品命中了 lore-black-list。
• 当前等级的 level-reward.replace 不是 none，物品已被替换或删除。
• 本次经验没有达到继续升级或循环的条件。

level-reward 会在升级到指定等级时执行。只要奖励替换了物品，当前充能流程就会直接返回替换结果，不会再进入循环。

循环充能次数在哪里保存？

循环次数保存在物品 NBT 中，不依赖玩家数据文件或数据库。可用于配置文本的变量为：

变量	说明
{loop_count}	物品已经完成的循环次数
{loop_count_max}	当前充能方案允许的最大循环次数

这些变量可用于等级经验公式、等级 lore、永久词条、永久词条 NBT、永久词条指令和充能消息等支持位置。

经验已经足够，为什么没有继续连升？

插件支持溢出经验连续升级，但每次升级后会检查新等级是否仍配置了本次经验来源。

例如，本次经验来自 online，升级后的等级范围中没有 online 规则时，插件会停止本次溢出结算，并将当前经验重置为 0。请确认 gain-exp 的等级范围覆盖所有希望由该来源连续升级的等级。

为什么配置负数经验后会降低等级？

已经初始化的物品取得负数经验时，击杀、在线、等级经验转化和材料来源会调用耗能逻辑。经验不足时会向前回退等级，最低回到 1 级、0 经验。

尚未初始化的物品只会在经验大于 0 时开始充能，负数经验不会初始化物品。

管理指令中的 take 和 takeslot 也会直接扣除已有充能经验。

永久词条没有生成怎么办？

永久词条只会在物品实际升级到指定等级时触发。直接处于该等级、重载配置或扣除经验后回到该等级，都不会自动重新生成。

检查以下内容：

• permanent-lore 下的等级节点是否等于本次升级后的等级。
• generate-lore 是否存在权重大于 0 的词条。
• spawn-count 是否大于 0。
• locate-lore 是否与物品原 lore 一致。
• lore-put 是否填写支持的操作。
• 物品是否被同等级的 level-reward 替换。

如果没有找到 locate-lore，插件会以 lore 最后位置作为默认定位位置，而不是取消生成。

lore-put 应该怎么填写？

值	效果
next	插入到定位 lore 的下一行
last	插入到定位 lore 的上一行
replace	首次生成时替换定位 lore；同次后续生成追加在其后
remove	删除定位 lore，不抽取和生成随机词条

remove 会直接删除定位行。若没有找到定位 lore，当前实现会使用默认定位位置，因此应先确保 locate-lore 准确，避免删除错误行。

spawn-count 为什么没有生成配置的次数？

spawn-count 支持固定值和整数范围：

spawn-count: '2'

spawn-count: '1-3'

加载配置时，插件会把生成次数上限限制为 generate-lore 中的词条数量。超出时会在控制台输出警告，并将范围缩小。

无效或空白配置会回退为 1。负数会按 0 处理。

spawn-repeat 到底代表什么？

当前实现中，spawn-repeat: true 表示同一次等级触发的多次抽取不允许重复抽到同一个词条 ID。

spawn-count: '2'
spawn-repeat: true

启用后，如果可用的正权重词条已经抽完，剩余抽取会提前结束。为了避免实际生成次数不足，应保证随机池中有足够多的有效词条。

该设置只限制同一次等级触发中的多次抽取，不会阻止物品在后续循环再次到达该等级时抽到相同词条。

永久词条权重如何计算？

只有权重大于 0 的词条会进入随机池。每个词条的概率为自身权重除以全部可用词条的总权重。

例如三个词条权重均为 20，每个词条的抽取概率相同。配置 lore: 'none' 的词条可以作为不生成 lore 的空结果，但仍会参与权重抽取。

永久词条中的随机数为什么每次不同？

永久词条的 lore 和 NBT 支持 {random:最小值-最大值}。插件会在指定范围内生成随机小数，并保留两位小数。

generate-lore:
  随机属性:
    weight: 10
    lore:
      - '&7随机数值: {random:1-10}'

如果最小值大于最大值，插件会交换两端数值后再生成。该随机变量不用于普通 level-lore。

永久词条指令没有执行怎么办？

永久词条指令由控制台执行。检查：

• 抽中的词条是否配置了 command。
• 该词条权重是否大于 0。
• 指令是否省略了开头的 /。
• PlaceholderAPI 变量解析后是否仍是有效指令。
• 物品是否真的在本次操作中升级到了对应等级。

可使用的内部替换包括 {item}、{level}、{lore}、{loop_count} 和 {loop_count_max}。其中 {lore} 会被替换为本次生成 lore 列表的字符串形式。

等级奖励没有执行或物品没有替换怎么办？

level-reward 只会在实际升级到对应等级时执行。等级键支持单个等级和范围。

replace 值	效果
none	不替换物品
null	删除物品
MythicMobs#物品ID	替换为 MythicMobs 物品
NeigeItems#物品ID	替换为 NeigeItems 物品
SX-Item#物品ID	替换为 SX-Item 物品

对应物品插件必须存在，并且物品 ID 必须有效。奖励指令由控制台执行，并会先解析 PlaceholderAPI 变量。

如果物品在满级奖励中被替换或删除，循环充能不会继续处理原物品。

condition 配置后所有物品都失效怎么办？

condition 中的每一项都必须通过，任意一项失败都会导致该充能方案不匹配。

支持的条件类型包括：

类型	说明
permission:{权限}	玩家必须拥有指定权限
nopermission:{权限}	玩家必须没有指定权限
papi:{表达式}	PlaceholderAPI 变量表达式必须成立

papi 表达式支持 >=、>、==、!=、<、<=，也支持使用 && 和 || 组合判断。字符串比较时，两侧字符串需要使用单引号或双引号包裹。

condition:
  - 'permission:{充能.权限}'
  - 'papi:{%player_level% >= 10}'
  - "papi:{'%player_name%' != '测试玩家'}"

复杂条件会在物品匹配时频繁解析。充能方案和槽位较多时，不建议大量使用复杂 PlaceholderAPI 表达式。

PlaceholderAPI 变量没有解析怎么办？

plugin.yml 将 PlaceholderAPI 声明为软依赖，但条件、等级经验公式、等级 lore、永久词条、奖励指令和经验加成等功能会直接调用 PlaceholderAPI。

需要使用这些功能时，应确保：

• PlaceholderAPI 已安装并成功启用。
• 对应变量扩展已经安装。
• 变量在当前玩家上下文中能返回有效内容。
• 返回值符合所在配置项需要的类型。

数值公式中出现无法计算的文字时，可能导致公式异常。

经验加成变量没有效果怎么办？

exp-addition-placeholder 会先解析 PlaceholderAPI 和 {v.变量ID}，然后作为数学公式计算。计算结果中的每 1 点代表 1% 额外经验。

例如结果为 25，额外经验为基础经验的 25%。额外经验会格式化为整数，因此基础经验或加成比例过小时，最终可能为 0。

检查以下内容：

• 表达式最终只能包含可计算的数字和 +、-、*、/、括号。
• 不要在结果中保留 %、颜色代码或说明文字。
• PlaceholderAPI 变量不能为空。
• {v.变量ID} 必须已经在 lore-get-value 中定义。

解析异常时，控制台会输出“充能插件经验加成变量异常”。

lore-get-value 为什么总是使用默认值？

lore-formula 必须包含 <value>，其余文本需要与物品 lore 中的实际文本一致。

lore-get-value:
  个体值:
    default-value: 1
    lore-formula: '&7充能个体值: <value>'

插件会查找 <value> 左右两侧的固定文本，并把中间内容解析为数字。以下情况会使用 default-value：

• 没有找到对应 lore。
• 固定文本不一致。
• 中间内容不是有效数字。
• 颜色字符或额外文本导致匹配失败。

读取结果可通过 {v.个体值} 使用。变量替换时通常格式化为两位小数。

lore-black-list 没有阻止物品充能怎么办？

当前实现对黑名单执行的是 lore 文本包含判断，不会解析 contain@ 或 equals@ 前缀。黑名单内容会先把 & 转换为颜色字符，然后直接检查物品 lore 是否包含整段配置文本。

因此建议直接填写需要阻止的实际 lore 文本：

lore-black-list:
  - '&7此物品无法被充能'

不要写成 equals@&7此物品无法被充能，除非物品 lore 本身确实包含 equals@ 这段文字。

命中黑名单后，击杀、在线、等级经验转化、材料点击和循环充能都会受到阻止。

自定义充能消息没有生效怎么办？

每个充能方案可以使用自己的 message 覆盖 config.yml 中的全局消息。只有方案内不存在对应消息键时，才会使用全局消息。

消息键	触发时机
CHARGE_GET_EXP	取得充能经验时
CHARGE_LEVEL_UP	升级时

取得经验消息支持 {item}、{exp}、{extra_exp}、{loop_count} 和 {loop_count_max}。升级消息支持 {item}、{level}、{loop_count} 和 {loop_count_max}。

send-charge-exp-message: false 只会关闭取得经验消息，不会关闭升级消息。

修改 match-key 后 lore 重复或无法更新怎么办？

插件会在动态等级 lore 后附加 match-key，后续更新时依靠该标记找到并移除旧的等级 lore。

默认值为：

match-key: '§l§y§c§n'

已经生成充能 lore 后再修改 match-key，插件可能无法识别旧标记，导致旧 lore 残留或新增重复 lore。除非确认与其他系统冲突，否则不要修改该配置。

修改公式符号后计算失败怎么办？

calculate-key-left 和 calculate-key-right 用于标记 lore 与永久词条中的公式区域，默认分别为 < 和 >。

calculate-key-left: '<'
calculate-key-right: '>'

左右符号必须成对出现。公式支持整数、小数、括号和 +、-、*、/。格式部分写在 ~ 后，例如：

<0.01*{level}~%.1f>

尖括号公式写入 Markdown 文档时必须放在行内代码或代码块中，实际 YAML 配置中可以直接使用。

管理指令没有权限怎么办？

当前管理指令没有独立权限节点，只检查执行者是否为服务器管理员，也就是 isOp()。

可确认的指令包括：

指令	作用
/lycn reload	重载插件配置
/lycn give 玩家 充能ID 经验	为指定玩家对应充能方案的槽位物品增加经验
/lycn giveslot 玩家 槽位ID 经验	为指定玩家的指定槽位物品增加经验
/lycn take 玩家 充能ID 经验	扣除指定充能方案物品的经验
/lycn takeslot 玩家 槽位ID 经验	扣除指定槽位物品的经验

目标玩家必须在线。give 和 take 使用的是充能配置最外层 ID，不是配置文件名。

经验参数支持固定数字或 最小值-最大值 的随机范围。使用范围时应填写非负数字，避免把负号误判为范围分隔符。

/lycn give 执行后没有任何提示，也没有充能怎么办？

该指令在正常执行后不会向命令发送者返回“充能成功”消息。需要检查实际目标物品是否发生变化。

没有变化时，通常是以下原因：

• 玩家不在线。
• 充能 ID 不存在。
• 对应方案的 slot 为空或填写错误。
• 槽位中的物品名称不匹配。
• 玩家不满足 condition。
• 未初始化物品缺少 init-lore。
• 目标物品数量大于 1。

giveslot 还要求指定槽位必须出现在某个充能方案的 slot 列表中。

重载后示例配置为什么恢复了？

每次重载时，插件都会覆盖保存 charge/示例充能道具.yml。该文件只用于展示配置格式，不适合直接保存正式修改。

需要创建正式方案时，请复制示例文件并改为其他文件名，再修改复制后的文件。插件会递归读取 plugins/LyCharging/charge 目录及其子目录中的全部 .yml 文件。

支持哪些 Minecraft 版本？

项目中存在以下明确的 NMS 实现：

• 1.7.10
• 1.8.8
• 1.11.2
• 1.12.2
• 1.13.2
• 1.14.4
• 1.15.2
• 1.16.5
• 1.17.1
• 1.18.2
• 1.19.2
• 1.19.4
• 1.20.1
• 1.20.2
• 1.20.3

版本判断使用服务端 Bukkit 版本字符串的开头进行精确匹配。没有对应实现的版本会导致 NBT API 初始化失败，物品等级、经验、配置 ID 和循环次数等数据无法正常读写。

为什么换到相近的小版本后插件无法工作？

NMS 实现按具体服务端版本加载。例如 1.20.3 有对应实现，但不能据此认定 1.20.4 也受支持。

启动时检查控制台中的 NBT API 初始化信息。如果出现“初始化API失败”，应确认服务端版本是否在明确支持列表中。