炼丹 LyAlchemy
LyAlchemy 是一个 Bukkit/Paper 服务端插件，提供丹方探索、丹方熟练度、等待炼制、成品品质、丹药服用和属性增量玩法。
玩家可以查看公开或已经学会的丹方，投入材料进行探索或炼制，等待炼制完成后领取按权重抽取的丹药，再通过右键服用丹药获得配置中的属性增量。
这是服务端插件，不包含客户端 MOD 模块，客户端无需安装 MOD。
插件信息
| 项目 | 内容 |
|---|---|
| 插件名 | LyAlchemy |
| 项目版本 | 1.0.0 |
| 发布类型 | Bukkit/Paper 服务端插件 |
| 服务端 API 声明 | api-version: 1.13 |
| 编译期服务端 API | Paper API 1.16.5 |
| Java 编译目标 | Java 8 |
| 主指令 | /lyld |
| 数据目录 | plugins/LyAlchemy/ |
| 客户端要求 | 不需要安装客户端 MOD |
项目文件只确认了服务端 API 声明、编译期 Paper API 和 Java 编译目标，没有提供完整的精确服务器版本支持列表。实际兼容性需要以发布包说明和服务器测试结果为准。
依赖与兼容组件
| 组件 | 用途与条件 |
|---|---|
PlaceholderAPI | 注册并解析 %lyld_变量名% 变量。不使用变量时可以不安装。 |
MythicMobs、LyItemSave、AzureFlow、NeonFlash、SX-Item、NeigeItems、OriginAttribute | 创建丹方材料和丹药实际物品。材料和成品需要由其中一个可用物品库提供。 |
AttributePlus、AttributeSystem、SX-Attribute | 为服用丹药的玩家提交属性增量。需要在 attribute-plugin 中选择已经安装且可用的属性插件。SX-Attribute 兼容配置可使用 SX-Attribute、SX-Attribute2 或 SX-Attribute3。 |
LyLootsWarehouse、LyWarehouse、SpaceRingPlus、StarStorage | 按 delivery-order 接收炼制产物。未安装、未启用或无法接收时会跳过并继续尝试下一目标。 |
LyMySQLCore | 仅在 mysql.enable: true 时需要。必须安装并成功连接数据库，玩家数据存储才会生效。 |
plugin.yml 还声明了 YeeCore 软依赖，但项目配置没有为它定义具体的 Wiki 功能。
物品库选择规则
丹方材料和丹药实际物品使用 物品库@物品ID 格式；没有填写前缀时使用主配置中的 item-provider。
支持的物品库包括：
MythicMobsLyItemSaveAzureFlowNeonFlashSX-ItemNeigeItemsOriginAttribute
MythicMobs 与 LyItemSave 同时启用时：
MythicMobs@物品ID优先查询 MythicMobs，找不到后回退 LyItemSave。LyItemSave@物品ID优先查询 LyItemSave，找不到后回退 MythicMobs。
只启用其中一个物品库时，两个前缀都可以访问当前可用的物品库。
GUI 槽位、丹方图标和丹药图标不使用物品库，只使用 ItemUtil 解析原版物品 ID，例如 262:0、PAPER:0 和 APPLE:0。不支持 Vanilla@ 前缀。
功能概览
丹方探索
public: true的丹方可以直接查看和炼制。public: false的丹方不会直接显示详情，需要通过探索收录。- 探索只匹配未公开且玩家尚未学会的丹方。
- 探索材料和数量必须完全匹配，忽略材料所在槽位顺序。
- 空探索不会启动冷却，也不会扣除材料。
- 非空探索尝试无论成功或失败都会扣除材料，并立即进入冷却。
- 同时匹配多个丹方时，会从候选丹方中随机收录一个。
- 探索冷却使用主配置
exploration-cooldown的固定秒数，并应用权限时间倍率。
默认资源只有一个公开的 示例丹方，没有 public: false 的隐藏丹方。需要由服主配置隐藏丹方后，才能验证探索成功收录分支。
丹方熟练度与炼制
- 每个丹方独立保存熟练度等级和经验，不存在全局炼丹等级。
need-time.formula根据当前丹方等级计算炼制时间，need-time.minimum-time设置基础最低时间。- 权限时间倍率在最低时间计算后应用，因此最终时间可以低于
minimum-time。 - 每名玩家同时只能拥有一个炼制任务。其他丹方可以查看，但不能同时开始炼制。
- 普通炼制开始时会扣除材料，等待完成后进入待领取状态；玩家需要点击炼制按钮领取奖励。
- 开启循环炼制后，会自动领取当前丹方奖励并继续下一炉，直到材料不足、产物检测失败、奖励检测失败或循环被关闭。
- 关闭炼制界面不会取消当前这一炉，但会停止循环；循环开关只在当前在线会话生效，退出或重新登录后不会恢复。
- OP 开始新炼制任务时可以跳过背包材料检测和扣除，待领取、奖励检测和探索流程不受影响。
成品品质与数量
level-bonus 使用权重抽取成品，不是直接填写百分比。系统会将当前等级所有正权重相加，再用单项权重除以总权重计算实际几率；负权重按 0 处理。
每个成品配置 weight 和 amount：
amount可以是固定正整数，例如1。amount可以是正整数范围，例如1-2，领取时随机发放范围内的数量。- 非法、非正规整数、倒置范围或小于
1的数量按1发放。 product-chances-format可以同时显示成品名称、实际几率和发放数量。
领取前任务会锁定为 CLAIMING 并保存已确定的产物。检测失败时可以恢复待领取；投递结果异常或任务清除失败时会保持领取锁，避免奖励结果不确定时重复发放。残留的 CLAIMING 任务需要管理员核对。
丹药服用与属性
- 玩家通过右键主手物品服用丹药。
- 服用交互冷却为
100毫秒。 - 为兼容 1.7 服务端，旧版本按主手处理；新版本的副手相关读取通过兼容方式处理。
- 丹药必须至少存在一组有效的
attribute范围，才允许服用并显示在丹药界面中。 - 第 N 次服用使用属性配置中匹配 N 的范围，并重新提交全部历史服用增量。
- 玩家数据加载完成后会重新计算并应用累计丹药属性。
- 最大服用次数由
attribute范围决定；最大次数为0时表示无限。 - 丹药实际物品与玩家物品都有真实
displayName时按名称完全匹配；任一方没有显示名称时回退ItemStack.isSimilar。 - GUI 图标、配置显示名称和 Lore 不参与实际物品识别。
- 无属性配置的丹药不会进入服用匹配，也不会显示在丹药界面；已有无属性服用记录同样不显示。
产物投递
delivery-order 按配置顺序尝试以下目标：
inventoryLyLootsWarehouseLyWarehouseSpaceRingPlusStarStorage
空列表或全部目标无效时默认使用玩家背包。所有目标处理后仍有剩余物品，会掉落在玩家当前位置。不支持把 drop 作为配置目标，掉落是剩余物品的自动兜底行为。
GUI 界面
| 文件 | 功能 |
|---|---|
gui/丹方界面.yml | 显示公开或已学会的丹方，支持分页、名称过滤和炼制界面跳转。动态丹方信息包含当前与下一熟练度、经验、炼制时间和成品几率。 |
gui/丹药界面.yml | 显示有服用记录且存在有效属性配置的丹药，展示服用次数和当前累计属性。 |
gui/炼制界面.yml | 显示丹方、材料、炼制状态、领取按钮和循环炼制开关。材料槽为只读展示槽。 |
gui/探索界面.yml | 隐藏未知丹方详情，提供探索材料输入、冷却显示和探索按钮。 |
四个 GUI 会取消原版背包点击和拖拽，只由插件手动处理普通左键和右键业务。
探索界面中，点击玩家底部背包物品会扣除 1 个并放入第一个空的 M 槽；点击已有 M 槽会返还整槽材料；关闭界面时会返还剩余材料。炼制界面的 M 槽仅用于展示丹方材料。
GUI 中的 {attribute}、{product_chances} 等多行占位符会拆成独立 Lore 行，同时兼容实际换行和字面量 \n。炼制和探索界面会定时刷新动态倒计时。玩家数据未加载完成前，四个 GUI、相关指令业务和丹药服用都会被拦截。
指令
| 指令 | 权限或限制 | 说明 |
|---|---|---|
/lyld | 玩家可用 | 查看当前发送者可用的帮助。 |
/lyld recipes [名称过滤] | 玩家可用 | 打开丹方界面。不填写过滤内容时显示全部可展示丹方；填写内容后按丹方显示名称进行不区分大小写的包含匹配，多个参数会合并为空格分隔的文本。 |
/lyld medicines | 玩家可用 | 打开已服用丹药界面。 |
/lyld craft [丹方ID] | 玩家可用 | 不填写丹方 ID 时打开丹方列表；填写丹方 ID 时直接打开指定丹方的炼制界面。 |
/lyld explore | 玩家可用 | 打开丹方探索界面。 |
/lyld reload | 仅 OP | 重载主配置、权限时间规则、丹方、丹药和四个 GUI。 |
/lyld give recipe <玩家> <丹方ID> | 仅 OP | 让在线玩家直接学会指定的未公开丹方。 |
/lyld remove recipe <玩家> <丹方ID> | 仅 OP | 删除在线玩家的未公开丹方学会状态，保留熟练度等级和经验。 |
/lyld give medicine <玩家> <丹药ID> <数量> | 仅 OP | 增加在线玩家的丹药服用次数，受丹药最大次数限制。 |
/lyld remove medicine <玩家> <丹药ID> <数量> | 仅 OP | 扣除在线玩家的丹药服用次数，最低扣到 0。 |
项目没有在 plugin.yml 中注册独立权限节点。重载和管理指令通过 OP 判断；管理指令的目标玩家必须在线且炼丹数据已经加载完成。丹药次数修改后会重新计算累计属性并立即保存玩家数据。公开丹方始终可用，不能通过管理指令删除公开丹方的可用状态。
PlaceholderAPI 变量
安装并启用 PlaceholderAPI 后，插件会注册 lyld 标识符，完整格式为 %lyld_变量名%。动态丹方 ID 和丹药 ID 放在变量末尾，ID 中的下划线无需转义。
| 变量 | 返回内容 |
|---|---|
%lyld_recipe_learned_<丹方ID>% | 玩家是否可以使用该丹方。公开丹方和已探索丹方返回 true，否则返回 false。 |
%lyld_recipe_level_<丹方ID>% | 当前丹方熟练度等级。丹方不存在或玩家未解锁时返回 0。 |
%lyld_recipe_experience_<丹方ID>% | 当前等级经验。丹方不存在或玩家未解锁时返回 0。 |
%lyld_recipe_next_level_<丹方ID>% | 下一熟练度等级。满级时返回当前等级。 |
%lyld_recipe_next_experience_<丹方ID>% | 升到下一等级所需经验。满级时返回 0。 |
%lyld_recipe_max_level_<丹方ID>% | 丹方通过 level-bonus 可实现的最高熟练度等级。 |
%lyld_recipe_time_<丹方ID>% | 当前等级且应用权限倍率后的炼制时间，单位为秒。 |
%lyld_recipe_next_time_<丹方ID>% | 下一等级且应用权限倍率后的炼制时间，单位为秒。满级时返回 0。 |
%lyld_medicine_count_<丹药ID>% | 玩家当前服用该丹药的累计次数。 |
%lyld_known_recipe_count% | 公开或已学会的丹方数量。 |
%lyld_consumed_medicine_count% | 有服用记录的丹药种类数量。 |
%lyld_exploration_cooldown% | 探索冷却剩余时间，单位为秒。 |
%lyld_crafting_status% | 是否存在进行中或待领取的炼制任务，返回 true 或 false。 |
%lyld_crafting_recipe% | 当前炼制任务的丹方 ID，无任务时返回空文本。 |
%lyld_crafting_level% | 当前任务开始时的丹方熟练度等级，无任务时返回 0。 |
%lyld_crafting_remaining% | 当前炼制任务剩余时间，单位为秒。任务为 READY 时返回 0；无任务时也返回 0。 |
%lyld_crafting_time% | 当前炼制任务的总炼制时间，单位为秒，无任务时返回 0。 |
%lyld_crafting_finish_time% | 当前炼制任务完成时间的 Unix 毫秒时间戳，无任务时返回 0。 |
%lyld_crafting_claim_status% | 当前任务状态：CRAFTING、READY、CLAIMING 或无任务时的 NONE。 |
%lyld_crafting_product% | 当前任务已确定的丹药配置 ID；尚未确定或无任务时返回空文本。 |
%lyld_crafting_loop% | 当前任务是否开启循环炼制，无任务时返回 false。 |
除 %lyld_recipe_learned_<丹方ID>% 外，丹方变量在玩家未解锁或目标不存在时返回 0；未知变量不会影响其他 PlaceholderAPI 变量。
配置文件
| 路径 | 内容 |
|---|---|
config.yml | 物品库、产物投递、自动保存、YAML/MySQL 存储、属性插件、探索冷却、权限时间倍率、属性模板、几率格式、GUI 格式、音效和消息。 |
recipe/*.yml | 丹方公开状态、图标、名称、Lore、材料、炼制时间、熟练度经验、升级经验、升级指令、成品权重和数量。 |
item/*.yml | 丹药实际物品、GUI 图标、显示名称、Lore 和服用属性范围。 |
gui/丹方界面.yml | 丹方分页列表和导航按钮。 |
gui/丹药界面.yml | 丹药分页列表和属性展示。 |
gui/炼制界面.yml | 材料展示、炼制状态、领取按钮和循环开关。 |
gui/探索界面.yml | 探索材料槽、冷却信息和探索按钮。 |
config.yml 配置键
| 配置键 | 说明 |
|---|---|
item-provider | 没有显式物品库前缀时使用的默认物品库；留空时默认使用 MythicMobs。 |
delivery-order | 炼制产物投递顺序，只支持 inventory、LyLootsWarehouse、LyWarehouse、SpaceRingPlus 和 StarStorage。 |
loop-save-thread-time | YAML 玩家数据自动保存间隔，单位为秒。0 或负数关闭 YAML 自动保存。 |
mysql.enable | 是否使用 MySQL 存储。只在插件启动时读取，修改后需要重启服务器。 |
mysql.databasename | MySQL 数据库名称。 |
mysql.username | MySQL 用户名。 |
mysql.password | MySQL 密码。 |
mysql.port | MySQL 端口。 |
mysql.ip | MySQL 地址。 |
attribute-plugin | 选择 AttributePlus、AttributeSystem 或 SX-Attribute 属性适配。 |
exploration-cooldown | 每次非空探索尝试使用的固定冷却秒数。 |
permission-time | 按权限缩短炼制时间和探索冷却的倍率列表。多个命中权限只取最小倍率，不叠加。 |
attribute-template | 属性快捷显示模板，属性配置中的 {value} 会替换为实际数值。 |
product-chances-format | {product_chances} 和 {next_product_chances} 的逐行显示格式。支持 {name}、{chance}、{amount}、{min} 和 {max}。 |
gui-format.status | 炼制状态文本，支持 NONE、CRAFTING、READY 和 CLAIMING。 |
gui-format.loop_status | 循环炼制开关文本，支持 ON 和 OFF。 |
gui-format.enough | 材料是否足够的文本，使用 TRUE 和 FALSE。 |
sound | 炼制完成、探索成功、探索失败和列表翻页音效。 |
message | 炼制、探索、熟练度、丹药服用、数据加载和错误提示。 |
permission-time 中的 multiplier: 0.90 表示最终使用基础时间的 90%，也就是缩短 10%。权限倍率会同时影响炼制时间和探索冷却，且缩短结果可以低于丹方的 need-time.minimum-time。
炼制和探索相关音效默认使用 ENTITY_PLAYER_LEVELUP、BLOCK_ANVIL_DESTROY 和 UI_BUTTON_CLICK。在 1.7 服务端中，配置对应音效名需要使用 LEVEL_UP、ANVIL_BREAK 和 CLICK。
熟练度和炼制状态相关消息使用主配置中的大写键，包括 CRAFT_SUCCESS、CRAFT_FAILURE、CRAFT_READY、MATERIALS_INSUFFICIENT、CRAFTING、CRAFT_COOLDOWN、CRAFT_CLAIMING、CRAFT_OTHER_RECIPE、CRAFT_NO_ACTIVE_RECIPE、CRAFT_LOOP_ENABLED、CRAFT_LOOP_DISABLED、CRAFT_LOOP_INTERRUPTED、RECIPE_MAX_LEVEL、MAX_LEVEL、LEVEL_UP、EXPERIENCE_GAIN、NO_AVAILABLE_RESULT、EXPLORATION_SUCCESS、EXPLORATION_FAILURE、EXPLORATION_COOLDOWN、EXPLORATION_MATERIALS_INSUFFICIENT、MEDICINE_CONSUMED、MEDICINE_MAX_COUNT、MEDICINE_CONSUME_FAILURE、ATTRIBUTE_PROVIDER_UNAVAILABLE 和 DATA_LOADING。
满级文本优先使用 message.RECIPE_MAX_LEVEL，缺失时回退 message.MAX_LEVEL。MEDICINE_CONSUMED 和 MEDICINE_MAX_COUNT 支持 {count} 与 {max_count}，无限服用次数的 {max_count} 显示为无限。
丹方配置
丹方文件位于 recipe/ 目录。文件最外层键是丹方 ID，主要字段如下：
| 字段 | 说明 |
|---|---|
icon | 丹方界面和炼制界面的原版 GUI 图标，例如 PAPER:0。 |
name | 丹方显示名称。 |
lore | 丹方显示 Lore。 |
public | 是否公开。公开丹方可直接查看和炼制，非公开丹方需要探索收录。 |
need-item | 丹方材料列表，格式为 物品库@物品ID 数量。 |
need-time.formula | 炼制时间公式，{level} 表示当前丹方熟练度等级。结果单位为秒。 |
need-time.minimum-time | 炼制时间基础最低值，单位为秒。 |
experience-gain | 每次完成炼制获得的随机经验，格式为 最小值-最大值。 |
level-up.experience | 升级所需经验，可按单等级或等级范围填写固定值或包含 {level} 的公式。不需要填写 max 范围。 |
level-up.commands | 熟练度升级时执行的指令，支持 [console]、[op] 和无前缀玩家身份。 |
level-bonus | 按熟练度等级范围配置成品权重和发放数量。 |
level-bonus 的成品配置格式如下：
yaml
level-bonus:
1-9:
示例_中品筑基丹:
weight: '136 + {level}*8'
amount: '1-2'weight 可以填写固定数字或包含 {level} 的公式。系统只累加正权重，全部权重为零时不会生成可用产物。amount 不参与几率计算，只决定领取时的发放数量。
丹方最高熟练度由 level-bonus 可以实现的最终等级决定。使用 10-max 时，当前实现把 10 作为最终可实现等级；level-up.experience 需要覆盖达到最终等级前的升级区间。
打开炼制界面前会校验丹方全部材料和全部等级权重中的成品丹药。物品库缺失、成品配置缺失或物品标识为空时不会打开炼制界面，并会输出具体丹方和物品标识。
丹药配置
丹药文件位于 item/ 目录。主要字段如下：
| 字段 | 说明 |
|---|---|
item | 丹药实际物品，使用 物品库@物品ID 或无前缀物品 ID。 |
icon | 丹药 GUI 图标，只使用原版物品 ID。 |
name | 丹药显示名称。 |
lore | 丹药显示 Lore。 |
attribute | 按服用次数配置属性增量。键可以是单次数或次数范围，例如 1、2-9。 |
丹药至少需要一组有效的 attribute 范围，才能被服用或显示在丹药列表中。属性范围的最大次数决定有限的最大服用次数；没有有限上限时最大次数为 0，表示无限。
GUI 配置
四个 GUI 文件使用 title、layout、button 和 slot 结构：
丹方界面.yml：动态丹方列表使用R，支持当前和下一等级熟练度、经验、时间、几率及翻页。丹药界面.yml：动态丹药列表使用D，支持服用次数和累计属性展示。炼制界面.yml：使用R展示丹方，使用M展示只读材料，使用B处理开始炼制和领取，使用L切换循环炼制。探索界面.yml：使用M作为材料目标槽，使用B尝试探索，显示总冷却和剩余冷却，不显示未知丹方的详细信息。
GUI 槽位、按钮图标和丹方、丹药图标必须使用可解析的原版物品 ID。非法原版材质不会静默替换为石头，对应配置会加载失败。
玩家数据存储
玩家数据包括：
- 已学丹方。
- 各丹方熟练度等级和经验。
- 丹药服用次数。
- 探索冷却截止时间。
- 当前炼制任务、开始等级、完成时间、状态和已确定产物。
循环开关只存在当前在线会话，不写入玩家存档；关闭炼制界面或退出后不会恢复循环。
YAML 模式
当 mysql.enable: false 时，玩家数据保存于：
plugins/LyAlchemy/playerdata/<玩家UUID>.yml
YAML 保存会保留 .bak 备份，并使用临时文件和原子替换方式写入。玩家数据自动保存由 loop-save-thread-time 控制，停服时会执行最终保存。
MySQL 模式
当 mysql.enable: true 时，必须安装并启用 LyMySQLCore，且数据库连接和表初始化成功后玩家数据功能才会生效。连接或初始化失败时不会自动切换到 YAML。
运行时使用 LyAlchemy_player_data 表保存玩家数据，玩家名称作为主键，完整玩家数据文本保存于 data 字段。MySQL 使用玩家名称关联数据，玩家改名后不会自动迁移旧数据。
修改 mysql.enable 后需要重启服务器，重载配置不会在 YAML 和 MySQL 之间切换当前运行模式。
数据未加载完成前，四个 GUI、指令业务和丹药服用都会被拦截。
默认资源
默认资源包含：
recipe/示例丹方.yml：根节点 ID 为示例丹方，显示名称为示例_筑基丹方，公开可用。item/示例丹药.yml：包含示例_残破筑基丹、示例_下品筑基丹、示例_中品筑基丹、示例_上品筑基丹、示例_极品筑基丹和示例_天道筑基丹。- 四个 GUI 配置文件。
示例丹方使用 MythicMobs@筑基灵液 和 MythicMobs@玄黄草，炼制时间公式为 66-{level}*3，最低炼制时间为 30 秒，探索冷却默认是 60 秒。
示例丹方的 level-bonus 覆盖 1 至 10 级。10 级档位中，中品、上品、极品和天道筑基丹的权重分别为 20、60、18 和 2，对应实际几率 20%、60%、18% 和 2%。