Minecraft Folia: when multithreading pays off

Folia is PaperMC's fork of Paper that removes the main thread. Instead of ticking the whole world in one loop on one core, it splits loaded chunks into independent regions and ticks each region on its own thread, in parallel. For a server with hundreds of players spread across a huge map and a machine with a lot of real cores, it is the only real answer to Minecraft's single-thread ceiling. For almost everybody else - an SMP where people live in one town, a modest plan with two or three vCPUs, a plugin list that includes EssentialsX - it is slower to run, harder to administer and incompatible with most of what you rely on. The rest of this post explains the mechanism, because once you see it the decision mostly makes itself.

What Folia changes about the tick#

A normal Minecraft server, vanilla or Paper, runs one tick loop. Twenty times a second the main thread walks through every loaded world, every ticking chunk, every entity, every block entity, every scheduled redstone update, and every plugin task, in order. If the total work takes longer than 50 milliseconds, the tick is late and TPS falls below 20. Paper moves a lot of side work off that thread - chunk loading and generation, lighting, some networking - but the simulation itself is still one queue on one core. That is why a Minecraft server cares about clock speed far more than core count, and why CPU vs RAM for game servers keeps telling people to check single-thread performance first.

Folia breaks that queue apart. Loaded chunks that are near each other are grouped into an independent region. Each region has its own tick loop, runs at the normal 20 ticks per second, and is executed on a pool of tick threads alongside every other region. There is no main thread any more; each region is effectively its own small server sharing a process.

Regions are not fixed areas of the map. They form around whatever is loaded, which in practice means around players. Two players a few thousand blocks apart are two regions on two threads. When those players walk towards each other, their regions merge as the loaded areas touch, and from that moment they are one region ticked by one thread. When they separate again, the region splits.

What does not belong to any region - world time, weather, game rules, the console, and similar global state - lives on a separate global region that also ticks independently.

The diagram contains the whole catch. Region C, with forty players in one place, is still one region on one thread. Folia does nothing for a crowd. It only helps when the load is spread across areas far enough apart to stay separate regions.

Who Folia is built for, in PaperMC's own words#

The Folia project is unusually blunt about its audience. Its documentation describes servers where players are naturally spread out - large survival servers and skyblock-style servers are the examples it gives - and recommends hardware with at least 16 physical cores, not threads. It also says, in effect, that every existing plugin should be expected to need changes.

That gives a fair test before you go further:

If you answered "Stay on Paper" to any one of those rows, Folia is very unlikely to be an improvement. The single-thread ceiling is a real limit, but a well-tuned Paper server reaches it far later than people expect - usually somewhere past a hundred active players on a fast core with sensible view distances. Paper optimisation and a spark profile are cheaper than a platform change and solve the problem most servers actually have.

Plugin compatibility: the wall most servers hit#

Folia refuses to load a plugin that has not declared support. The declaration is one line in the plugin's plugin.yml:

name: ExamplePluginversion: 1.4.0main: com.example.ExamplePluginapi-version: '1.21'folia-supported: true

That line is not a formality. Without a main thread, the classic Bukkit pattern - "run this on the next tick" through BukkitScheduler - has no thread to run on. Folia replaces it with four schedulers:

• Global region scheduler for work that belongs to the global region, such as broadcasting a message or changing the weather.
• Region scheduler for work at a specific location, run on whichever thread owns that location's region.
• Entity scheduler for work that follows an entity, so a task attached to a player moves with the player when they cross into another region.
• Async scheduler for work that does not touch the world at all, such as database queries and web requests.

Paper's API includes the same schedulers, so a plugin written for them can run on both Paper and Folia from one jar. A plugin written the old way cannot run on Folia without being rewritten, because touching a block or an entity from the wrong thread is now an error rather than a habit.

The practical consequences for a server owner:

