MagmaLib Documentation v2.1

init() Standard

Initializes the library. Call in onEnable(). Throws IllegalStateException if plugin is null.

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

isFolia()

Automatically detects if the server is Folia using cached reflection. Throws exception if init() was not called.

if (MagmaLib.isFolia()) {
    // Code optimized for Folia
} else {
    // Fallback for Paper/Spigot
}

task(Runnable) v1.x

Entry point for tasks without return value. Compatible with previous versions.

task(Supplier) v2.1

Entry point for type-safe composition with thenApply/thenAccept.

at()

Executes in the chunk region (Folia) or main thread (Paper).

with()

Binds the task to the entity's scheduler in Folia.

afterTicks()

Direct delay in Minecraft ticks (1 tick = 50ms).

everyTicks()

Repetitive interval in ticks for periodic tasks.

handleException()

Custom error handler for the task.

named() v2.1

Assigns a name for debugging and logs with rich context.

unsafe() Direct

⚠️ Disables validations. Only in hot paths with guaranteed parameters.

run()

Executes the task and returns a Task object for manual cancellation.

thenApply() Transform

Transforms the result by applying a function. Changes the builder type for type-safe chaining.

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

thenAccept() Consume

Consumes the result without returning a value. Ideal for side effects like sending messages.

// Consume final result
MagmaLib.task(() -> fetchUserData(player))
    .thenApply(data -> data.username)
    .thenAccept(username -> {
        player.sendMessage("Welcome, " + username);
    })
    .run();

exceptionally() Fallback

Provides a recovery value when an exception occurs. Similar to try-catch but functional.

// Fallback on error
MagmaLib.task(() -> database.query(player.getUniqueId()))
    .thenApply(result -> result.score)
    .exceptionally(e -> {
        getLogger().warning("Query failed: " + e.getMessage());
        return 0; // Default value
    })
    .thenAccept(score -> updateUI(score))
    .run();

named() Debugging

Assigns a name for logs with context. Includes task name, location and entity in error messages.

// More useful logs in production
MagmaLib.task(() -> processTransaction(player, amount))
    .named("EconomyDeduction")
    .at(player.getLocation())
    .handleException(e -> {
        // Log: "Error in MagmaLib task ['EconomyDeduction'] location=world@123,45,67..."
        getLogger().severe("Transaction failed: " + e.getMessage());
    })
    .run();

runDirect() ⚡

Immediate execution on global thread. ~25% faster than task().run().

runDirectAt() ⚡

Execution in chunk region. Ideal for massive block processing.

runDirectWith() ⚡

Execution on entity scheduler. For massive update loops. v2.1 Fix: 0L delay for immediate execution.

runDirectLater() ⚡

Direct delay in ticks. No TimeUnit conversion.

runDirectTimer() ⚡

Direct periodic task. No builder or extra allocations.

runTimerUntilFast() New

Optimized version without AtomicReference. ~15% faster.

runAsync()

Executes asynchronously and returns a future for composition.

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

callSync()

Executes on main thread and returns value via CompletableFuture.

MagmaLib.callSync(() -> {
    return player.getInventory().getContents();
}).thenAccept(items -> {
    // Process on async thread
});

runWithRetry() New

Executes with automatic retries. Compatible with Folia.

runTimerUntil() New

Executes periodically until a condition is met.

forAllPlayers()

Iterates players with safe error handling. Executes on main thread.

forAllLoadedChunks()

Processes loaded chunks (executes async by default).

ticksToMs() / msToTicks()

Optimized time conversion (multiplication by 50L).

executeIfLoaded()

Executes only if the location's chunk is loaded.

Will my v1.x code work in v2.1?

✅ Yes, 100% compatible. All v1.x APIs work without changes. The new composition features are optional and are activated by using task(Supplier<T>) instead of task(Runnable).

When to use thenApply vs thenAccept?

thenApply: When you need to transform the value and continue the pipeline (returns new type). thenAccept: When you want to consume the final value for a side effect (doesn't return value, ends the pipeline).

Is it safe to use .unsafe()?

Yes, if you follow these rules:

• ✅ Validate manually before calling
• ✅ Use only in code you fully control
• ✅ Document why it's safe in that context
• ❌ Never use with user inputs or external data

Does it work on Paper and Folia?

✅ Yes, 100% compatible. MagmaLib automatically detects the server type and uses the appropriate scheduler:

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

Your code needs no changes to work on both.

How to debug tasks with named()?

Error logs will automatically include:

• 🏷️ Task name: ['MyTask']
• 📍 Location: location=world@x,y,z
• 👤 Entity: entity=Player[Notch]
• 📋 Creation stack trace (if you enable debug)

How to install v2.1 now?

While JitPack is not available:

1. Download MagmaLib.java from the repository
2. Copy it to your plugin: src/main/java/your/package/MagmaLib.java
3. Done! No external dependencies

Coming soon: jitpack.io/#MagmaEnginers/MagmaLib