插件变量

LySimplePlaceholder 注册 PlaceholderAPI 变量扩展 lsp，用于读取数字或其他 PlaceholderAPI 变量，并将结果格式化为适合显示的数字文本。插件版本为 1.1.0。

使用该变量前，必须安装并启用 PlaceholderAPI。插件仅在检测到 PlaceholderAPI 已启用时注册 lsp 扩展。

变量格式

变量格式	说明
%lsp_数字%	直接处理变量中的数字文本
%lsp_去掉百分号的变量%	读取其他 PlaceholderAPI 变量，再处理返回值

变量请求需要由玩家上下文解析。如果请求没有对应玩家，lsp 变量返回空文本。

直接处理数字

将数字直接写在 lsp 后面：

写法	处理内容
%lsp_100000%	直接处理整数 100000
%lsp_-100000%	处理负数
%lsp_1000000.5%	处理带小数的数字
%lsp_1,000,000%	处理带逗号千分位的数字
%lsp_1e6%	处理科学计数法数字
%lsp_1.5E+6%	处理带正号的科学计数法数字

读取其他变量

使用其他 PlaceholderAPI 变量时，需要去掉原变量两侧的百分号：

写法	读取的原变量
%lsp_ap_damage:min%	%ap_damage:min%
%lsp_player_level%	%player_level%

插件会将 lsp 后面的内容还原为 PlaceholderAPI 变量，再读取该变量的返回值并进行数字处理。

数字识别

lsp 变量支持以下数字格式：

• 正数和负数。
• 整数和小数。
• 使用逗号分隔的千分位数字，例如 1,000,000。
• 科学计数法数字，例如 1e6、1.5E+6、-2.5e-3。

数字处理前会移除合法数字中的逗号。数字必须完整匹配支持的格式，包含其他文本的内容不会被当作单个数字处理。

如果变量返回值为空或无法解析为数字，处理结果为 0。如果 lsp 后面的内容不是有效的 PlaceholderAPI 变量，插件会保留带百分号的原始变量文本。

缩写规则

缩写起始位数由配置项 abbreviation-value 控制，默认值为 4。插件根据数字整数部分的位数选择可用的最大单位；配置为 4 时，五位整数开始进入万级缩写。

数值级别	换算值	缩写单位
10^4	10000	万
10^8	100000000	亿
10^12	1000000000000	兆
10^16	10000000000000000	京
10^20	100000000000000000000	垓
10^24	1000000000000000000000000	秭
10^28	100000000000000000000000000	穰
10^32	1000000000000000000000000000000	沟
10^36	1000000000000000000000000000000000000	涧
10^40	10000000000000000000000000000000000000000	正
10^44	100000000000000000000000000000000000000000000	载
10^48	1000000000000000000000000000000000000000000000000	极
10^52	10000000000000000000000000000000000000000000000000000	恒河沙
10^56	100000000000000000000000000000000000000000000000000000000	阿僧祇
10^60	1000000000000000000000000000000000000000000000000000000000000	那由他
10^64	10000000000000000000000000000000000000000000000000000000000000000	不可思议
10^68	100000000000000000000000000000000000000000000000000000000000000000000	无量
10^72	1000000000000000000000000000000000000000000000000000000000000000000000000	大数

缩写时，插件会将数值除以对应单位的换算值，并在格式化结果后追加单位文本。例如，达到万级的数值会转换为带有 万 的显示文本。

负数同样参与数字识别和格式化。是否进入缩写处理由数字整数部分的位数和可用单位共同决定。

小数格式

变量结果的小数位数由配置项 format 控制。默认配置为：

format: '%.2f'

插件会读取格式中的小数位数，并使用向下取整方式处理显示结果，不会进行四舍五入。

当数值本身是整数时，插件会按整数格式去除无意义的小数部分；其他数值按照配置的小数位数格式化。

可以通过 designated-placeholder-format 为指定的原始变量设置独立的小数格式：

designated-placeholder-format:
  '%ap_damage:min%': '%.0f'

配置后，%lsp_ap_damage:min% 会优先使用 %ap_damage:min% 对应的格式，不使用全局 format。

配置项	作用
format	未单独指定格式时使用的全局小数格式
designated-placeholder-format	为指定的原始 PlaceholderAPI 变量设置独立的小数格式
abbreviation-value	控制数字进入缩写处理的位数

配置格式应使用 %.数字f 形式，例如 %.0f、%.2f。插件根据其中的数字读取小数位数。

变量返回值

情况	返回结果
直接输入有效数字	返回格式化后的数字或缩写文本
原始变量存在且返回有效数字	返回格式化后的数字或缩写文本
原始变量返回空内容	返回 0
原始变量返回无法解析的内容	返回 0
lsp 后的内容不是有效 PlaceholderAPI 变量	返回带百分号的原始变量文本
请求没有玩家上下文	返回空文本

其他文本中的数字替换

除 lsp 变量外，插件还会通过 ProtocolLib 处理部分发往客户端的文本和物品信息。该功能使用全局 format 配置，并只替换达到缩写条件的数字片段：

• 聊天消息：只有消息包含 message-replace-key 中的任意关键词时才会处理。
• 物品描述：根据 item-number-abbreviation 开关处理物品 Lore 中的数字。
• BossBar：根据 bossbar-number-abbreviation 开关和 bossbar-keyword 关键词处理 BossBar 文本。
• 全息文本：根据 hologram-number-abbreviation 开关和 hologram-keyword 关键词处理实体元数据中的名称。

这些功能不是新的 PlaceholderAPI 变量，具体开关、关键词和黑名单配置应以配置文件中的对应配置项为准。

使用限制

lsp 变量用于显示文本，不应作为原始数字参与计算、条件判断或属性计算。

原因是变量返回值可能包含小数格式、万、亿 等单位文本，结果已经不是纯数字。

提示

需要进行价格计算、条件判断或属性计算时，请直接使用原始数字变量，不要使用 %lsp_...% 变量。

配置位置

变量处理相关配置位于：

plugins/LySimplePlaceholder/config.yml

变量相关配置示例：

# 默认小数点后位数
format: '%.2f'

# 指定变量的小数点后位数
designated-placeholder-format:
  '%ap_damage:min%': '%.0f'

# 从什么位数开始缩写
abbreviation-value: 4

修改配置后，使用 /lsp reload 重载配置。插件会重新读取配置，并重新注册相关数据包处理功能。

常见问题

为什么变量没有返回缩写结果？

请确认以下条件：

1. PlaceholderAPI 已安装并启用。
2. 使用的是 lsp 标识符，例如 %lsp_100000%。
3. 读取的原始变量返回的是可识别数字。
4. 数字整数部分的位数已达到 abbreviation-value 设置的缩写条件。

为什么变量返回 0？

原始变量返回空内容、非数字文本或不符合插件支持的数字格式时，处理结果为 0。

为什么直接写变量时保留了百分号？

如果 lsp 后面的内容无法被 PlaceholderAPI 识别为有效变量，插件会返回带百分号的原始文本，而不会将其当作数字处理。

为什么小数没有四舍五入？

插件使用向下取整方式格式化数字。配置为 %.2f 时，会保留两位小数，但不会按四舍五入规则进位。

为什么修改配置后显示没有立即变化？

配置修改后需要执行 /lsp reload。如果修改的是已经发送给客户端的物品缩写内容，部分情况下还需要执行 /lsp update 刷新背包内物品信息。

lsp 变量可以用于计算吗？

不建议。该变量的返回值是用于显示的格式化文本，可能包含缩写单位，不保证是纯数字。