Skip to content
DarkBladeDev Docs

Modular Capabilities and State Variables

CraftingEngine decouples recipes from hardcoded block materials using Capabilities and State Variables. Rather than requiring an ANVIL or FURNACE directly, recipes require abstract traits like forging, heating, or pressure.

1. What are Capabilities?

Capabilities represent functional attributes that workstations or the environment provide:

+---------------------+           +------------------------+
| Recipe Requirements |           | Workstation Definition |
+---------------------+           +------------------------+
|  - forging          | <=======> | capabilities:          |
|  - high_temperature |           |   - forging            |
+---------------------+           |   - high_temperature   |
                                  +------------------------+

Why use Capabilities?

  • Multiple Stations, One Recipe: A single “Folded Steel” blueprint can be crafted at a humble Iron Anvil, a massive 3D Runic Forge, or an industrial power press, as long as they provide the forging capability.
  • Dynamic Tiering: Capabilities can define levels (e.g. heating_tier_1, heating_tier_2).
  • Conditional Activation: A workstation may provide a capability only when powered by redstone or heated by lava below.

2. Defining Capabilities (capabilities/*.yml)

Capabilities can be defined as standalone YAML files inside plugins/CraftingEngine/capabilities/:

id: "high_temperature"
name: "<gradient:#ff8a80:#ff5252>High Temperature</gradient>"
description: "Requires ambient heat exceeding 300°C."


# Conditions required for this capability to be considered active
evaluations:
  - type: "BLOCK_STATE"
    offset: [0, -1, 0] # Inspect block underneath the station
    materials:
      - "LAVA"
      - "MAGMA_BLOCK"
      - "SOUL_FIRE"


variables:
  temperature:
    initial: 350.0
    decay_rate: 1.5

3. State Variables Storage

Workstations and active processes maintain isolated, sealed state variable maps:

  • temperature: Current heat level in °C.
  • fluid_level: Millibuckets (mB) of fluid present in a basin.
  • pressure: Hydraulic or steam pressure in PSI.
  • durability: Structural integrity of custom workstation blocks.

Referencing Variables in Blueprints

You can check state variables directly within blueprint condition expressions:

requirements:
  conditions:
    - id: "heat_check"
      environment: "craftingengine"
      condition: "capability.temperature >= 250"

4. Consumable Capabilities & Drain Policies (v2.7.0+)

By default, workstation capabilities are permanently available as long as environmental conditions are satisfied. However, advanced crafting often involves consumable workstation resources—such as forge heat, mana reserves, water tanks, or hydraulic pressure—that deplete as recipes are crafted.

CraftingEngine provides CapabilityDrainPolicy to govern dynamic capability consumption and exhaustion:

+-----------------------------------------------------------------------------+
|                          CAPABILITY DRAIN LIFECYCLE                         |
+-----------------------------------------------------------------------------+
|                                                                             |
|  1. PRE-EXECUTION CHECK & PER-USE DRAIN                                     |
|     - Verifies station state satisfies: variable >= min_threshold + per_use |
|     - Deducts drain_per_use immediately upon process start.                 |
|                                                                             |
|  2. CONTINUOUS PER-TICK DRAIN                                               |
|     - Deducts drain_per_tick (scaled by delta time) during active stages.   |
|     - Ticks continuously while crafts are executing.                        |
|                                                                             |
|  3. EXHAUSTION & RECOVERY ROUTING                                           |
|     - If variable falls below min_threshold:                                |
|       * Emits CAPABILITY_EXHAUSTED event to Process Flight Recorder.        |
|       * Diverts active stage to failure_transition (salvage stage).         |
|       * If no recovery transition exists, terminates craft via fail policy. |
|                                                                             |
+-----------------------------------------------------------------------------+

Workstation Declaration Syntax

In stations/*.yml, configure capabilities with a nested drain: block:

capabilities:
  # Static capability (always available)
  - "forging"


  # Consumable capability governed by drain policy
  - high_temperature:
      drain:
        variable: "temperature"     # Tracked station state variable
        drain_per_second: 5.0       # Continuous drain rate (or drain_per_tick: 0.25)
        drain_per_use: 15.0         # Discrete deduction on process start
        min_threshold: 200.0        # Minimum level required to initiate/maintain craft

Drain Policy Configuration Properties

PropertyTypeDefaultDescription
variableStringRequiredState variable key in StationState tracked and mutated by this capability.
drain_per_secondDouble0.0Continuous drain rate per second. Automatically converted to drain_per_tick = rate / 20.0.
drain_per_tickDouble0.0Direct continuous drain rate applied per server tick.
drain_per_useDouble0.0Discrete amount subtracted immediately upon process initiation (scaled by multi-craft multiplier).
min_thresholdDouble0.0Minimum threshold below which the capability becomes unavailable (isAvailable == false).

Capability Exhaustion & Salvage Transitions

When a workstation runs out of a consumable capability mid-craft (e.g. the temperature drops below min_threshold while forging):

  1. The engine logs a CAPABILITY_EXHAUSTED telemetry event in the Flight Recorder.
  2. If the current active stage defines a failure_transition, the process diverts immediately to the salvage stage without recursive loops: 
    stages:
      - id: "high_heat_forging"
        duration: "10s"
        failure_transition: "cooling_salvage"
  3. If no failure_transition is defined, the process terminates and enforces the blueprint’s policies.failure policy (REFUND_INPUTS or DESTROY_INPUTS).

Next Steps