Skip to content
DarkBladeDev Docs

Stages, Modes, and Non-Linear Transitions

CraftingEngine processes execute through a sequence of stages. Stages transform crafting from static timers into dynamic state machines with manual physical interactions, minigames, weighted probabilistic branching, and recovery routing.

1. Stage Execution Modes

CraftingEngine provides 5 distinct execution modes configured via the mode: key:

+-----------------------------------------------------------------------------+
|                            STAGE EXECUTION MODES                            |
+-----------------------------------------------------------------------------+
|                                                                             |
|  1. PASSIVE                                                                 |
|     Progresses automatically over time (duration: "5s", "1m").              |
|                                                                             |
|  2. MANUAL_ACTION                                                           |
|     Requires physical player strikes (left-click or right-click with tool). |
|                                                                             |
|  3. WAITING_FOR_CONDITION                                                    |
|     Pauses until an environmental or capability state is reached            |
|     (e.g., cauldron reaches 100°C or rain starts).                          |
|                                                                             |
|  4. MINIGAME                                                                |
|     Interactive arcade HUD with momentum meters or timing sweet spots.     |
|                                                                             |
|  5. ITEM_INSERTION                                                          |
|     Requires player to toss or insert specific mid-craft components.        |
|                                                                             |
+-----------------------------------------------------------------------------+

Mode YAML Syntax Examples

Passive Stage

- id: "tempering"
  mode: "PASSIVE"
  duration: "4s"
  on_tick:
    - action: "spawn_particle(SMOKE, 2, 0.1, 0.2, 0.1)"

Manual Action Stage

- id: "hammering"
  mode: "MANUAL_ACTION"
  action_type: "LEFT_CLICK_BLOCK" # LEFT_CLICK_BLOCK | RIGHT_CLICK_BLOCK
  required_strikes: 5
  cooldown_ticks: 10              # Rhythmic delay between allowed strikes
  on_action:
    - action: "play_sound(block.anvil.use)"
    - action: "damage_tool(1)"

Waiting for Condition Stage

- id: "boiling"
  mode: "WAITING_FOR_CONDITION"
  timeout: "30s"
  condition: "capability.temperature >= 100"
  failure_transition: "cool_down_failure"

2. Non-Linear Stage Transitions (v2.6.0+)

CraftingEngine v2.6.0 introduced statechart transitions, eliminating rigid linear progression and enabling branching paths, random outcomes, and failure recovery.

                       +-------------------+
                       |   Initial Stage   |
                       +---------+---------+
                                 |
                     (Evaluates Transitions)
                                 |
           +---------------------+---------------------+
           | (Weight: 70%)                             | (Weight: 30%)
           v                                           v
+---------------------+                     +---------------------+
| Masterwork Branch   |                     | Flawed Branch       |
+----------+----------+                     +----------+----------+
           |                                           |
           +---------------------+---------------------+
                                 |
                                 v
                       +-------------------+
                       |    Final Polish   |
                       +-------------------+

A. Weighted Probabilistic Branching

Transitions support normalized roulette-wheel selection. When multiple transitions specify weight:, CraftingEngine normalizes the weights and picks an outcome randomly:

stages:
  - id: "enchanting_infusion"
    duration: "5s"
    transitions:
      - target_stage: "legendary_outcome"
        weight: 0.15 # 15% probability
      - target_stage: "standard_outcome"
        weight: 0.85 # 85% probability

B. Action-Driven Explicit Jumps

During interactive manual stages, specific player choices or click actions can immediately jump to any stage:

stages:
  - id: "forging_choice"
    mode: "MANUAL_ACTION"
    transitions:
      - target_stage: "folded_steel"
        action: "RIGHT_CLICK_BLOCK"
      - target_stage: "standard_edge"
        action: "LEFT_CLICK_BLOCK"

C. Failure Recovery Transitions (failure_transition)

If a timed stage expires or a minigame fails, instead of destroying the craft immediately, you can route the process to a recovery or salvage stage:

stages:
  - id: "delicate_shaping"
    mode: "MINIGAME"
    minigame:
      type: "TIMING_SWEET_SPOT"
    failure_transition: "salvage_scrap"
    transitions:
      - target_stage: "perfect_polish"


  - id: "salvage_scrap"
    mode: "PASSIVE"
    duration: "2s"
    on_complete:
      - action: "produce_output(minecraft:iron_nugget, 3)"

3. Quality Scaling and Scoring

Processes can evaluate player accuracy, reaction times, and capability thresholds to compute a Quality Score (0-100%):

  • Tier 1 (Normal): 0% - 49%
  • Tier 2 (Superior): 50% - 84%
  • Tier 3 (Masterwork): 85% - 100%

The computed quality tier can dynamically alter output item lore, attach custom NBT modifiers, or apply custom attribute modifiers (e.g. +15% Attack Damage).

4. Failure Policies and Abandonment

When crafts fail (due to timeout, tool breakage, or manual cancellation):

  • REFUND_INPUTS: All unconsumed ingredients are returned to the player or safely dropped.
  • DESTROY_INPUTS: Materials are destroyed (for high-risk endgame recipes).
  • PRODUCE_FAILURE_OUTPUTS: Grants slag, charcoal, or defective scrap items.

If a player leaves the workstation radius (policies.abandonment.max_distance: 5.0), a grace period countdown begins on the floating hologram. Returning resets the timer; exceeding the grace period triggers the failure policy.

Next Steps