Threads, performance and lag

A plugin that works can still make a server lag. On this page you will learn what TPS and MSPT mean, how to measure your own plugin, why most of the API may only be used on the main thread, and how to spread a big job over many ticks so nobody notices it.

Ticks, TPS and MSPT

A Minecraft server does its work in small steps called ticks. In each tick it moves mobs, grows crops, runs redstone, handles what players did, and runs your plugin's code. A healthy server runs 20 ticks every second, so each tick gets exactly 50 milliseconds. That is the tick budget.

Two numbers tell you how the server is doing:

• TPS (ticks per second): how many ticks the server finishes per second. 20.0 is perfect. 15 means the game runs at three quarters of normal speed: crops grow slower, mobs move in slow motion.
• MSPT (milliseconds per tick): how long the work of one tick really takes. Under 50 is fine. Over 50, the server cannot finish in time, and TPS drops.

MSPT is the more useful number, because TPS stays at a flat 20 until you run out of budget and then falls suddenly. A server at 45 ms is already close to trouble even though it still shows 20 TPS.

This small program plays out the rule. Each number in the list is how many milliseconds of work one tick needed. Run it and read the verdicts:

1void main() {12    int budgetMillis = 50;3    int[] workPerTick = {18, 22, 31, 49, 64, 80, 36};4 5    for (int tick = 0; tick < workPerTick.length; tick++) {6        int work = workPerTick[tick];27        int tickLength = Math.max(work, budgetMillis);38        double tps = 1000.0 / tickLength;9        String verdict = work <= budgetMillis ? "fits, the server waits " + (budgetMillis - work) + " ms" : "OVER by " + (work - budgetMillis) + " ms, the next tick starts late";10        IO.println("Tick " + (tick + 1) + ": " + work + " ms of work -> " + String.format("%.1f", tps) + " TPS, " + verdict);11    }12}

Measuring: is my server slow?

You do not have to guess. Paper has measuring tools built in. Type these in the console or in chat if you are an operator:

> tpsTPS from last 1m, 5m, 15m: 20.0, 20.0, 20.0> msptServer tick times (avg/min/max) from last 5s, 10s, 1m:2.5/0.4/42.2, 2.5/0.4/42.2, 2.5/0.4/42.2

/mspt prints three numbers for each time window: the average, the fastest and the slowest tick. The slowest one is often the interesting one: a spike up to 42 ms in the example is a tick that was almost over budget. A plugin that does a big job once an hour causes exactly this kind of spike.

Finding out which plugin is slow: spark

Paper includes a profiler called spark. A profiler records what the server is doing many times per second and tells you where the time goes. Your plugin will show up by name, and even by method.

1. Start the profiler

   Run /spark profiler start and play normally, or do the thing you think is slow.

2. Stop and open the report

   After a few minutes run /spark profiler stop. spark uploads the result and gives you a link to a web page with a call tree.

3. Read the tree from the top

   Find your plugin in the list. The percentages tell you how much of the server's time each method used. A plugin that uses more than a few percent deserves a look.

For a quick health check without a full profile, /spark tps and /spark health print summaries. Paper's own guide at docs.papermc.io/paper/profiling explains how to read a report.

Timing your own code

When you suspect one particular piece of your code, time it. System.nanoTime() returns a very precise clock. Read it before and after, and subtract:

13static void timed(Plugin plugin, String label, Runnable work) {114    long start = System.nanoTime();215    work.run();316    long micros = TimeUnit.NANOSECONDS.toMicros(System.nanoTime() - start);417    if (micros > SLOW_THRESHOLD_MICROS) {18        plugin.getLogger().info(label + " took " + micros / 1000.0 + " ms");19    }20}

You would use it like Stopwatch.timed(plugin, "rebuild ranking", () -> rebuildRanking());. Remove the timing before you ship, or keep it behind a debug setting.

The demo plugin on this page also has a /perf command that shows the numbers for you with one command:

