配方系统

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

主要字段

字段	说明
id	配方唯一 ID。
display_name	配方显示名。
blueprint_requirements	图纸要求列表，每项包含 item_sources 和 amount。
materials	材料列表或材料规则。
forge_capacity	锻造容量，限制投入材料规模。
optional_material_limit	可选材料数量上限。
condition_type	条件组合方式。
condition_required_count	需要满足的条件数量。
conditions	条件列表。
quality	品质配置。详见品质系统文档。
result.item_sources	输出物品来源。为空时表示目标输入模式。
result.actions	结果生成后执行的动作列表。
result.meta_actions	结果元数据动作，包含 name_actions 和 lore_actions。
actions.pre	锻造前动作。失败时中止锻造并触发 failure。
actions.success	成功动作。
actions.failure	失败动作。
permission	使用该配方需要的权限。

目标输入模式

result.item_sources 为空时，表示配方不会创建全新物品，而是对玩家放入的目标装备执行锻造重建。

适合：

• 给已有武器添加锻造品质。
• 让材料改变装备属性。
• 给装备写入 forge layer。
• 保留原装备的强化、宝石、套装等其他模块状态。

固定输出模式

如果 result.item_sources 指向某个物品，则锻造成功后生成该物品。

适合：

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

品质配置

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

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

tiers 格式为 "品质名-权重-倍率" 的字符串列表。权重越大越常见，倍率影响材料效果数值。

建议：

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

条件和权限

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

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

动作节点

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

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'

结果元数据动作（meta_actions）

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

result:
  item_sources: null
  meta_actions:
    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>%player_name%</white></gray>"

name_actions 和 lore_actions 的操作类型与 CoreLib 名称/Lore 操作系统一致。

可用模板变量

变量	说明
%quality%	品质 ID。
%quality_name%	品质显示名。
%multiplier%	品质倍率。
%player_name%	执行锻造的玩家名称。
%player_uuid%	执行锻造的玩家 UUID。
{变量名}	材料效果注入的变量值。

最小示例

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
conditions: []
quality:
  enabled: true
  tiers:
    - "普通-80-1.0"
    - "精良-20-1.05"
result:
  item_sources: null
  meta_actions:
    name_actions:
      - action: "append_suffix"
        value: " <gray>[%quality_name%]</gray>"
    lore_actions:
      - action: "append"
        content:
          - ""
          - "<gray>锻造品质: <white>%quality_name%</white></gray>"
          - "<gray>锻造者: <white>%player_name%</white></gray>"
actions:
  success:
    - 'sendmessage text="<green>烈焰力量被注入武器。"'