Scheduler API

PotatoMC provides a robust, thread-safe scheduler for delaying tasks, repeating ticks, and executing heavy asynchronous operations off the main server thread.

1. Synchronous Tasks

Run tasks safely on the main server thread. Required for modifying blocks, entities, or sending packets.

// Run task after 20 ticks (1 second)
context.scheduler().run_task_later(20, || {
    player.send_message("1 second has passed!");
});

// Run task every 10 ticks, starting after 50 ticks
context.scheduler().run_task_timer(50, 10, || {
    player.set_health(player.health() + 1.0);
});

2. Asynchronous Workers

Offload heavy I/O tasks (database queries, HTTP requests) to the Rayon thread pool.

⚠️ WARNING: Thread Safety

Never modify block states, spawn entities, or interact with the world directly from an async task. Always dispatch back to the main thread.

context.scheduler().run_task_asynchronously(|| {
    // 1. Heavy database query happens off-thread
    let stats = fetch_player_stats_from_db(player_uuid);
    
    // 2. Dispatch back to main thread to update UI
    context.scheduler().run_task(move || {
        player.send_message(&format!("Your kills: {}", stats.kills));
    });
});