Init

content/core-concepts/tasks/_index.en.md

@@ -0,0 +1,69 @@
+---
+title: Tasks
+type: docs
+weight: 3
+---
+
+The task system in Hytale manages asynchronous operations using Java's standard concurrency APIs.
+
+{{< cards >}}
+  {{< card link="task-registry" title="TaskRegistry" subtitle="Registering and tracking tasks" >}}
+  {{< card link="async-operations" title="Async Operations" subtitle="Thread-safe async patterns" >}}
+{{< /cards >}}
+
+## Overview
+
+{{< callout type="warning" >}}
+**Important:** TaskRegistry does NOT have `runAsync()`, `runSync()`, `runLater()`, or `runRepeating()` methods. Hytale uses Java's standard `CompletableFuture` and `ScheduledExecutorService` APIs.
+{{< /callout >}}
+
+The TaskRegistry allows plugins to:
+- **Register tasks** - Track `CompletableFuture` and `ScheduledFuture` for cleanup
+- **Async operations** - Use `CompletableFuture.runAsync()`
+- **Delayed operations** - Use `CompletableFuture.delayedExecutor()`
+- **Repeating operations** - Use `ScheduledExecutorService`
+
+## Quick Start
+
+```java
+// Run async operation
+CompletableFuture.runAsync(() -> {
+    // Background thread code
+    Data result = computeExpensiveData();
+
+    // Return to world thread for game state changes
+    world.execute(() -> {
+        playerRef.sendMessage(Message.raw("Result: " + result));
+    });
+});
+
+// Delayed operation (3 seconds)
+CompletableFuture.delayedExecutor(3, TimeUnit.SECONDS)
+    .execute(() -> {
+        world.execute(() -> {
+            // Delayed code on world thread
+        });
+    });
+```
+
+## Key Concepts
+
+{{< callout type="warning" >}}
+**Thread Safety:** Each World runs on its own dedicated thread. Always use `world.execute()` when modifying game state (players, entities, blocks) from async code. Direct manipulation from async threads can cause crashes or data corruption.
+{{< /callout >}}
+
+```java
+// Correct pattern
+PlayerRef playerRef = player.getPlayerRef();
+World world = player.getWorld();
+
+CompletableFuture.runAsync(() -> {
+    // Do heavy computation here (background thread)
+    Data result = computeExpensiveData();
+
+    // Return to world thread for game state changes
+    world.execute(() -> {
+        playerRef.sendMessage(Message.raw("Result: " + result));
+    });
+});
+```