> For the complete documentation index, see [llms.txt](https://openjs.wiki.gd/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://openjs.wiki.gd/openjs-components/in-build-classes/scheduling.md).
# 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
```javascript
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).
{% hint style="warning" %}
**If called on the main server thread, a warning will be logged because this can freeze the server.**
{% endhint %}
**Example:**
```javascript
task.wait(2); // Waits for 2 seconds
```
***
#### `task.waitForScript(scriptName: string): void`
Waits until the specified script is fully loaded and running.
**Example:**
```javascript
task.waitForScript("other-script.js");
```
***
#### `task.waitForPlugin(pluginName: string): void`
Waits until a specific plugin is loaded and enabled.
**Example:**
```javascript
task.waitForPlugin("CoreProtect");
```
***
#### `task.spawn(func: () => void): number`
Runs a function asynchronously. Returns the `taskId` so it can be cancelled later.
**Example:**
```javascript
const id = task.spawn(function() {
log.info("Running in a new async thread!");
});
```
{% hint style="info" %}
**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.
{% endhint %}
***
#### `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:**
```javascript
task.main(function() {
player.sendMessage("Hello from the main thread!");
});
```
{% hint style="danger" %}
The example code will not work on Folia servers, use `task.entitySchedule(entity, function)` if on Folia
{% endhint %}
***
#### `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:**
```javascript
task.entitySchedule(player, function() {
player.sendMessage("This was run in your entity thread!");
});
```
{% hint style="success" %}
#### 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!
{% endhint %}
***
#### `task.delay(delay: number, func: () => void): number`
Runs a function **once** after the specified delay (in seconds). Returns a `taskId`.
**Example:**
```javascript
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:**
```javascript
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:**
```javascript
const id = task.delay(5, function() {
log.info("Should not appear");
});
task.cancel(id); // Cancel before it runs
```
***
{% hint style="info" %}
### Notes[^1]
* **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.
{% endhint %}
***
[^1]:
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.
Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:
```
GET https://openjs.wiki.gd/openjs-components/in-build-classes/scheduling.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.