魂玉 LySoulJade

MySQL 前置要求

启用 MySQL 存储时，必须安装 LyMySQLCore，并确认它已成功连接数据库。否则本插件的 MySQL 数据读取、保存、同步和玩家界面临时数据恢复不会生效。

LySoulJade 是一个魂玉鉴定与熔铸插件。插件通过可配置的魂玉方案、词条池和两个 GUI，实现未鉴定魂玉鉴定、随机词条生成、词条强度计算、魂玉熔铸、材料消耗、金币消耗、成功后执行指令和高强度词条全服公告。

插件包含以下两个界面：

• 魂玉鉴定：将符合魂玉配置的未鉴定物品放入界面，按配置成功率鉴定并生成随机词条。
• 魂玉熔铸：放入目标魂玉和来源魂玉，从来源魂玉中随机抽取词条，预览保留原词条或替换为新词条。

插件信息

项目	内容
插件名	LySoulJade
插件版本	1.0.1
作者	离渊
主命令	/lsj
Java 兼容版本	Java 8；1.17 及以上 NMS 模块使用 Java 17
支持版本	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、Vault、PlayerPoints、LyMySQLCore

支持版本以项目提供的 NMS 模块和对应 Bukkit、Spigot 或 CraftBukkit API 为准。未列出的服务端版本没有在项目文件中确认。

依赖与存储

软依赖

依赖	用途
PlaceholderAPI	解析界面文本、金币公式和材料数量中的占位符。
Vault	读取玩家金币余额并扣除鉴定或熔铸费用。未接入 Vault 时，界面会显示未接入状态，金币扣除不会执行。
PlayerPoints	在 plugin.yml 中声明为软依赖。当前项目证据未确认具体使用方式。
LyMySQLCore	提供 MySQL 数据库连接。启用 MySQL 存储时必须安装，并且必须成功连接数据库。

存储方式

mysql.enable 为 false 时，玩家的鉴定界面、熔铸界面和熔铸预览数据保存到插件数据目录：

plugins/LySoulJade/data/<玩家 UUID>.yml

玩家数据文件包含以下数据组：

数据组	内容
appraisal-slot-items	鉴定界面槽位中的物品。
smelt-slot-items	熔铸界面槽位中的物品。
smelt-preview-args	熔铸预览使用的变量数据。

mysql.enable 为 true 且 LyMySQLCore 已成功连接数据库时，相关数据保存到 MySQL。修改数据库开关后需要重启服务器。

功能

功能	说明
未鉴定魂玉匹配	根据物品显示名和初始 lore 匹配魂玉方案。
魂玉鉴定	按魂玉配置中的成功率判断是否鉴定成功，并计算鉴定金币。
随机词条	从当前魂玉自己的词条池中抽取指定数量的不同词条。
词条权重	每个词条可以设置独立权重；正常权重随机时，权重小于等于 0 的词条不参与权重计算。
权重兜底随机	当前可用词条的总权重小于等于 0 时，从可用词条中进行普通随机。
词条强度	每条词条生成 1 到 100 的强度，并根据强度计算词条数值。
强度显示	强度可以显示为数字百分比，也可以替换为 strengthen-replace-text 中配置的文本。
强度平均	开启 strength-average-three-enable 后，当前实现会生成两次 1 到 100 的随机值并取平均值。
魂玉熔铸	从来源魂玉中随机提取一条词条，替换目标魂玉中的一条词条。
词条保留	熔铸前可以选择保留目标魂玉的原词条，或使用来源魂玉抽取的新词条。
熔铸次数	支持配置最大熔铸次数；次数写入物品 lore 和 NBT。使用 -1 表示不限制次数。
动态金币	鉴定和熔铸金币支持 PlaceholderAPI 变量、{count} 和四则运算。
动态材料	熔铸材料数量支持 {count} 和四则运算。
成功指令	鉴定成功和熔铸成功后，可以由控制台执行魂玉配置中的指令。
防误熔	lore 中包含指定关键词的物品不能放入熔铸副槽。
全服公告	鉴定或熔铸获得达到指定强度的词条时，可以发送全服公告。
音效反馈	支持配置鉴定成功、鉴定失败、熔铸成功以及取回或上传物品时的音效。
界面数据恢复	玩家重新进入服务器后，可以恢复之前保存的鉴定槽位、熔铸槽位和熔铸预览数据。

指令

主命令：/lsj

指令	说明
/lsj reload	重载插件配置、魂玉配置和界面配置。
/lsj jd	打开魂玉鉴定界面。
/lsj rl	打开魂玉熔铸界面。
/lsj debug	切换 GUI 调试消息。

项目提供的 plugin.yml 未声明独立权限节点。权限名称以实际运行版本为准。

配置文件

