Timing and tasks: the scheduler

Plugins often need to do something later, over and over, or without freezing the game. On this page you will delay a message, repeat a task every few seconds, build a countdown with a boss bar, cancel tasks properly, and move slow work off the main thread so the server never stutters.

Why plugins need a scheduler

Your plugin's code only runs when Paper calls it: when the plugin starts, when an event happens, when a command is typed. Between those moments, nothing of yours is running. So how do you say "send this message in 10 seconds" or "heal the player once per second"?

You cannot write "wait 10 seconds" in the middle of a method, as you will see in a moment. Instead you ask Paper's scheduler to run a piece of code later. You hand it the code and a time, and Paper calls it back when the time comes. Each piece of scheduled code is called a task.

Time in Minecraft is measured in ticks

The server does its work in small steps called ticks. Every tick, Paper moves mobs, grows crops, runs redstone and calls your tasks. There are 20 ticks every second, so one tick lasts 50 milliseconds. All scheduler methods count in ticks, not seconds.

The scheduler wants a long (a big whole number), which is why the numbers end in L. Writing 5 * 20L instead of 100L makes the code explain itself. Even better, give the number a name, as the examples below do with TICKS_PER_SECOND. The Tick Calculator converts any time for you.

Your first tasks: later, and again and again

This small plugin does two things for every player who joins. After 3 seconds it welcomes them, and every 10 seconds it repeats a tip until they earn their first experience level. First the listener, then the main class.

1package com.example.schedulerfirst;2 3import org.bukkit.entity.Player;4import org.bukkit.event.EventHandler;5import org.bukkit.event.Listener;6import org.bukkit.event.player.PlayerJoinEvent;7import org.bukkit.plugin.java.JavaPlugin;8 9public final class NudgeListener implements Listener {10 111    private static final long TICKS_PER_SECOND = 20L;12 213    private final JavaPlugin plugin;14 15    public NudgeListener(JavaPlugin plugin) {16        this.plugin = plugin;17    }18 19    @EventHandler20    public void onJoin(PlayerJoinEvent event) {21        Player player = event.getPlayer();22 323        plugin.getServer().getScheduler().runTaskLater(plugin, () -> {524            if (player.isOnline()) {25                player.sendRichMessage("<green>Glad you stayed. Have a look around!");26            }27        }, 3 * TICKS_PER_SECOND);28 629        plugin.getServer().getScheduler().runTaskTimer(plugin, task -> {30            if (!player.isOnline() || player.getLevel() > 0) {731                task.cancel();32                return;33            }34            player.sendRichMessage("<gray>Tip: mine some ore or defeat a mob to earn your first experience level.");835        }, 5 * TICKS_PER_SECOND, 10 * TICKS_PER_SECOND);36    }37}

1package com.example.schedulerfirst;2 3import org.bukkit.plugin.java.JavaPlugin;4 5public final class SchedulerFirstPlugin extends JavaPlugin {6 7    @Override8    public void onEnable() {19        getServer().getPluginManager().registerEvents(new NudgeListener(this), this);210        getServer().getScheduler().runTaskLater(this,311            () -> getLogger().info("Five seconds have passed since the plugin started."), 100L);12    }13}

Join the test server and, after three seconds, this appears. If your level is still zero, the tip follows 5 seconds after joining, then every 10 seconds:

[14:02:14 INFO]: [SchedulerFirst] Enabling SchedulerFirst v1.0.0[14:02:19 INFO]: [SchedulerFirst] Five seconds have passed since the plugin started.

Delay and period

Every scheduler method is a mix of these two numbers. The delay is how long to wait before the first run. The period is how long to wait between the following runs. A "later" task has only a delay; a repeating task has both.

These are the methods you will use all the time. They all live on the BukkitScheduler, which you get with getServer().getScheduler(). Every one takes your plugin as the first argument.

Three ways to write the task

