Blueprints and Materials

Forge recipes use blueprint requirements and material entries. Materials can consume item sources, occupy forge capacity, contribute variables, write Attribute payloads, attach Skills, and modify name or lore.

Blueprint requirements

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

Field	Description
item_sources	Allowed blueprint item sources. Omit it and the item source is unrestricted.
matcher	Non-item-source conditions (component, PDC, lore, variable). ANDed with the sibling item_sources; the entry never matches only when both are omitted. See Item Matcher.
amount	Required amount.
id	Optional counting identity. Defaults to being derived from item_sources.

Blueprint requirements are checked before forging. They are suitable for recipe scrolls, unlock items, or profession certificates.

Accepting several forms of one blueprint

Write each acceptable form as its own entry sharing one id. Counts aggregate by id, so holding any one form satisfies the requirement instead of being read as two separate blueprints the player must hold at once.

blueprint_requirements:
  # Narrow form first: an official knowledge book carrying the marker
  - id: blueprint_accepted
    item_sources:
      - "minecraft-knowledge_book"
    amount: 1
    matcher:
      type: component
      component: custom_model_data
      path: "floats[0]"
      operator: "=="
      value: 1.0
  # Broad form last: a plain enchanted book
  - id: blueprint_accepted
    item_sources:
      - "minecraft-enchanted_book"
    amount: 1

This replaces the older approach of packing every form into one matcher's any_of.

Material list

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
  - item_sources:
      - "minecraft-fire_charge"
    amount: 1
    optional: true
    capacity_cost: 12
    effects:
      - type: "variables"
        variables:
          fire_damage: 12

Field	Description
item_sources	Allowed item sources for this material. Omit it and the item source is unrestricted; when no explicit identity is present, the sources help derive one.
matcher	Non-item-source conditions (component, PDC, lore, variable). ANDed with the sibling item_sources; the material never matches only when both are omitted. See Item Matcher.
material_id	Stable selection and lookup identity. It may be declared independently from count_key and audit_id.
count_key	Quantity aggregation and consumption identity. Defaults to the resolved material_id when omitted.
audit_id	Identity written into the forged-item audit data and used for refresh lookup. Defaults to the resolved material_id when omitted.
amount	Required amount.
capacity_cost	Forge capacity occupied by this material.
optional	Whether this material is optional.
effects	Effects contributed by this material.

General item matcher

item_sources and matcher are sibling fields on both blueprint_requirements[] and materials[], and both must hold (AND). Keep item sources in item_sources; matcher carries only component, PDC, lore, and variable conditions. Item source conditions written inside a matcher (type: item_source and its aliases) are rejected at load time with a warning and never match. Full syntax is in Item Matcher.

Material identity

The three identities are resolved independently but default from the same material identity:

1. material_id is taken from the explicit material_id, then count_key / audit_id, then the source shorthand, then a matcher digest.
2. count_key defaults to the resolved material_id when omitted.
3. audit_id defaults to the resolved material_id when omitted.

DANGER

A matcher-only material (no item_sources) should declare material_id explicitly. Otherwise its identity falls back to a matcher digest, so a later matcher edit changes the identity and an already-forged item can report that material as missing during refresh. Explicit identities keep selection, counting, and audit/refresh lookup stable while allowing their values to differ.

materials:
  # Narrow condition first: only iron ingots carrying Sharpness
  - item_sources:
      - minecraft-iron_ingot
    matcher:
      type: component
      component: enchantments
      path: sharpness
      operator: '>='
      value: 3
    amount: 1
    capacity_cost: 10
  # Broad condition last: plain iron ingots
  - item_sources:
      - "minecraft-iron_ingot"
    amount: 3
    capacity_cost: 5
  # Matcher-only material: pin the identity with material_id
  - material_id: inherited_sharpness_source
    matcher:
      type: component
      component: enchantments
      path: "minecraft:sharpness"
      operator: '>='
      value: 3
    amount: 1
    capacity_cost: 8

DANGER

Materials are first-match in declaration order, so a broad condition declared earlier shadows a narrower one declared later.

Forge scans materials top to bottom for each submitted item and stops at the first match. If the plain iron ingot entry above came first, enchanted iron ingots would match it too and the narrower entry would never be reached.

The rule is simple: narrow conditions first, broad conditions last. blueprint_requirements uses the same first-match logic and the same ordering requirement.

Capacity

forge_capacity: 35
optional_material_limit: 3

forge_capacity limits the total material capacity cost. optional_material_limit limits how many optional material types can be used in one forge.

Effect types

Type	Description
variables	Contribute text/template variable values. They do not automatically write Attribute PDC.
ea_attribute	Write attributes into the structured PDC layer through the EmakiAttribute authoritative API. Requires EmakiAttribute; otherwise this effect takes a no-op path.
es_skill	Attach EmakiSkills skills; payload uses the es_skills list.
name_action	Execute name operations on the result item.
lore_action	Execute lore operations on the result item.
quality_modify	Force or raise the minimum quality tier. Use tier for the target quality id.
capacity_bonus	Increase forge capacity limit. Use value for the capacity bonus.

Name action example

effects:
  - type: "name_action"
    name_actions:
      - action: "prepend_prefix"
        value: "<red>Flame </red>"
      - action: "append_suffix"
        value: " <gray>[Forged]</gray>"

Template variables

Available in name_actions value fields and lore_actions content fields:

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.
%<name>%	Any value injected through variables effects, already scaled by material amount and quality multiplier.

Design notes

• Use stable item_sources instead of display names, and pin material_id on matcher-only materials.
• Assign capacity costs according to material value.
• Keep optional material count limited so players cannot stack too many effects.
• Use variables for presentation and template context; use ea_attribute for real Attribute integration.
• Current examples should use es_skills as a list, not the old single es_skill form.
• Current Forge configs should not rely on ea_attribute_meta.
• Current quality_modify uses tier; current capacity_bonus uses value.