文件	作用
config.yml	数据库、消息、强度显示、词条格式、防误熔、公告和音效配置。
souljade/*.yml	魂玉匹配规则、鉴定参数、熔铸参数和词条池配置。
鉴定界面.yml	鉴定界面标题、布局、槽位和按钮配置。文件名不可修改。
熔炼界面.yml	熔铸界面标题、布局、槽位和按钮配置。文件名不可修改。

界面配置使用 layout 字符映射槽位。button 定义业务按钮对应的布局字符，slot 定义布局字符对应的展示物品、名称、lore 和模板。插件固定读取 鉴定界面.yml 和 熔炼界面.yml。

鉴定与熔铸

魂玉匹配

未鉴定魂玉需要同时满足以下条件：

1. 物品显示名命中魂玉配置中的 match-name。
2. 物品 lore 中存在魂玉配置中的 init-lore。
3. 物品没有写入鉴定后的 souljade-data 数据。

鉴定后的物品会写入以下 NBT 数据：

NBT 键	内容
souljade-count	当前熔铸次数。新鉴定魂玉初始为 0。
souljade-data	魂玉方案 ID、词条 ID 和词条强度。

鉴定流程

点击鉴定按钮后，插件按以下规则处理：

• 未放入魂玉时不执行鉴定。
• 未接入 Vault 时不会执行金币扣除。
• 接入 Vault 且金币不足时不会开始鉴定。
• 鉴定失败时发送失败消息并播放失败音效，不生成词条。
• 鉴定成功后，从当前魂玉自己的词条池中抽取配置数量的不同词条。
• 每条词条生成 1 到 100 的强度，并将计算后的 lore 写入物品。
• 鉴定成功后，才会扣除金币、播放成功音效、发送成功消息、执行成功指令和检查全服公告。
• 已经写入鉴定数据的魂玉再次放入鉴定界面时不会重复鉴定，点击按钮会直接取回物品。

熔铸界面槽位

按钮名	默认布局字符	作用
jade-a	A	需要熔铸的目标魂玉。来源魂玉的词条会替换目标魂玉中的一条词条。
jade-b	B	作为词条来源的魂玉。熔铸成功后会被扣除。
keep-result	<	预览并选择保留目标魂玉的原词条。
replace-result	>	预览并选择使用来源魂玉抽取的新词条。
material	X	显示本次熔铸所需材料和玩家当前拥有数量。
button	Y	执行熔铸。

熔铸规则

• 熔铸界面显示的成功率为 100%。
• 实际执行时仍会检查目标魂玉、来源魂玉、材料、金币、熔铸次数和防误熔条件。
• 来源魂玉中的词条会随机抽取一条。
• 目标魂玉中的词条会随机选择一条作为替换目标。
• 熔铸完成后，玩家可以选择保留目标魂玉原词条，或使用来源魂玉抽取的新词条。
• 来源魂玉在熔铸成功后会被扣除。
• 熔铸次数写入目标魂玉的 souljade-count，并按 max-smelet-count 限制次数；配置为 -1 时不限制。
• lore 命中 prevent-mishandling-lore 关键词的物品不能作为 jade-b 放入熔铸副槽。

词条强度与格式

词条 lore 支持区间数值占位符：

{10-20-%.0f}
{1-10-%.1f}

插件会根据词条强度，将区间映射为最终数值，再按照格式化字符串输出。词条模板中的 {strength} 会替换为当前词条的强度显示文本。

未启用强度替换时，强度显示为数字百分比。启用 strengthen-replace-enable 后，插件根据 strengthen-replace-text 的区间配置替换显示内容。

entry-format 用于控制鉴定后词条的整体排版。包含 {entry} 的配置行会为每条词条展开一次；不包含 {entry} 的配置行只输出一次。{count} 和 {count_max} 会替换为当前熔铸次数和最大熔铸次数。

相关页面

页面	内容
配置说明	config.yml、数据库、消息、强度显示、公告和音效配置。
魂玉配置	souljade/*.yml 文件、魂玉字段、词条字段和公式写法。
鉴定与熔铸	鉴定判定、词条生成、强度计算、熔铸流程、材料和费用规则。
变量、API 与机制	配置变量、物品数据、NBT 数据和相关机制说明。
常见问题	依赖、数据库、物品匹配、界面和配置问题。
更新日志	插件和文档更新记录。

项目内置示例

项目提供了以下示例配置文件：

• souljade/示例魂玉.yml
• 鉴定界面.yml
• 熔炼界面.yml

示例魂玉节点包含以下字段：

配置键	作用
match-name	可匹配的物品显示名列表。
init-lore	未鉴定魂玉必须存在的初始 lore。
appraisal-chance	鉴定成功率，示例值使用 0.8 表示 80%。
appraisal-eco	鉴定金币公式。
appraisal-success-commands	鉴定成功后执行的控制台指令列表。
smelet-material	熔铸材料及其数量公式。
smelet-eco	熔铸金币公式。
smelt-success-commands	熔铸成功后执行的控制台指令列表。
max-smelet-count	最大熔铸次数，-1 表示不限制。
spawn-entry-count	鉴定时抽取的词条数量，不能小于 2。
entry	当前魂玉的词条池。

示例中的材料键使用 插件缩写@物品 ID 格式，项目示例列出的插件缩写为 MM、NI、SI 和 ZAP。

魂玉成功指令支持以下变量：

变量	说明
{player}	玩家名。
{item}	物品名。
{souljade}	魂玉 ID。
{count}	当前熔铸次数。
{count_max}	最大熔铸次数。