常见问题

插件支持哪些服务端版本？

plugin.yml声明的服务端 API 版本为 1.13。项目中包含旧版 1.7 主手服用兼容处理，并通过反射兼容新版本副手读取，但项目证据没有提供完整的逐版本支持清单，也没有进行服务器运行验证，因此不能将所有更高版本写成已验证支持版本。

需要安装哪些前置？

前置取决于实际启用的功能：

功能	前置要求
PlaceholderAPI 变量	安装并启用 PlaceholderAPI；未安装时插件主体仍可运行，但变量不会生效。
丹方材料、丹药产物	安装并启用实际使用的物品库，并保证对应物品标识存在。
丹药属性和服用	安装并启用主配置 attribute-plugin 选择的 AttributePlus、AttributeSystem 或 SX-Attribute。
MySQL 玩家数据	必须安装并启用 LyMySQLCore，并成功连接数据库、完成数据表初始化。
外部仓库投递	只有配置了对应仓库目标且目标插件已启用时才会使用；未启用的目标会自动跳过。

没有使用到的可选前置不需要安装。不要仅根据软依赖列表把所有插件都当作必需依赖。

插件为什么无法正常启用 MySQL 存储？

MySQL 模式必须同时满足以下条件：

• 主配置中的 mysql.enable 为 true。
• LyMySQLCore 已安装并启用。
• 数据库连接成功。
• LyAlchemy_player_data 表初始化成功。

任一条件失败时，MySQL 存储功能不会生效，也不会自动回退到 YAML。修改 mysql.enable 后必须重启服务器，单独执行 /lyld reload 不会切换存储模式。

/lyld reload 后丹方或丹药读取失败怎么办？

先查看控制台中的具体文件路径和失败原因。重点检查：

• YAML 缩进、文件编码、文件最外层丹方 ID 或丹药 ID。
• 丹方 need-item 中的材料标识和物品库前缀。
• level-bonus 中引用的每个丹药 ID 是否存在于丹药配置。
• need-time 公式、最低时间、熟练度升级经验范围是否有效。
• 每个可实现等级是否存在正权重，权重范围是否覆盖且没有重叠。
• 丹药实际 item、GUI icon、属性次数范围和属性数值是否有效。
• GUI 的 layout、button、slot 是否互相对应，原版物品 ID 是否有效。

重载会先保存主配置、权限时间规则、丹方/丹药和四个 GUI 的旧状态。任一阶段失败时会恢复旧运行时配置，不会保留部分新配置。

默认资源目录包括：

• config.yml
• item/
• recipe/
• gui/丹方界面.yml
• gui/丹药界面.yml
• gui/炼制界面.yml
• gui/探索界面.yml

修改配置后为什么没有生效？

确认修改的是插件数据目录中的文件，并执行 /lyld reload。

mysql.enable 只在插件启动时决定 YAML 或 MySQL 模式，修改后必须重启服务器。重载会重新读取主配置、权限规则、丹方、丹药和四个 GUI。

材料或产物提示不存在怎么办？

确认物品库插件已安装并启用，再检查物品标识格式：

item-provider: ''

丹方材料和丹药产物没有显式前缀时，使用 item-provider 指定的默认物品库；空值按配置默认规则使用 MythicMobs。也可以显式指定：

MythicMobs@物品ID
LyItemSave@物品ID
AzureFlow@物品ID
NeonFlash@物品ID
SX-Item@物品ID
NeigeItems@物品ID
OriginAttribute@物品ID

MythicMobs 与 LyItemSave 同时启用时：

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

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

GUI 槽位、丹方图标和丹药图标不读取物品库，只使用原版物品 ID，例如 262:0、PAPER:0 和 APPLE:0。Vanilla@ 不是受支持的格式。

为什么 GUI 图标显示异常？

GUI 物品、丹方图标和丹药图标只使用原版材质解析，不使用物品库。检查以下内容：

