图纸与材料

Forge 通过图纸限制配方入口，通过材料决定锻造成本、品质和附加效果。图纸通常代表"会不会做"，材料代表"用什么做、做得多好"。

图纸要求

blueprint_requirements:
  - item_sources:
      - "minecraft-enchanted_book"
    amount: 1

字段	类型	说明
id	string	可选。图纸要求的稳定身份键，计数按它聚合。见下方同一图纸的多种形态。
item_sources	list	允许的图纸物品来源。省略表示不限来源。
matcher	object	可选。通用物品匹配器，只写组件、PDC、Lore 等非物品源条件。与同级 item_sources 取 AND。见 物品匹配器。
amount	number	需要数量。

图纸不消耗，仅检测持有。用于实现"需要先获得配方图纸"的玩法。

同一图纸的多种形态

一种图纸有多种可接受形态时，写成多个 id 相同的条目，计数按 id 聚合，玩家持有任一形态即算满足：

blueprint_requirements:
  # 两种形态都算"烈焰之剑图纸"，各算一份
  - id: flame_sword_blueprint
    item_sources:
      - "minecraft-enchanted_book"
    amount: 1
  - id: flame_sword_blueprint
    item_sources:
      - "minecraft-paper"
    matcher:
      type: component
      component: custom_name
      operator: contains
      value: 烈焰之剑图纸
    amount: 1

这取代了过去把多种形态塞进同一个 matcher 的 any_of 的做法。

材料列表

materials:
  - item_sources:
      - "minecraft-iron_ingot"
    amount: 3
    capacity_cost: 5
    effects:
      - type: "variables"
        variables:
          physical_damage: 5
      - type: "ea_attribute"
        ea_attributes:
          physical_attack: 5.0

字段	说明
material_id	可选。材料的选择与 lookup 稳定身份；可独立于 count_key / audit_id。见下方材料身份键。
count_key	可选。数量聚合与消费身份；省略时回退到解析出的 material_id。
audit_id	可选。写入成品 PDC 并用于刷新 lookup 的审计身份；省略时回退到解析出的 material_id。
item_sources	允许的材料物品来源列表。省略表示不限来源；未声明身份时参与派生材料身份。
matcher	可选。通用物品匹配器，只写组件、PDC、Lore 等非物品源条件。与同级 item_sources 取 AND。见 物品匹配器。
amount	需要数量。
capacity_cost	该材料占用的锻造容量。
optional	是否为可选材料（默认 false）。
effects	此材料提供的效果列表。

item_sources 与 matcher 都省略时，该材料条目永不命中。

容量与可选材料

forge_capacity 限制配方允许投入的材料总容量。所有材料的 capacity_cost 总和不能超过此值。

forge_capacity: 35

建议：

• 基础配方容量小，避免玩家一次投入过多难以理解。
• 高级配方可以给更多可选材料空间，让玩家追求更高品质。
• 可选材料要在 GUI 中展示清楚，否则玩家不知道为什么品质变化。

材料匹配建议

• 使用稳定的 item_sources 格式（"提供者-物品ID"）。
• 贵重材料建议开启精确匹配，避免玩家用伪造物品替代。
• 如果材料来自其他模块，确认该模块加载顺序早于 Forge。

材料身份键

每条材料有三类可独立配置的身份：material_id 决定材料选择与 lookup，count_key 决定数量聚合与消费，audit_id 写入成品 PDC 并用于锻造审计/刷新 lookup。未填写时按以下顺序补齐：

1. material_id 优先取显式 material_id，再回退到 count_key / audit_id、item_sources 简写，最后才是 matcher 内容摘要。
2. count_key 省略时使用解析出的 material_id。
3. audit_id 省略时使用解析出的 material_id。

纯 matcher 材料请显式写 material_id

一条材料只写 matcher、不写 item_sources 时，材料身份会回退到 matcher 摘要——随 matcher 内容漂移。之后只要改动 matcher，已经锻造好的物品在刷新时可能报告材料缺失。

给这类材料显式写 material_id；需要把选择、消费聚合和审计刷新拆开时，再分别写 count_key 与 audit_id。Forge 读取旧审计记录时按 audit_id → material_id → count_key → 旧 material_item / source 依次回退；非完整 canonical 记录在成功解析后会请求刷新回写，解析不到材料则保留原物品并告警，不会用不完整数据覆盖。

通用物品匹配器（matcher）

blueprint_requirements[] 和 materials[] 的判定都由两个同级字段合成，取 AND：item_sources 只写允许的物品源，matcher 只写组件 / PDC / Lore 等非物品源条件。完整语法（类型全集、operator、path、嵌套写法）见 物品匹配器。

WARNING

matcher 内部不能写物品源条件。type: item_source / item_sources / source / sources 会被解析器拒绝并告警，该 matcher 恒不匹配。

materials:
  # 窄条件写在前面：附了锋利的铁锭才吃这一条
  - material_id: enchanted_iron_ingot
    item_sources:
      - "minecraft-iron_ingot"
    matcher:
      type: component
      component: enchantments
      path: sharpness
      operator: '>='
      value: 3
    amount: 1
    capacity_cost: 10
    effects:
      - type: "variables"
        variables:
          physical_damage: 15
  # 宽条件写在后面：普通铁锭
  - item_sources:
      - "minecraft-iron_ingot"
    amount: 3
    capacity_cost: 5

上例两条材料的物品源相同，所以窄条件那条必须显式写 material_id——否则两条会派生出同一个身份键，计数会混到一起。

DANGER

材料按配方内声明顺序首命中，先声明的宽条件会遮蔽后声明的窄条件。

Forge 对每个投入的物品从上往下找第一条匹配的材料，找到就停。如果上例把普通铁锭那条写在前面，附魔铁锭也会先命中它，后面的窄条件永远轮不到。