The task argument can take three shapes, and you will meet all of them in other people's plugins. Which one you choose depends on what the task needs to remember.

1. A lambda: () -> player.sendRichMessage("Hi"). Best for short, one-off code, like the delayed welcome above.
2. A lambda with a task parameter: task -> { ... task.cancel(); }. Java calls this form a Consumer: code that receives one value, here the running task. Best for a repeating task that decides by itself when it is finished, like the tip. This form returns nothing, so use one of the other two shapes when you want to save the BukkitTask for later.
3. A class that implements Runnable or extends BukkitRunnable. Best when the task has its own variables or is long enough to deserve a name.

The auto-broadcast in the demo plugin is the third kind. It is a class that implements Runnable, a promise that it has a run() method. Scheduler calls run() every period:

1package com.example.schedulerdemo;2 3import java.util.List;4import net.kyori.adventure.text.minimessage.MiniMessage;5import org.bukkit.Bukkit;6 17final class AutoBroadcast implements Runnable {8 9    private final List<String> messages;210    private int nextIndex;11 12    AutoBroadcast(List<String> messages) {313        this.messages = List.copyOf(messages);14    }15 16    @Override17    public void run() {418        if (messages.isEmpty() || Bukkit.getOnlinePlayers().isEmpty()) {19            return;20        }521        Bukkit.getServer().sendMessage(MiniMessage.miniMessage().deserialize(messages.get(nextIndex)));622        nextIndex = (nextIndex + 1) % messages.size();23    }24}

The main class starts it. Look at the arguments: the first run comes after 60 seconds, then one every 5 minutes.

14@Override15public void onEnable() {16    List<String> tips = List.of(17        "<gray>Tip: <white>/countdown 10</white> starts a boss bar countdown.",18        "<gray>Tip: <white>/primes 5000000</white> counts primes without freezing the server.",19        "<gray>Tip: <white>/remind 30 stretch</white> sends you a reminder later.");120    autoBroadcastTask = getServer().getScheduler().runTaskTimer(221        this, new AutoBroadcast(tips), 60 * TICKS_PER_SECOND, 5 * 60 * TICKS_PER_SECOND);22 23    getLifecycleManager().registerEventHandler(LifecycleEvents.COMMANDS, event -> {24        event.registrar().register("countdown", "Show a boss bar countdown", new CountdownCommand(this));25        event.registrar().register("primes", "Count primes on another thread", new PrimesCommand(this));26        event.registrar().register("remind", "Send yourself a reminder later", new RemindCommand(this));27    });28}

A task with state: BukkitRunnable

Many tasks count something: seconds left, blocks placed, loops done. Tasks like that belong in a class, because a class can have variables that survive between runs. Bukkit provides a ready-made base class for this, BukkitRunnable. It is a Runnable that also knows how to schedule and cancel itself, so inside run() you can simply write cancel().

This is the countdown from the demo plugin. It shows a boss bar that shrinks every second, plays a tick sound, and finishes with a title:

1package com.example.schedulerdemo;2 3import java.util.HashSet;4import java.util.List;5import java.util.Set;6import net.kyori.adventure.bossbar.BossBar;7import net.kyori.adventure.text.Component;8import net.kyori.adventure.text.format.NamedTextColor;9import net.kyori.adventure.title.Title;10import org.bukkit.Sound;11import org.bukkit.entity.Player;12import org.bukkit.plugin.Plugin;13import org.bukkit.scheduler.BukkitRunnable;14 115final class CountdownTask extends BukkitRunnable {16 17    private static final long TICKS_PER_SECOND = 20L;218    private static final Set<CountdownTask> RUNNING = new HashSet<>();19 20    private final Player player;21    private final int totalSeconds;22    private final BossBar bar;323    private int remaining;24 425    private CountdownTask(Player player, int seconds) {26        this.player = player;27        this.totalSeconds = seconds;28        this.remaining = seconds;29        this.bar = BossBar.bossBar(Component.empty(), 1.0f, BossBar.Color.GREEN, BossBar.Overlay.NOTCHED_10);30    }31 532    static void start(Plugin plugin, Player player, int seconds) {33        CountdownTask task = new CountdownTask(player, seconds);34        player.showBossBar(task.bar);635        task.runTaskTimer(plugin, 0L, TICKS_PER_SECOND);36        RUNNING.add(task);37    }38 39    static void cancelAll() {740        for (CountdownTask task : List.copyOf(RUNNING)) {41            task.cancel();42        }43    }44 45    @Override46    public void run() {847        if (!player.isOnline()) {48            cancel();49            return;50        }951        if (remaining <= 0) {52            player.showTitle(Title.title(Component.text("Go!", NamedTextColor.GOLD), Component.empty()));53            player.playSound(player, Sound.ENTITY_PLAYER_LEVELUP, 1.0f, 1.0f);54            cancel();55            return;56        }57        bar.name(Component.text("Starting in " + remaining + "s", NamedTextColor.WHITE));1058        bar.progress((float) remaining / totalSeconds);59        bar.color(remaining <= 3 ? BossBar.Color.RED : BossBar.Color.GREEN);60        player.playSound(player, Sound.BLOCK_NOTE_BLOCK_HAT, 0.7f, remaining <= 3 ? 1.6f : 1.0f);1161        remaining--;62    }63 64    @Override1265    public void cancel() {66        super.cancel();67        player.hideBossBar(bar);68        RUNNING.remove(this);69    }70}

The command that starts it checks the input first, because players type anything:

16@Override17public void execute(CommandSourceStack source, String[] args) {118    if (!(source.getExecutor() instanceof Player player)) {19        source.getSender().sendRichMessage("<red>Only players can watch a boss bar.");20        return;21    }22    if (args.length != 1) {23        player.sendRichMessage("<red>Usage: /countdown <seconds>");24        return;25    }26    int seconds;27    try {228        seconds = Integer.parseInt(args[0]);29    } catch (NumberFormatException exception) {30        player.sendRichMessage("<red>That is not a whole number.");31        return;32    }333    if (seconds < 1 || seconds > 300) {34        player.sendRichMessage("<red>Pick a number of seconds from 1 to 300.");35        return;36    }437    CountdownTask.start(plugin, player, seconds);38}

Canceling tasks

A repeating task runs until something stops it. There are four ways to stop one:

• From inside: call task.cancel() in the Consumer form, or cancel() in a BukkitRunnable. This is the cleanest way, and the one the examples use.
• From outside, with a saved task: the Runnable and BukkitRunnable forms of runTaskTimer return a BukkitTask, a handle for the running task. Save it in a field and call cancel() on it later, as the auto-broadcast does.
• By number: every task has an id. getScheduler().cancelTask(id) stops it.
• All at once: getScheduler().cancelTasks(plugin) stops every task your plugin owns.

30@Override31public void onDisable() {132    if (autoBroadcastTask != null) {233        autoBroadcastTask.cancel();34    }335    CountdownTask.cancelAll();36}

When your plugin is disabled, for example when the server stops, Paper cancels all of its tasks for you. So why does onDisable still clean up? Because canceling the task does not clean up what the task left behind. A boss bar that was shown would stay on a player's screen, frozen, until they relog. Cancel your own tasks when you need that cleanup to happen, and always remove what they created.

Slow work: async tasks

Here is the most important idea on this page. Almost everything your plugin does runs on the main thread, the single thread that also moves every mob and loads every chunk. A thread is one line of work the computer follows; the main thread has 50 ms per tick for everything. If your code takes 2 seconds, the whole server freezes for 2 seconds: nobody can move, mobs stop, and players see "Can't keep up!" in the console.

The fix is to run slow work on another thread, called an asynchronous ("async") task. The main thread carries on with the game while your work happens elsewhere. runTaskAsynchronously does exactly that.