• layout 中使用的字符是否都在对应的 button 或 slot 中声明。
• button 指向的字符是否与 layout 和 slot 完全一致。
• GUI 物品是否使用有效的原版物品 ID。
• 探索界面的 button.materials: M 是否存在 slot.M。
• 探索界面的 slot.M.item 是否为空。
• 是否误把炼制界面的只读 M 槽当成探索输入槽。

非法 GUI 原版材质会导致对应 GUI 配置加载失败，不会静默回退成石头。GUI Lore 中的 {attribute}、{product_chances} 等多行内容会自动拆分为独立行。

丹药能炼制出来，但右键不能服用怎么办？

按以下顺序检查：

1. attribute-plugin 是否填写为服务器实际安装的 AttributePlus、AttributeSystem 或 SX-Attribute。
2. 丹药配置是否至少存在一组有效的 attribute 范围。没有属性或属性范围为空的丹药不会被服用匹配，也不会进入丹药列表。
3. 玩家手中的是否是物品库实际生成的丹药，而不是 GUI 图标。
4. 丹药配置中的物品库前缀和服务器实际注册位置是否一致。
5. 是否使用右键交互。插件通过 PlayerInteractEvent 处理服用，并使用玩家级交互冷却。

丹药识别优先比较物品库实际物品与玩家物品的真实 displayName。双方都有真实显示名称时必须完全一致；任一方没有真实显示名称时，才回退到 ItemStack.isSimilar。丹药配置中的 name、Lore 和 GUI 图标不参与实际识别。

多个不同物品不要使用相同的真实显示名称，否则可能按配置加载顺序匹配到第一个。

旧版服务端按主手处理；新版本可以通过兼容逻辑读取主手或副手。属性提交成功后才会扣除手中一件丹药。

没有属性的丹药为什么不显示在丹药界面？

这是插件的有效性规则。丹药必须至少配置一组有效 attribute 范围，才允许服用并显示在丹药界面中。已有无属性丹药服用记录也会被列表过滤，但相关历史记录仍可能参与统计变量。

未公开丹方如何探索？

探索只会匹配同时满足以下条件的丹方：

• public: false。
• 玩家尚未学会该丹方。
• 探索界面中的材料种类和总数量与丹方 need-item 完全一致。
• 材料槽位顺序不影响匹配。

非空探索尝试无论成功或失败都会扣除材料，并立即开始固定冷却。多个丹方同时匹配时，插件会随机收录其中一个。空输入只提示材料不足，不会开始冷却。

探索界面不会显示未知丹方的名称、炼制时间或产物概率。

探索界面总是提示失败怎么办？

默认示例资源只有一个公开丹方 示例丹方，没有 public: false 的隐藏丹方。因此全新安装时没有可供默认配置探索成功的目标。

如果要使用探索功能，需要在 recipe/ 中配置未公开丹方，并确保其材料能够由当前物品库创建。配置重载成功后，再使用完全匹配的材料进行探索。

探索界面的材料为什么不能直接拖进去？

这是当前交互规则：

• 点击玩家底部背包中的物品时，插件只扣除 1 个并放入第一个空的 M 槽。
• 点击已有 M 槽会返还整槽物品。
• 关闭界面时会返还所有剩余材料。
• 所有原版物品点击和拖拽都会被取消，只有插件处理的普通左键和右键业务会生效。

探索 GUI 的 M 槽必须声明为空物品：

slot:
  'M':
    item: ''

炼制界面的 M 槽是只读的丹方材料展示槽，不能当作探索输入槽使用。

炼制完成后没有立即获得丹药怎么办？

普通炼制完成后，任务会进入 READY 待领取状态，不会自动投递。打开当前丹方的炼制界面，点击同一个炼制按钮领取奖励。

领取前会检查玩家状态、任务丹方、产物配置和物品创建结果。检测失败时任务会继续保留为待领取状态，不会重新随机产物。

领取状态说明如下：