规则很简单：窄条件写在前面，宽条件写在后面。 图纸要求（blueprint_requirements）用同样的首命中逻辑，顺序要求一致。

材料效果

材料可以附带效果（effects），在锻造成功后对结果物品产生影响。效果定义在材料配置的 effects 列表中。

效果类型

类型	说明
variables	为锻造结果贡献文本/模板变量值，不会自动写入 Attribute PDC。
ea_attribute	向结果物品写入 PDC 属性（需要 EmakiAttribute）。
es_skill	向结果物品绑定技能 ID（需要 EmakiSkills）；payload 使用 es_skills 列表。
name_action	对结果物品的名称执行操作。
lore_action	对结果物品的 Lore 执行操作。
quality_modify	修改品质结果（强制或设置下限）。
capacity_bonus	贡献额外锻造容量（材料本身 capacity_cost 为 0）。

NOTE

效果值的最终计算公式：配置值 × 材料数量 × 品质倍率。这适用于 variables 和 ea_attribute 效果，但两者语义不同：variables 只用于文本/模板上下文，真实属性输出必须写在 ea_attributes。

variables 效果

向锻造结果注入变量值，这些值可以被品质倍率影响，也可以在 lore_actions 和 name_actions 模板中使用。

effects:
  - type: "variables"
    variables:
      fire_damage: 10
      fire_resistance: 5

ea_attribute 效果

通过 EmakiAttribute 的权威 API 向结果物品写入结构化 PDC 属性层（需要安装 EmakiAttribute）。

effects:
  - type: "ea_attribute"
    ea_attributes:
      physical_attack: 15.0
      physical_defense: 5.0

当前配置线不再使用 ea_attribute_meta。属性值最终为 配置值 × 材料数量 × 品质倍率。EmakiAttribute 未安装时该效果走 no-op 路径，锻造照常完成但不写入属性。

es_skill 效果

向结果物品绑定技能 ID（需要安装 EmakiSkills）。

effects:
  - type: "es_skill"
    es_skills:
      - "fire_slash"
      - "flame_shield"

当前推荐只使用 es_skills 列表写法；旧的单个 es_skill 字段不再作为当前文档推荐形式。

name_action 效果

对锻造结果物品的名称执行操作，支持 CoreLib 名称操作系统的所有动作类型。

effects:
  - type: "name_action"
    name_actions:
      - action: "prepend_prefix"
        value: "<red>烈焰 </red>"
      - action: "append_suffix"
        value: " <gray>[锻造]</gray>"

lore_action 效果

对锻造结果物品的 Lore 执行操作，支持 CoreLib Lore 操作系统的所有动作类型。

effects:
  - type: "lore_action"
    lore_actions:
      - action: "insert_below"
        anchor: "锻造属性:"
        content:
          - "<gray>物理伤害: <red>+%physical_damage%</red></gray>"
          - "<gray>生命值: <green>+%max_health%</green></gray>"

模板变量

在 name_actions 的 value 字段和 lore_actions 的 content 字段中，可以使用以下变量：

变量	说明
%quality%	品质名。仅在品质档位解析成功时注入。
%quality_name%	品质显示名，与 %quality% 取值相同。
%quality_multiplier%	品质倍率，按 0.## 格式化。
%multiplier%	品质倍率的简写别名。
%变量名%	任何通过 variables 效果注入的变量值，已乘材料数量与品质倍率。

quality_modify 效果

修改品质计算结果。支持两种模式：

模式	说明
force	强制将品质设为指定等级，忽略随机结果。
minimum	设置品质下限，随机结果低于此值时提升到该等级。

effects:
  - type: "quality_modify"
    mode: "force"
    tier: "史诗"

IMPORTANT

当前推荐字段名是 tier。旧的 quality 不再作为当前文档推荐写法。force 模式会跳过保底计数器逻辑。

capacity_bonus 效果

携带此效果的材料本身 capacity_cost 为 0，并向配方贡献额外容量。

effects:
  - type: "capacity_bonus"
    value: 20

IMPORTANT

当前推荐字段名是 value。旧的 amount、bonus、capacity 不再作为当前文档推荐写法。

完整示例

id: "example_recipe"
display_name: "<gold>烈焰之剑锻造配方</gold>"
forge_capacity: 35

blueprint_requirements:
  - item_sources:
      - "minecraft-enchanted_book"
    amount: 1

materials:
  - item_sources:
      - "minecraft-iron_ingot"
    amount: 3
    capacity_cost: 5
    effects:
      - type: "variables"
        variables:
          physical_damage: 5
          max_health: 2
      - type: "ea_attribute"
        ea_attributes:
          physical_attack: 5.0
          max_health: 2.0
      - type: "lore_action"
        lore_actions:
          - action: "insert_below"
            anchor: "锻造属性:"
            content:
              - "<gray>物理伤害: <red>+%physical_damage%</red></gray>"
              - "<gray>生命值: <green>+%max_health%</green></gray>"

  - item_sources:
      - "minecraft-blaze_powder"
    amount: 1
    capacity_cost: 10
    effects:
      - type: "variables"
        variables:
          fire_damage: 10
          critical_chance: 5
      - type: "ea_attribute"
        ea_attributes:
          fire_damage: 10.0
          physical_crit_rate: 5.0
      - type: "es_skill"
        es_skills:
          - "flame_strike"
      - type: "name_action"
        name_actions:
          - action: "prepend_prefix"
            value: "<red>烈焰 </red>"
      - type: "lore_action"
        lore_actions:
          - action: "insert_below"
            anchor: "锻造属性:"
            content:
              - "<red>火焰伤害: +%fire_damage%</red>"