丹药配置

丹药文件放在 plugins/LyAlchemy/item/。每个文件的最外层键是丹药 ID，丹方 level-bonus 中的产物键必须与丹药 ID 完全一致。

丹药配置分为三部分：

• item：实际生成、炼制产物和服用识别使用的物品。
• icon、name、lore：丹药界面中的展示内容。
• attribute：每次服用增加的属性以及最大服用次数。

icon、name 和 lore 不会替代 item。玩家必须持有物品库能够创建的实际丹药物品，才能被识别和服用。

配置结构

示例_下品筑基丹:
  item: 'MythicMobs@示例_下品筑基丹'
  icon: 'APPLE:0'
  name: '&f下品筑基丹'
  lore:
    - '&7一枚下品筑基丹'
  attribute:
    1:
      攻击力: 100
      生命力: 100
    2-9:
      攻击力: 10
      生命力: 10
    10:
      攻击力: 120
      生命力: 120

字段	类型	说明
最外层键	文本	丹药 ID，必须与丹方产物键一致。
item	文本	实际生成和服用识别使用的物品，支持 物品库@物品ID。
icon	文本	丹药界面使用的原版物品图标。
name	文本	丹药界面显示名称。
lore	文本列表	丹药界面显示的说明。
attribute	配置节点	按服用次数或次数范围配置属性增量。

实际物品 item

item 只用于丹方材料、丹药产物和丹药服用识别。丹药界面的 icon 不使用物品库。

主配置中的 item-provider 支持以下物品库名称：

• MythicMobs
• LyItemSave
• AzureFlow
• NeonFlash
• SX-Item
• NeigeItems
• OriginAttribute

未填写物品库前缀时，使用主配置 item-provider 指定的默认物品库。item-provider 为空时，默认使用 MythicMobs。

item-provider: ''

显式前缀优先于默认物品库：

写法	处理方式
MythicMobs@物品ID	优先查询 MythicMobs。
LyItemSave@物品ID	优先查询 LyItemSave。
其他已支持前缀	查询对应物品库。
不填写前缀	查询 item-provider 指定的默认物品库。

当 MythicMobs 和 LyItemSave 同时启用时：

• MythicMobs@物品ID 先查询 MythicMobs，找不到时再查询 LyItemSave。
• LyItemSave@物品ID 先查询 LyItemSave，找不到时再查询 MythicMobs。

只启用其中一个物品库时，两个前缀都可以访问当前可用的物品库。

item 为空、物品库未启用或物品无法创建时，丹药不能正常使用。Vanilla@ 不属于丹药实际物品的支持写法。

丹药界面展示

丹药界面文件为 plugins/LyAlchemy/gui/丹药界面.yml。动态丹药槽使用丹药配置中的 icon、name 和 lore，不会显示玩家背包中的实际丹药物品。

GUI 图标只使用 ItemUtil 解析原版物品 ID，例如：

icon: 'APPLE:0'

GUI 图标不经过 item-provider。原版物品 ID 无效时，相关配置加载失败，不会静默替换为石头。

丹药列表只显示同时满足以下条件的丹药：

• 存在至少一组有效的 attribute 范围。
• 玩家已经有该丹药的服用记录。

丹药界面布局使用 丹药界面.yml 中的 D 动态列表、P 上一页、N 下一页和底部导航按钮。列表支持跳转到丹方、炼制和探索界面。

动态丹药模板支持以下占位符：

占位符	含义
{now_count}	当前累计服用次数。
{max_count}	attribute 的最大服用次数；没有有限上限时显示“无限”。
{attribute}	按主配置 attribute-template 渲染后的当前累计属性。

示例模板：

template:
  - ''
  - '&7服用次数: &f{now_count} / {max_count}'
  - '&7当前属性:'
  - '{attribute}'

{attribute} 等多行占位符会在 Lore 中拆分为独立行，同时兼容实际换行和文本形式的 \\n。

属性配置

主配置使用 attribute-plugin 选择属性插件：

attribute-plugin: 'AttributePlus'

支持的值为：

• AttributePlus
• AttributeSystem
• SX-Attribute

属性模板由主配置的 attribute-template 定义：

attribute-template:
  '攻击力': '&7攻击力 &6+{value}'
  '生命力': '&7生命力 &6+{value}'

attribute 的键是属性插件支持的属性名称，值是该次服用增加的数值。次数范围包含起始值和结束值。

写法	含义
1	第 1 次服用使用这一组属性。
2-9	第 2 至第 9 次服用使用这一组属性。
10	第 10 次服用使用这一组属性。

属性范围必须从大于等于 1 的次数开始，范围不能重叠，属性值必须是有限数字。配置重载时会校验范围、属性名称和属性数值。

每次服用时，插件会读取该丹药所有历史服用记录，将每次服用对应的属性增量合并后提交给所选属性插件。玩家数据加载完成后，也会重新计算并提交全部已服用丹药的累计属性。

丹药至少需要存在一组有效的 attribute 范围，才允许服用并显示在丹药界面中。没有 attribute、属性节点为空或属性范围无效的丹药可以被读取，但运行时会跳过服用识别，也不会进入丹药列表。