状态	含义
NONE	没有炼制任务。
CRAFTING	正在等待炼制完成。
READY	已完成，等待玩家领取。
CLAIMING	奖励正在领取或领取锁已经保存，需要核对处理。

领取前会先在玩家数据锁内原子切换为 CLAIMING，并记录本次产物；随后在外部投递前保存领取锁。普通检测或创建失败时可以恢复为 READY 并复用同一产物。

如果外部投递结果异常、任务清除失败或结果无法确认，任务会保持 CLAIMING，不会自动恢复领取，避免重复发放。此时应先核对玩家背包、仓库等实际投递结果，再由管理员处理。

为什么不能同时炼制多个丹方？

每名玩家同时只能存在一个炼制任务。玩家可以查看其他丹方，但当前任务完成或清除前，不能开始另一个丹方的炼制。

循环炼制为什么停止了？

循环炼制会在当前任务领取成功后自动结算熟练度，并继续同一个丹方。出现以下情况时会停止：

• 材料不足。
• 产物不存在或无法创建。
• 奖励检测失败。
• 玩家关闭炼制界面。
• 当前任务进入 CLAIMING 锁定状态。

关闭炼制界面不会取消当前这一炉，只会停止循环；当前炉完成后仍会保留为普通待领取任务。

循环开关只存在当前在线会话，关闭界面或退出服务器后不会恢复。旧存档中的 loop 字段也会被忽略。

OP 炼制时为什么不需要材料？

OP 点击炼制界面开始新任务时，可以跳过玩家背包材料检测和扣除。

该旁路不跳过以下检查和流程：

• 丹方是否存在、是否已经学会。
• 玩家是否已有其他炼制任务。
• 炼制时间计算。
• 成品配置和物品创建检查。
• 待领取和奖励投递检查。
• 探索流程。

如何调整炼制时间？

在丹方的 need-time 中配置公式和最低时间。公式中的 {level} 表示该丹方当前熟练度等级，结果单位为秒：

need-time:
  formula: '66-{level}*3'
  minimum-time: 30

权限倍率配置在主配置的 permission-time 中：

permission-time:
  - permission: 'lyalchemy.time.vip1'
    multiplier: 0.90
  - permission: 'lyalchemy.time.vip2'
    multiplier: 0.70

multiplier: 0.90 表示使用基础时间的 90%，即缩短 10%。玩家同时拥有多个配置权限时只取最小倍率，不叠加。

权限倍率会在丹方最低时间限制之后应用，因此最终时间可以低于 minimum-time。同一权限倍率规则也会影响探索冷却，但探索冷却本身只读取主配置的固定 exploration-cooldown，不会随丹方熟练度等级变化。

如何调整丹药概率和数量？

level-bonus 中每个产物都使用 weight 和 amount：

level-bonus:
  1-max:
    示例_中品筑基丹:
      weight: '20'
      amount: '1-2'

weight 是相对权重，不是固定百分比。实际概率等于该产物的正权重除以当前等级所有正权重总和。负权重按 0 处理，某个等级所有产物都没有正权重时，该等级不能产生有效结果。

amount 是抽中后的发放数量：

• 1 表示固定发放 1 个。
• 1-2 表示在 1 到 2 个之间随机发放。
• 非正规整数、范围倒置、0 或负数会按 1 个处理。

max 不是无限等级标记，而是最终等级档位的写法。例如 10-max 的最终可实现等级按 10 级处理。

GUI 中的几率和数量显示不正确怎么办？

确认主配置存在 product-chances-format，并检查占位符拼写：

• {name}：丹药显示名称。
• {chance}：当前等级的百分比几率。
• {amount}：数量文本。
• {min}、{max}：数量范围的起止值。

{product_chances} 和 {next_product_chances} 使用同一格式。多行占位符会在 Lore 中拆成独立行。

PlaceholderAPI 变量不显示怎么办？

确认 PlaceholderAPI 已安装并启用，变量标识符为 lyld，完整格式必须包含两侧百分号：