1. Check every plugin before you plan anything. The plugin's page or its plugin.yml will say. If it does not mention Folia, assume it is not supported.
2. Expect gaps in the categories you care about most. Permissions (LuckPerms) and profiling (spark) have long supported Folia, and pre-generation with Chunky works. The big all-in-one plugins, most economy and shop plugins, and a large share of minigame plugins have not, and EssentialsX in particular is a Paper plugin. Check the current state yourself - support changes, and lists online go stale.
3. Do not patch the line in yourself. Adding folia-supported: true to a plugin that was not written for Folia makes it load and then fail unpredictably, often by corrupting the state it was trying to change. The declaration is the plugin author's promise, not a switch.

Teleports are a good example of why this matters. On Paper, moving a player across the world is a method call. On Folia, the destination may belong to another region on another thread, so teleporting is asynchronous and the plugin has to handle the moment in between. Plugins that assume teleports are instant are the source of a whole class of Folia bugs.

Installing Folia and its configuration#

PaperMC publishes Folia builds alongside Paper on its downloads site, and Folia has usually arrived for a new Minecraft version some time after Paper does. Check that a build exists for the version you want before you plan an upgrade around it.

The jar starts exactly like Paper's, with the same Java requirements - Java 21 for current versions - and it writes the same configuration files: server.properties, bukkit.yml, spigot.yml, and the config/ directory with paper-global.yml and paper-world-defaults.yml. Folia adds its own section to paper-global.yml for the tick threads:

threaded-regions:  threads: -1chunk-system:  io-threads: -1  worker-threads: -1

threads: -1 lets Folia choose the number of tick threads from the available cores. The chunk system settings are the same ones Paper has and control the threads used for loading and generating chunks. On a machine with plenty of cores you can set these explicitly so tick threads, chunk workers and network threads are not all competing for the same cores; on a small allocation there is nothing to divide, which is the point of the next section.

Three administration differences to know before the first start:

• Pre-generate the world. Folia's own guidance is to pre-generate so that chunk generation does not compete with ticking. On Folia this matters more than on Paper, because exploring players are exactly the spread-out load it is built for. World borders and pre-generation has the procedure with Chunky.
• TPS is per region. A Folia server does not have one TPS. One region can be at 20 and another at 12 because forty players built a mob farm in it. Folia reports region health through its own commands, and you have to read it region by region rather than glancing at one number.
• Some vanilla behaviour is different or missing. Anything that assumed one global tick order - certain scoreboard tricks, cross-region redstone and command-block contraptions, plugins that iterate every online player in one go - may behave differently. Test on a copy.

Why Folia is a poor fit for a small plan#

Folia trades single-thread speed for parallelism, and parallelism is worth nothing without cores to run it on. On a server allocated two or three vCPUs - which covers most game hosting plans, including the Minecraft line here - the tick threads, the chunk workers, the network threads and garbage collection all share the same small slice. Splitting the work into regions adds coordination overhead and gives it nowhere to go.

Here is the honest arithmetic. Suppose your Paper server spends 40 milliseconds per tick at peak. On Folia with two usable cores, the best case is that the regions divide the load evenly between two threads - 20 milliseconds each - minus the cost of region bookkeeping. The realistic case is that most of your players are in one or two areas, one region does most of the work, and you are back near 40 milliseconds with extra overhead and fewer plugins. Meanwhile the chunk workers and the garbage collector are competing for the same two cores that the tick threads are trying to use.

On RE:NODE, CPU is a hard throttle to the share you bought: a Minecraft plan runs from one core on Starter to 3.5 vCPU on Premium, and the limit is enforced per container rather than borrowed from neighbours. That is a perfectly good allocation for Paper, where one fast thread does the simulation and the rest absorbs chunk work and GC. It is nowhere near the 16 physical cores Folia is designed around. A server sitting at 100% CPU is slow rather than broken and is never suspended for it - but on Folia you would hit that 100% sooner, not later.

Even a whole dedicated machine needs thought. The VDS line here tops out at six cores on an i9-9900K, which is a fast chip for Paper and still below the core count Folia's documentation recommends. If you are genuinely at the scale where Folia is the answer, you are also at the scale where you are speccing hardware around it.

