缩写规则

LySimplePlaceholder 用于将数字格式化为带中文单位的文本，也可以通过 PlaceholderAPI 变量、聊天数据包、物品 Lore、BossBar 和实体名称进行数字缩写。

基本信息

项目	内容
插件版本	1.1.0
PlaceholderAPI 变量标识	lsp
主命令	/lsp
可选依赖	PlaceholderAPI、ProtocolLib、MythicMobs
支持版本	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

PlaceholderAPI 和 ProtocolLib 用于对应功能的注册与数据包处理。未安装对应依赖时，相关功能不会生效。

指令

指令	权限要求	作用
/lsp	无	查看当前可用指令提示。
/lsp reload	OP	重新读取配置文件；核心模式下还会重新注册相关数据包监听器。
/lsp update	OP	延迟 1 tick 刷新执行者自己的背包和装备栏物品显示。

/lsp update 只能由玩家执行，不能由控制台执行。该指令主要用于刷新已经发送到客户端的物品显示。

插件没有注册独立的权限节点，管理指令通过 Bukkit 的 OP 状态判断。

数字格式

插件支持普通数字、合法的逗号千分位数字和科学计数法数字。

数字格式	输入示例	是否识别
整数	10000	是
小数	12500.75	是
负数	-10000	是，但不同替换入口的处理存在差异。
逗号千分位	10,000、1,000,000.5	是
科学计数法	1e8、1.25E+12	是
非标准逗号分组	10,00	否
混合文本	金币10000	不能直接作为 %lsp_...% 的数字参数。

数字参数必须完整匹配数字格式。带有额外文字的内容不会被 PlaceholderAPI 数字变量直接识别。

PlaceholderAPI 变量

LySimplePlaceholder 注册的 PlaceholderAPI 标识为 lsp。

使用其他 PlaceholderAPI 变量时，需要去掉原变量首尾的 %，再放入 %lsp_...% 中。

原变量	缩写变量
%ap_damage:min%	%lsp_ap_damage:min%
%player_health%	%lsp_player_health%

也可以直接把数字写入变量：

变量	返回示例
%lsp_10000%	1万
%lsp_100000000%	1亿
%lsp_10,000%	1万
%lsp_1e8%	1亿

使用 %lsp_原变量内容% 时，玩家对象不能为空。插件会先解析内部 PlaceholderAPI 变量，再对返回值进行数字格式化。

如果内部变量不存在，插件会返回重新补全百分号后的原文本。如果内部变量存在，但返回内容不是有效数字，数字转换结果为 0。

提示

缩写变量只适合显示，不适合继续参与数值计算。返回结果可能包含 万、亿 等中文单位，本质上是一段文本。

缩写触发条件

abbreviation-value 控制开始尝试缩写时所需的最小整数位数。

abbreviation-value: 4

插件会先将数值格式化为无小数整数，再检查整数文本长度是否达到 abbreviation-value。数字还必须达到至少 10000，能够匹配到中文单位，才会真正追加单位。

因此，默认值 4 下：

• 1000 不会转换为带单位文本，因为插件没有“千”单位。
• 10000 可以转换为 1万。
• 第一个实际产生中文单位的正整数是 10000。

如果将 abbreviation-value 设置为 8，插件会从八位整数开始尝试缩写，但八位数仍可能使用 万。单位由数字本身的数量级决定，不会因为配置值较大而强制使用 亿。

文本扫描功能还会检查当前数字是否确实存在可用中文单位。未达到单位条件的数字会保持原文本。

单位顺序

插件会选择当前正数能够使用的最大单位，再用原数值除以该单位的换算值。

数值起点	单位	换算值
10^4	万	10000
10^8	亿	100000000
10^12	兆	1.0E12
10^16	京	1.0E16
10^20	垓	1.0E20
10^24	秭	1.0E24
10^28	穰	1.0E28
10^32	沟	1.0E32
10^36	涧	1.0E36
10^40	正	1.0E40
10^44	载	1.0E44
10^48	极	1.0E48
10^52	恒河沙	1.0E52
10^56	阿僧祇	1.0E56
10^60	那由他	1.0E60
10^64	不可思议	1.0E64
10^68	无量	1.0E68
10^72	大数	1.0E72

