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

(This article will receive ongoing updates as more information becomes available)

Folia GitHub Page (TBA)
Official Release (TBA)

Last updated: March 20th, 2023 for Folia version 1.19.4

Table of Contents

Introduction to Folia
Benefits of Folia
Server Admin Support
Developer Support
Folia Plugins
Special Thanks
Community screenshots
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

There is no planned release date for either the API or server jar at the moment, that will come when it is ready.

For technical details: REGION_LOGIC.md

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.

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.

By a stroke of luck, we managed to snatch a server with dual AMD EPYC CPUs with 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 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!

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.

We also gathered a bunch of community submitted screenshots located in the end of this article if you want to check it out.

Who are likely to see benefits running Folia?

• Medium to large sized server with sufficient hardwares (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-games server.

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 performance increase as a small survival server owner?

"Yes," if you have sufficient threads available. Folia also benefits smaller servers as it restores mob spawning behavior to be closer to Vanilla and allows people to make larger farms without tanking the performance of the entire server as a whole. Check the next section for the benefits of 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!

What are some interesting things observed from our testing?

• 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 ran 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 is 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.

Admin Support🔗

(This section is planned to be updated as more information becomes available)

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🔗

(This section is planned to be updated as more information becomes available)

If you are a developer and wish to provide support for Folia, please check out (NOT YET PUBLIC) the official GitHub repository and join the discussion on future API implementations in our 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!

(Information here are subjected to changes)

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🔗

Due to the aforementioned API changes, existing Paper plugins are not likely to work with Folia out of the box. Ideally, Hangar would be a perfect hub to discover Folia-compatible plugins; however, it is still currently in closed beta.

In the meantime, this guide will maintain a list of plugins that support Folia. If you are a developer and interested in having your plugin listed here, please contact EterNity via Discord.

Pending API announcements... and more Folia supported plugin to come...!

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!

Community Screenshots during Folia testing🔗

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: https://github.com/PaperMC
Discord: https://discord.gg/PaperMC
Forum: https://forums.papermc.io
Wiki: https://docs.papermc.io
JavaDocs: https://papermc.io/javadocs
Donate: https://papermc.io/sponsors