%lyld_recipe_level_示例丹方%

动态丹方或丹药 ID 必须放在变量末尾，ID 中的下划线不需要转义。常用变量如下：

变量	返回内容
%lyld_recipe_learned_<丹方ID>%	丹方是否可用；公开丹方或已探索丹方返回 true。
%lyld_recipe_level_<丹方ID>%	当前熟练度等级。
%lyld_recipe_experience_<丹方ID>%	当前等级经验。
%lyld_recipe_next_level_<丹方ID>%	下一熟练度等级；满级时返回当前等级。
%lyld_recipe_next_experience_<丹方ID>%	升级所需经验；满级时返回 0。
%lyld_recipe_max_level_<丹方ID>%	丹方可实现的最高熟练度等级。
%lyld_recipe_time_<丹方ID>%	当前等级、应用权限倍率后的炼制时间，单位为秒。
%lyld_recipe_next_time_<丹方ID>%	下一等级炼制时间，单位为秒。
%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%	当前任务开始时的熟练度等级。
%lyld_crafting_remaining%	任务剩余秒数。
%lyld_crafting_time%	当前任务总炼制时间，单位为秒。
%lyld_crafting_finish_time%	任务完成时间的 Unix 毫秒时间戳。
%lyld_crafting_claim_status%	NONE、CRAFTING、READY 或 CLAIMING。
%lyld_crafting_product%	已确定的产物丹药 ID。
%lyld_crafting_loop%	当前任务是否开启循环炼制。

目标丹方不存在或玩家未解锁时，除 recipe_learned 外的丹方变量通常返回 0。内部 GUI、消息和公式占位符使用 {...}，不要写成 PlaceholderAPI 的 %...% 格式。

玩家数据保存在哪里？

YAML 模式

当 mysql.enable: false 时，玩家数据保存在：

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

保存时会使用临时文件、.bak 备份和原子替换；主文件损坏时会尝试从 .bak 恢复。loop-save-thread-time 的单位是秒，设置为 0 或负数会关闭 YAML 自动保存。退出保存和停服最终保存仍会执行。

MySQL 模式

当 mysql.enable: true 时，必须安装并启用 LyMySQLCore，并确保数据库连接和表初始化成功。玩家数据保存到 LyAlchemy_player_data 表，data 字段保存与 YAML 相同的完整文本。

MySQL 通过玩家名称关联数据，玩家改名后会产生新的数据行，不会自动迁移旧名称数据。数据库连接、表初始化或 LyMySQLCore 流程失败时，不会自动回退到 YAML。

玩家刚进服时为什么不能打开 GUI？

玩家数据需要先完成加载。加载完成前，丹方、丹药、炼制和探索四个 GUI，以及相关指令操作都会被拒绝，并提示数据正在加载。

等待加载完成后再操作，避免默认数据覆盖正在读取的玩家存档。

丹方熟练度如何计算？

炼制完成后会按照丹方的 experience-gain 随机增加经验。升级经验配置位于丹方的 level-up.experience，可以使用单等级或等级范围，并支持包含 {level} 的公式。

丹方最高熟练度由 level-bonus 可以实现的最终等级档位决定，不需要在 level-up.experience 中填写 max 范围。升级和获得经验消息统一读取主配置：

• message.LEVEL_UP
• message.EXPERIENCE_GAIN

丹方中的 level-up.commands 仍然属于丹方自身配置，可使用 [console]、[op] 或无前缀玩家身份执行。

达到最高可实现等级时，GUI 相关满级文本优先使用 message.RECIPE_MAX_LEVEL，缺失时回退 message.MAX_LEVEL。

丹方管理指令怎么用？

以下管理指令仅限 OP，目标玩家必须在线且炼丹数据已经加载完成：