超过 10^72 的数值仍使用“大数”作为最大单位，不会继续生成新的单位名称。

小数格式

默认小数格式由 format 控制：

format: '%.2f'

指定 PlaceholderAPI 变量可以单独设置格式：

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

格式	效果
%.0f	不保留小数。
%.1f	最多保留一位小数。
%.2f	最多保留两位小数。

格式必须符合 %.数字f。无法识别的格式会按两位小数处理。

插件使用不补零的小数格式，因此 1.50 会显示为 1.5，不会强制显示为 1.50。需要舍弃的小数会按向零方向截断，而不是四舍五入。

未进入中文单位缩写的整数会按无小数格式返回。未进入缩写的小数使用当前配置的格式处理。

负数处理

当前版本对负数的两种入口处理不同：

入口	处理规则
直接使用 %lsp_-10000%	能识别为数字，但不会选择中文大数单位，通常返回格式化后的原负数。
聊天、物品 Lore、BossBar、实体名称扫描	扫描器匹配数字部分，前面的负号会保留，因此文本中的 -10000 可显示为 -1万。

需要统一显示效果时，应避免直接把负数作为 %lsp_...% 的纯数字参数。

文本扫描规则

聊天、物品 Lore、BossBar 和实体名称功能会扫描文本中的数字片段。每个数字片段都会独立检查，不满足缩写条件的内容保持不变。

扫描时支持：

• 普通整数和小数。
• 合法的逗号千分位数字。
• 带 e 或 E 的科学计数法。
• 一段文本中出现的多个数字。

插件会在提取数字前排除以下内容，避免将格式代码中的数字误认为需要缩写的数值：

• 传统颜色代码和格式代码。
• 六位十六进制颜色文本。
• 八位十六进制颜色文本。
• 聊天扫描中的 Unicode 转义文本。

自动替换范围

自动替换功能通过 ProtocolLib 数据包处理。各范围拥有独立的启用条件和关键词规则。

范围	触发条件	处理内容
聊天消息	消息包含 message-replace-key 中任意关键词。	扫描聊天数据包中的数字片段。
物品描述	item-number-abbreviation 为 true，且物品未命中整体黑名单。	只处理物品 Lore，不修改物品显示名称。
BossBar	bossbar-number-abbreviation 为 true，且文本包含 bossbar-keyword 中任意关键词。	处理 BossBar 文本中的数字片段。
全息与实体名称	hologram-number-abbreviation 为 true，且名称包含 hologram-keyword 中任意关键词。	处理实体元数据中的名称文本。实际实现使用 1.12.2 的实体元数据类型。

聊天消息

聊天消息只有在包含 message-replace-key 中至少一个字符串时，才会执行数字扫描。此范围处理服务器发送的聊天数据包，包括插件发送的消息。

关键词使用包含匹配，不要求整条消息与关键词完全相同。配置中的 & 颜色符号会转换为内部颜色占位符后参与匹配。

默认配置如下：

message-replace-key:
  - '系统'

物品 Lore

物品缩写只处理发送给客户端的物品 Lore。物品显示名称本身不会被缩写，但会参与整体黑名单检查。

规则	效果
物品显示名称包含 item-abbreviation-black-list 内容	整个物品不处理。
任意 Lore 行包含 item-abbreviation-black-list 内容	整个物品不处理。
某一 Lore 行包含 item-line-black-list 内容	仅跳过该行，其他 Lore 行仍可处理。

黑名单中的 & 颜色代码会转换为 § 后再进行包含匹配。

插件会克隆发给客户端的物品并修改显示内容，不直接修改服务器中的原物品。缩写前的名称和 Lore 会写入物品 NBT，用于玩家在创造模式提交该物品时恢复原始内容，并在恢复后移除临时 NBT。

物品恢复依赖当前 Minecraft 版本对应的 NMS NBT 实现。项目内提供了以下版本的 NBT 适配：

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。

关闭物品缩写后，已经发送到客户端的显示内容不会立即自动恢复。配置文件说明要求通过重启服务器恢复；必要时也可以由管理员玩家执行 /lsp update，延迟 1 tick 刷新自己的背包和装备栏物品。

