API para Desarrolladores y Eventos Bukkit

CraftingEngine proporciona un módulo de API pública independiente (craftingengine-api) que permite a otros plugins iniciar procesos, registrar acciones y condiciones personalizadas, reaccionar a eventos del ciclo de vida y consultar estaciones activas.

---

1. Coordenadas de Maven y Gradle

Añade la dependencia de la API a tu archivo de construcción:

Gradle (Kotlin DSL - build.gradle.kts)

repositories {
    maven("https://repo.codemc.io/repository/maven-releases/")
}

dependencies {
    compileOnly("dev.darkblade.craftingengine:craftingengine-api:2.9.0")
}

Maven (pom.xml)

<dependency>
    <groupId>dev.darkblade.craftingengine</groupId>
    <artifactId>craftingengine-api</artifactId>
    <version>2.9.0</version>
    <scope>provided</scope>
</dependency>

---

2. Acceso al Servicio Central

Obtén la instancia de CraftingEngineAPI mediante el ServicesManager de Bukkit:

import dev.darkblade.craftingengine.api.CraftingEngineAPI;
import org.bukkit.Bukkit;

public class MiPluginIntegration {
    private CraftingEngineAPI api;

    public void onEnable() {
        this.api = Bukkit.getServicesManager().load(CraftingEngineAPI.class);
        if (this.api == null) {
            getLogger().warning("CraftingEngine no encontrado.");
        }
    }
}

---

3. Eventos del Ciclo de Vida de Bukkit

CraftingEngine emite eventos sincrónicos y asíncronos en los momentos clave del crafteo:

Clase del Evento	¿Cancelable?	Momento del Disparo
ProcessPreStartEvent	Sí	Se emite antes de retirar los ingredientes. Permite bloquear el inicio del crafteo.
ProcessStartedEvent	No	Se dispara tras consumir los materiales y comenzar la primera etapa.
StageTransitionEvent	No	Se dispara cuando un proceso pasa de una etapa a la siguiente.
ProcessCompletedEvent	No	Se emite al completar con éxito todas las etapas y otorgar las recompensas.
ProcessFailedEvent	No	Se dispara cuando un proceso se interrumpe, abandona o falla.

Ejemplo: Listener de Eventos

import dev.darkblade.craftingengine.api.event.ProcessPreStartEvent;
import org.bukkit.event.EventHandler;
import org.bukkit.event.Listener;

public class MiListener implements Listener {

    @EventHandler
    public void onProcessPreStart(ProcessPreStartEvent event) {
        if (event.getRecipeId().equals("infernal_blade") && !event.getPlayer().hasPermission("miplugin.maestro")) {
            event.setCancelled(true);
            event.setCancelReason("¡No posees el conocimiento para forjar la Hoja Infernal!");
        }
    }
}

---

4. Contratos de Dominio y Modelos Clave (craftingengine-api)

El módulo craftingengine-api se encuentra completamente desacoplado de Bukkit y expone modelos puros en Java:

Reserva Transaccional de Insumos (v2.8.0)

• InputMode.RESERVE: Los requisitos de insumos con InputMode.RESERVE emiten ResourceReservedEffect al iniciar y ResourceReleasedEffect ante cancelación o fallo.
• ProcessEvent: Interfaz sellada que incluye los eventos de dominio ResourceReservedEvent y ResourceReleasedEvent.

Políticas de Drenaje de Capacidad (v2.7.0)

• CapabilityDrainPolicy: Record inmutable que define la variable monitoreada, drainPerTick, drainPerUse y minimumThreshold.
• StationCapability: Incluye el método Optional<CapabilityDrainPolicy> drainPolicy() y la comprobación isAvailable(StationState).

Canal de Herencia de Propiedades (v2.9.0)

• InheritanceMode: Enum con los modos COPY, MULTIPLY y EXPRESSION.
• PropertyInheritanceRule: Record declarativo de regla que especifica claves origen/destino, modos y expresiones matemáticas.
• ResourceProducedEffect: Incluye el mapa Map<String, StateValue> inheritedProperties inyectado en las etiquetas PDC del ítem resultante.

Almacenamiento de Estado Sellado (StateValue)

• dev.darkblade.craftingengine.api.state.StateValue autoriza 6 records inmutables:
  • StateValue.IntVal(int value)
  • StateValue.DoubleVal(double value)
  • StateValue.LongVal(long value)
  • StateValue.BoolVal(boolean value)
  • StateValue.StringVal(String value)
  • StateValue.ResourceRefVal(String resourceId)

---

5. Registro de Acciones y Condiciones Propias

Puedes extender la lógica de los blueprints registrando funciones Java en el RegistryManager:

api.getRegistryManager().registerAction("custom_teleport", (context, args) -> {
    Player player = context.getPlayer();
    Location target = parseLocation(args);
    player.teleport(target);
});

---

Siguientes Pasos

• Blueprints de Procesos - Conoce la sintaxis YAML para invocar tus acciones personalizadas y reglas de herencia.
• Diagnóstico y Grabador de Vuelo - Inspecciona la telemetría de la API y las trazas en runtime.