丹方配置

丹方文件位于 plugins/LyAlchemy/recipe/。每个 YAML 文件的最外层键都是丹方 ID。丹方材料和成品必须能由对应物品库创建，成品 ID 还必须存在于 item/ 目录的丹药配置中。

文件与标识规则

项目	规则
丹方 ID	YAML 文件最外层键。玩家学习状态、熟练度和炼制任务都按此 ID 保存。重命名后不会自动迁移旧进度。
`icon`	丹方界面和炼制界面显示的原版物品 ID，例如 `PAPER:0`。不读取物品库。
`name`	丹方显示名称，也用于 `/lyld recipes` 的名称过滤。过滤按显示名称进行包含匹配，不区分大小写。
`lore`	丹方界面显示的 Lore。
材料	`need-item` 中使用 `物品库@物品ID 数量`。没有前缀时使用主配置的 `item-provider`。
成品	`level-bonus` 中的键必须对应 `item/` 中的丹药 ID，并且实际 `item` 必须能够创建。

icon、name 和 lore 只用于 GUI 显示，不参与材料、丹药或成品的实际识别。

丹方材料和丹药产物不支持 Vanilla@。原版物品只用于 GUI 图标；丹方材料和丹药产物必须使用物品库前缀，或使用主配置中的默认物品库。

主配置的 item-provider 支持 MythicMobs、LyItemSave、AzureFlow、NeonFlash、SX-Item、NeigeItems 和 OriginAttribute。留空时默认使用 MythicMobs。显式填写 物品库@物品ID 时，优先使用指定物品库。

实际物品匹配时，插件优先比较物品库生成物品与玩家物品的真实 displayName。任一方没有真实显示名称时，回退到 ItemStack.isSimilar。GUI 图标、配置中的显示名称和 Lore 不参与材料、探索材料或丹药的实际匹配。

完整配置结构

yaml

示例丹方:
  icon: 'PAPER:0'
  name: '示例_筑基丹方'
  lore:
    - ''
    - '&7一张神秘的筑基丹方'
  public: true
  need-item:
    - 'MythicMobs@筑基灵液 1'
    - 'MythicMobs@玄黄草 3'
  need-time:
    formula: '66-{level}*3'
    minimum-time: 30
  experience-gain: '1-3'
  level-up:
    experience:
      1-5: '50 + {level}*50'
      6-10: '100 + {level}*50'
    commands: []
  level-bonus:
    1-9:
      示例_残破筑基丹:
        weight: '480 - {level}*48'
        amount: '1'
      示例_下品筑基丹:
        weight: '304 - {level}*16'
        amount: '1'
      示例_中品筑基丹:
        weight: '136 + {level}*8'
        amount: '1-2'
      示例_上品筑基丹:
        weight: '12 + {level}*24'
        amount: '1-2'
      示例_极品筑基丹:
        weight: '{level}*30 - 30'
        amount: '1'
      示例_天道筑基丹:
        weight: '{level}*2 - 2'
        amount: '1'
    10-max:
      示例_残破筑基丹:
        weight: '0'
        amount: '1'
      示例_下品筑基丹:
        weight: '0'
        amount: '1'
      示例_中品筑基丹:
        weight: '20'
        amount: '1-2'
      示例_上品筑基丹:
        weight: '60'
        amount: '1-2'
      示例_极品筑基丹:
        weight: '18'
        amount: '1'
      示例_天道筑基丹:
        weight: '2'
        amount: '1'

基础字段

字段	说明
`icon`	GUI 使用的原版物品图标，例如 `PAPER:0`。非法图标会导致丹方配置加载失败。
`name`	丹方显示名称。`/lyld recipes [名称过滤]` 会按此名称进行包含过滤，支持多个参数合并为空格分隔的过滤文本。
`lore`	丹方列表界面显示的 Lore 列表。
`public`	`true` 表示公开丹方，玩家可以直接使用；`false` 表示隐藏丹方，需要通过探索学会。
`need-item`	材料列表，每行格式为 `物品库@物品ID 数量`。没有物品库前缀时使用 `item-provider`。

need-item 中的数量必须是正整数。炼制界面会显示每种材料的需求数量和玩家当前数量，打开炼制界面前会校验全部材料是否能够创建。任一材料创建失败时，界面不会打开。

炼制时间与熟练度

