Folia plugin generator for regionized multithreading

Folia is a fork of Paper maintained by the PaperMC team. A regular server ticks the whole world on one main thread. Folia groups nearby loaded chunks into independent regions and ticks those regions in parallel on several threads. Regions merge when players come close and split again when they move apart.

The design targets large servers with many players spread far from each other, running on hardware with plenty of CPU cores. On a small server where everyone gathers around spawn, most activity lands in the same region and the gain is limited.

The catch: Folia has no single main thread. Any plugin that assumes one can break, and a lot of well-known plugins do.

Classic plugins schedule work with Bukkit.getScheduler() or a BukkitRunnable. Folia does not support those calls and throws an UnsupportedOperationException, because there is no main thread for the task to run on. A timer that works on Paper stops the plugin cold on Folia.

The second trap is thread ownership. Every entity, block and chunk belongs to the region currently holding it, and only that region's thread may touch it. A plugin that teleports a player from an async task, or edits blocks in a distant part of the world from a listener, reaches across regions and fails.

Folia guards against this by refusing to load any plugin that does not declare folia-supported: true in its plugin.yml. Adding the line without fixing the code only moves the crash from startup to gameplay.

When you select Folia, the generator gives the AI a dedicated set of rules before it writes anything. Instead of the Bukkit scheduler, the code uses the four schedulers Folia provides, each for one kind of work:

The AI also keeps every entity, block and chunk on its own region thread, hopping between schedulers rather than reaching across regions, and writes folia-supported: true into plugin.yml. The project is then compiled with Maven against the Paper API, which contains these scheduler interfaces.

A plugin that genuinely supports Folia is designed around regions from the start. A timer that affects every player runs through each player's entity scheduler, so it executes on the right thread wherever that player stands. An area effect runs on the region that owns the area.

Recent Paper versions expose the same scheduler APIs and run them on the main thread, so a plugin written this way can usually run on Paper as well. Spigot and Bukkit do not have them, which is why a Folia plugin is not a Spigot plugin.

Some features stay hard on Folia whoever writes the code, such as logic that needs a consistent view of the entire world in a single tick. Describe what you need precisely, and check the result on your own Folia server before going live.

Open the generated project in the online editor to see how each scheduler is used, then ask for changes in plain language. Every change is saved in the version history, so you can roll back if a tweak goes wrong.

Download the .jar, place it in the plugins folder of your Folia server and restart. Check the console on the first start to confirm the plugin enabled, then try its commands in game.