< Back to posts index

Folia - Multithreading Coming to your Minecraft server

11 min read 2409 words
EterNity
Thumbnail

Folia - Multithreading Coming to your Minecraft server

Project Folia 🔗

Folia is the latest project under the PaperMC organization, which aims to achieve true multithreading and regionalized ticking. The goal of this project is to provide better scalability and performance, while fixing a few long-standing issues that have been the limiting factor to scaling up a Minecraft server.

Folia is a fork of Paper by none other than the Minecraft optimization legend Spottedleaf. Originally started in August 2020, just before Tuinity merged with Paper, Folia represents the culmination of a series of prerequisite patches, including Starlight, player chunkmap, and chunk rewrite, which were added to Paper in the last few years.

Spottedleaf has systematically tackled the roadblocks in Vanilla Minecraft that prevented all previous attempts at multithreading by countless other developers and projects. The goal of the Folia project is to provide a no-compromise solution for a true multithreaded server, achieved through a brand new set of APIs designed specifically for this environment.

The purpose of this article is to present the information in an easy-to-understand format and provide some detailed insights that may not necessarily be included in the official announcement. Official Folia GitHub Page

Editor’s Update (2024): 🔗

Since the publication of this blog post, a full year has passed. With the help of plugin developers and server owners who are willing to experiment with the cutting-edge technology infused in Folia, we have seen promising growth in server adaptations. Among those hundreds of servers using Folia, 2b2t and DonutSMP stand out as testaments to Folia’s scalability and stability.

2b2t, nicknamed the oldest anarchy server, has a long history of low TPS and frequent crashes and exploits. The update to 1.19 was thought to be impossible, but it has been smooth sailing since the switch to Folia.

DonutSMP, perhaps the current biggest network using Folia, has deployed multiple instances of Folia to support their huge SMP network, managing thousands of concurrent players daily and over 460k entities on its server clusters.

I wish for your continued support of this project. To help Spottedleaf, the developer of Folia, directly, you can donate here.

folia2

Some stats from DonutSMP with real player activities. Thanks to Pedro Pagani ❤️

folia3

DonutSMP Region Utilization

Last updated: June 4th, 2026 for Folia version 26.1.2.

Table of Contents

Introduction to Folia 🔗

Folia groups nearby loaded chunks to form an “independent region.” Each independent region has its own tick loop, which is ticked at the regular Minecraft tick rate (20TPS). The tick loops are executed on a thread pool in parallel. There is no main thread anymore, as each region effectively has its own “main thread” that executes the entire tick loop. Note that each region does not have a unique thread, but rather shares threads from a configurable thread pool.

For a server with many spread out players, Folia will create many spread out regions and tick them all in parallel, which will perform significantly better than the current method of ticking all worlds one after the other. - Spottedleaf

For technical details:

It is worth noting that the “region” referred to in Folia is not the same as the region in Vanilla Minecraft. Instead, it is defined as follows:

A region is simply a set of owned chunk positions and an implementation defined unique data object tied to that region. It is important to note that for any non-dead region x, for each chunk position y it owns, there is no other non-dead region z such that region z owns the chunk position y.

The entire process of region creation, merging, and separation is handled by the Regioniser governed by Fundamental Regionising Logic.

Imagine each active region as a bubble! When two bubbles get close, they will merge into a bigger bubble.

Benefits of Folia 🔗

What are the Benefits of Folia?

Unlike the countless failed attempts at multithreading that are plagued with bugs and game-breaking behavioral changes, Folia is built on a strong foundation and is created by someone with a deep understanding of the Vanilla codebase. Many forks of Paper have tried to optimize the server further, but with limited success due to the main tick loop still running within a single thread. This is a hard ceiling that a simple fork of Paper cannot overcome without some drastic changes, such as those made in Folia.

Who is Likely to See Benefits Running Folia?

  • Medium to large sized servers with sufficient hardware (threads) to support it. Folia shines when the server has unused threads, as each region is now ticked independently. This should result in a noticeable performance gain, especially with powerful hardware.

  • Survival multiplayer, anarchy, skyblocks, or some mini-game servers. Game modes such as survival multiplayer and skyblock, in which players are often spread apart, can fully utilize the regionizer and provide additional performance boosts that were previously not achievable on Paper.

  • Smaller server networks that are looking to scale up their operations. Large networks that already have custom sharding solutions for their scaling problems may not be too interested, as they have already invested a significant amount into their infrastructure. However, Folia will enable smaller server owners who may not have the necessary budget for such an endeavor yet to scale up their operations without drastically complicating their setup.

  • Single core performance is no longer the only option to increase performance. Server owners now have more options when picking a suitable CPU for their Minecraft servers. Single-threaded performance is no longer the only factor directly related to performance. Instead, a slightly lower clock speed but higher core count CPU model may not only save the server owner a few bucks but also provide more benefits than top of the line CPUs, which often come at a premium cost.

  • Will I see a performance increase as a small survival server owner? “Yes,” if you have sufficient threads available. Folia may benefit smaller niche server owners who wish to restore mob spawning behavior closer to Vanilla. It allows them to create larger farms without negatively impacting the overall server performance.

folia4

It is recommended to have a minimum of 16 physical cores in order to fully benefit from Folia.

Breaking the hard ceiling…

The current maximum capacity for a Minecraft server with Vanilla-like configuration is around 60 - 80 players. There is no server software that can handle more players without compromising the Vanilla feel or imposing harsh limits on player freedom. Folia is here to change that!

Let’s be real here, playing on a server with 3 view distance and 8 mobs per player sucks.