指令	作用
/lyld give recipe <玩家> <丹方ID>	让玩家直接学会指定的未公开丹方。
/lyld remove recipe <玩家> <丹方ID>	删除未公开丹方的学会状态，但保留熟练度等级和经验。
/lyld give medicine <玩家> <丹药ID> <数量>	增加有效属性丹药的服用次数，不能超过配置的有限上限。
/lyld remove medicine <玩家> <丹药ID> <数量>	扣除服用次数，最低为 0。

公开丹方始终可用，不需要单独增加学会状态。丹药次数修改后会重新计算累计属性并立即保存。

指令和权限节点在哪里配置？

已确认的玩家入口包括：

指令	作用
/lyld recipes [名称过滤]	打开丹方列表；过滤内容按丹方显示名称进行不区分大小写的包含匹配，多个参数会合并为空格分隔的文本。
/lyld medicines	打开丹药界面。
/lyld craft [丹方]	打开丹方列表或指定丹方的炼制界面。
/lyld explore	打开探索界面。
/lyld reload	OP 重载配置。

项目证据没有定义独立的权限节点名称，因此 Wiki 不列出未经确认的权限字段。permission-time 中的权限只用于时间倍率规则，例如 lyalchemy.time.vip1 和 lyalchemy.time.vip2，不会自动赋予管理权限。

外部仓库为什么没有收到炼制产物？

检查主配置的 delivery-order。当前支持的投递目标为：

delivery-order:
  - 'LyLootsWarehouse'
  - 'LyWarehouse'
  - 'SpaceRingPlus'
  - 'StarStorage'
  - 'inventory'

插件会按列表顺序依次尝试投递。未安装或未启用的目标会自动跳过；列表为空或全部目标无效时默认使用玩家背包。所有目标处理后仍有剩余物品时，剩余物品会掉落在玩家位置。

如果领取任务进入 CLAIMING，不要直接重复点击领取。应先核对玩家背包和仓库的实际结果，再处理锁定任务。

修改 GUI 后为什么没有显示预期内容？

检查以下内容：

• layout 中使用的字符是否都在对应的 button 或 slot 中声明。
• button 指向的字符是否与 layout 和 slot 完全一致。
• GUI 物品是否使用有效的原版物品 ID。
• 丹方和丹药的动态图标是否使用原版材质，而不是物品库 ID。
• 探索界面的 button.materials: M 是否存在空的 slot.M。
• 是否误把炼制界面的只读 M 槽当成探索输入槽。

丹方和丹药列表使用前 45 个槽位显示动态内容，并提供翻页和其他界面跳转。炼制界面第 40 槽为循环炼制开关，探索界面不会显示未知丹方的详细信息。

外部插件如何调用 LyAlchemy API？

公共 API 只提供同步业务方法，不携带服务端数据类，也不负责配置重载、物品创建、PlaceholderAPI 文本替换或产物投递。

当前公开方法为：

learnRecipe
isRecipeLearned
getLearnedRecipes
getRecipeLevel
getRecipeExperience
getRecipeNeedTime
startCrafting
setCraftingLoop
claimCrafting
getCraftingRemaining
findMedicineId
getMedicineCount
addMedicineCount
getExplorationCooldown
startExplorationCooldown

外部调用方应使用这些已确认的方法名，不要根据历史文档臆造生命周期方法、内部数据类型或额外配置接口。

炼丹完成、探索和翻页音效在哪里配置？

音效配置位于主配置的 sound 节点：

配置键	用途	默认值
sound.craft-finish	炼丹完成进入可领取状态时播放。	ENTITY_PLAYER_LEVELUP
sound.exploration-success	探索成功时播放。	ENTITY_PLAYER_LEVELUP
sound.exploration-failure	探索失败时播放。	BLOCK_ANVIL_DESTROY
sound.page-turn	列表实际翻页时播放。	UI_BUTTON_CLICK

旧版服务端对应名称分别为 LEVEL_UP、LEVEL_UP、ANVIL_BREAK 和 CLICK。材料不足、探索冷却中或没有实际翻页时不会播放对应结果音效。