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 & Action DSL

In addition to transition lists, actions can trigger instantaneous stage jumps via the Action DSL directive transition: "<stageId>" (or alias jump_stage: "<stageId>"). This works across all stage lifecycle hooks (on_start, on_tick, on_action, on_complete, on_fail):

stages:
  - id: "forging_choice"
    mode: "MANUAL_ACTION"
    on_action:
      - condition: "var:process.strike_count >= 5"
        action: "transition: 'rapid_cooling'" # Explicit stage jump
    transitions:
      - target_stage: "folded_steel"
        action: "RIGHT_CLICK_BLOCK"
      - target_stage: "standard_edge"
        action: "LEFT_CLICK_BLOCK"

C. Failure Recovery Transitions (failure_transition)

When a stage encounters an operational failure—such as a minigame timeout, score deficiency, invalid interaction, or consumable capability exhaustion (v2.7.0+)—the process does not need to terminate immediately. Defining failure_transition: (or aliases fail_stage:, failure_stage:) routes the craft directly to an alternate salvage or recovery stage:

stages:
  - id: "high_heat_tempering"
    duration: "10s"
    failure_transition: "salvage_scrap" # Triggered on timeout or capability exhaustion
    transitions:
      - target_stage: "perfect_polish"


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

D. Non-Reentrancy Invariant (RT-007)

To prevent infinite synchronous loops and stack overflow exceptions, action-driven jumps and failure transitions strictly adhere to invariant RT-007:

  • When an explicit jump or failure recovery transition executes, active stage timers are cleared.
  • Execution of the target stage’s onStart hooks and requirement evaluations is deferred to the subsequent server tick.

E. Flight Recorder Transition Badges

The in-memory telemetry system traces every transition with visual diagnostic badges rendered in /cfe process trace:

  • [BRANCH 20/100]: Probabilistic roulette-wheel branch selection with weight payload.
  • [JUMP]: Explicit Action DSL stage jump.
  • [RECOVERY]: Stage diverted to failure_transition due to timeout or capability exhaustion.
  • [TIMEOUT]: Sequential transition triggered by stage duration expiration.
  • [STAGE]: Normal sequential progression to next stage.

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