Some Interesting Facts on Folia

  • Lag is now localized. Since each region is ticked independently of one another, lag is now localized and contained within an active region. This renders all existing lag machines useless, as griefers would only be lagging themselves. Players with super large farms will no longer tank server TPS as a whole; rather, the TPS drop will be contained within that particular region.
  • Entity spawning behavior is now closer to Vanilla single player. Mob spawning has always been an issue in Minecraft multiplayer. This is due to the fact that the mob spawn logic is run globally while taking all loaded chunks into account, which creates a bias in entity distribution. However, in Folia, each region runs its own mob spawning logic. The days of slower mob yield when multiple players are online on a server are no more.
  • An enhanced TPS report. The command /tps has been reworked and now shows each region independently. Server admins can now click to teleport directly from the report to inspect the immediate area of a problematic region.
folia5

Admin Support 🔗

The success of the Folia project relies on you, the many server owners and admins who have helped make Paper the enormous success it is today. To ensure a smooth launch for Folia, we encourage everyone to join the discussion and help test the software in order to identify any issues or bugs that may arise. Join the Paper Discord here and be part of the discussion!

Developer Support 🔗

If you are a developer and wish to provide support for Folia, please check out the Folia Project Overview and join the discussion in the PaperMC Discord community. Your expertise is the most valuable feedback for us. This is also a rare chance to fix a few long-standing issues that have been plaguing the CraftBukkit and Spigot ecosystem. Together, we can build a better foundation for the future of Minecraft!

To prevent end users from loading any Paper plugin onto Folia without first confirming its compatibility, we have added a check to the plugin’s plugin.yml file using folia-supported: true. If your plugin requires no update, this would be a simple one-line change to ensure compatibility with Folia.

Folia Plugins 🔗

Since 2023, several new plugins have extended their support to Folia, and you can find them on either Hangar, PaperMC’s own plugin hub, or Modrinth, another popular resource website that hosts a wide variety of Minecraft plugins.

Below are a few notable plugins with full Folia support!

Special Thanks 🔗

To the Kind Sponsors of PaperMC:

Thank you for your continued support of the project. The Folia open beta testing, initially for sponsors and later open to the public, was a successful and enjoyable community bonding activity. Together, we can create the best Minecraft community!!

To the Entire Paper Chan Discord:

This section is dedicated to you, the many closed beta testers of the Paper Chan Discord cult community who took the time to show up for testing, helped identify issues in the early stages, and were supportive while keeping the project a secret. It was genuinely a pleasant experience, and the voice chat was super fun! You guys rock!

Folia Testing Records 🔗

Below is a record of our Public testing…

What has our Public and Private Testing Shown?

The “Regioniser” (region logic) can fully utilize all 32 CPU threads without any apparent bottleneck or significant degradation of performance.

But wait, why stop at 32 cores!? It’s go big or go home!!

By a stroke of luck, we managed to snatch a server with dual AMD EPYC CPUs with the following specs!

  • 2x AMD EPYC 7713 (128c/256t @ 2.0 GHz)
  • 2x 480GB SSD
  • 10x 6.4TB NVMe
  • 2TB RAM
  • 25TB Bandwidth
  • 25Gbps Network

The server was able to handle the ultimate stress test of pinging everyone in PaperMC Discord and publishing the message for thousands of servers to see.

At its peak, the testing server was able to handle over 320 players on a brand new, ungenerated map without major issues or TPS drops. We did find a few issues, and valuable stack traces were collected and documented during the process.

With over 500 peak viewers on Spottedleaf’s Twitch and over 180 audience members on Discord’s staging channel, it was an epic first impression and overall a very successful public stress test! Below are some fun screenshots from our test!

folia6folia7
folia8
folia9folia10

Fun fact: The test server was running on a fine-tuned Shenandoah GC with 500 GB allocated.

A Little Side Note on the Information Above:

  • Do I need specs like this to run Folia?

No, this was purely done as a proof of concept. The hardware we acquired for the public test is complete overkill, and every aspect of it was just ridiculous. I hope it makes a drastic first impression!

  • Do I need 500GB of RAM and Shenandoah GC to run Folia?

No, it was just a rare chance for us to test Shenandoah GC as this is the perfect environment it is made for. G1GC with Aikar’s flags is still recommended and the most suitable GC for the majority of Minecraft servers.

Community Screenshots during Folia testing 🔗

folia111folia112folia113folia114folia115folia116folia117folia118folia119folia120folia121folia122folia123folia124folia125folia126folia127folia128folia129folia130folia131folia132folia133folia134

The test server was also hooked up to Minehut’s external server proxy and managed to reach the front page of the server list!

Additional Test 🔗

On June 18th, 2023, another large-scale test was conducted on Folia with a record-breaking 1000 players online on a single physical CPU (AMD Ryzen 9 7950 X3D), without sharding. You can find the technical details below!

Breaking the Limits: How Folia Made a 1,000 Player Minecraft Server a Reality

On August 20, 2023, a third smaller test was done on Folia with a 96-core EPYC CPU. View the technical writeup below!

Running Folia on a 96-Core EPYC CPU

Closing Notes 🔗

To You, the Reader:

Folia is an ambitious project aimed at taking your Minecraft server to the next level. It will coexist with Paper and become the software of choice for large-scale servers under the PaperMC organization. I hope this post gives you a bit more information about the project. Furthermore, if you have any suggestions or feedback regarding this article, please reach out to EterNity on Paper Chan Discord.

Helpful Links 🔗

GitHub Discord Forum Wiki JavaDocs Donate foliabanner