Folia: when you need regionised multithreading

Folia is for big servers whose players are spread across the world: SMP, survival, SkyBlock with a large player count on a powerful machine. It splits the world into independent regions and ticks them in parallel. A typical server gains nothing from it, and most plugins simply won't load. PaperMC itself says Folia "is by no means a drop-in replacement for Paper".

How Folia works#

Regular Paper runs the whole world on one main thread: 20 ticks per second, with mobs, redstone and players all squeezed into 50 ms per tick. As the player count grows, a single CPU core becomes the ceiling.

Folia is a fork of Paper by the same PaperMC team. It groups nearby loaded chunks into independent regions. Each region has its own tick loop at the regular 20 TPS, and the loops run in parallel on a thread pool. There is no main thread any more: each region is effectively its own. Data that isn't tied to a place — time of day, weather, the world border, console commands — is handled by a separate global region.

That's the key property: when players spread out, Folia creates many regions and spreads them across cores. When everyone stands at spawn, that's essentially one region — and one core, just like Paper. Folia is its own project too: per the README, it won't be merged into Paper for the foreseeable future.

Who Folia is for#

Before moving, ask yourself honestly: is the server actually capped by one core right now? If TPS drops because of a specific plugin or farm, Folia won't fix it — that region will lag on Folia too. Find the cause with a profiler first, as in Why your server lags. Every option side by side: Which server software to choose.

Hardware and thread allocation#

The Folia README suggests at least 16 physical cores — cores, not threads. It also recommends pre-generating the world, which greatly reduces the number of chunk worker threads you need. How to do that: pre-generating the world.

Threads are allocated by hand. The developers give a very rough estimate based on their test server, which peaked at around 330 players, and stress it's only a starting point:

• netty IO — about 4 threads per 200–300 players;
• chunk system IO — about 3 per 200–300 players;
• chunk system workers on a pre-generated world — about 2 per 200–300 players;
• garbage collection — whatever -XX:ConcGCThreads sets (not -XX:ParallelGCThreads, which only runs while the application is paused);
• the rest goes to region tick threads, threaded-regions.threads in the global config, keeping total allocation under 80 % of the cores.

The 20 % headroom exists because the server and plugins create threads you can't configure or predict. Expect to tune the split once you see real thread usage.

Plugins on Folia#

This is the real barrier. Much of the Bukkit API relies on the main thread, and Folia doesn't have one. The README's author expects every existing plugin to need some modification and says to set your expectations for compatibility at zero.

The loading rule is simple: Folia loads only plugins with `folia-supported: true` in their `plugin.yml` — that's how an author declares the plugin ready for regions. Everything else won't load. Ready plugins use Folia's schedulers (RegionScheduler, EntityScheduler and others) instead of the Bukkit scheduler, and teleport players only asynchronously with teleportAsync.

name: ExamplePlugin
main: com.example.ExamplePlugin
version: 1.0
folia-supported: true

• Some API is unsupported: the entire scoreboard API, world loading and unloading, parts of the portal, respawn and login API.
• Some commands are disabled, including /scoreboard, /team, /spectate, /reload, /data, /clone, /function and /tick — the full list is in the Folia docs FAQ.
• Support is growing: LuckPerms, for instance, lists Folia among its platforms on Modrinth. Still, check every plugin on your list before the move, not after.

Anticheats on Folia#

Folia is especially hard on anticheats: they track every player's movement, combat and packets, and on Folia that data lives on different threads. Check an anticheat's Folia support as strictly as any other plugin's — on its own page and docs.

DGuard doesn't support Folia. It's built for Paper and Leaf on versions 1.21–26.3. If your server can stay on Paper or Leaf, you get DGuard across every front — combat, movement, building, inventory, packets — and the AI Combat neural network for PvP.

For PvP DGuard has AI Combat — its own AI combat model, trained on billions of gameplay data points from the most popular PvP servers: it reads KillAura, aim and TriggerBot in DGuard's cloud check. That's why for a big PvP server Leaf with DGuard is often the better call than Folia without anticheat support. More on the AI Combat page.

FAQ#