11@Override12public void execute(CommandSourceStack source, String[] args) {13    CommandSender sender = source.getSender();114    double[] tps = Bukkit.getTPS();215    double millisecondsPerTick = Bukkit.getAverageTickTime();16 317    String color = millisecondsPerTick < 40 ? "green" : millisecondsPerTick < 50 ? "yellow" : "red";18    sender.sendRichMessage("<gray>TPS over 1m / 5m / 15m: <white><one> / <five> / <fifteen>",19        Placeholder.unparsed("one", format(tps[0])),20        Placeholder.unparsed("five", format(tps[1])),21        Placeholder.unparsed("fifteen", format(tps[2])));22    sender.sendRichMessage("<gray>Average tick time: <" + color + "><ms> ms</" + color + "> <dark_gray>(the budget is 50 ms)",23        Placeholder.unparsed("ms", format(millisecondsPerTick)));24}

The main thread rule

A computer can do several things at once by using several threads. Think of threads as workers. A Minecraft server has many, but only one of them runs the game: the main thread. Mobs, blocks, players, inventories and the world all belong to it.

The rule is simple: use the Bukkit API only from the main thread. Your event handlers, commands and normal scheduled tasks already run there, so you are safe by default. Trouble starts when you move work to another thread, for example with an async task, and then touch the world from it.

The reason: the main thread keeps the world in a consistent state while it ticks. If a second worker changed a block at the same moment, two pieces of code could disagree about what the world looks like, and the server could corrupt data or crash. So Paper checks, and refuses.

The classic error

This plugin breaks the rule on purpose. It starts an async task and places a block from inside it:

10@Override11public void onEnable() {112    getServer().getAsyncScheduler().runNow(this, task -> {13        World world = getServer().getWorlds().getFirst();14        Block block = world.getBlockAt(0, 100, 0);215        block.setType(Material.GOLD_BLOCK);16    });17}

The server refuses and prints this. This is real output from a Paper 26.3 server:

[12:44:30 ERROR]: Thread Folia Async Scheduler Thread #0 failed main thread check: block onPlacejava.lang.Throwable	at org.spigotmc.AsyncCatcher.catchOp(AsyncCatcher.java:9) ~[paper-26.3.jar:26.3-142-1c92a6c]	at org.bukkit.craftbukkit.block.CraftBlock.setType(CraftBlock.java:170) ~[paper-26.3.jar:26.3-142-1c92a6c]	at threads-performance-asyncbug.jar//com.example.threadsperformanceasyncbug.AsyncBugPlugin.lambda$onEnable$0(AsyncBugPlugin.java:15) ~[?:?][12:44:30 WARN]: [AsyncBug] Async task for AsyncBug v1.0.0 generated an exceptionjava.lang.IllegalStateException: Asynchronous block onPlace!

How to read it, from the bottom up of what matters:

• IllegalStateException: Asynchronous block onPlace! is the real error. "Asynchronous" is the word to look for: it always means "you used the API from the wrong thread". The words after it, here "block onPlace", say what you tried to do.
• The line with AsyncBugPlugin.java:15 is your code. That is where to look. The line above it names the Bukkit method you called.
• The thread name in the first line, Folia Async Scheduler Thread #0, shows that the code ran on a worker. The name says "Folia" because Paper's modern schedulers share their code with Folia. It is not an error in itself.

Other versions of the same message say things like Asynchronous entity add! or Asynchronous chunk access!. They all mean the same thing, and the fix is always the same.

The fix: do the slow part async, then come back

Split the job into two parts. The slow, safe part (files, databases, web requests, big calculations) runs async. When it is done, the result is handed back to the main thread, which then touches the world or the player.

