常见问题
插件主要做什么？
LySimplePlaceholder 会识别文本中的数字，并按照配置自动格式化或缩写，例如将较大的数字显示为带有“万”“亿”等单位的文本。
插件支持以下处理场景：
- PlaceholderAPI 变量返回值的数字格式化与缩写。
- 聊天消息中的数字缩写。
- 发往客户端的物品描述数字缩写。
- BossBar 文本中的数字缩写。
- 指定关键词的非发包全息文本缩写。
插件通过 ProtocolLib 监听和修改相关数据包。聊天、物品、BossBar 和全息等数据包处理功能需要服务器能够正常使用 ProtocolLib。
为什么 %lsp_变量% 没有缩写？
先确认以下内容：
- 已安装并启用 PlaceholderAPI。
- 原变量能够返回有效数字。
- 原变量不是普通文本、空值或带单位文本。
- 数值达到了
abbreviation-value和缩写单位的判断条件。
用法是将原变量去掉两侧的百分号，再放入 lsp 变量中。例如原变量为 %ap_damage:min%，应使用：
text
%lsp_ap_damage:min%该变量只能用于显示，不能用于计算。插件返回的是格式化后的文本，而不是可继续参与计算的数字。
如果变量本身返回带逗号的数字或科学计数法数字，插件可以识别这类数字；但变量最终必须仍然是合法的数字文本。
为什么 PlaceholderAPI 变量返回了原样文本？
lsp 变量需要先让 PlaceholderAPI 解析内部变量。如果内部变量无法解析，或者返回内容不是插件支持的数字格式，插件不会得到可处理的数字。
另外，PlaceholderAPI 扩展注册时要求服务器中存在 PlaceholderAPI。没有启用 PlaceholderAPI 时，lsp 变量不会正常提供。
为什么数字没有显示为“万”或“亿”？
检查 abbreviation-value 配置。
默认值为 4，表示从整数位数达到四位时开始进入大数字格式处理。插件支持的缩写单位按数值大小包括：
- 万
- 亿
- 兆
- 京
- 垓
- 秭
- 穰
- 沟
- 涧
- 正
- 载
- 极
- 恒河沙
- 阿僧祇
- 那由他
- 不可思议
- 无量
- 大数
同时，具体数值还必须能够匹配到对应的缩写单位。例如没有达到“万”的数值不会显示为“万”。
为什么小数位数不符合预期？
默认小数格式由 format 控制：
yaml
format: '%.2f'如果某个变量需要单独设置小数位数，可以在 designated-placeholder-format 中配置原始变量和格式：
yaml
designated-placeholder-format:
'%ap_damage:min%': '%.0f'指定变量时，键必须使用原始变量的完整形式，包括两侧的百分号。%lsp_ap_damage:min% 只是显示时使用的外层变量，配置键仍然是 %ap_damage:min%。
插件格式化数字时使用截断方式处理小数，不是四舍五入。例如保留两位小数时，多余的小数位会被直接截去。
为什么聊天里的数字没有变化？
聊天消息不会无条件进行缩写。插件会先检查消息是否包含 message-replace-key 中的任意关键词。
默认配置如下：
yaml
message-replace-key:
- '系统'因此，默认只有包含“系统”的聊天消息才会进入数字替换流程。需要处理其他消息时，应将对应关键词加入该列表。
关键词支持配置中的颜色代码写法，插件会将 & 颜色代码转换后再进行匹配。
聊天消息中的所有数字都会被替换吗？
只有满足缩写条件的数字片段才会被替换。插件会识别文本中的普通数字、带逗号的千分位数字和科学计数法数字，并跳过不满足缩写条件的数字。
文本中的传统颜色代码、十六进制颜色代码和聊天中的 Unicode 转义格式不会被当成数字内容的一部分。
为什么物品描述没有缩写？
检查以下配置：
yaml
item-number-abbreviation: true还需要确认：
- 物品确实包含物品元数据或描述。
- 物品描述中的数字达到了缩写条件。
- 物品名称和描述没有命中
item-abbreviation-black-list。 - 对应描述行没有命中
item-line-black-list。
该功能修改的是发往客户端的物品显示内容，不是服务器内部保存的原始物品文本。
为什么某个物品完全没有缩写？
如果物品名称或任意一行描述包含 item-abbreviation-black-list 中的内容，整个物品都会跳过缩写。
默认配置为：
yaml
item-abbreviation-black-list:
- '玩家属性'该配置适合排除不希望被处理的菜单按钮或特殊物品。
为什么物品描述只有部分行没有缩写？
如果某一行描述包含 item-line-black-list 中的任意内容，该行不会进行数字缩写，其他行仍然可以继续处理。
默认配置为：
yaml
item-line-black-list:
- 'QQ群:'与 item-abbreviation-black-list 不同，item-line-black-list 只跳过匹配的描述行，不会跳过整个物品。
修改物品缩写开关后为什么没有恢复？
配置注释明确说明，关闭 item-number-abbreviation 后需要重启服务器。已经发给客户端的缩写物品不会仅靠修改配置立即恢复。
如果物品显示仍未恢复，可以按以下顺序处理：
- 重启服务器。
- 让玩家重新进入服务器。
- 由管理员执行
/lsp update，延迟一个 tick 刷新玩家背包中的物品显示。
/lsp update 的执行逻辑要求发送者是玩家，并且要求发送者拥有管理员权限。
/lsp update 有什么作用？
/lsp update 会延迟一个 tick，重新设置玩家背包和装备栏中的物品，用于刷新客户端显示的物品信息。
该命令主要用于物品缩写显示没有及时恢复或没有及时刷新的情况。命令只能由管理员玩家执行，控制台不能使用该功能。
/lsp reload 重载哪些内容？
/lsp reload 会重新读取插件配置，并重新注册数据包监听功能。因此，修改数字格式、关键词、黑名单和功能开关后，应使用该命令让配置重新生效。
该命令需要管理员权限。
为什么执行 /lsp reload 没有反应？
检查以下内容：
- 执行者是否拥有管理员权限。
- 命令是否写成了
/lsp reload。 - 配置文件中的 YAML 缩进和引号是否正确。
- 修改后的配置键是否属于插件实际读取的配置项。
插件命令注册名为 lsp。未提供参数时，插件会显示可用的重载提示；核心模块还会显示物品刷新提示。
BossBar 或全息没有缩写？
先确认对应开关已经开启，并检查文本是否包含配置的关键词。
BossBar 配置示例：
yaml
bossbar-number-abbreviation: true
bossbar-keyword:
- '生命'全息配置示例：
yaml
hologram-number-abbreviation: true
hologram-keyword:
- '魔王'BossBar 只有包含 bossbar-keyword 中任意关键词的文本才会处理。全息只有包含 hologram-keyword 中任意关键词的实体名称才会处理。
全息缩写支持哪些版本？
项目代码中的全息处理使用 1.12 的实体数据结构。配置注释也明确说明，全息功能仅支持 1.12，并且只能修改非发包的全息。
其他版本不应依赖该功能。
为什么开启了全息缩写仍然无效？
全息功能有以下限制：
hologram-number-abbreviation必须为true。- 全息文本需要包含
hologram-keyword中的关键词。 - 该功能只处理实体元数据中的名称。
- 只支持配置说明中的
1.12环境。 - 只能修改非发包的全息。
如果全息插件通过自己的数据包直接发送文本，LySimplePlaceholder 无法按该功能进行修改。
物品缩写会不会修改服务器中的原始物品？
插件处理的是发往客户端的物品副本。缩写前的物品名称和描述会保存到该显示副本的 NBT 中，用于后续恢复原始内容。
在创造模式下，玩家提交物品时，插件会尝试还原这些原始名称和描述，并移除用于保存原始内容的 NBT 数据。
因此，物品显示被缩写不等于服务器中的原始物品文本已经永久改写。
为什么物品恢复功能没有生效？
物品恢复依赖当前 Minecraft 版本对应的 NMS 实现。如果插件启动时没有成功初始化对应版本的 NBT 工具，物品缩写和恢复相关逻辑可能无法正常工作。
项目中提供了以下版本实现：
1.7.101.8.81.11.21.12.21.13.21.14.41.15.21.16.51.17.11.18.21.19.21.19.41.20.11.20.21.20.3
如果服务器版本不在上述实现范围内，项目证据中没有对应的版本适配实现。
为什么插件启动后功能没有生效？
插件启动时会根据服务器 Bukkit 版本选择对应的 NMS 实现，并注册 ProtocolLib 数据包监听。如果版本识别失败或 NMS 初始化失败，控制台会记录初始化失败信息。
优先检查：
- 服务器版本是否属于项目已提供的版本实现。
- ProtocolLib 是否已安装并正常启用。
- 插件是否能够正常加载配置。
- 控制台是否出现 NMS 初始化失败信息。
PlaceholderAPI、ProtocolLib 和 MythicMobs 都是必须的吗？
项目的 plugin.yml 将以下插件声明为软依赖：
| 插件 | 作用 |
|---|---|
| PlaceholderAPI | 提供 %lsp_变量% 形式的变量解析基础。 |
| ProtocolLib | 提供聊天、物品、BossBar 和全息等数据包监听能力。 |
| MythicMobs | 项目包含 MythicMobs 相关编译引用。 |
其中，PlaceholderAPI 变量功能需要 PlaceholderAPI，数据包替换功能需要 ProtocolLib。项目证据没有表明普通数字格式化必须安装 MythicMobs。
为什么 %lsp_变量% 不能用于计算？
%lsp_变量% 返回的是格式化后的字符串，可能包含小数格式或“万”“亿”等中文单位。因此它只能用于显示，不能作为原始数字再次参与数学计算。
需要计算时，应使用原始变量或其他能够返回数字的变量；需要显示时，再使用 lsp 变量进行格式化。
修改配置后需要重启服务器吗？
普通配置修改可以使用 /lsp reload 重新读取配置。
但 item-number-abbreviation 的配置注释明确要求关闭该功能时重启服务器，因为已经发给客户端的缩写物品不会自动恢复。遇到物品显示残留时，还可以配合重新进服或 /lsp update 刷新。
配置中的颜色代码如何处理？
物品黑名单、物品行黑名单和全息关键词会将配置中的 & 颜色代码转换为 Minecraft 使用的颜色代码后再匹配。
聊天关键词也会兼容配置中的 & 颜色代码。关键词匹配仍然要求消息实际包含对应文本。
为什么数字缩写后仍然显示两位小数？
如果没有为变量单独配置格式，插件会使用 format 的值。默认值为：
yaml
format: '%.2f'如果希望不显示小数，可以将默认格式设置为 %.0f，或者为指定变量增加单独的格式配置。
需要注意，整数值在部分处理路径中会自动使用零位小数格式；带有小数的数值则会按照默认格式或指定格式处理。
配置文件中没有某个键怎么办？
插件会对部分列表配置使用空列表作为后备值，但核心缩写阈值和默认数字格式来自配置文件。建议保留插件生成的完整 config.yml，只修改项目中已经提供的配置键。
项目证据中确认的主要配置键如下：
| 配置键 | 作用 |
|---|---|
format | 默认数字格式。 |
designated-placeholder-format | 指定原始变量的数字格式。 |
abbreviation-value | 数字进入大数字格式处理的位数阈值。 |
message-replace-key | 聊天消息替换关键词。 |
item-number-abbreviation | 物品数字缩写开关。 |
item-abbreviation-black-list | 物品级黑名单。 |
item-line-black-list | 物品描述行黑名单。 |
bossbar-number-abbreviation | BossBar 数字缩写开关。 |
bossbar-keyword | BossBar 替换关键词。 |
hologram-number-abbreviation | 全息数字缩写开关。 |
hologram-keyword | 全息替换关键词。 |
为什么包含关键词但仍然没有替换？
关键词只是进入替换流程的条件，文本中的数字仍然必须满足插件的数字识别和缩写判断条件。
同时检查以下情况：
- 数字是否实际存在于发送给客户端的文本中。
- 数字是否已经带有不支持的单位或其他文字。
- 功能开关是否已经开启。
- 当前功能是否受到版本或数据包类型限制。
为什么部分龙核界面中的物品无法缩写？
配置注释明确说明，物品数字缩写在部分龙核界面下可能无法使用。该功能依赖服务器发出的物品数据包；如果界面没有通过插件能够监听和修改的物品数据包发送显示内容，插件就无法处理。
如何确认重载是否成功？
执行 /lsp reload 后，管理员会收到“重载成功”提示。插件重载时还会根据配置重新注册聊天、物品、BossBar 和全息相关的数据包监听。
如果某项功能仍未生效，应继续检查对应开关、关键词、ProtocolLib 状态和服务器版本，而不是只重复执行重载命令。