Saltearse al contenido
DarkBladeDev Docs

Etapas, Modos y Transiciones No Lineales

Los procesos de CraftingEngine avanzan a través de una secuencia de etapas (stages). Las etapas transforman los crafteos pasivos en máquinas de estado dinámicas con interacciones manuales, minijuegos, ramificaciones aleatorias ponderadas y rutas de recuperación.

1. Modos de Ejecución de Etapas

CraftingEngine cuenta con 5 modos configurables mediante la clave mode::

+-----------------------------------------------------------------------------+
|                          MODOS DE EJECUCIÓN DE ETAPA                        |
+-----------------------------------------------------------------------------+
|                                                                             |
|  1. PASSIVE                                                                 |
|     Avanza automáticamente en función del tiempo (duración: "5s", "1m").    |
|                                                                             |
|  2. MANUAL_ACTION                                                           |
|     Requiere golpes físicos del jugador (clic izquierdo/derecho con tool).  |
|                                                                             |
|  3. WAITING_FOR_CONDITION                                                    |
|     Pausa el avance hasta alcanzar un estado ambiental o de capacidad       |
|     (ej. el caldero alcanza 100°C o empieza a llover).                      |
|                                                                             |
|  4. MINIGAME                                                                |
|     Minijuego arcade interactivo en la barra de acción (Action Bar).        |
|                                                                             |
|  5. ITEM_INSERTION                                                          |
|     Requiere que el jugador lance o inserte componentes específicos.        |
|                                                                             |
+-----------------------------------------------------------------------------+

Sintaxis YAML por Modo

Etapa Pasiva

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

Etapa de Acción Manual

- id: "hammering"
  mode: "MANUAL_ACTION"
  action_type: "LEFT_CLICK_BLOCK" # LEFT_CLICK_BLOCK | RIGHT_CLICK_BLOCK
  required_strikes: 5
  cooldown_ticks: 10              # Retardo rítmico entre golpes permitidos
  on_action:
    - action: "play_sound(block.anvil.use)"
    - action: "damage_tool(1)"

Espera de Condición

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

2. Transiciones No Lineales (v2.6.0+)

La versión v2.6.0 incorporó soporte completo para transiciones tipo statechart, eliminando la linealidad forzada y permitiendo bifurcaciones y recuperación ante fallos:

                       +-------------------+
                       |    Etapa Inicial  |
                       +---------+---------+
                                 |
                     (Evaluación de Transición)
                                 |
           +---------------------+---------------------+
           | (Peso: 70%)                               | (Peso: 30%)
           v                                           v
+---------------------+                     +---------------------+
| Rama Obra Maestra   |                     | Rama Defectuosa     |
+----------+----------+                     +----------+----------+
           |                                           |
           +---------------------+---------------------+
                                 |
                                 v
                       +-------------------+
                       |    Pulido Final   |
                       +-------------------+

A. Ramificación Probabilística Ponderada

Las transiciones admiten ruleta ponderada normalizada mediante weight:. Si se definen varios destinos, CraftingEngine normaliza las probabilidades y escoge un camino aleatorio:

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

B. Saltos Explícitos mediante Action DSL

Además de las listas de transiciones, las acciones pueden forzar un salto instantáneo a cualquier etapa mediante la directiva transition: "<stageId>" (o el alias jump_stage: "<stageId>"). Es compatible con todos los ganchos de ciclo de vida (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'" # Salto explícito de etapa
    transitions:
      - target_stage: "folded_steel"
        action: "RIGHT_CLICK_BLOCK"
      - target_stage: "standard_edge"
        action: "LEFT_CLICK_BLOCK"

C. Transiciones de Recuperación ante Fallos (failure_transition)

Cuando una etapa sufre un fallo operacional —como tiempo agotado en minijuegos, puntuación deficiente, interacción inválida o agotamiento de capacidad consumible (v2.7.0+)—, el crafteo no tiene por qué terminar de inmediato. Definir failure_transition: (o alias fail_stage:, failure_stage:) redirige el proceso directamente a una etapa alternativa de rescate:

stages:
  - id: "high_heat_tempering"
    duration: "10s"
    failure_transition: "salvage_scrap" # Se activa por tiempo o por agotamiento de capacidad
    transitions:
      - target_stage: "perfect_polish"


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

D. Invariante de No-Reentrancia (RT-007)

Para evitar bucles síncronos infinitos y excepciones de desbordamiento de pila (StackOverflowError), los saltos de acción y las transiciones de fallo respetan estrictamente el invariante RT-007:

  • Al ejecutarse un salto o transición de fallo, se limpian los temporizadores de la etapa activa.
  • La ejecución de los ganchos onStart y la evaluación de requisitos de la etapa destino se aplazan al siguiente tick del servidor.

E. Distintivos de Transición en el Flight Recorder

El sistema de telemetría en memoria registra cada transición con distintivos visuales en /cfe process trace:

  • [BRANCH 20/100]: Selección probabilística proporcional mediante ruleta con peso porcentual.
  • [JUMP]: Salto explícito provocado por directiva de Action DSL.
  • [RECOVERY]: Desvío a failure_transition por fallo o agotamiento de capacidad.
  • [TIMEOUT]: Transición secuencial activada por vencimiento de duración.
  • [STAGE]: Avance secuencial estándar a la siguiente etapa.

3. Puntuación y Escala de Calidad

Los procesos calculan una Puntuación de Calidad (Quality Score) del 0% al 100% evaluando la precisión y sincronización del jugador:

  • Nivel 1 (Normal): 0% - 49%
  • Nivel 2 (Superior): 50% - 84%
  • Nivel 3 (Obra Maestra): 85% - 100%

El nivel alcanzado puede añadir lore exclusivo, atributos aumentados (+15% Daño de Ataque) o modificadores NBT.

Siguientes Pasos