15static void tellPlayerTheirNote(Plugin plugin, Player player, Path noteFile) {116    plugin.getServer().getAsyncScheduler().runNow(plugin, task -> {217        String note = readNote(noteFile);18 319        plugin.getServer().getScheduler().runTask(plugin, () -> {420            if (player.isOnline()) {21                player.sendRichMessage("<gray>Your note: <white><note>", Placeholder.unparsed("note", note));22            }23        });24    });25}

The Scheduler page explained the two schedulers. The new rule to remember is: the async part reads and computes, the main-thread part touches Bukkit. Never pass Bukkit objects such as Block or Entity into an async task to modify them. Pass plain values (numbers, text, coordinates), not live game objects.

What is expensive?

Most plugin code is cheap. A handful of things are not, and they cause nearly all the lag that plugins cause. Learn this list.

1. Loading chunks

A chunk is a 16 by 16 column of the world. Asking for a block in a chunk that is not loaded makes the server read or even generate that chunk, right now, on the main thread. On the test server for this page, generating the chunks under a 256 by 256 area took about 2.7 seconds, all inside a single tick. That is 54 ticks' worth of freezing.

The better way is to ask for the chunk and let the server load it in the background. When it is ready, you get called on the main thread:

15static void placeGoldBlockWithoutFreezing(Location target) {116    int chunkX = target.getBlockX() >> 4;17    int chunkZ = target.getBlockZ() >> 4;218    target.getWorld().getChunkAtAsync(chunkX, chunkZ)319        .thenAccept(chunk -> target.getBlock().setType(Material.GOLD_BLOCK));20}

2. Doing heavy work on every movement

PlayerMoveEvent fires every time a player moves or even turns their head. With 50 players that is thousands of calls per second. Anything slow in that handler is multiplied by thousands. The first rule for such hot paths is to exit early:

13@EventHandler(ignoreCancelled = true)14public void onMove(PlayerMoveEvent event) {115    if (!event.hasChangedBlock()) {16        return;17    }18    Location to = event.getTo();219    if (to.getBlockX() == GOAL_X && to.getBlockZ() == GOAL_Z) {20        event.getPlayer().sendRichMessage("<green>You reached the goal block!");21    }22}

3. Scanning for entities

Methods like getNearbyEntities look at every entity around a point. One call is fine. Hundreds per second add up. Never call them from a hot path such as PlayerMoveEvent without a limit, and prefer the typed version getNearbyEntitiesByType, which only returns the kind of entity you asked for.

4. Files and databases on the main thread

Reading or writing a file, talking to a database or fetching a web page waits for something outside the computer's fast memory. A disk read that takes 20 ms freezes the entire server for 20 ms. Do this kind of work async, as in the AsyncRoundTrip example above.

5. Building text nobody reads

Strings are cheap one at a time, but not in a hot path. This logs a message on every move, even though nobody ever reads most of them:

1@EventHandler2public void onMove(PlayerMoveEvent event) {3    String text = "Player " + event.getPlayer().getName() + " moved to " + event.getTo();4    getLogger().info(text);5}

The text is built every time, and the console fills up. Build text only when you need it, and put debug messages behind a setting that is off by default.

Caching, batching and spreading work

Three ideas fix most slow code.

