Scheduling and Async

The task API allows JavaScript scripts to schedule and manage tasks within your plugin environment. It's a bridge to Minecraft's asynchronous and scheduled task systems, designed with Folia compatibility in mind.

---

Overview

You can access the task object directly in your script. It offers utilities to:

• Pause execution (wait)

• Wait for other scripts or plugins to load

• Run functions asynchronously or on the main thread

• Delay or repeat function execution

• Schedule tasks per entity

• Cancel scheduled tasks

---

Usage Example

task.spawn(() => {
  task.wait(1.5); // Wait 1.5 seconds
  log.info("Spawned task finished waiting!");
});

task.repeat(2, 5, () => {
  log.info("Repeating every 5 seconds (after 2s delay)");
});

---

API Reference

task.wait(seconds: number): void

Pauses the script execution for the specified number of seconds (can be fractional).

If called on the main server thread, a warning will be logged because this can freeze the server.

Example:

task.wait(2); // Waits for 2 seconds

---

task.waitForScript(scriptName: string): void

Waits until the specified script is fully loaded and running.

Example:

task.waitForScript("other-script.js");

---

task.waitForPlugin(pluginName: string): void

Waits until a specific plugin is loaded and enabled.

Example:

task.waitForPlugin("CoreProtect");

---

task.spawn(func: () => void): number

Runs a function asynchronously. Returns the taskId so it can be cancelled later.

Example:

const id = task.spawn(function() {
  log.info("Running in a new async thread!");
});

On Folia:

• task.spawn() and related functions will create real threads and submit them to the thread pool. This means you’re not limited by the Cpu thread count. You can run as many concurrent tasks as needed!

On Non-Folia Servers (Bukkit, Spigot, Paper):

• These methods will fall back to Bukkit’s async scheduler, meaning they still run off the main thread, but within Bukkit’s thread limits. You can still spawn many async tasks, making this API a safe and compatible choice across all server types.

---

task.main(func: () => void): number

Runs the function on the main server thread. Use for tasks that must access Bukkit APIs that aren’t thread-safe.

Example:

task.main(function() {
  player.sendMessage("Hello from the main thread!");
});

The example code will not work on Folia servers, use task.entitySchedule(entity, function) if on Folia

---

task.entitySchedule(entity: Entity, func: () => void): number

Runs the function in context of a specific entity (Folia only). This is ideal for AI or entity-specific logic.

Example:

task.entitySchedule(player, function() {
  player.sendMessage("This was run in your entity thread!");
});

Compatibility Note

You can still use task.entitySchedule() API on non-Folia servers

• On traditional Bukkit/Spigot/Paper setups, task.entitySchedule() will simply run on the main server thread.

• This makes it ideal for writing cross-compatible scripts that work on both Folia and non-Folia servers without needing code changes!

---

task.delay(delay: number, func: () => void): number

Runs a function once after the specified delay (in seconds). Returns a taskId.

Example:

task.delay(3, function() {
  log.info("Ran after 3 seconds!");
});

---

task.repeat(delay: number, period: number, func: () => void): number

Repeats a function periodically, starting after a delay. Time is in seconds. Returns a taskId.

Example:

task.repeat(1, 10, function() {
  log.info("Runs every 10s, starting after 1s");
});

---

task.cancel(taskId: number): void

Cancels a scheduled task using its taskId.

Example:

const id = task.delay(5, function() {
  log.info("Should not appear");
});

task.cancel(id); // Cancel before it runs

---

• Thread Safety: Use task.main() or task.entitySchedule() if accessing Bukkit or Minecraft internals.

• Exception Handling: Errors in scripts are caught and logged; they won't crash the server.

• Integration: All tasks are registered per-script and tracked for clean cancellation on script reload.

---