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

a year ago

Latest Post Folia - Multithreading Coming to your Minecraft server by EterNity public

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 longstanding 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 onto 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

Last updated: September 4th, 2023 for Folia version 1.20.1

Table of Contents

Introduction to Folia
Benefits of Folia
Server Admin Support
Developer Support
Folia Plugins on Hangar
Special Thanks
Folia Testing Records
Community screenshots
Additional Tests
Closing Notes

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 tickrate (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 threadpool.

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:
Project overview

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 implementation defined unique data object tied to that region. It is important to note that for any non-dead region x, that for each chunk position y it owns that there is no other non-dead region z such that the region z owns the chunk position y.

The entire process of region creation, merge, 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 server further, but with limited success due to the main tick loop is still ran 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 are likely to see benefits running Folia?

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.

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.

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.

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.

"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.


It is recommended to have a minimum 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 suck. 

Some interesting facts on Folia

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.


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 Folia Project overview and join the discussion in PaperMC Discord community.

Your expertise is the most valuable feedback for us. This is also a rare chance to fix a few longstanding 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.

paperweight 1.5.4 has been released with Folia dev bundle!

See full changelog here.

Folia PluginsπŸ”—

Due to the aforementioned API changes, existing Paper plugins are not likely to work with Folia out of the box.

Hangar - PaperMC's official plugin site!

Please visit Hangar - our official plugin site at Hangar to discover Folia-compatible plugins!

Additionally, Modrinth is also a great place to find additional Folia plugins.

Belows are a few notable plugins with full Folia support!

Chunky Pre-generates chunks.

LuckPerms Simple permission plugin.

BlueMap An epic map plugin in 3D!

squaremap An optimized and superfast 2D Minecraft map plugin.

AnnouncerPlus Powerful and fully customizable announcer plugin.

Spark A performance profiler.

Bolt A modern protection plugin.

ChestShop Simple plugin that trun chest into a shop.

GrimAC Epic anti-cheat.

ViaVersion / ViaRewind Allow other version of Minecraft to join.

GravityControl Add sand duping to Paper/Folia.

FreedomChat Freedom!

GSit Sit on anything.

FarmControl The solution to overpopulated farms.

Maintenance Add Maintenance mode.

RustyConnector A player and server connection manager for Velocity based Minecraft Networks!

UnifiedMetrics Metrics collection plugin.

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 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 following specs!

The server was able to handle the ultimate stress test of pinging everyone in PaperMC discord and publish the message for thousands of server 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 on Discord staging channel, it was an epic first impression and overall a very successful public stress test!

Belows are some fun screenshots from our test!

Fun fact: Test server is running on a fine tuned Shenandoah GC with 500 GB allocated.

A little side notes on the information above:

Do I need a spec like this to drive Folia?

No, this was purely done as a proof of concept. The hardware we acquired for the public test is a 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 flag is still recommended and the most suitable GC for the majority of Minecraft servers.

Community Screenshots during Folia testingπŸ”—

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 Ryzen9 7950 X3D), without sharding. You can find the technical details below!

Breaking the Limits: How Folia Made 1,000 Player Minecraft Server a Reality
Check out the impressive results of the large-scale Folia test that took place on June 18th, 2023. Learn more about our findings and technical challenges in this post.

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
Recently, I had the privilege of deploying Folia, a Minecraft server software, on a 96-core EPYC CPU. Check out my experience and observations in this blog post.

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.



Published a year ago