Saltearse al contenido
DarkBladeDev Docs

Capacidades Modulares y Variables de Estado

CraftingEngine desacopla las recetas de materiales de bloque fijos mediante Capacidades y Variables de Estado. En lugar de exigir un bloque específico de ANVIL o FURNACE, las recetas solicitan capacidades abstractas como forging, heating o pressure.

1. ¿Qué son las Capacidades?

Las capacidades representan cualidades funcionales provistas por una estación o por el entorno:

+-----------------------+           +-----------------------------+
| Requisitos de Receta  |           | Definición de la Estación   |
+-----------------------+           +-----------------------------+
|  - forging            | <=======> | capabilities:               |
|  - high_temperature   |           |   - forging                 |
+-----------------------+           |   - high_temperature        |
                                    +-----------------------------+

Ventajas de las Capacidades:

  • Múltiples Estaciones, Misma Receta: Un crafteo de “Acero Plegado” puede realizarse en un yunque de hierro sencillo o en una gigantesca forja rúnica 3D, siempre que ambas provean la capacidad forging.
  • Niveles y Rangos: Permite definir jerarquías (ej. heating_tier_1, heating_tier_2).
  • Activación Condicional: Una estación puede aportar calor únicamente cuando esté alimentada por redstone o cuando tenga lava debajo.

2. Definición de Capacidades (capabilities/*.yml)

Las capacidades pueden definirse como archivos YAML independientes en plugins/CraftingEngine/capabilities/:

id: "high_temperature"
name: "<gradient:#ff8a80:#ff5252>Alta Temperatura</gradient>"
description: "Requiere calor ambiental superior a 300°C."


# Evaluaciones requeridas para activar esta capacidad
evaluations:
  - type: "BLOCK_STATE"
    offset: [0, -1, 0] # Inspecciona el bloque inmediatamente debajo de la estación
    materials:
      - "LAVA"
      - "MAGMA_BLOCK"
      - "SOUL_FIRE"


variables:
  temperature:
    initial: 350.0
    decay_rate: 1.5

3. Variables de Estado

Las estaciones y procesos activos mantienen mapas sellados y aislados de variables de estado:

  • temperature: Nivel de calor actual en °C.
  • fluid_level: Milicubos (mB) de fluido contenidos en un caldero.
  • pressure: Presión hidráulica o de vapor en PSI.
  • durability: Resistencia estructural de bloques especiales.

Comprobación en Blueprints

Puedes evaluar variables de estado directamente en las condiciones de tus blueprints:

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

4. Capacidades Consumibles y Políticas de Drenaje (v2.7.0+)

Por defecto, las capacidades de una estación están permanentemente disponibles mientras se cumplan sus condiciones ambientales. No obstante, las recetas complejas a menudo demandan recursos consumibles propios de la estación —como calor acumulado en la forja, reservas de maná, tanques de agua o presión de vapor— que se desgastan a medida que se ejecutan los crafteos.

CraftingEngine introduce CapabilityDrainPolicy para gestionar el consumo progresivo y el agotamiento dinámico de capacidades:

+-----------------------------------------------------------------------------+
|                     CICLO DE VIDA DEL DRENAJE DE CAPACIDAD                  |
+-----------------------------------------------------------------------------+
|                                                                             |
|  1. VALIDACIÓN PREVIA Y DRENAJE POR USO                                     |
|     - Verifica que la estación cumpla: variable >= min_threshold + per_use  |
|     - Descuenta drain_per_use inmediatamente al iniciar el proceso.         |
|                                                                             |
|  2. DRENAJE CONTINUO POR TICK                                               |
|     - Descuenta drain_per_tick (escalado por delta time) en etapas activas. |
|     - Se descuenta progresivamente mientras el crafteo avanza.              |
|                                                                             |
|  3. AGOTAMIENTO Y DERIVACIÓN DE RECUPERACIÓN                                |
|     - Si la variable cae por debajo de min_threshold:                       |
|       * Emite el evento CAPABILITY_EXHAUSTED al Flight Recorder.            |
|       * Deriva la etapa activa a failure_transition (etapa de rescate).     |
|       * Si no hay etapa de rescate, aborta el crafteo según su política.    |
|                                                                             |
+-----------------------------------------------------------------------------+

Sintaxis de Declaración en la Estación

En stations/*.yml, define capacidades estructuradas mediante un bloque drain::

capabilities:
  # Capacidad estática (siempre disponible)
  - "forging"


  # Capacidad consumible regulada por política de drenaje
  - high_temperature:
      drain:
        variable: "temperature"     # Variable de estado monitoreada en StationState
        drain_per_second: 5.0       # Tasa de drenaje continuo por segundo (o drain_per_tick: 0.25)
        drain_per_use: 15.0         # Deducción discreta al iniciar el proceso
        min_threshold: 200.0        # Nivel mínimo requerido para iniciar o mantener el proceso

Propiedades de Configuración de drain

PropiedadTipoValor por DefectoDescripción
variableStringObligatorioClave de la variable en StationState monitoreada y modificada por esta capacidad.
drain_per_secondDouble0.0Tasa de drenaje continuo por segundo. Se convierte internamente a drain_per_tick = tasa / 20.0.
drain_per_tickDouble0.0Tasa de drenaje continuo aplicada directamente en cada tick del servidor.
drain_per_useDouble0.0Cantidad discreta que se descuenta al iniciar el proceso (multiplicada en crafteos en lote).
min_thresholdDouble0.0Umbral mínimo por debajo del cual la capacidad pasa a estar agotada (isAvailable == false).

Agotamiento de Capacidad y Etapas de Rescate

Cuando una estación agota una capacidad consumible durante un crafteo (por ejemplo, si la temperatura cae por debajo de min_threshold mientras se forja):

  1. El motor registra un evento de telemetría CAPABILITY_EXHAUSTED en el Flight Recorder.
  2. Si la etapa activa define una failure_transition, el proceso se desvía inmediatamente a dicha etapa de rescate sin bucles recursivos: 
    stages:
      - id: "high_heat_forging"
        duration: "10s"
        failure_transition: "cooling_salvage"
  3. Si no se especificó failure_transition, el proceso termina como fallido y ejecuta la política global del blueprint (REFUND_INPUTS o DESTROY_INPUTS).

Siguientes Pasos