• Do it less often. Ask: does this really have to run every tick? A scoreboard that updates once per second instead of every tick does 5% of the work.
• Cache answers. If you look up the same thing again and again (a player's rank, a coin balance, a config value), remember the answer and reuse it. Update the cache when the value really changes, and remove entries when players leave, or the cache grows forever.
• Spread big jobs. A job that needs 500 ms cannot run in one tick. Split it into pieces and do a few milliseconds of it per tick. Players see a short delay instead of a freeze.

Spreading a job: the idea

Here is the same idea in plain Java, with no Minecraft in the way. There are 5,000 jobs and each tick can do 800 of them:

1void main() {2    int totalJobs = 5000;13    int jobsPerTick = 800;4 5    int finished = 0;6    int tick = 0;27    while (finished < totalJobs) {8        tick++;39        int thisTick = Math.min(jobsPerTick, totalJobs - finished);10        finished += thisTick;11        IO.println("Tick " + tick + ": did " + thisTick + " jobs, " + finished + " of " + totalJobs + " finished");12    }13 14    IO.println("All done after " + tick + " ticks, which is " + tick / 20.0 + " seconds");15}

Spreading a job: a real plugin

The example plugin has a command /bigfill SIZE BLOCK [instant], for example /bigfill 64 stone (the word in brackets is optional). It fills a flat square of blocks under your feet. Without instant it spreads the work over many ticks. With instant it does everything in one tick, so you can compare them.

The heart of it is FillJob. It remembers how far it got in a counter called nextIndex and does as much work as it may each tick:

57private void runOneTick(BukkitTask task) {58    long start = System.nanoTime();159    long deadline = start + BUDGET_NANOS_PER_TICK;260    while (nextIndex < totalBlocks && System.nanoTime() < deadline) {61        placeBlock(nextIndex);362        nextIndex++;63    }64    workNanos += System.nanoTime() - start;65    ticksUsed++;66 67    if (nextIndex >= totalBlocks) {468        task.cancel();69        reportFinished();570    } else if (player.isOnline()) {71        int percent = nextIndex * 100 / totalBlocks;72        player.sendActionBar(Component.text("Filling... " + percent + "%", NamedTextColor.YELLOW));73    }74}

The counter is turned into a position with two small calculations:

76private void placeBlock(int index) {177    int x = minX + index % size;278    int z = minZ + index / size;379    world.getBlockAt(x, y, z).setType(material, false);80}

The command starts it with a repeating task. The two numbers 1L, 1L mean "start in one tick, then repeat every tick":

42void startSpread() {143    plugin.getServer().getScheduler().runTaskTimer(plugin, this::runOneTick, 1L, 1L);44}

On the test server, a 256 by 256 fill (65,536 blocks) in an already loaded area printed this when run the spread way:

That is about 6.7 seconds of game time, with the plugin using only a few milliseconds of every tick. The average is a bit above the 2 ms budget because a single block that triggers extra work can run past the limit. The check only happens between blocks, so a budget is a goal, not a guarantee. Keep it small enough that one slow block cannot hurt.

Thread-safety basics

Sometimes you do want several threads to share data: an async task fills a cache while the main thread reads it. Then a second danger appears: two threads changing the same value at once. That is called a race condition, and Java's ordinary tools are not thread-safe against it.

This program makes two threads each add one to a counter a million times. Three versions of the counter take part. Run it:

1import java.util.concurrent.ConcurrentHashMap;2import java.util.concurrent.atomic.AtomicInteger;3 14int plainCounter = 0;5 6void main() throws InterruptedException {27    AtomicInteger atomicCounter = new AtomicInteger();8    ConcurrentHashMap<String, Integer> kills = new ConcurrentHashMap<>();9 10    Runnable work = () -> {11        for (int i = 0; i < 1_000_000; i++) {12            plainCounter++;13            atomicCounter.incrementAndGet();314            kills.merge("Steve", 1, Integer::sum);15        }16    };17 18    Thread first = new Thread(work);19    Thread second = new Thread(work);20    first.start();21    second.start();422    first.join();23    second.join();24 25    IO.println("Plain int:           " + plainCounter + " (should be 2000000)");26    IO.println("AtomicInteger:       " + atomicCounter.get());27    IO.println("ConcurrentHashMap:   " + kills.get("Steve"));28}

The plain number comes out smaller than 2,000,000, because sometimes both threads read the same old value and one of the additions is lost. Your exact number will differ every time you run it. The atomic counter and the ConcurrentHashMap always get it right.

The practical rules for plugins:

• Data shared between the main thread and async tasks goes into thread-safe containers: ConcurrentHashMap instead of HashMap, and AtomicInteger instead of a plain number you change from several threads.
• Data only the main thread touches can stay in normal HashMaps. This is most of your plugin, and it is simpler and faster.
• Bukkit objects (players, blocks, worlds) are never thread-safe. Do not touch them from async code. Pass plain values instead.

Here is a small cache that follows the rules. It may be filled from async tasks and read from event handlers, and it forgets players who leave:

1package com.example.threadsperformancesnippets;2 3import java.util.Map;4import java.util.UUID;5import java.util.concurrent.ConcurrentHashMap;6import org.bukkit.event.EventHandler;7import org.bukkit.event.Listener;8import org.bukkit.event.player.PlayerQuitEvent;9 10final class PlayerCache implements Listener {11 112    private final Map<UUID, Integer> coinsByPlayer = new ConcurrentHashMap<>();13 14    int coinsOf(UUID playerId) {215        return coinsByPlayer.computeIfAbsent(playerId, this::loadCoinsFromDisk);16    }17 18    void addCoins(UUID playerId, int amount) {319        coinsByPlayer.merge(playerId, amount, Integer::sum);20    }21 22    @EventHandler23    public void onQuit(PlayerQuitEvent event) {424        coinsByPlayer.remove(event.getPlayer().getUniqueId());25    }26 27    private int loadCoinsFromDisk(UUID playerId) {28        return 0;29    }30}

Mistakes to avoid

• Touching blocks, entities or players from an async task. Do the slow part async, then hop back to the main thread.
• Reading files or databases in an event handler. Load once, cache, or load async.
• Heavy work in PlayerMoveEvent without an early exit. Start with hasChangedBlock().
• A cache that is never cleaned. Remove entries when players leave or when data changes.
• Using Thread.sleep to "wait". It freezes the thread it runs on, and on the main thread it freezes the whole server. Use a delayed task instead.
• Guessing instead of measuring. Run /spark profiler start and look at the report before you rewrite anything.

1@EventHandler2public void onMove(PlayerMoveEvent event) {3    Player player = event.getPlayer();4    int monsters = player.getWorld().getNearbyEntitiesByType(Monster.class, player.getLocation(), 16).size();5    player.sendActionBar(Component.text("Monsters within 16 blocks: " + monsters));6}

23@EventHandler(ignoreCancelled = true)24public void onMove(PlayerMoveEvent event) {125    if (!event.hasChangedBlock()) {26        return;27    }28    Player player = event.getPlayer();229    int now = Bukkit.getCurrentTick();30    Integer lastScan = lastScanTickByPlayer.get(player.getUniqueId());331    if (lastScan != null && now - lastScan < SCAN_INTERVAL_TICKS) {32        return;33    }34    lastScanTickByPlayer.put(player.getUniqueId(), now);35 36    int monsters = player.getWorld().getNearbyEntitiesByType(Monster.class, player.getLocation(), SCAN_RADIUS).size();37    player.sendActionBar(Component.text("Monsters within 16 blocks: " + monsters, NamedTextColor.RED));38}

Recap

• The server has 50 ms per tick. MSPT is how long a tick really takes, TPS falls when MSPT goes over 50.
• Measure with /tps, /mspt and the bundled /spark profiler, and time your own code with System.nanoTime().
• Use the Bukkit API only on the main thread. The error to know is IllegalStateException: Asynchronous ...!.
• Do slow, safe work async, then hop back to the main thread to touch the world.
• The expensive things are chunk loading, hot paths like PlayerMoveEvent, entity scans, file and database work on the main thread, and text nobody reads.
• Cache answers, do less often, and spread big jobs over many ticks with a time budget.
• Data shared between threads needs ConcurrentHashMap or atomic classes. Bukkit objects are never thread-safe.

Quick quiz

Next steps

• Review the schedulers in Scheduling tasks.
• Learn how the same ideas change when the server runs many threads at once in Folia and regionized scheduling.
• Find bugs faster in Debugging.