{"id":13775461,"url":"https://github.com/PaperMC/Folia","last_synced_at":"2025-05-11T07:32:36.603Z","repository":{"id":148845432,"uuid":"603952413","full_name":"PaperMC/Folia","owner":"PaperMC","description":"Fork of Paper which adds regionised multithreading to the dedicated server.","archived":false,"fork":false,"pushed_at":"2025-04-21T01:48:26.000Z","size":5960,"stargazers_count":3862,"open_issues_count":56,"forks_count":510,"subscribers_count":101,"default_branch":"master","last_synced_at":"2025-05-06T15:25:23.062Z","etag":null,"topics":["bukkit","craftbukkit","hacktoberfest","java","minecraft","minecraft-api","minecraft-multithreading","minecraft-performance","minecraft-server","multithreading","paper-fork","papermc"],"latest_commit_sha":null,"homepage":"","language":"Batchfile","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/PaperMC.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"github":"PaperMC","open_collective":"PaperMC"}},"created_at":"2023-02-20T02:29:01.000Z","updated_at":"2025-05-06T14:54:32.000Z","dependencies_parsed_at":"2023-06-26T02:08:17.869Z","dependency_job_id":"38c9c3eb-1806-4576-a315-7603de37ff52","html_url":"https://github.com/PaperMC/Folia","commit_stats":{"total_commits":343,"total_committers":16,"mean_commits":21.4375,"dds":0.2157434402332361,"last_synced_commit":"8af1aef1f14630ede6575a72632e7f943d8fb903"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PaperMC%2FFolia","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PaperMC%2FFolia/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PaperMC%2FFolia/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PaperMC%2FFolia/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/PaperMC","download_url":"https://codeload.github.com/PaperMC/Folia/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253492529,"owners_count":21916959,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bukkit","craftbukkit","hacktoberfest","java","minecraft","minecraft-api","minecraft-multithreading","minecraft-performance","minecraft-server","multithreading","paper-fork","papermc"],"created_at":"2024-08-03T17:01:39.095Z","updated_at":"2025-05-11T07:32:36.577Z","avatar_url":"https://github.com/PaperMC.png","language":"Batchfile","readme":"\u003cdiv align=center\u003e\n    \u003cimg src=\"./folia.png\"\u003e\n    \u003cbr /\u003e\u003cbr /\u003e\n    \u003cp\u003eFork of \u003ca href=\"https://github.com/PaperMC/Paper\"\u003ePaper\u003c/a\u003e which adds regionised multithreading to the dedicated server.\u003c/p\u003e\n\u003c/div\u003e\n\n## Overview\n\nFolia groups nearby loaded chunks to form an \"independent region.\"\nSee [the PaperMC documentation](https://docs.papermc.io/folia/reference/region-logic) for exact details on how Folia\nwill group nearby chunks.\nEach independent region has its own tick loop, which is ticked at the\nregular Minecraft tickrate (20TPS). The tick loops are executed\non a thread pool in parallel. There is no main thread anymore, \nas each region effectively has its own \"main thread\" that executes\nthe entire tick loop.\n\nFor a server with many spread out players, Folia will create many\nspread out regions and tick them all in parallel on a configurable sized\nthreadpool. Thus, Folia should scale well for servers like this.\n\nFolia is also its own project, this will not be merged into Paper\nfor the foreseeable future. \n\nA more detailed but abstract overview: [Project overview](https://docs.papermc.io/folia/reference/overview).\n\n## FAQ\n\n### What server types can benefit from Folia?\nServer types that naturally spread players out, \nlike skyblock or SMP, will benefit the most from Folia. The server\nshould have a sizeable player count, too.\n\n### What hardware will Folia run best on?\nIdeally, at least 16 _cores_ (not threads).\n\n### How to best configure Folia?\nFirst, it is recommended that the world is pre-generated so that the number\nof chunk system worker threads required is reduced greatly.\n\nThe following is a _very rough_ estimation based off of the testing\ndone before Folia was released on the test server we ran that\nhad ~330 players peak. So, it is not exact and will require further tuning - \njust take it as a starting point.\n\nThe total number of cores on the machine available should be \ntaken into account. Then, allocate threads for: \n- netty IO :~4 per 200-300 players\n- chunk system io threads: ~3 per 200-300 players\n- chunk system workers if pre-generated, ~2 per 200-300 players\n- There is no best guess for chunk system workers if not pre-generated, as\n  on the test server we ran we gave 16 threads but chunk generation was still\n  slow at ~300 players.\n- GC Settings: ???? But, GC settings _do_ allocate concurrent threads, and you need\n  to know exactly how many. This is typically through the `-XX:ConcGCThreads=n` flag. Do not\n  confuse this flag with `-XX:ParallelGCThreads=n`, as parallel GC threads only run when\n  the application is paused by GC and as such should not be taken into account.\n\nAfter all of that allocation, the remaining cores on the system until 80%\nallocation (total threads allocated \u003c 80% of cpus available) can be\nallocated to tickthreads (under global config, threaded-regions.threads). \n\nThe reason you should not allocate more than 80% of the cores is due to the\nfact that plugins or even the server may make use of additional threads \nthat you cannot configure or even predict.\n\nAdditionally, the above is all a rough guess based on player count, but\nit is very likely that the thread allocation will not be ideal, and you \nwill need to tune it based on usage of the threads that you end up seeing.\n\n## Plugin compatibility\n\nThere is no more main thread. I expect _every_ single plugin\nthat exists to require _some_ level of modification to function\nin Folia. Additionally, multithreading of _any kind_ introduces\npossible race conditions in plugin held data - so, there are bound\nto be changes that need to be made.\n\nSo, have your expectations for compatibility at 0.\n\n## API plans\n\nCurrently, there is a lot of API that relies on the main thread. \nI expect basically zero plugins that are compatible with Paper to \nbe compatible with Folia. However, there are plans to add API that \nwould allow Folia plugins to be compatible with Paper.\n\nFor example, the Bukkit Scheduler. The Bukkit Scheduler inherently\nrelies on a single main thread. Folia's RegionScheduler and Folia's\nEntityScheduler allow scheduling of tasks to the \"next tick\" of whatever\nregion \"owns\" either a location or an entity. These could be implemented\non regular Paper, except they schedule to the main thread - in both cases,\nthe execution of the task will occur on the thread that \"owns\" the\nlocation or entity. This concept applies in general, as the current Paper\n(single threaded) can be viewed as one giant \"region\" that encompasses\nall chunks in all worlds. \n\nIt is not yet decided whether to add this API to Paper itself directly\nor to Paperlib.\n\n### The new rules\n\nFirst, Folia breaks many plugins. To aid users in figuring out which\nplugins work, only plugins that have been explicitly marked by the\nauthor(s) to work with Folia will be loaded. By placing\n\"folia-supported: true\" into the plugin's plugin.yml, plugin authors\ncan mark their plugin as compatible with regionised multithreading.\n\nThe other important rule is that the regions tick in _parallel_, and not \n_concurrently_. They do not share data, they do not expect to share data,\nand sharing of data _will_ cause data corruption. \nCode that is running in one region under no circumstance can \nbe accessing or modifying data that is in another region. Just \nbecause multithreading is in the name, it doesn't mean that everything \nis now thread-safe. In fact, there are only a _few_ things that were \nmade thread-safe to make this happen. As time goes on, the number \nof thread context checks will only grow, even _if_ it comes at a \nperformance penalty - _nobody_ is going to use or develop for a \nserver platform that is buggy as hell, and the only way to \nprevent and find these bugs is to make bad accesses fail _hard_ at the \nsource of the bad access.\n\nThis means that Folia compatible plugins need to take advantage of \nAPI like the RegionScheduler and the EntityScheduler to ensure \ntheir code is running on the correct thread context.\n\nIn general, it is safe to assume that a region owns chunk data\nin an approximate 8 chunks from the source of an event (i.e. player\nbreaks block, can probably access 8 chunks around that block). But,\nthis is not guaranteed - plugins should take advantage of upcoming\nthread-check API to ensure correct behavior.\n\nThe only guarantee of thread-safety comes from the fact that a\nsingle region owns data in certain chunks - and if that region is\nticking, then it has full access to that data. This data is \nspecifically entity/chunk/poi data, and is entirely unrelated\nto **ANY** plugin data.\n\nNormal multithreading rules apply to data that plugins store/access\ntheir own data or another plugin's - events/commands/etc. are called \nin _parallel_ because regions are ticking in _parallel_ (we CANNOT \ncall them in a synchronous fashion, as this opens up deadlock issues \nand would handicap performance). There are no easy ways out of this, \nit depends solely on what data is being accessed. Sometimes a \nconcurrent collection (like ConcurrentHashMap) is enough, and often a \nconcurrent collection used carelessly will only _hide_ threading \nissues, which then become near impossible to debug.\n\n### Current API additions\n\nTo properly understand API additions, please read\n[Project overview](https://docs.papermc.io/folia/reference/overview).\n\n- RegionScheduler, AsyncScheduler, GlobalRegionScheduler, and EntityScheduler \n  acting as a replacement for  the BukkitScheduler.\n  The entity scheduler is retrieved via Entity#getScheduler, and the\n  rest of the schedulers can be retrieved from the Bukkit/Server classes.\n- Bukkit#isOwnedByCurrentRegion to test if the current ticking region\n  owns positions/entities\n\n### Thread contexts for API\n\nTo properly understand API additions, please read\n[Project overview](https://docs.papermc.io/folia/reference/overview).\n\nGeneral rules of thumb:\n\n1. Commands for entities/players are called on the region which owns\nthe entity/player. Console commands are executed on the global region.\n\n2. Events involving a single entity (i.e player breaks/places block) are\ncalled on the region owning entity. Events involving actions on an entity\n(such as entity damage) are invoked on the region owning the target entity.\n\n3. The async modifier for events is deprecated - all events\nfired from regions or the global region are considered _synchronous_, \neven though there is no main thread anymore. \n\n### Current broken API\n\n- Most API that interacts with portals / respawning players / some\n  player login API is broken.\n- ALL scoreboard API is considered broken (this is global state that\n  I've not figured out how to properly implement yet)\n- World loading/unloading\n- Entity#teleport. This will NEVER UNDER ANY CIRCUMSTANCE come back, \n  use teleportAsync\n- Could be more\n\n### Planned API additions\n\n- Proper asynchronous events. This would allow the result of an event\n  to be completed later, on a different thread context. This is required\n  to implement some things like spawn position select, as asynchronous\n  chunk loads are required when accessing chunk data out-of-region.\n- World loading/unloading\n- More to come here\n\n### Planned API changes\n\n- Super aggressive thread checks across the board. This is absolutely\n  required to prevent plugin devs from shipping code that may randomly\n  break random parts of the server in entirely _undiagnosable_ manners.\n- More to come here\n\n### Maven information\n* Maven Repo (for folia-api):\n```xml\n\u003crepository\u003e\n    \u003cid\u003epapermc\u003c/id\u003e\n    \u003curl\u003ehttps://repo.papermc.io/repository/maven-public/\u003c/url\u003e\n\u003c/repository\u003e\n```\n* Artifact Information:\n```xml\n\u003cdependency\u003e\n    \u003cgroupId\u003edev.folia\u003c/groupId\u003e\n    \u003cartifactId\u003efolia-api\u003c/artifactId\u003e\n    \u003cversion\u003e1.20.1-R0.1-SNAPSHOT\u003c/version\u003e\n    \u003cscope\u003eprovided\u003c/scope\u003e\n\u003c/dependency\u003e\n ```\n\n\n## License\nThe PATCHES-LICENSE file describes the license for api \u0026 server patches,\nfound in `./patches` and its subdirectories except when noted otherwise.\n\nThe fork is based off of PaperMC's fork example found [here](https://github.com/PaperMC/paperweight-examples).\nAs such, it contains modifications to it in this project, please see the repository for license information\nof modified files.\n","funding_links":["https://github.com/sponsors/PaperMC","https://opencollective.com/PaperMC"],"categories":["Server Software","Batchfile","minecraft","Paper-Based","Shell"],"sub_categories":["Velocity","No resourcepack"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FPaperMC%2FFolia","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FPaperMC%2FFolia","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FPaperMC%2FFolia/lists"}