Recipes

Forge recipes define blueprint requirements, material entries, capacity, quality rules, result items, metadata operations, and actions. Recipe files are stored in recipes/*.yml.

Main fields

Field	Description
id	Unique recipe id.
display_name	Recipe display name.
forge_capacity	Total capacity limit for materials.
blueprint_requirements	Required blueprint items.
materials	Required or optional material entries.
optional_material_limit	Maximum optional material types.
quality	Quality pool and pity configuration.
success_rate	Forge success rate in percent. Defaults to 100 (always succeeds).
failure_outcomes	Failure outcome plans, meaningful only when success_rate < 100.
result.success.outputs	Success-branch output list. Forge uses the first entry as the primary result.
result.success.name_actions	Name operation chain for the result item.
result.success.lore_actions	Lore operation chain for the result item.
result.success.actions	Actions executed after result generation.
actions	Pre, success, and failure actions.
permission	Optional permission requirement.

Result output

When result.success.outputs is configured, a successful forge creates the first entry as the primary result item and attaches the forge layer snapshot.

The bundled forge_gui template only provides blueprint and material slots; it has no target equipment input slot. When using the bundled GUI you must configure result.success.outputs, otherwise no forge result can be produced.

Success rate and failure outcomes

success_rate defaults to 100, meaning the forge always succeeds. Setting it below 100 makes forging able to fail, in which case one plan is picked from failure_outcomes by 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

Outcome types handled distinctly by the current implementation:

type	Behavior	params
return_materials	Return materials at return_rate.	return_rate, default 1.0.
partial_consume	Partially return materials at return_rate.	return_rate, default 0.5.
consume_materials	Consume everything, return nothing.	none.

Without failure_outcomes, the default is return_materials with a full refund. Other type values do not raise an error but are treated as a full material refund.

Quality configuration

Note the recipe-level field names differ from the global config: the pool field is custom_pool and the pity threshold field is attempts.

quality:
  enabled: true
  custom_pool:
    - "Common-70-1.0"
    - "Fine-25-1.05"
    - "Epic-5-1.15"
  guarantee:
    enabled: true
    attempts: 60
    minimum: "Flawless"

Result name and lore actions

result.success.name_actions and result.success.lore_actions execute name and lore operations on the result item after a successful forge.

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>Quality: <white>%quality_name%</white></gray>"
          - "<gray>Multiplier: <white>%quality_multiplier%</white></gray>"

Recipe result actions, material effect actions, and quality item_meta actions are merged and then applied to the result item together.

Available template variables

Variable	Description
%quality%	Quality tier name. Injected only when a quality tier resolved.
%quality_name%	Quality display name, same value as %quality%.
%quality_multiplier%	Quality multiplier, formatted as 0.##.
%multiplier%	Short alias of the quality multiplier.
%<stat_id>%	Any variable injected through material variables effects, already scaled by material amount and quality multiplier.

Minimal example

id: "flame_sword"
display_name: "<red>Flame Sword</red>"
forge_capacity: 10
blueprint_requirements:
  - item_sources:
      - "minecraft-paper"
    amount: 1
materials:
  - item_sources:
      - "minecraft-blaze_rod"
    amount: 3
    capacity_cost: 5
    effects:
      - type: "variables"
        variables:
          fire_damage: 10
      - type: "lore_action"
        lore_actions:
          - action: "append"
            content:
              - "<red>Fire Damage: +%fire_damage%</red>"
optional_material_limit: 2
quality:
  enabled: true
  custom_pool:
    - "Common-80-1.0"
    - "Fine-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>Quality: <white>%quality_name%</white></gray>"
actions:
  success:
    - 'sendmessage text="<green>Flame power infused into the weapon."'

Action nodes

Node	Trigger
actions.pre	Before recipe execution.
actions.success	After successful forge.
actions.failure	After failed forge.
result.success.actions	When the result is generated or applied.

The successful result chain runs in this order: result.success.actions → actions.success → quality actions. Actions inside each list run serially, and each stage waits for the previous stage to finish. Forge reads the final stack from the mutable item_target holder and delivers it only after all three stages settle. This lets EmakiItem component actions safely mutate the forge result without an older stack being delivered early. Failed action batches are logged but do not discard an already generated forge result.