字段	说明
`need-time.formula`	炼制时间公式，结果单位为秒；`{level}` 会替换为当前丹方熟练度等级。
`need-time.minimum-time`	应用权限倍率前的炼制时间下限，单位为秒。
`experience-gain`	每次成功领取炼制产物后随机获得的经验，格式为包含首尾的 `最小值-最大值`，例如 `1-3`。
`level-up.experience`	升到下一等级所需经验。键可以是单个等级或等级范围，值可以是固定数字或包含 `{level}` 的公式。
`level-up.commands`	丹方升级时执行的指令列表。没有指令时使用空列表。

丹方熟练度默认从 1 级、0 经验开始，不需要配置初始值。丹方最高等级由 level-bonus 可以实现的最终等级决定，不需要在 level-up.experience 中填写 max 范围。

主配置的 permission-time 会在丹方最低时间计算完成后应用。玩家同时拥有多个配置权限时只取最小 multiplier，不叠加。例如 0.90 表示保留 90% 的时间。最终时间可以低于 minimum-time。

升级指令

level-up.commands 支持以下执行身份：

前缀	执行身份
`[console]`	以控制台身份执行。
`[op]`	临时以管理员身份执行。
无前缀	以玩家身份执行。

指令文本支持玩家名称、丹方和熟练度相关占位符，例如 {recipe}、{level}、{exp}、{total_exp} 和 {next_exp}。熟练度升级提示和获得经验提示不在丹方中配置，统一读取主配置的 message.LEVEL_UP 与 message.EXPERIENCE_GAIN。

`level-bonus` 成品配置

level-bonus 的第一层键是熟练度等级范围，范围内的等级共用同一组配置。每个成品必须同时配置 weight 和 amount。

字段	说明
`weight`	抽取权重，可以是固定数字或包含 `{level}` 的公式。负数按 0 处理，权重为 0 的成品不会被抽中。
`amount`	抽中后发放的数量。支持正整数或正整数范围，例如 `1`、`1-2`。范围在领取时随机取值。

实际概率不是固定百分比，计算方式为：

text

成品实际概率 = 当前等级该成品的正权重 ÷ 当前等级全部正权重总和

例如当前等级的总正权重为 900，某成品权重为 180，则该成品的实际概率为 20%。

amount 为 0、负数、非整数、范围倒置或其他不规范格式时，按 1 个发放。数量范围不会影响成品抽取概率。

主配置的 product-chances-format 控制 GUI 中的几率行。支持以下占位符：

占位符	含义
`{name}`	丹药显示名称。
`{chance}`	当前等级的百分比几率。
`{amount}`	数量文本，固定数量或数量范围。
`{min}`	数量范围的最小值。
`{max}`	数量范围的最大值。

{product_chances} 和 {next_product_chances} 会分别展开为当前等级和下一等级的多行内容，GUI 渲染时会拆分为独立 Lore 行。

等级范围校验

丹方重载时会校验公式、熟练度经验、等级范围和成品引用。以下情况会导致丹方配置失败，不会以部分配置提交：

等级范围没有覆盖丹方可以实现的全部等级。
两个等级范围重复覆盖同一等级。
某个可以实现的等级没有正权重成品。
level-up.experience 没有覆盖最高等级之前的升级过程。
公式、范围、数量或经验格式无法解析。
level-bonus 中的成品 ID 不存在于丹药配置。

max 档位表示从该档位起使用最后一组配置，但不表示无限升级。例如 10-max 的最高可实现等级是 10 级。达到最高等级后不再计算下一等级经验。

打开炼制界面时还会再次校验：

丹方全部材料是否能由物品库创建。
所有等级档位中的成品丹药是否存在对应配置。
成品丹药的实际物品标识是否为空。
成品丹药的实际物品是否能由物品库创建。

任一项校验失败都会拒绝打开炼制界面，并输出对应丹方和物品标识。

隐藏丹方与探索

public: false 的丹方不会直接公开使用。探索界面不会显示目标丹方名称、炼制时间或成品概率，只会匹配尚未学会的隐藏丹方。

探索规则如下：

输入材料必须与 need-item 的物品和总数量完全一致，忽略输入槽位顺序。
空输入不会开始有效探索。
非空探索尝试无论成功还是失败都会扣除材料，并立即开始主配置 exploration-cooldown 指定的固定冷却。
多个隐藏丹方同时匹配时，随机学会其中一个。
探索冷却不按丹方熟练度变化。
主配置的 permission-time 会对探索冷却应用时间倍率。

默认资源只有公开的 示例丹方，没有 public: false 的隐藏丹方。新增隐藏丹方后，探索才可能产生成功结果。