What to do instead, at every size#

The single-thread ceiling is real, and there are cheaper ways to stay under it than replacing the server platform.

Under 50 players. Paper with sane settings. view-distance around 8 and simulation-distance around 6, entity limits that match your farms, a pre-generated world and a border. This range is nearly always limited by one misbehaving thing rather than by the platform. Why TPS drops and what to do covers the usual suspects.

50 to 150 players. Still Paper, with tuning: per-world entity activation ranges, hopper and redstone settings, and a careful plugin list. Consider Purpur or Pufferfish if you need their specific features, but the gains come mostly from configuration, not from the fork.

Several distinct game modes. Split them into separate servers behind a proxy instead of one big process. A lobby, a survival world and a minigame server on three backends are three main threads on three CPU allocations, each restartable without the others. That is multithreading by architecture rather than by fork, and every plugin you own still works. Building a Velocity network is the walkthrough.

Hundreds of players in one shared world, with the hardware. This is Folia's case. Even then, plan for a plugin audit, a staging server, and someone on staff who can read a thread-ownership exception.

You need Folia only if all of these are true:  - the world is shared and genuinely large  - players are spread across it, not gathered in one place  - you have well over 8 physical cores for this one server  - every plugin you need declares folia-supported: true  - Paper, tuned and profiled, has already hit its limit

Moving to Folia, and back again#

If you have passed every test above, the move itself is not dramatic. Folia uses Paper's world format and folder layout - world, world_nether and world_the_end at the top level - so a Paper world loads on Folia without conversion, and a Folia world loads back on Paper.

1. Take a backup off the machine and confirm you can restore it. Backups that actually restore explains why a copy in the same folder does not count.
2. Remove every plugin without Folia support from plugins/, and keep their data folders somewhere safe so you can return to them.
3. Swap the jar for the matching Folia build, keeping the same Minecraft version.
4. Start with nobody online and read the log from the top. Any plugin Folia refuses to load is named there.
5. Test the things that cross regions: teleports, portals, cross-world commands, anything that broadcasts to all players, and any economy or claim plugin that has to look up blocks far from the person running the command.
6. Load test with real players before announcing it. Synthetic load rarely spreads out the way real players do.

Going back is the same in reverse: stop the server, swap in the Paper jar, restore the plugins you removed. Because the world format is shared, the only things you lose are the region-aware behaviours you came for.

On RE:NODE the Minecraft line ships Paper with the matching Java already chosen. Folia is something you would upload yourself through the file manager or SFTP and point the Startup tab at - there is no whitelist of allowed jars, and equally there is no one-click switch. Backup slots are on every plan, can be locked against rotation while you test, and restore with a button if the experiment does not work out.

FAQ#

Is Folia faster than Paper?

Only for a specific shape of load. With many players spread across a large world on a machine with many cores, Folia can keep every region at 20 TPS where Paper would fall behind. With players clustered together, or on a small CPU allocation, it is usually no faster and can be slower because of the coordination overhead.

Can I run normal Paper plugins on Folia?

Not unless the author has added Folia support and declared folia-supported: true in plugin.yml. Folia refuses to load anything else. Plugins written with Paper's region and entity schedulers can run on both from one jar; plugins written around the old Bukkit scheduler cannot.

Does Folia help a server with 20 players?

No. Twenty players are well within what one fast thread on Paper can handle when the server is configured sensibly. If a 20-player server lags, something specific is eating the tick, and a profiler will find it faster than a platform change.

Will my world survive switching to Folia?

Yes. Folia uses the same world format and the same Bukkit-style folder layout as Paper, so the world loads in both directions. What changes is which plugins can run, so back up the plugin data folders along with the world.

Is Folia stable enough for production?

Some very large servers run it in production, and PaperMC publishes regular builds. It still lags Paper on new Minecraft versions, its plugin ecosystem is much smaller, and fewer people can help when something goes wrong. Treat it as infrastructure for large networks with technical staff rather than an upgrade for any server.