常见问题
插件启动后没有任何映射属性
按以下顺序检查：
- 确认插件已经完成验证并正常启动。核心功能会在验证通过后初始化。
- 检查
attribute-plugin是否与服务器实际使用的属性插件一致。值为0时不会向任何属性插件写入属性。 - 检查对应属性插件是否已经安装并成功启用。
- 检查检测节点是否已被加载。插件会读取
config.yml和extra目录内所有以.yml结尾的文件。 - 检查检测节点中的
condition、槽位格式和属性格式。 - 执行
/lmr reload重新载入配置。
attribute-plugin 支持的编号以配置文件注释为准：
| 值 | 属性插件 |
|---|---|
1 | AttributePlus 2 |
2 | SX-Attribute 2.0 |
3 | SX-Attribute 3.0 |
4 | DZ |
5 | ItemLoreOrigin |
6 | AttributePlus 3 |
7 | LyAttribute |
8 | AttributeSystem |
项目代码中没有发现编号 4 对应的属性写入逻辑。将 attribute-plugin 设置为 4 时，映射结果可能不会实际写入属性插件。
检测条件已经满足，但属性没有生效
同一个检测节点中的 condition 需要全部通过，才会添加该节点的属性。重点检查以下内容：
| 检测格式 | 检查内容 |
|---|---|
name:{文本} | 物品名称是否包含指定文本 |
equalsName:{文本} | 物品名称是否与指定文本完全一致 |
lore:{文本} | 任意一行 Lore 是否包含指定文本 |
equalsLore:{文本} | 任意一行 Lore 是否与指定文本完全一致 |
permission:{权限} | 玩家是否拥有指定权限 |
nopermission:{权限} | 玩家是否没有指定权限 |
papi:{表达式} | PlaceholderAPI 替换后的表达式是否成立 |
suit:{套装文本} | %lsr_show% 的结果是否包含指定文本 |
名称和 Lore 条件支持使用 & 颜色代码。插件检测时会将其转换为 Minecraft 颜色符号。
如果节点写了 check-slot，会优先使用该节点自己的槽位列表；只有未配置或列表为空时，才会使用全局 plugin-slot。
没有配置条件时会发生什么
condition 不存在或为空时，检测会直接视为通过。节点仍会按照 check-event 的刷新方式计算属性。
如果不希望节点无条件生效，请至少配置一个有效条件。
修改配置后没有生效
使用管理员身份执行：
text
/lmr reload重载会重新读取 config.yml，并递归读取 plugins/LyMappingReload/extra 目录内的所有 .yml 文件。映射检测和属性包数据会先清空，再根据当前文件重新注册。
重载配置不会保留已被配置删除的检测定义。多个文件中使用相同检测 ID 或属性包 ID 时，后加载的数据可能覆盖先加载的数据，因此所有 ID 应保持唯一。
extra 目录中的配置没有加载
检查以下项目：
- 文件扩展名必须是
.yml，大小写不敏感。 - 文件必须位于
plugins/LyMappingReload/extra或其子目录中。 - 文件需要同时包含可读取的
check和attribute-group配置节。当前加载逻辑会分别读取这两个配置节。 - YAML 缩进必须正确，列表项前需要使用
-。 - 修改后需要执行
/lmr reload。
槽位中的物品一直检测不到
先检查槽位字符串的段数和名称。插件根据 # 拆分槽位：
| 槽位来源 | 格式 |
|---|---|
| 原版背包槽位 | Minecraft#槽位编号 |
| 龙之核心槽位 | DragonCore#槽位名 |
| GermPlugin 槽位 | GermPlugin#槽位名 |
| APInventory 槽位 | APInventory#分页ID#槽位编号 |
| LyInventory 槽位 | LyInventory#背包ID#槽位类型 |
| LyInventoryReload 槽位 | LyInventoryReload#背包ID#槽位类型 |
| YeeJewelry 槽位 | YeeJewelry#背包ID#槽位ID |
| 原版主手 | Origin#MainHand |
| 原版副手 | Origin#OffHand |
| 原版头盔 | Origin#Helmet |
| 原版胸甲 | Origin#ChestPlate |
| 原版护腿 | Origin#Legging |
| 原版靴子 | Origin#Boots |
使用第三方背包槽位时，对应插件必须已经安装并可正常提供物品数据。槽位编号还必须在对应背包的有效范围内。
原版主手或副手槽位报错
Origin#MainHand、Origin#OffHand 使用了新版 Bukkit 的主副手接口。项目同时包含 1.7.10 支持代码，但旧版本服务端没有副手机制，相关槽位和 swap_hand 检测不适用于 1.7.10。
旧版本服务器应避免配置副手槽位和主副手交换事件。
关闭背包或切换物品后没有立即刷新
检查检测节点的 check-event：
| 值 | 触发时机 |
|---|---|
second | 每秒检测 |
close_inventory | 玩家关闭背包时检测 |
held_item | 玩家切换快捷栏槽位时检测 |
swap_hand | 玩家交换主手和副手物品时检测 |
删除 check-event 或将其配置为空时，该节点会由每秒检测任务处理。
held_item 只有在新旧快捷栏槽位不同时才会执行对应的事件检测。swap_hand 依赖服务端提供主副手交换事件，不适用于没有副手机制的版本。
每秒检测时出现短暂属性丢失或波动
second-update-type-async: true 会让每秒计算任务在异步线程运行，以降低主线程压力。部分属性插件或物品槽位接口不适合异步访问，可能出现属性短暂丢失、恢复延迟或读取结果波动。
可以改为：
yaml
second-update-type-async: false修改后执行 /lmr reload。关闭异步检测后，计算会在主线程执行，稳定性通常更高，但大量检测节点可能增加主线程负担。
属性刷新后触发了物品切换相关逻辑
每秒检测完成并且实际向属性插件写入了新属性时，插件会模拟触发一次玩家当前快捷栏槽位到当前槽位的 PlayerItemHeldEvent，用于通知其他插件刷新相关数据。
这个模拟事件的新旧槽位相同。LyMappingReload 自己的 held_item 监听会忽略这种事件，但其他监听该事件的插件仍可能执行自己的逻辑。
属性重复叠加或叠加层数不正确
max-stack-layers 限制单个检测节点最多添加多少层属性，默认值为 1。
物品名称和 Lore 条件会统计匹配数量。多个槽位或多行 Lore 同时命中时，可能增加计算出的层数，最终层数不会超过 max-stack-layers。
如果只希望属性最多添加一次，请设置：
yaml
max-stack-layers: 1同时避免在同一个物品的多行 Lore 中重复出现用于检测的相同文本。
PlaceholderAPI 条件始终不成立
papi:{...} 会先通过 PlaceholderAPI 替换变量，再计算表达式。请确认：
- PlaceholderAPI 已安装并成功启用。
- 表达式使用的变量扩展已经安装。
- 变量能够为当前玩家返回有效内容。
- 数值比较的两侧是合法数字或四则运算公式。
- 字符串相等或不等比较时，字符串使用成对的单引号或双引号。
支持的逻辑和比较运算符包括：
| 类型 | 运算符 |
|---|---|
| 或 | ` |
| 与 | && |
| 大于、大于等于 | >、>= |
| 小于、小于等于 | <、<= |
| 等于、不等于 | ==、!= |
数值公式支持 +、-、*、/。非法数值公式会在控制台输出“非法公式”。
eval:{...} 没有生成属性
检查公式是否符合以下要求：
- 公式只能使用数字、PlaceholderAPI 变量、括号和
+、-、*、/。 - PlaceholderAPI 变量替换后必须形成可计算的表达式。
- 上限分隔符必须与
eval-max-tag一致，默认是:。 eval:{公式:上限}只能包含一个用于分隔上限的标记。
公式计算出现异常时，该条属性会被跳过，不会加入最终属性列表。
公式结果为什么没有小数
value-number 控制公式结果格式：
| 配置 | 结果 |
|---|---|
true | 转换为整数，小数部分直接舍去 |
false | 保留两位小数 |
例如公式结果为 12.75 时，开启后得到 12，关闭后得到 12.75。
公式上限没有生效
默认写法为：
text
eval:{公式:上限}如果修改了 eval-max-tag，公式也必须使用新的分隔符。上限只会限制超过上限的结果，不会限制低于上限的结果。
例如：
yaml
eval-max-tag: ':'对应公式：
text
攻击力: eval:{%player_level% * 2:100}Lore 取值一直是 0
确认 lore-get-placeholder 的文本可以匹配物品 Lore，并且 <value> 所在位置确实是纯数值。
yaml
lore-get-placeholder:
等级点: '获得 <value>x玩家等级点攻击力'对应 Lore 中位于“获得 ”和“x玩家等级点攻击力”之间的内容必须能够直接转换为数字。无法转换的内容会被忽略；所有槽位都没有取得有效数字时，该变量会被设置为 0。
属性公式中的引用格式是 <v.变量名>。变量名必须与 lore-get-placeholder 下的节点名完全一致：
yaml
attribute:
- '攻击力: eval:{<v.等级点> * 2}'Lore 中有多行或多个物品匹配时如何取值
插件会扫描当前检测使用的所有槽位，并累计所有成功提取出的数值。
例如两个槽位分别取得 5 和 8，则 <v.变量名> 的结果为 13.0。如果同一个物品有多行 Lore 符合相同模板，也会累计这些数值。
如需只读取一个数值，请缩小 check-slot 范围，并确保模板只会匹配一行 Lore。
Lore 模板以 <value> 结尾时能否读取
可以。模板中 <value> 右侧没有文本时，插件会读取左侧文本之后直到该行 Lore 末尾的内容。
yaml
lore-get-placeholder:
数值: '攻击力：<value>'Lore 末尾不能附带无法转换为数字的字符，否则该行会被忽略。
变量显示为空
PlaceholderAPI 变量的属性行数从 1 开始。以下情况会返回空文本：
- 检测 ID 或属性包 ID 不存在。
- 行数小于等于
0。 - 行数超过该节点的属性行数。
- 请求变量时没有玩家对象。
检测属性变量格式为 %lmr_check-检测ID:行数%，属性包变量格式为 %lmr_group-属性包ID:行数%。
变量返回的是经过公式计算后的完整属性行，不只是数值。
PlaceholderAPI 未安装时会发生什么
插件仅在检测到 PlaceholderAPI 已启用时注册 %lmr_...% 变量扩展。
同时，papi:{...} 条件和 eval:{...} 中的 PlaceholderAPI 变量也依赖 PlaceholderAPI。配置使用了这些功能时，应安装 PlaceholderAPI 以及对应变量扩展。
药水效果报错或没有生效
药水格式必须包含药水类型、等级和持续时间：
text
药水类型-等级-持续时间例如：
yaml
potion:
- 'SPEED-1-2'检查以下项目：
- 药水类型必须是当前服务端版本可识别的 Bukkit 药水效果名称。
- 三个字段必须使用
-分隔。 - 等级和持续时间必须填写整数。
- 等级从
1开始填写。 - 检测条件必须成立。
- 对应检测事件必须实际执行。
未知药水类型会在控制台输出 lmr检测到未知的药水报错。不同 Minecraft 版本可用的药水名称可能不同，应以当前服务端支持的 Bukkit 名称为准。
药水效果会按照叠加层数重复添加吗
不会。max-stack-layers 只控制属性列表的叠加次数，药水效果不会按层数重复添加。
药水效果会在检测节点通过时刷新。如果玩家已经拥有同类效果，插件会根据当前效果等级决定是否移除并重新应用。
NBT 属性没有读取到
get-nbt-attribute 只读取 plugin-slot 指定物品中的 NBT 字符串值，并将读取结果作为属性行加入最终属性列表。
项目只为以下服务端版本提供了 NBT 实现：
- Minecraft 1.7.10，对应
v1_7_R4。 - Minecraft 1.12.2，对应
v1_12_R1。
其他版本启动时会提示当前游戏版本不支持 NBT 检测。此时应删除或留空 get-nbt-attribute，不要依赖该功能。
此外，当前读取逻辑针对单行字符串类型 NBT。NBT 键不存在、值不是字符串属性行或槽位没有物品时，都不会产生属性。
NBT 路径写成 a.b.c 为什么读取不到
get-nbt-attribute 调用的是顶层 NBT 字符串读取方法，代码不会按 . 逐层进入复合标签。因此，虽然默认配置注释给出了 a.b.c 形式，实际属性读取仅能确认支持顶层字符串键。
如果需要读取 NBT 属性，请优先使用物品根 NBT 下的字符串键，并在目标服务端版本上验证结果。
属性包添加后没有效果
检查以下内容：
- 属性包 ID 是否存在于
attribute-group中。 - 目标玩家是否在线。单个玩家必须在线才能通过命令添加。
attribute-plugin是否正确。- 属性包的
attribute是否能正常计算。 - 插件是否已经完成初始化。
添加命令为：
text
/lmr add 玩家 属性包ID为所有在线玩家添加时，玩家位置使用 *：
text
/lmr add * 属性包ID重复添加同一个属性包会覆盖该玩家原有的同 ID 属性包，并重新计算结束时间。
属性包时间结束后仍显示属性
属性包状态每秒检查一次，过期数据会在监听任务中移除。实际属性还需要等待下一次属性计算和刷新，因此可能存在短暂延迟。
如果长时间没有移除，请检查：
- 玩家是否在线。
- 属性插件是否正常接受刷新。
- 是否又执行了添加同 ID 属性包的命令。
- 是否有同名映射检测产生了相似属性。
玩家离线后属性包会永久保存吗
不会。属性包数据只保存在内存中，没有数据库或本地持久化文件。
代码会在玩家离线一段时间后清理其属性包数据。服务器重启或插件重新加载后，也不应将属性包视为永久保存的数据。属性包适合临时属性效果，不适合作为永久玩家数据存储。
属性包启用或结束消息没有颜色
enable-message 和 disable-message 支持 & 颜色代码，发送前会转换为 Minecraft 颜色符号。
如果不需要消息，可以删除对应配置项。未配置时不会发送消息。
ItemLoreOrigin 属性刷新不及时
当 attribute-plugin 设置为 5 时，插件会通过 ItemLoreOrigin 的虚拟物品 Lore 写入属性。刷新间隔由 ilo-update-task 控制，单位为 tick，20 tick 约为 1 秒。
yaml
ilo-update-task: 20间隔过大时，属性变化会延迟；间隔过小会增加刷新频率。ItemLoreOrigin 还必须已经安装并成功启用，否则对应属性写入功能不会初始化。
玩家退出后重新进入，属性没有立即恢复
玩家加入后，插件会延迟 20 tick 执行一次相关刷新。加入后的短时间内可能暂时看不到属性。
加入刷新主要处理配置了 close_inventory 的检测节点和当前内存中的属性包。由 second 处理的节点会等待每秒检测任务重新计算。
配置中的属性修改后仍显示旧结果
插件会记录上次实际写入属性插件的属性快照。只有当前计算结果发生变化时，才会再次写入属性插件。
执行 /lmr reload 后，如果新旧最终计算结果完全相同，不会产生额外刷新。若结果确实不同但仍显示旧值，请检查属性插件本身是否正确覆盖同一来源 LyMappingReload 的旧属性。
控制台出现未知药水错误后插件停止刷新
先删除或修正对应检测节点中的错误 potion。药水配置需要直接拆分并转换等级、持续时间，字段缺失或数字格式错误可能影响该次检测任务。
建议每条药水配置都严格使用：
yaml
potion:
- 'SPEED-1-2'不要省略等级或持续时间，也不要在数字位置填写单位。
重载命令或属性包命令没有反应
/lmr reload、/lmr add 玩家 属性包ID 和无参数帮助信息都要求命令发送者是服务器管理员，即 isOp() 返回 true。
项目证据中没有定义独立权限节点。非管理员执行时不会收到权限不足提示，也不会执行对应操作。
控制台可以执行重载和为在线玩家添加属性包；指定单个玩家时，该玩家必须在线。