主配置中的默认探索冷却为 60 秒：

yaml

exploration-cooldown: 60

探索界面中的 {cooldown} 显示应用权限倍率后的总冷却时间，{cooldown_remaining} 显示剩余秒数。

炼制状态与循环炼制

玩家同时只能存在一个炼制任务。其他丹方可以查看，但当前任务结束前不能开始其他丹方。

普通炼制的流程如下：

开始炼制时扣除材料。
按当前丹方熟练度计算炼制时间。
时间结束后进入 READY 待领取状态。
玩家点击炼制按钮后校验奖励、确定成品并投递。
成功领取后结算熟练度经验，并执行升级指令。

领取中的任务会进入 CLAIMING 状态，并记录本次确定的丹药配置 ID，用于防止重复领取。检测失败通常会恢复为 READY；如果投递结果不确定或任务清除失败，则保留 CLAIMING 锁定状态，避免再次发放同一份奖励。服务器重启后，残留的 CLAIMING 任务不会自动再次领取，需要管理员核对。

开启循环炼制后，插件会在领取当前产物并结算经验后继续同一丹方。以下情况会停止循环：

材料不足。
成品配置或成品物品不可用。
奖励检测失败。
关闭炼制界面。

关闭炼制界面不会取消当前这一炉；当前任务完成后仍会保留为普通待领取状态。循环开关只存在当前在线会话，关闭界面或退出后不会恢复。

丹方界面显示内容

丹方列表和炼制界面的动态丹方槽会显示：

丹方名称和 Lore。
当前熟练度等级。
当前等级经验和下一等级经验。
当前等级炼制时间。
当前等级各成品实际几率和发放数量。
下一熟练度等级。
下一等级炼制时间。
下一等级各成品实际几率和发放数量。

达到最高可实现等级时，下一等级信息使用主配置中的满级文本显示。

/lyld recipes 直接使用丹方列表界面。不输入过滤内容时显示全部可展示丹方；输入过滤内容时，按丹方显示名称进行不区分大小写的包含匹配。

玩家数据与 MySQL 注意事项

丹方学习状态、熟练度、探索冷却和炼制任务会随玩家数据保存。玩家数据未加载完成前不能打开本插件 GUI，也不能执行相关炼制操作。

使用 MySQL 存储时，必须安装并启用 LyMySQLCore，并确保数据库连接和表初始化成功，相关玩家数据功能才会生效。数据库初始化失败时不会自动回退到 YAML。

mysql.enable 只在服务器启动时决定存储模式，修改后需要重启服务器。YAML 模式使用玩家 UUID 文件保存；MySQL 模式使用 LyAlchemy_player_data 表保存玩家数据文本。

常见问题

为什么丹方能显示，但炼制界面打不开？

打开炼制界面会重新校验全部材料和所有等级档位中的成品。如果物品库插件未启用、物品 ID 不存在、丹药配置缺失或实际物品无法创建，插件会拒绝打开界面，并在控制台输出具体丹方和物品标识。

为什么探索界面没有成功结果？

默认资源只有公开的 示例丹方，没有隐藏丹方。只有新增 public: false 的丹方，并投入与其 need-item 物品和总数量完全一致的材料后，探索才可能成功。

为什么重命名丹方后熟练度消失？

熟练度和学习状态按丹方 ID 保存。修改 YAML 最外层键后，旧 ID 的存档不会自动迁移。

为什么不能使用 `Vanilla@`？

Vanilla@ 不属于丹方材料和丹药产物的有效格式。原版物品只用于 GUI 图标；材料和产物应使用显式物品库前缀，或使用主配置中的 item-provider。

为什么 MySQL 模式下玩家数据没有生效？

请确认已安装并启用 LyMySQLCore，数据库连接成功且表初始化完成。MySQL 初始化失败时不会自动使用 YAML，相关玩家数据功能也不会正常生效。

丹方配置 ​

文件与标识规则 ​

完整配置结构 ​

基础字段 ​

炼制时间与熟练度 ​

升级指令 ​

level-bonus 成品配置 ​

等级范围校验 ​

隐藏丹方与探索 ​

炼制状态与循环炼制 ​

丹方界面显示内容 ​

玩家数据与 MySQL 注意事项 ​

常见问题 ​

为什么丹方能显示，但炼制界面打不开？ ​

为什么探索界面没有成功结果？ ​

为什么重命名丹方后熟练度消失？ ​

为什么不能使用 Vanilla@？ ​

为什么 MySQL 模式下玩家数据没有生效？ ​