BossBar

BossBar 数字缩写默认关闭：

bossbar-number-abbreviation: false

开启后，只有 BossBar 数据包中的 JSON 文本包含 bossbar-keyword 中任意关键词时，才会执行数字缩写。关键词使用包含匹配。

默认关键词如下：

bossbar-keyword:
  - '生命'

全息与实体名称

该功能读取实体元数据中的名称字段，可处理非发包全息及怪物名称。只有名称包含 hologram-keyword 中任意关键词时才会处理。

该功能默认关闭：

hologram-number-abbreviation: false

默认关键词如下：

hologram-keyword:
  - '魔王'

项目实现直接使用 1.12.2 的 NMS 实体元数据类型，因此全息与实体名称缩写不能仅根据其他版本存在 NBT 适配，就视为跨版本全息支持。

配置项

配置文件为插件目录下的 config.yml。

数字格式配置

配置键	类型	默认值	说明
format	字符串	'%.2f'	默认小数格式。
designated-placeholder-format	对象	包含 %ap_damage:min% 的 %.0f 示例	为指定 PlaceholderAPI 变量单独设置小数格式。
abbreviation-value	数字	4	开始尝试缩写所需的最小整数位数。

示例：

format: '%.2f'
designated-placeholder-format:
  '%ap_damage:min%': '%.0f'
abbreviation-value: 4

聊天配置

配置键	类型	默认值	说明
message-replace-key	字符串列表	['系统']	聊天消息包含列表中任意字符串时，才执行数字扫描。

示例：

message-replace-key:
  - '系统'

物品配置

配置键	类型	默认值	说明
item-number-abbreviation	布尔值	true	是否缩写发送给客户端的物品 Lore。
item-abbreviation-black-list	字符串列表	['玩家属性']	物品名称或任意 Lore 行包含列表内容时，整个物品不处理。
item-line-black-list	字符串列表	['QQ群:']	Lore 某一行包含列表内容时，仅跳过该行。

示例：

item-number-abbreviation: true
item-abbreviation-black-list:
  - '玩家属性'
item-line-black-list:
  - 'QQ群:'

BossBar 配置

配置键	类型	默认值	说明
bossbar-number-abbreviation	布尔值	false	是否启用 BossBar 数字缩写。
bossbar-keyword	字符串列表	['生命']	BossBar 文本包含列表中任意字符串时才处理。

示例：

bossbar-number-abbreviation: false
bossbar-keyword:
  - '生命'

全息配置

配置键	类型	默认值	说明
hologram-number-abbreviation	布尔值	false	是否启用全息与实体名称数字缩写。
hologram-keyword	字符串列表	['魔王']	实体名称包含列表中任意字符串时才处理。

示例：

hologram-number-abbreviation: false
hologram-keyword:
  - '魔王'

重载影响

执行 /lsp reload 后，插件会重新读取 config.yml，更新 abbreviation-value，并重新注册聊天、物品、BossBar 和全息数据包监听器。

重载时会先移除插件原有的数据包监听器，再按照当前配置重新注册：

• 聊天监听始终注册。
• item-number-abbreviation 为 true 时注册物品监听和创造模式物品恢复监听。
• bossbar-number-abbreviation 为 true 时注册 BossBar 监听。
• hologram-number-abbreviation 为 true 时注册全息与实体名称监听。

物品缩写具有客户端显示状态。仅重载配置不保证已经显示为缩写的物品立即恢复，特别是关闭 item-number-abbreviation 时，应按配置说明重启服务器，或由管理员玩家执行 /lsp update 刷新自身背包和装备栏显示。

依赖与兼容性

依赖	用途
PlaceholderAPI	注册 %lsp_...% 变量，并解析被嵌套的 PlaceholderAPI 变量。
ProtocolLib	处理聊天、物品、BossBar 和实体元数据数据包。
MythicMobs	项目声明为软依赖，配置示例中的 BossBar 缩写可用于兼容相关血量显示场景。

项目没有使用 MySQL 存储，也不需要安装 LyMySQLCore。

如果服务器版本不在项目提供的 NMS 适配列表中，物品 NBT 处理和相关物品恢复功能可能无法初始化。