Skip to content
DarkBladeDev Docs

Process Blueprints Reference

Process blueprints are the core crafting definitions in CraftingEngine. Stored as YAML files inside plugins/CraftingEngine/processes/, they define multi-stage crafting workflows, item requirements, tools, catalysts, and station conditions.

1. Top-Level Schema Structure

id: "infernal_blade"
name: "<gradient:#ff4500:#ff8c00>Infernal Greatsword</gradient>"
priority: 10
station_id: "example_runic_forge"
close_gui_on_craft: true
cancel_on_gui_close: false


policies:
  multiplayer: "INDIVIDUAL" # INDIVIDUAL | CO_OP
  failure: "REFUND_INPUTS"  # DESTROY_INPUTS | REFUND_INPUTS | PRODUCE_FAILURE_OUTPUTS
  obtaining: "DROP_IN_INVENTORY" # DROP | DROP_IN_WORLD | DROP_IN_INVENTORY | INTERACTION
  abandonment:
    max_distance: 6.0
    grace_period_ticks: 60
  tool_breakage:
    allow_hotbar_swap: true
    grace_period_ticks: 40


requirements:
  capabilities:
    - "high_temperature"
    - "forging"
  stations:
    - "example_runic_forge"
  conditions:
    - id: "night_time"
      environment: "minecraft"
      condition: "time_between"
      args: ["13000", "23000"]


inputs:
  - resource: "minecraft:netherite_ingot"
    quantity: 3
    mode: "CONSUME"
  - resource: "ia:infused_ruby"
    quantity: 1
    mode: "RESERVE" # Transactional reservation (v2.8.0)


tools:
  - resource: "minecraft:netherite_pickaxe"
    quantity: 1


catalysts:
  - resource: "minecraft:lava_bucket"
    quantity: 1
    mode: "PRESERVE"


triggers:
  - type: "INTERACTION"


stages:
  # See Stages & Transitions Guide for stage details
  - id: "heating"
    duration: "4s"
  - id: "hammering"
    mode: "MANUAL_ACTION"
    action_type: "LEFT_CLICK_BLOCK"
    required_strikes: 6


outputs:
  - resource: "minecraft:netherite_sword"
    display: "<gradient:#ff4500:#ff8c00><b>Infernal Greatsword</b></gradient>"
    quantity: 1
    type: "SUCCESS"
    inheritance: # Property inheritance pipeline (v2.9.0)
      - target_key: "attack_bonus"
        source_key: "ruby_power"
        from: "ia:infused_ruby"
        mode: "MULTIPLY"
        factor: 1.5
        default: 10
      - target_key: "artisan"
        source_key: "crafter"
        mode: "COPY"

2. Detailed Field Specifications

Identity & Presentation

  • id (String, Required): Unique identifier used in commands, APIs, and GUI matrix binders.
  • name (String, Optional): Formatted display name supporting Adventure MiniMessage tags (gradients, hover text, hex colors).
  • priority (Integer, Default: 0): Controls sorting order in workstation recipe browser menus. Higher values appear first.
  • station_id (String, Optional): Restricts crafting to a specific workstation definition.

Operational Policies (policies)

  • multiplayer:
    • INDIVIDUAL: Only the initiating player can interact with and progress the crafting stages.
    • CO_OP: Allows multiple nearby players with valid tools to contribute strikes or actions.
  • failure:
    • REFUND_INPUTS: Returns all consumed inputs back to player inventory or drops them safely.
    • DESTROY_INPUTS: Deletes materials upon failure (hardcore crafting).
    • PRODUCE_FAILURE_OUTPUTS: Generates specific failure scrap (e.g. Slag, Charcoal).
  • obtaining:
    • DROP_IN_INVENTORY: Automatically places finished outputs into player inventory. Drops on ground if inventory is full.
    • DROP_IN_WORLD: Spawns physical dropped item entity on top of the workstation block.
    • INTERACTION: Leaves the output hovering or resting on the station until the player right-clicks to collect it.
  • abandonment:
    • max_distance: Distance in blocks the player can move away before abandonment countdown starts.
    • grace_period_ticks: Delay in server ticks (20 ticks = 1 second) before an abandoned craft is cancelled.
  • tool_breakage:
    • allow_hotbar_swap: If a player’s tool breaks mid-craft, allows swapping to an identical tool from their hotbar without aborting the process.
    • grace_period_ticks: Time window allowed to perform the hotbar tool swap.

Requirements (requirements)

  • capabilities: List of capability IDs (e.g. heating, cooling, crushing) that the workstation must actively satisfy.
  • stations: List of allowed workstation IDs or vanilla block materials (e.g. blacksmith_anvil, minecraft:cauldron).
  • conditions: Environmental checks evaluated before starting the process:
    • minecraft: Time of day, weather, biome, light level, height (Y coordinate).
    • worldguard: Region membership or flag verification.
    • papi: Custom PlaceholderAPI condition expressions.

Resources: Inputs, Tools & Catalysts

Inputs (inputs)