The catch: the Bukkit API is not safe to use off the main thread. Two threads changing the same chest or the same entity at once corrupt data and crash the server in strange ways. So an async task follows a simple rule:

The pattern always has three steps. Collect what you need on the main thread, do the slow work async, and hop back to the main thread with runTask to use the result.

17@Override18public void execute(CommandSourceStack source, String[] args) {119    CommandSender sender = source.getSender();20    if (args.length != 1) {21        sender.sendRichMessage("<red>Usage: /primes <limit>");22        return;23    }24    int limit;25    try {226        limit = Integer.parseInt(args[0]);27    } catch (NumberFormatException exception) {28        sender.sendRichMessage("<red>That is not a whole number.");29        return;30    }31    if (limit < 10 || limit > 50_000_000) {32        sender.sendRichMessage("<red>Pick a limit from 10 to 50,000,000.");33        return;34    }35 36    sender.sendRichMessage("<gray>Counting primes up to <white><limit></white> in the background...",737        Placeholder.unparsed("limit", String.valueOf(limit)));38 339    plugin.getServer().getScheduler().runTaskAsynchronously(plugin, () -> {440        long startedAt = System.nanoTime();541        int count = PrimeCounter.countUpTo(limit);42        long millis = (System.nanoTime() - startedAt) / 1_000_000;43 644        plugin.getServer().getScheduler().runTask(plugin, () -> sender.sendRichMessage(45            "<green>Found <white><count></white> primes up to <white><limit></white> in <white><time> ms</white>.",46            Placeholder.unparsed("count", String.valueOf(count)),47            Placeholder.unparsed("limit", String.valueOf(limit)),48            Placeholder.unparsed("time", String.valueOf(millis))));49    });50}

While the background count runs, the server keeps its 20 ticks per second, and other players do not notice anything. The time in the message is just what this computer measured; yours will differ.

Moving work between threads has more rules and some traps. Threads, performance and lag goes deeper, including how to find out which code makes your server lag.

Never sleep on the main thread

Beginners often try the obvious way to wait: Java has Thread.sleep(5000), which pauses the current thread for 5 seconds. Inside a command or event handler, that is the main thread, so the whole server pauses for 5 seconds.

1@EventHandler2public void onJoin(PlayerJoinEvent event) throws InterruptedException {3    Thread.sleep(5000);4    event.getPlayer().sendRichMessage("<green>Welcome!");5}

Everyone on the server freezes while this waits, and a watchdog may even crash the server after a while. Schedule instead: runTaskLater(plugin, () -> ..., 100L) does the same job without stopping anything. The server keeps running during the wait and calls you back.

Newer schedulers: global, entity and async

You will also see three newer schedulers in Paper code. They come from Folia, a Paper fork that splits the world into regions and runs them on many threads at once. Paper itself still has one main thread, but it offers the same API, so plugins written this way work on both. They differ from the classic scheduler in a few ways: tasks are passed as a Consumer<ScheduledTask>, delays are at least 1 tick, and the task you get back is a ScheduledTask.

The /remind command in the demo plugin uses the entity scheduler. Here is the part that schedules:

146player.getScheduler().runDelayed(plugin,347    task -> player.sendRichMessage("<gold>Reminder:</gold> <white><message>",48        Placeholder.unparsed("message", message)),449    null,550    seconds * TICKS_PER_SECOND);

The other two read very much alike. These short snippets are correct as written inside your main plugin class, where this is the plugin, once TimeUnit is imported from java.util.concurrent:

1getServer().getGlobalRegionScheduler().runAtFixedRate(this, task -> {2    getServer().sendRichMessage("<gray>The server is still running.");3}, 20L, 6000L);

1getServer().getAsyncScheduler().runDelayed(this, task -> {2    getLogger().info("Five seconds later, on another thread.");3}, 5, TimeUnit.SECONDS);

