强化配方

强化配方定义装备在不同星级的成功率、材料消耗、失败惩罚、效果和动作。文件位于 recipes/*.yml，文件名即为配方的内部标识。

顶层字段

字段	类型	说明
id	string	配方唯一 ID。
display_name	string	配方显示名（MiniMessage 格式）。
gui_template	string	GUI 模板引用。
economy	object	经济系统配置（每次强化扣费）。
limits	object	强化限制（最大星级、锻印等）。
success_rates	map	各星级基础成功率。
matcher	object	通用物品匹配器，按非物品源条件判定哪些装备可使用此配方。见匹配规则。
source_patterns	list	物品来源模式匹配（正则），与其余三个字段是且关系。见匹配规则。
slot_groups	list	槽位组匹配，与其余三个字段是且关系。见匹配规则。
stats_any	list	属性匹配，与其余三个字段是且关系。
match	object	已废弃，不再被读取。见从 match 迁移。
stat_lines	map	属性行模板定义。
name_actions	list	全局名称修改操作。
lore_actions	list	全局 Lore 修改操作。
stars	map	各星级阶段定义。
branch_tree	object	分支树定义。详见分支树系统。
condition	object	使用该配方的条件组。

经济配置

economy:
  enabled: true
  currencies:
    - provider: "vault"
      currency_id: ""
      base_cost: 320
      cost_formula: "%base_cost% * %star%"
      display_name: "<gold>金币</gold>"

cost_formula 支持表达式，可引用 %base_cost%、%star% 等变量。

强化限制

limits:
  max_star: 12
  max_temper: 4
  temper_chance_bonus_per_level: 5.0
  success_chance_cap: 90.0

字段	说明
max_star	最大可强化星级。
max_temper	最大锻印等级（失败时累积，提升下次成功率）。
temper_chance_bonus_per_level	每级锻印提供的成功率加成（百分比）。
success_chance_cap	成功率上限（含锻印加成后不超过此值）。

匹配规则

目标装备的匹配由文件顶层的四个字段决定，它们之间是且关系：

slot_groups:
  - "weapon"

source_patterns:
  - "^emakiitem-example_item$"

字段	类型	说明
source_patterns	list	顶层的物品源条件，按物品来源模式匹配（正则）。
matcher	object	通用物品匹配器，只按组件、PDC、Lore、变量等非物品源条件判定。语法见 物品匹配器。
slot_groups	list	粗粒度槽位组/装备类型组（weapon/armor/offhand/generic），不是 main_hand/helmet 这类具体装备槽位。
stats_any	list	拥有指定属性之一。

顶层物品源条件走 source_patterns

配方顶层没有 item_sources 字段，物品源条件用既有的 source_patterns。它是正则、忽略大小写的部分匹配，所以要精确绑定单一物品源就加锚点："^emakiitem-example_item$"。不加锚点的 "emakiitem-example_item" 会把 emakiitem-example_item_v2 这类来源也一并命中。

matcher 内部不能写物品源条件（type: item_source / item_sources / source / sources 会被拒绝并告警）。

NOTE

推荐用带锚点的 source_patterns 精确绑定物品 ID，避免配方泛匹配所有武器。

从 match 迁移

旧版的 match 块已不再被读取。字段的去向：

旧字段	现在的写法
match.source_ids	顶层 source_patterns，每个 ID 写成带锚点的正则（"^minecraft-diamond_sword$"）
match.lore_contains	matcher 里的 type: component + component: lore + operator: contains，每条文本一个子条件
match.slot_groups	提升为顶层 slot_groups
match.stats_any	提升为顶层 stats_any
match.source_patterns	提升为顶层 source_patterns
match.source_types	无法自动转换，需手工改写为 source_patterns 或 matcher 条件

/emakistrengthen convert-legacy 可以自动完成转换：

命令	行为
/emakistrengthen convert-legacy	预演，只打印将要产生的差异，不改文件。
/emakistrengthen convert-legacy confirm	实际改写 recipes/*.yml，并为每个文件留一份 .bak 备份。

--apply 与 confirm 等价。命令需要 emakistrengthen.admin 权限。

WARNING

含 match.source_types 的文件会被判为无法转换并跳过；文件里同时存在 match 和已写好的 matcher（或对应顶层字段）时会报冲突并跳过。两种情况都需要手工处理。

match.source_ids 会被自动转成带锚点的正则并合并进顶层 source_patterns，不会写进 matcher，转换结果无需手工修正。转换出的正则是精确匹配：两端补了 ^ / $ 锚点，ID 里的特殊字符也做了转义（形如 ^\Qemakiitem-xxx\E$）。

旧材料字段的规范化与拒绝条件

阶段材料解析会把旧的标量 item 规范化为 item_sources，并按 material_id → id → count_key → 单一来源 → 阶段索引的顺序补出 material_id；count_key 省略时回退到 material_id。如果未声明身份却提供多个来源，解析器无法安全选择唯一身份，会拒绝该材料，不会改写原始映射。上述行为只由当前 JVM 解析代码与本地测试证明，尚未在 Paper/Folia 实机上验证旧配置或旧存档的运行结果。

通用物品匹配器（matcher）

配方支持两处 matcher：文件顶层的 matcher 判定目标装备，materials[].matcher 判定强化材料。两处语法一致，但物品源条件的落位不同：

位置	物品源条件写在哪	与 matcher 的关系
顶层 matcher	顶层 source_patterns（正则）	顶层 source_patterns、slot_groups、stats_any、matcher 四者是且关系，都要成立才命中。
materials[].matcher	同级 item_sources	两者取且：先按 item_sources 选中材料，再用 matcher 复核那一枚。任一不成立就不算这份材料。

NOTE

enhancement_recipes/*.yml 的 materials[] 同样是 item_sources + matcher 同级取 AND。过去写在 matcher 内部的物品源条件请移到同级 item_sources。

完整说明见 物品匹配器。

id: enchanted_sword_strengthen

# 顶层：只有附了锋利 3 以上的钻石剑能用这条配方
# 物品源走 source_patterns（带锚点精确绑定），matcher 只写组件条件
source_patterns:
  - "^minecraft-diamond_sword$"
matcher:
  type: component
  component: enchantments
  path: sharpness
  operator: '>='
  value: 3

stars:
  1:
    materials:
      # 材料：item_sources 先选材料，matcher 再复核「没被重命名过」
      - item_sources:
          - minecraft-copper_ingot
        matcher:
          type: component
          component: custom_name
          operator: absent
        amount: 3

WARNING

物品源用连字符（minecraft-copper_ingot），不是冒号。写成 minecraft:copper_ingot 会被解析器判为无效并静默丢弃，整个 item_sources 被丢空后等同于"不限来源"。详见 物品源用连字符，组件 ID 用冒号。

附魔强化配方的 target.filter

enhancement_recipes/*.yml（与本页的 recipes/*.yml 是两套独立配方）的 target.filter 也接受通用物品匹配器：filter 里含 type 键时按匹配器解析，否则按原有的 Provider 自由键值对解释。

target:
  provider: equipment
  # 含 type 键 → 按通用物品匹配器解析
  filter:
    type: component
    component: enchantments
    operator: exists

target:
  provider: equipment
  # 不含 type 键 → 仍按 Provider 自由键值对解释（原有行为）
  filter:
    item_type: SWORD

可引用的锻造品质变量

target.filter 的 variable.<变量名> 键、target 的 matcher，以及配方 conditions，都能引用从目标物品 PDC 读到的锻造品质变量。这些变量来自 EmakiForge 写在物品上的 emakiforge 命名空间 PDC。

变量	类型	物品无锻造数据时	说明
forge_quality_id	string	""	品质档位标识。
forge_quality_display	string	""	品质显示名。
forge_quality_multiplier	double	1.0	品质倍率。
forge_recipe_id	string	""	锻造配方 ID。

每个变量都有三种等价写法，可任选其一：

规范名	点号写法（历史兼容）	简短写法
forge_quality_id	forge.quality_id	quality_id
forge_quality_display	forge.quality_display	quality_display
forge_quality_multiplier	forge.quality_multiplier	quality_multiplier
forge_recipe_id	forge.forge_recipe_id	无

点号写法为何保留

Forge 的 PDC 键已从 forge.quality_id 改名为 forge_quality_id（见 PDC 键名规范）。点号写法作为历史兼容别名保留，已写好的配置无需修改。新配置建议直接用规范名。

target:
  provider: equipment
  filter:
    # filter 是相等判定：只命中品质档位恰为 legendary 的物品
    variable.forge_quality_id: legendary

filter 只做相等判定

filter 里的每一项都是相等比较，不支持 >=、< 这类比较符。数值按数值比，其余按字符串忽略大小写比。写 variable.forge_quality_multiplier: '>= 1.5' 不会报错，但会拿字符串 ">= 1.5" 去和实际倍率比，永远不命中。

需要数值区间判断时，改用 target 的 matcher（type: variable_expr）或配方 conditions。

另有一个辅助变量 forge_quality_multiplier_valid：物品上的倍率能正常解析为有限正数时为 1，写坏了（非数值、负数、NaN）时为 0，同时 forge_quality_multiplier 回退为 1.0。用它可以区分"这件物品没锻造过"和"锻造数据坏了"。

filter 中引用不存在的键会导致整条规则不命中

filter 里写了既不是内置键、也不在变量表里的键名时，该条过滤直接判为不匹配。上表四个变量始终存在（无锻造数据时取默认值），因此可以安全引用。

NOTE

enhancement_recipes/ 这套配方的其余字段目前尚未在本文档站中说明，本节只覆盖它的 matcher 落位与可引用的锻造品质变量。

全局名称与 Lore 修改

这些操作在每次强化成功后都会应用到物品上，支持 %star%、%temper%、%max_temper%、%temper_color% 等占位符。

name_actions:
  - action: "append_suffix"
    value: " [+%star%]"

lore_actions:
  - action: "prepend"
    content:
      - "<gradient:#F2C46D:#C9703D>强化等级 +%star%</gradient>"
      - "<gray>锻印: %temper_color%%temper%/%max_temper%</gray>"

星级阶段定义（stars）

每个星级可以包含：

字段	说明
name	该星级的里程碑名称（可选，用于 GUI 展示）。
effects	效果列表（统一格式）。
materials	强化所需材料。
economy_override	覆盖该星级的经济费用（currencies 结构与顶层 economy 相同）。
actions	强化成功/失败时执行的动作，支持 success 和 failure 两个键。

材料字段

字段	类型	默认值	说明
material_id	string	按 id、单一来源或阶段索引派生	材料选择与阶段规则身份。显式填写可避免来源或配置形态变化时身份漂移。
count_key	string	material_id	数量聚合与消费身份。可与 material_id 不同。
item_sources	list	无	允许的材料物品来源。省略表示不限来源；旧的 item 字段会被规范化为此字段。
matcher	object	无	通用物品匹配器，只写组件、PDC、Lore 等非物品源条件。与同级 item_sources 取 AND，两者都省略时该材料永不命中。见 物品匹配器。
amount	integer	1	需要数量。设为 -1 表示不消耗，仅检测是否持有。
optional	boolean	false	是否为可选材料（不放也能强化）。
protection	boolean	false	放入后提供保护效果，失败时不降星。
temper_boost	integer	0	放入后额外提供的锻印等级，用于提升本次成功率。

materials:
  - item_sources:
      - "minecraft-copper_ingot"
    amount: 3
  # 保护材料：不消耗，仅检测持有
  - item_sources:
      - "minecraft-gold_nugget"
    amount: -1
    optional: true
    protection: true
  # 锻印材料：额外提供 1 级锻印加成
  - item_sources:
      - "minecraft-potion"
    amount: -1
    optional: true
    temper_boost: 1

效果类型

type	说明
variables	表达式引擎变量（用于 Lore 渲染、名称/Lore 模板和占位符上下文，不会自动写入 Attribute PDC）。
ea_attribute	EmakiAttribute PDC 属性（显式覆盖）。
es_skill	EmakiSkills 技能附加；payload 使用 es_skills 列表。
lore_action	对物品 Lore 的修改。
name_action	对物品名称的修改。

当前效果语义边界：

• variables 只提供文本、占位符和动作模板上下文，不会自动成为 Attribute PDC 属性。
• 需要真实属性输出时，必须显式配置 type: "ea_attribute" 和 ea_attributes。
• 技能附加使用 type: "es_skill"，但具体技能 ID 写在 es_skills 列表中。

Lore 操作策略

强化配方中的 Lore 操作遵循以下策略，确保每种属性在 Lore 中始终只有一行：

场景	操作	说明
★1 首次添加	action: "append"	首次使用 append 添加属性行。
★2+ 更新已有行	action: "replace_line"	通过 anchor 匹配已有行并替换为新数值。
里程碑解锁新属性	先 replace_line 再 append	先更新旧行，再 append 添加新属性行。

星级示例

stars:
  # ★1: 首次添加属性行
  1:
    effects:
      - type: "variables"
        variables:
          physical_attack: 4
      - type: "lore_action"
        lore_actions:
          - action: "append"
            content:
              - "<gray>物理伤害: <gold>+4</gold></gray>"
    materials:
      - item_sources:
          - "minecraft-copper_ingot"
        amount: 1
      - item_sources:
          - "minecraft-gunpowder"
        amount: 2

  # ★2: 使用 replace_line 更新已有行
  2:
    effects:
      - type: "variables"
        variables:
          physical_attack: 4
      - type: "lore_action"
        lore_actions:
          - action: "replace_line"
            anchor: "物理伤害:"
            content:
              - "<gray>物理伤害: <gold>+8</gold></gray>"
    materials:
      - item_sources:
          - "minecraft-copper_ingot"
        amount: 1

  # ★6 里程碑: 解锁新属性
  6:
    name: "觉醒"
    effects:
      - type: "variables"
        variables:
          physical_attack: 6
          physical_crit_rate: 3
      - type: "ea_attribute"
        ea_attributes:
          physical_attack: 28.0
          physical_crit_rate: 3.0
      - type: "es_skill"
        es_skills:
          - "weapon_aura"
      - type: "lore_action"
        lore_actions:
          # 先更新已有行
          - action: "replace_line"
            anchor: "物理伤害:"
            content:
              - "<gray>物理伤害: <gold>+28</gold></gray>"
          # 再添加新属性行
          - action: "append"
            content:
              - "<gray>暴击率: <gold>+3%</gold></gray>"
              - "<yellow>★ 觉醒: 解锁武器光环</yellow>"
    materials:
      - item_sources:
          - "minecraft-iron_ingot"
        amount: 3
    actions:
      success:
        - 'send_message text="<gold>★ 觉醒！装备提升至 +%star%！</gold>"'
        - "play_sound sound=minecraft:entity.player.levelup volume=1 pitch=1.5"
      failure:
        - 'send_message text="<red>强化失败，装备等级下降至 +%star%。</red>"'

分支配方

强化配方支持分支树系统，允许在特定星级分叉为不同的强化路线。详见 分支树系统 文档。

完整示例

id: "weapon_physical"
display_name: "<gold>物理武器强化</gold>"
gui_template: "strengthen_gui"

economy:
  enabled: true
  currencies:
    - provider: "vault"
      currency_id: ""
      base_cost: 320
      cost_formula: "%base_cost% * %star%"
      display_name: "<gold>金币</gold>"

limits:
  max_star: 12
  max_temper: 4
  temper_chance_bonus_per_level: 5.0
  success_chance_cap: 90.0

success_rates:
  1: 100.0
  2: 100.0
  3: 95.0
  4: 85.0
  5: 75.0
  6: 60.0
  7: 45.0
  8: 32.0
  9: 22.0
  10: 14.0
  11: 8.0
  12: 4.0

slot_groups:
  - "weapon"

name_actions:
  - action: "append_suffix"
    value: " [+%star%]"

lore_actions:
  - action: "prepend"
    content:
      - "<gradient:#F2C46D:#C9703D>强化等级 +%star%</gradient>"
      - "<gray>锻印: %temper_color%%temper%/%max_temper%</gray>"

stars:
  1:
    effects:
      - type: "variables"
        variables:
          physical_attack: 4
      - type: "lore_action"
        lore_actions:
          - action: "append"
            content:
              - "<gray>物理伤害: <gold>+4</gold></gray>"
    materials:
      - item_sources:
          - "minecraft-copper_ingot"
        amount: 1
  2:
    effects:
      - type: "variables"
        variables:
          physical_attack: 4
      - type: "lore_action"
        lore_actions:
          - action: "replace_line"
            anchor: "物理伤害:"
            content:
              - "<gray>物理伤害: <gold>+8</gold></gray>"
    materials:
      - item_sources:
          - "minecraft-copper_ingot"
        amount: 2