Documentación de MagmaLib v2.0

init() Estándar

Inicializa la librería. Llamar en onEnable(). Lanza IllegalStateException si plugin es null.

@Override
public void onEnable() {
    MagmaLib.init(this);
}

isFolia()

Detecta automáticamente si el servidor es Folia usando reflexión con caché. Lanza excepción si no se llamó init().

if (MagmaLib.isFolia()) {
    // Código optimizado para Folia
} else {
    // Fallback para Paper/Spigot
}

task(Runnable) v1.x

Punto de entrada para tareas sin retorno. Compatible con versiones anteriores.

task(Supplier) v2.0

Punto de entrada para composición type-safe con thenApply/thenAccept.

at()

Ejecuta en la región del chunk (Folia) o hilo principal (Paper).

with()

Vincula la tarea al scheduler de la entidad en Folia.

afterTicks()

Retraso directo en ticks de Minecraft (1 tick = 50ms).

everyTicks()

Intervalo repetitivo en ticks para tareas periódicas.

handleException()

Manejador personalizado de errores para la tarea.

named() v2.0

Asigna nombre para debugging y logs con contexto rico.

unsafe() Directo

⚠️ Desactiva validaciones. Solo en hot paths con parámetros garantizados.

run()

Ejecuta la tarea y devuelve objeto Task para cancelación manual.

thenApply() Transformar

Transforma el resultado aplicando una función. Cambia el tipo del builder para encadenamiento type-safe.

// Integer → String
MagmaLib.<Integer>task(() -> player.getLevel())
    .thenApply(level -> "Nivel: " + level)
    .thenAccept(msg -> player.sendMessage(msg))
    .run();

thenAccept() Consumir

Consume el resultado sin retornar valor. Ideal para efectos secundarios como enviar mensajes.

// Consumir resultado final
MagmaLib.task(() -> fetchUserData(player))
    .thenApply(data -> data.username)
    .thenAccept(username -> {
        player.sendMessage("Bienvenido, " + username);
    })
    .run();

exceptionally() Fallback

Proporciona un valor de recuperación cuando ocurre una excepción. Similar a try-catch pero funcional.

// Fallback ante error
MagmaLib.task(() -> database.query(player.getUniqueId()))
    .thenApply(result -> result.score)
    .exceptionally(e -> {
        getLogger().warning("Query falló: " + e.getMessage());
        return 0; // Valor por defecto
    })
    .thenAccept(score -> updateUI(score))
    .run();

named() Debugging

Asigna nombre para logs con contexto. Incluye task name, ubicación y entidad en mensajes de error.

// Logs más útiles en producción
MagmaLib.task(() -> processTransaction(player, amount))
    .named("EconomyDeduction")
    .at(player.getLocation())
    .handleException(e -> {
        // Log: "Error en tarea MagmaLib ['EconomyDeduction'] location=world@123,45,67..."
        getLogger().severe("Transacción fallida: " + e.getMessage());
    })
    .run();

runDirect() ⚡

Ejecución inmediata en hilo global. ~25% más rápido que task().run().

runDirectAt() ⚡

Ejecución en región de chunk. Ideal para procesamiento masivo de bloques.

runDirectWith() ⚡

Ejecución en scheduler de entidad. Para bucles de actualización masiva. Fix v2.0: delay 0L para ejecución inmediata.

runDirectLater() ⚡

Retraso directo en ticks. Sin conversión de TimeUnit.

runDirectTimer() ⚡

Tarea periódica directa. Sin builder ni allocations extra.

runTimerUntilFast() Nuevo

Versión optimizada sin AtomicReference. ~15% más rápido.

runAsync()

Ejecuta asíncronamente y retorna futuro para composición.

MagmaLib.runAsync(() -> {
    return heavyComputation();
}).thenAccept(result -> {
    MagmaLib.runSync(() -> player.sendMessage(result));
});

callSync()

Ejecuta en hilo principal y retorna valor vía CompletableFuture.

MagmaLib.callSync(() -> {
    return player.getInventory().getContents();
}).thenAccept(items -> {
    // Procesar en hilo asíncrono
});

runWithRetry() Nuevo

Ejecuta con reintentos automáticos. Compatible con Folia.

runTimerUntil() Nuevo

Ejecuta periódicamente hasta que se cumpla una condición.

forAllPlayers()

Itera jugadores con manejo seguro de errores. Ejecuta en hilo principal.

forAllLoadedChunks()

Procesa chunks cargados (ejecuta asíncrono por defecto).

ticksToMs() / msToTicks()

Conversión de tiempo optimizada (multiplicación por 50L).

executeIfLoaded()

Ejecuta solo si el chunk de la ubicación está cargado.

¿Mi código de v1.x funcionará en v2.0?

✅ Sí, 100% compatible. Todas las APIs de v1.x funcionan sin cambios. Las nuevas features de composición son opcionales y se activan usando task(Supplier<T>) en lugar de task(Runnable).

¿Cuándo usar thenApply vs thenAccept?

thenApply: Cuando necesitas transformar el valor y continuar el pipeline (retorna nuevo tipo). thenAccept: Cuando quieres consumir el valor final para un efecto secundario (no retorna valor, finaliza el pipeline).

¿Es seguro usar .unsafe()?

Sí, si sigues estas reglas:

• ✅ Valida manualmente antes de llamar
• ✅ Úsalo solo en código que controlas totalmente
• ✅ Documenta por qué es seguro en ese contexto
• ❌ Nunca lo uses con inputs de usuario o datos externos

¿Funciona en Paper y Folia?

✅ Sí, 100% compatible. MagmaLib detecta automáticamente el tipo de servidor y usa el scheduler apropiado:

• Folia: RegionScheduler, EntityScheduler, GlobalRegionScheduler
• Paper/Spigot: Bukkit Scheduler tradicional

Tu código no necesita cambios para funcionar en ambos.

¿Cómo debuggear tareas con named()?

Los logs de error incluirán automáticamente:

• 🏷️ Nombre de la tarea: ['MiTarea']
• 📍 Ubicación: location=world@x,y,z
• 👤 Entidad: entity=Player[Notch]
• 📋 Stack trace de creación (si habilitas debug)

¿Cómo instalar v2.0 ahora?

Mientras JitPack no esté disponible:

1. Descarga MagmaLib.java del repositorio
2. Cópialo en tu plugin: src/main/java/tu/paquete/MagmaLib.java
3. ¡Listo! Sin dependencias externas

Próximamente: jitpack.io/#MagmaEnginers/MagmaLib