有限属性范围的最大次数就是丹药的最大服用次数。没有有限上限时最大次数为 0，界面和服用消息显示为“无限”。

丹药识别与服用

玩家右键使用手中的丹药物品时，插件通过 PlayerInteractEvent 检查丹药。每个玩家的服用交互有 100 毫秒冷却，避免同一次交互被重复处理。

1.7 服务端按主手处理；较新版本支持副手，副手相关接口通过兼容方式读取。即使交互事件已经被其他插件取消，插件仍会继续进行丹药检测。

实际识别使用丹药配置中的 item 创建物品，并按以下规则与玩家物品匹配：

1. 配置物品和玩家物品都有真实 displayName 时，比较两个显示名称。
2. 任一方没有真实 displayName 时，回退到 ItemStack.isSimilar。
3. GUI 图标、配置中的 name 和 lore 不参与实际识别。

多个实际物品拥有相同显示名称时，会按丹药配置加载顺序匹配到第一个符合的丹药。物品库中的丹药显示名称应保持唯一。

服用流程具有以下限制：

• 玩家数据尚未加载完成时不能服用丹药。
• 丹药必须存在有效的 attribute 配置。
• 达到有限最大服用次数后不能继续服用。
• 属性插件不可用、未启用或属性提交失败时，服用不会正常完成。
• 属性应用成功后扣除手中一件实际丹药，并增加对应的累计服用次数。
• 手中物品数量为 1 时，服用后清空对应手部；数量大于 1 时减少 1 个。

服用消息

相关消息位于主配置的 message 节点：

配置键	用途
MEDICINE_CONSUMED	服用成功。
MEDICINE_MAX_COUNT	达到最大服用次数。
MEDICINE_CONSUME_FAILURE	服用失败。
ATTRIBUTE_PROVIDER_UNAVAILABLE	属性插件不可用。
DATA_LOADING	玩家数据仍在加载。

服用消息支持以下占位符：

占位符	含义
{medicine}	丹药显示名称。
{count}	当前累计服用次数。
{max_count}	最大服用次数；没有有限上限时显示“无限”。

玩家数据保存

丹药服用次数使用丹药 ID 作为键保存：

medicine-counts:
  示例_中品筑基丹: 2

YAML 模式

玩家数据文件位于：

plugins/LyAlchemy/playerdata/<玩家UUID>.yml

YAML 模式使用临时文件、.bak 备份和原子替换保存，玩家退出、踢出、停服以及启用自动保存时会保存已加载的数据。

MySQL 模式

启用 MySQL 时，必须安装并启用 LyMySQLCore，并且成功连接数据库；否则玩家数据及依赖这些数据的丹药服用功能不会正常生效。

mysql:
  enable: true

mysql.enable 只在服务器启动时决定存储模式，修改后需要重启服务器。数据库连接或表初始化失败时不会自动切换到 YAML 模式。

PlaceholderAPI 丹药变量

安装并启用 PlaceholderAPI 后，可以使用丹药服用次数变量：

%lyld_medicine_count_<丹药ID>%

例如：

%lyld_medicine_count_示例_中品筑基丹%

该变量返回玩家当前累计服用次数。丹药 ID 位于变量末尾，ID 中的下划线无需转义。

配置校验与常见问题

重载丹药配置时会检查：

• item 是否为空，以及实际物品是否能够由当前物品库创建。
• icon 是否为有效的原版物品 ID。
• attribute 次数范围是否从有效次数开始、是否重叠。
• 属性键和值是否有效，属性值是否为有限数字。
• 丹药是否至少包含一组有效属性范围。

如果丹药界面中没有某种丹药，通常是该丹药没有服用记录，或没有有效的 attribute 范围。没有属性的丹药即使存在服用记录，也不会显示在丹药界面中。

如果炼制出的物品无法服用，应优先检查丹药配置中的 item、物品库前缀和物品库中的实际显示名称。炼制产物和服用识别使用实际物品，不能只配置 GUI 的 icon、name 或 lore。

如果启用 MySQL 后丹药次数不生效，应检查 LyMySQLCore 是否已安装启用，以及数据库连接和表初始化是否成功。SQL 初始化失败不会回退到 YAML。

默认丹药配置

默认资源包含以下六种示例丹药。六种丹药均配置了 1、2-9 和 10 三组属性范围。

丹药 ID	实际物品	界面名称	GUI 图标
示例_残破筑基丹	MythicMobs@示例_残破筑基丹	残破筑基丹	APPLE:0
示例_下品筑基丹	MythicMobs@示例_下品筑基丹	下品筑基丹	APPLE:0
示例_中品筑基丹	MythicMobs@示例_中品筑基丹	中品筑基丹	APPLE:0
示例_上品筑基丹	MythicMobs@示例_上品筑基丹	上品筑基丹	APPLE:0
示例_极品筑基丹	MythicMobs@示例_极品筑基丹	极品筑基丹	APPLE:0
示例_天道筑基丹	MythicMobs@示例_天道筑基丹	天道筑基丹	APPLE:0

实际丹药物品必须在当前可用的物品库中存在。示例配置使用 MythicMobs@ 前缀；当 MythicMobs 和 LyItemSave 同时启用且物品只存在于 LyItemSave 时，会按兼容规则回退查询 LyItemSave。