The async scheduler takes real time (a number plus a TimeUnit such as TimeUnit.SECONDS) instead of ticks, because async work has no connection to the tick loop. For a normal Paper plugin, the classic BukkitScheduler is perfectly fine and what most tutorials use. Learn the newer ones if you plan to support Folia, or when you want tasks tied to an entity.

The whole demo plugin

1name: SchedulerDemo2version: '1.0.0'3main: com.example.schedulerdemo.SchedulerDemoPlugin4api-version: '26.3'5description: An auto-broadcast, a boss bar countdown, a prime counter on another thread and delayed reminders.6permissions:17  schedulerdemo.use:8    description: Lets a player use the scheduler demo commands.9    default: true

Download the scheduler demo as a Gradle project, run it, and try /countdown 10, /primes 5000000 and /remind 10 drink water. Then use /primes 50000000 and watch that you can still walk around while it counts.

Mistakes to avoid

• Mixing up seconds and ticks. runTaskLater(plugin, task, 5) waits a quarter of a second, not five seconds. Multiply by 20.
• Forgetting to cancel. A repeating task that never stops keeps running (and keeps holding on to its player, its boss bar and everything else it uses) until the server stops. Always know how each task ends.
• Using a player after they left. Delays are long enough for anything to happen. Check player.isOnline(), or use the entity scheduler, which handles it for you.
• Touching the world from an async task. It may work a hundred times and then crash. If you need the result in the game, hop back with runTask.
• Sleeping. Never Thread.sleep in code the server calls.
• Scheduling a repeating task in an event handler without a plan. The tip task above starts once per join. That is correct, because each player gets one, and each one cancels itself. A task started on every block break without canceling would pile up thousands of tasks.
• Doing heavy work in a task that runs every tick. A period of 1 means 20 runs per second. Keep those tasks tiny.

If a task throws an error, Paper does not crash. It prints a message like Task #12 for SchedulerDemo v1.0.0 generated an exception with a stack trace in the console. Read the trace like any other, as Null, exceptions and stack traces teaches.

22@Override23public void execute(CommandSourceStack source, String[] args) {24    if (!(source.getExecutor() instanceof Player player)) {25        source.getSender().sendRichMessage("<red>Only players can sip.");26        return;27    }28    player.sendRichMessage("<green>You take a slow sip...");29 130    new BukkitRunnable() {31        private int sipsLeft = SIPS;32 33        @Override34        public void run() {235            if (!player.isOnline() || player.isDead() || sipsLeft <= 0) {36                cancel();37                return;38            }39            AttributeInstance maxHealth = player.getAttribute(Attribute.MAX_HEALTH);40            double limit = maxHealth == null ? 20.0 : maxHealth.getValue();341            player.setHealth(Math.min(limit, player.getHealth() + HEALTH_PER_SIP));42            sipsLeft--;43        }444    }.runTaskTimer(plugin, 20L, 20L);45}

Recap

• The scheduler runs your code later or repeatedly. Time is measured in ticks: 20 ticks per second.
• runTask runs next tick, runTaskLater runs once after a delay, runTaskTimer repeats with a delay and a period.
• Use a lambda for short tasks, the Consumer form for a task that cancels itself, and a BukkitRunnable class for tasks with state.
• Every repeating task needs an end: cancel it from inside, or keep its BukkitTask and cancel it from outside. Clean up what a task leaves behind in onDisable.
• Slow work goes on an async task and the Bukkit API stays on the main thread: do the work async, then hop back with runTask.
• Never Thread.sleep in code the server calls.
• The global, entity and async schedulers are the Folia-style API, available on Paper too.

Quick quiz

Next steps

• Patterns: cooldowns, toggles and player state: use timing to limit how often players can do things.
• Threads, performance and lag: more on what is safe off the main thread.
• Folia and regionized scheduling: when you want your plugin to run on Folia too.
• Titles, action bars, boss bars and sounds: the screen effects the countdown uses.