配方系统

Forge 配方定义一次锻造需要什么、如何判定、消耗什么、产出什么、成功或失败后执行哪些动作。配方文件通常位于 recipes/*.yml。

主要字段

字段	说明
id	配方唯一 ID。
display_name	配方显示名。
blueprint_requirements	图纸要求列表，每项包含 item_sources 和 amount。
materials	材料列表或材料规则。
forge_capacity	锻造容量，限制投入材料规模。
optional_material_limit	可选材料数量上限。
condition.type	条件组合方式。
condition.required_count	需要满足的条件数量。
condition.entries	条件列表。
quality	品质配置。详见品质系统文档。
success_rate	锻造成功率，百分比。默认 100（必定成功）。
failure_outcomes	失败结果方案列表，仅在 success_rate < 100 时有意义。
result.success.outputs	成功分支输出物品列表。Forge 使用第一项作为主产物。
result.success.name_actions	对结果物品名称执行的动作链。
result.success.lore_actions	对结果物品 Lore 执行的动作链。
result.success.actions	结果生成后执行的动作列表。
actions.pre	锻造前动作。失败时中止锻造并触发 failure。
actions.success	成功动作。
actions.failure	失败动作。
permission	使用该配方需要的权限。

结果输出

result.success.outputs 配置输出物品来源后，锻造成功时生成其中第一项作为主产物，并附加锻造层快照。

适合：

• 用材料合成一把新武器。
• 用图纸制造固定装备。
• 产出 EmakiItem 或外部插件物品。

内置 forge_gui 模板只提供图纸槽和材料槽，不提供目标装备输入槽。使用内置 GUI 时必须配置 result.success.outputs，否则无法生成锻造结果。

成功率与失败结果

success_rate 默认 100，表示必定成功。设为低于 100 的值后，锻造有概率失败，此时按 failure_outcomes 的 weight 加权随机选取一个方案。

success_rate: 70
failure_outcomes:
  - type: "return_materials"
    weight: 50
    params:
      return_rate: 1.0
  - type: "partial_consume"
    weight: 30
    params:
      return_rate: 0.5
  - type: "consume_materials"
    weight: 20

当前实现会区分处理的方案类型：

type	行为	params
return_materials	按 return_rate 返还材料。	return_rate，默认 1.0。
partial_consume	按 return_rate 部分返还材料。	return_rate，默认 0.5。
consume_materials	全部消耗，不返还任何材料。	无。

未配置 failure_outcomes 时，默认按 return_materials 全额返还。填写其他 type 时不会报错，但会按全额返还材料处理。

品质配置

品质系统的完整说明请参见品质系统文档。配方中的典型结构：

quality:
  enabled: true
  custom_pool:
    - "普通-70-1.0"
    - "精良-25-1.05"
    - "史诗-5-1.15"
  guarantee:
    enabled: true
    attempts: 10
    minimum: 精良

配方级品质池字段是 custom_pool，保底阈值字段是 attempts；全局 config.yml 中对应的字段分别是 tiers 和 threshold。custom_pool 使用 "品质名-权重-倍率" 字符串写法，为空时使用全局品质池。

建议：

• 普通品质权重大，稀有品质权重小。
• 高价值配方提供保底，避免玩家长期没有正反馈。
• 品质 ID 要和展示、属性、动作配置保持一致。

条件和权限

配方可以通过 permission 和 condition 限制使用者。例如：

• 只有铁匠职业能使用。
• 玩家等级达到 30。
• 目标装备属于某个类型。
• 必须在特定世界或区域。
• 必须拥有某个 PDC 标记。

动作节点

节点	触发时机
actions.pre	配方开始执行前。如果 pre 阶段动作失败，锻造中止并触发 failure。
actions.success	锻造成功后。
actions.failure	锻造失败后。
result.success.actions	结果物品生成或应用时（在 actions.success 之前触发）。

成功结果链按 result.success.actions → actions.success → 品质动作的顺序执行。每个动作列表内部串行执行，下一阶段会等待上一阶段全部完成；三个阶段都结束后，Forge 才从可变 item_target holder 读取最终物品并交付。因此 Item component 动作可以安全修改锻造结果，不会出现动作尚未完成就提前发放旧物品的情况。动作批次失败会记录警告，但不会吞掉已经生成的锻造结果。

actions.pre 失败时，错误消息中可用变量：%reason%、%action%、%line%。

示例：

actions:
  pre:
    - 'sendmessage text="<gray>锻造开始……"'
  success:
    - 'sendtitle title="<green>锻造成功" subtitle="<gray>你的装备已被重铸"'
    - 'playsound sound=BLOCK_ANVIL_USE volume=1 pitch=1'
  failure:
    - 'sendmessage text="<red>锻造失败，材料已损毁。"'
    - 'playsound sound=ENTITY_VILLAGER_NO volume=1 pitch=1'

结果名称与 Lore 动作

result.success.name_actions 与 result.success.lore_actions 用于在锻造成功后对结果物品执行名称和 Lore 操作。

result:
  success:
    outputs: []
    name_actions:
      - action: "prepend_prefix"
        value: "<light_purple>[%quality_name%]</light_purple> "
    lore_actions:
      - action: "append"
        content:
          - ""
          - "<gray>锻造品质: <white>%quality_name%</white></gray>"
          - "<gray>品质倍率: <white>%quality_multiplier%</white></gray>"

name_actions 和 lore_actions 的操作类型与 CoreLib 名称/Lore 操作系统一致。配方结果动作、材料效果动作和品质 item_meta 动作会合并后统一应用到结果物品上。

可用模板变量

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

最小示例

id: flame_sword
display_name: '<red>烈焰剑锻造'
permission: emakiforge.recipe.flame_sword
blueprint_requirements:
  - item_sources:
      - "minecraft-PAPER"
    amount: 1
materials:
  - item_sources:
      - "minecraft-BLAZE_ROD"
    amount: 3
forge_capacity: 10
optional_material_limit: 2
condition:
  type: all_of
  entries: []
quality:
  enabled: true
  custom_pool:
    - "普通-80-1.0"
    - "精良-20-1.05"
result:
  success:
    outputs:
      - item_sources:
          - "minecraft-DIAMOND_SWORD"
        amount: 1
    name_actions:
      - action: "append_suffix"
        value: " <gray>[%quality_name%]</gray>"
    lore_actions:
      - action: "append"
        content:
          - ""
          - "<gray>锻造品质: <white>%quality_name%</white></gray>"
actions:
  success:
    - 'sendmessage text="<green>烈焰力量被注入武器。"'