Materials required and handled by the process:

  • resource: Namespaced item identifier (Vanilla minecraft:iron_ingot, or external ia:custom_steel, oraxen:mythic_gem, eb:energy_core).
  • quantity: Amount required.
  • mode: Controls consumption and reservation behavior:
    • CONSUME (Default): Items are subtracted from the player or container upon process start (or deferred to ITEM_INSERTION stages).
    • PRESERVE: Items must be present in inventory/station to initiate and tick the process, but are never consumed.
    • RESERVE (v2.8.0+): Transactional Input Reservation. The required items are safely extracted into an isolated in-memory reservation buffer (ItemReservationManager) upon craft start:
      • Isolation: Prevents duplication exploits, mid-craft weapon swapping, or accidental ingredient loss during long minigames or manual stages.
      • Metadata Preservation: Retains all custom PDC tags, display names, custom lore, enchantments, and item durability intact.
      • Commit on Completion: When the process transitions to COMPLETED, reserved items are permanently committed (INPUT_COMMITTED).
      • Safe Release on Failure: If the craft is cancelled, abandoned, or fails under REFUND_INPUTS, reserved items are restored safely to the player inventory or naturally dropped in the world if full (ResourceReleasedEffect). Under DESTROY_INPUTS, the buffer is cleared.
      • Server Reload Protection: Server shutdowns and reloads automatically restore all active reservations to their owners, guaranteeing zero item loss.

Tools (tools)

Equipment required in hand or inventory to perform the craft:

  • resource: Namespaced tool identifier (e.g. minecraft:netherite_pickaxe, ia:blacksmith_hammer).
  • quantity: Quantity required (default: 1).
  • durability_cost: (Optional) Durability wear inflicted on the tool upon completion or per action. CraftingEngine supports multi-tool requirements simultaneously.

Catalysts (catalysts)

Reusable auxiliary items (e.g., fuel cells, reusable forging molds, runic lenses) that must be present in the station or nearby inventory without taking durability damage or being consumed.

Outputs & Property Inheritance (outputs)

Outputs define what the process yields upon success, byproduct generation, or failure:

outputs:
  - resource: "minecraft:netherite_sword"
    display: "<gradient:#ff4500:#ff8c00><b>Infernal Greatsword</b></gradient>"
    quantity: 1
    type: "SUCCESS" # SUCCESS | BYPRODUCT | FAILURE
    quality_scaling: # (Optional) Dynamic grading matrix
      thresholds:
        S: 0.90
        A: 0.75
        B: 0.50
    inheritance: # (v2.9.0+) Declarative metadata & PDC transfer
      - target_key: "attack_bonus"
        source_key: "ruby_power"
        from: "ia:infused_ruby"
        mode: "MULTIPLY"
        factor: 1.5
        default: 10
      - target_key: "artisan"
        source_key: "crafter"
        mode: "COPY"
      - target_key: "durability"
        mode: "EXPRESSION"
        expression: "source * 1.25 + 50"

Output Types (type)

  • SUCCESS: Standard output granted upon successful process completion.
  • BYPRODUCT: Extra secondary output (e.g. glass bottles, ashes, sawdust) granted alongside success.
  • FAILURE: Scrap or residue (e.g. Slag, Charcoal, Broken Hilt) granted when a process fails under policies.failure: PRODUCE_FAILURE_OUTPUTS.

Ingredient Property Inheritance Pipeline (v2.9.0+)

In modular RPG equipment forging, gem socketing, and alchemy, items carry dynamic attributes: purity ratings, artisan watermarks, or custom PersistentDataContainer (PDC) tags. Blueprints can declaratively inherit and scale these properties using inheritance: (or inheritance_rules:).

Rule Configuration Properties
PropertyAliasesDescription
target_keyto_key, target, toOutput property key written into the produced item’s PersistentDataContainer via NamespacedKey.
source_keyfrom_key, key, propertyMetadata key or PDC tag captured from the input ingredient. Defaults to target_key if omitted.
fromsource_resource, sourceSpecific ingredient resource ID (e.g. ia:infused_ruby) to read from, or * for any input (default: *).
mode-COPY (direct copy), MULTIPLY (multiply numeric value by factor), or EXPRESSION (evaluate math AST).
factor / expressionexprNumeric multiplier for MULTIPLY (e.g. 1.5) or mathematical expression for EXPRESSION (e.g. source * 1.25 + 50).
defaultdefault_valueSafe fallback StateValue applied if the ingredient lacks the requested property, preventing craft failure.
Metadata Snapshotting & Placeholder Injection
  • PDC Types Captured: ItemMetadataSnapshotter extracts all primitive PDC tags (INTEGER, DOUBLE, FLOAT, LONG, BYTE, SHORT, STRING), custom model data, display names, and durability from consumed or reserved ingredients into process variables.
  • Dynamic Text Placeholders: Inherited values are automatically injected into the output’s display: and lore lines using %key%, <key>, <inherited:key>, or {key}. For example: 
    display: "<gradient:#ffd700:#ffa500>Blade of %artisan%</gradient>"

Triggers (triggers)

Defines how a process is initiated:

  • INTERACTION: Player right-clicks the workstation block.
  • COMMAND: Triggered via /cfe process start <id>.
  • EVENT: Triggered by external Bukkit events (block break, entity kill, item drop).
  • AUTOMATIC: Ticked automatically when valid ingredients are placed into hopper or multiblock containers.
  • API: Initiated via developer Java API plugins.

3. Instant vs Multi-Stage Crafting

  • Instant Crafting: When the stages: block is omitted or left empty, the craft executes instantaneously. Players can shift-click to craft maximum stacks at once.
  • Multi-Stage Crafting: When stages: are declared, CraftingEngine initiates an active process instance with state tracking, holograms, timers, and step-by-step physical transformations.

Next Steps