Minecraft anticheat guide
Packet Processing and Async Threads for Minecraft Admins
How packet processing and async threads work on a Minecraft server, why thread ownership matters for anticheats, and what to check when packet work causes lag.
Packet processing and async threads in one answer
A Minecraft server receives each client packet on a network thread first. Packet listeners, including the ones an anticheat uses, run on that path before the main game thread applies the result. Work that touches world state must run on the main thread, so most checks and all punishments stay there. Async threads help only with work that reads or computes data without calling the Bukkit API.
Where each kind of work runs
Each stage of a packet has a different thread and a different failure mode. Keep this map in mind when a plugin's log says a call was made from the wrong thread, or when a lag spike lines up with a burst of client input.
The exact scheduling is version and server-software specific. Confirm it in the documentation for your release before you rely on it.
| Work | Usual thread | Admin risk if misplaced |
|---|---|---|
| Decode and read client packets | Network I/O thread | Slow listeners delay later packets for that player |
| Packet listener code from a plugin | Network I/O thread | Heavy per-packet work adds latency for every player |
| Bukkit events and entity or world changes | Main server thread | Calling these from async code can throw errors or corrupt state |
| Plugin tasks scheduled as async | Worker thread pool | Blocking I/O here is safe for the tick, but results must return to the main thread |
| Database and webhook writes | Async worker | A slow remote call that runs on the main thread stalls the tick |
Why thread ownership matters for anticheats
An anticheat that reads packets can record movement, clicks, and slot changes without waiting for the main thread. That is the reason packet-based checks can be cheap. The cost moves to the moment the anticheat decides to act. A punishment, a teleport, or a message to a player must go back through the main thread.
Ask your anticheat vendor how its checks handle these points:
Check whether packet work is the bottleneck
Packet work usually shows up as lag during bursts of input, not during quiet periods. Start by comparing lag timing with player activity. If lag rises with the number of players clicking, sprinting, or placing blocks, packet handling is a likely candidate. If lag stays flat while the tick time climbs with no player input, look elsewhere first.
When you need to see which threads are busy at the moment of lag, take a thread dump during an event. A JDK ships a tool for this. Replace the placeholder with the process ID of your server.
jcmd <server-pid> Thread.print > thread-dump-<timestamp>.txtHow to read a thread dump without guessing
Look for threads that are in a running state with a stack that includes your anticheat package, a database driver, or a web client. Do not conclude that a method is slow from one dump. Take two or three dumps several seconds apart during the same spike. A thread that stays in the same frame across dumps is the one to investigate.
A thread stuck in a socket read on a logging plugin points to the logging path, not the packet listener. Keep the dump, the timestamp, and the player count together so the evidence can be reviewed later.
Compare the dump with the event log for the same minute. If a player used a heavy action such as a mass chest sort, a large explosion, or a rapid sequence of block placements, note it beside the dump. Packet-driven cost tends to line up with a specific player action. A dump that shows no busy packet thread during a spike suggests the cost is elsewhere, and you should move on to the tick and world tasks rather than tuning the anticheat.
What we have not verified
This page does not measure how much time any packet listener takes on your hardware. It does not compare anticheats on packet cost. Thread behavior changes between Paper, Folia, and older server software, so treat these points as a checklist for your own staging tests, not as a guarantee.
Relevant background is in the PaperMC documentation and in the PacketEvents and ViaVersion project pages.
FAQ
Can an anticheat safely do work off the main thread?
Reading packet data and computing a score can be done off the main thread. Changing players, entities, or the world must happen on the main thread. Ask the vendor which of its checks do each.
Why does a thread dump show my anticheat during lag?
A single dump shows a single moment. Take several dumps during the same spike. If the anticheat appears in the same frame each time, check its logging or punishment path first.
Does more async work always reduce lag?
No. Extra async tasks add context switches and can queue results that must return to the main thread. Measure before and after a change in staging.