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

title, type, weight

title	type	weight
Tasks	docs	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

// 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 >}}

// 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));
    });
});