README

A lightweight, centralized conditional task and event manager for PocketMine-MP.

TaskOnDemand lets you easily schedule and execute delayed or conditional tasks in response to specific PocketMine events — all without manually handling event listeners, TaskHandler references, or cancellation logic.

Everything is centralized, so there are no loose closures or dangling references that could lead to memory leaks. The library handles event registration, validation, and task cleanup for you.

✨ Key Advantages

• 🧩 Centralized management — all conditional tasks are tracked and cleaned automatically.
• ⚡ Zero manual cleanup — no need to store or cancel TaskHandlers yourself.
• 🧠 Conditional triggers — run tasks only when event conditions evaluate to true.
• 🕒 Delayed execution — run actions after a specified delay.
• 🧺 Memory-safe — callables and parameters are released once tasks complete or are removed.
• 🔧 Modular design — ideal for plugins that need flexible event-driven logic.

📦 Installation

composer require nicktee/taskondemand

🧠 Usage Example — Combat Log System

⚙️ Registering an Event

Register conditional events in your plugin’s onEnable() method:

use Nicktee\TaskOnDemand\TaskOnDemand;
use pocketmine\event\player\PlayerQuitEvent;
use pocketmine\event\EventPriority;

TaskOnDemand::getInstance()->registerConditionalEvent(
    $this, // your plugin instance
    "player_quit_trigger", // unique identifier for this conditional event
    PlayerQuitEvent::class, // event class to listen for
    function (PlayerQuitEvent $event, array $parameters): bool {
        // return true if this event matches the desired condition
        // (return true unconditionally if you don't need a condition)
        return $event->getPlayer()->getUniqueId()->toString() === $parameters["player"];
    },
    EventPriority::NORMAL // optional; defaults to EventPriority::MONITOR
    false, // optional; whether to handle cancelled events (default: false)
);

⏳ Scheduling a Delayed Conditional Task

Once your event is registered, you can schedule a delayed task that listens for it:

use Nicktee\TaskOnDemand\TaskOnDemand;

$duration = 15 * 20; // 15 seconds in ticks
$player->sendMessage("You are now in combat. Do not log out!");

TaskOnDemand::getInstance()->scheduleConditionalTask(
    $this, // your plugin instance
    "combat_log", // unique identifier for this conditional task
    function(?Event $event, array $parameters) use($player): void {
        if ($event === null) {
            // Task was run by delay or force (not triggered by event)
            $player->sendMessage("You are no longer in combat.");
        } else {
            // Task was triggered early by event (e.g., player quit)
            $player->kill();
        }
    },
    ["player_quit_trigger"], // events that can trigger this task
    ["player" => $player->getUniqueId()->toString()], // parameters passed to condition
    $duration // delay in ticks
);

💡 This example means:

1. The task will automatically run after 15 seconds.
2. If the player quits before that, the event condition will trigger the task immediately.
3. You don’t need to manually cancel the task — TaskOnDemand manages that internally.

⚡ Forcing Task Execution

Force-run a task immediately (e.g., cancel combat):

use Nicktee\TaskOnDemand\TaskOnDemand;

TaskOnDemand::getInstance()->executeConditionalTask(
    "combat_log",
    ["player" => $player->getUniqueId()->toString()]
);

❌ Removing a Scheduled Task

Remove a pending task entirely:

use Nicktee\TaskOnDemand\TaskOnDemand;

TaskOnDemand::getInstance()->removeConditionalTask(
    "combat_log",
    ["player" => $player->getUniqueId()->toString()]
);

🔍 Checking if a Task Exists

You can check whether a specific conditional task currently exists using hasConditionalTask():

if (TaskOnDemand::getInstance()->hasConditionalTask(
    "combat_log",
    ["player" => $player->getUniqueId()->toString()]
)) {
    $player->sendMessage("You're still in combat!");
}

This is useful to verify whether a player is currently under an active timed condition (e.g., combat, cooldown, or ability effect).

🧩 When to Use TaskOnDemand

• Cooldown/Delayed task systems
• onDisable() tasks (use PluginDisableEvent)
• When you have several events modifying the same task
• Graceful handling of player disconnects and active player references
• Temporary player abilities/effects that should be reversed on death/quit/teleport etc.

🛠 Technical Details

• Automatically manages TaskHandlers and closures.
• Ensures memory safety by removing references when tasks are done.
• All event and task data is centralized for clean lifecycle management.
• Works seamlessly with PocketMine’s scheduler and event system.

💬 Feedback & Feature Requests

If you have suggestions, feature ideas, or bug reports, please open an issue on the GitHub repository.

Your feedback helps improve TaskOnDemand for everyone. ❤️