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.
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
Javadocs
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.
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?
- 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 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.
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!
Some interesting facts on Folia
- Lag is now localized.
Since eachregionis 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, eachregionruns 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/tpshas 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π
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.
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.
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.
Community Screenshots during Folia testingπ
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!
CubxityOn August 20, 2023, a third smaller test was done on Folia with a 96-Core Epyc CPU, view the technical writeup below!
CubxityClosing 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
