A fork of Folia that aims to make a region-threaded Minecraft server behave like a complete one.

Folia is the fastest way to scale a spread-out server: it groups nearby chunks into independent regions and ticks them in parallel, with no main thread. The cost is that a great deal of the server does not work. Whole vanilla commands are removed rather than adapted, scoreboards and world loading throw, and Entity#teleport is gone for good.

Branch keeps Folia's region engine exactly as SpottedLeaf wrote it and spends its effort on the parts Folia left behind — the commands, the APIs and the diagnostics that make the platform usable.

Status: early. Usable for testing, not for a production server. The build works end to end and produces a running server. All 66 console commands run, the Bukkit scoreboard API and the Bukkit scheduler work, Server#createWorld works, Entity#teleport works where its contract can be honoured, and the teleport and portal events fire. World creation is refused on the 1.21.8 line only, for a reason it states; world unloading, respawn and parts of the player login API are still Folia's. docs/status.md is the honest inventory.

---

Why a Folia fork rather than a Canvas fork

CanvasMC/Canvas is the other serious project in this space and it has solved many of these problems already. Branch does not build on it, for a reason worth stating plainly.

Canvas does not patch Folia. It vendors Folia's entire region-threading corpus as a single 1.74 MB, 33,645-line patch touching 308 files, and edits it in place. About 21,000 of those are added lines; roughly 1,100 of them carry a // Canvas marker. The fixes are real, but they are dissolved into the blob — there is no longer a seam between "Folia" and "what Canvas changed about Folia". Building on that means inheriting the dissolution permanently, and every future Folia fix has to be merged into a tree that no longer resembles Folia.

Branch takes the other trade. Folia stays upstream and untouched, so Folia's fixes keep arriving as ordinary upstream updates, and everything Branch changes is a small, titled, reviewable patch on top. The cost is that Branch has to earn each improvement itself instead of inheriting a working set. That is the deliberate trade, and docs/architecture.md explains the machinery.

Canvas remains the better choice today if you want the largest working feature set. Branch is the better shape if you want a tree that stays mergeable with Folia.

---

What is different so far

/save-all restored	Folia leaves it unregistered because saving the server from one thread would touch chunks other regions are ticking. Branch fans the save out: every region saves what it owns, on the thread that owns it. Verified across four regions in three worlds.
Console commands work before the world loads	Piping stop into a starting server used to throw a NullPointerException partway through and leave the process running until it was killed. Four code paths assumed a command source always has a level.
/version reports on Branch	It queried PaperMC/Folia's GitHub and PaperMC's download service, so it described a project this server is not — and answered with a stack trace whenever the API was unreachable.
/branch region added	Folia's /tps averages across regions, which hides the one failure region threading actually produces: a single region falling behind while the rest idle. /branch region lists every region worst-first, with its tick rate, MSPT, utilisation and contents.
Every other command restored	Folia leaves 24 vanilla commands unregistered. All of them run now, each routed to whatever owns the state it touches — the global region, the region owning a position, or the region owning an entity — and refusing whole rather than half-applying when one command spans several regions. Two stay unregistered on purpose, with the reason stated in place.
The Bukkit scoreboard API works	Folia makes five entry points throw. The storage is concurrent, its structural changes are atomic, and all five work from a region thread as well as the global one.
The Bukkit scheduler works	Folia disables it outright, which is the API almost every existing plugin schedules through. It runs again on a global-region heartbeat, asynchronous half included.
Entity#teleport works where it can	Same world, the entity's own region, destination chunks owned and loaded. Every other case is refused with the reason named, rather than removed outright.
The teleport and portal events fire	teleportAsync and Folia's asynchronous portal path fire nothing. Branch fires PlayerTeleportEvent, EntityTeleportEvent, EntityPortalReadyEvent, EntityPortalEvent and PlayerPortalEvent, with cancel and redirect honoured.
Command conformance harness	tools/command-smoke.sh drives a real server and reports which commands are ok, UNREGISTERED or ERROR. tools/plugin-probe does the same for the plugin API. This is how the numbers in this repository are produced.

Measured on a running Branch server: all 66 tested commands work, none error. On the 1.21.8 line two of them (ride, rotate) do not exist in that Minecraft version at all. docs/commands.md lists exactly which, and what each one needed.

---

Versions

This branch is ver/26.2.x, targeting Minecraft 26.2. Branch follows Folia's layout: one branch per Minecraft version, each pinned to the matching Folia branch.

Branch	Minecraft	Java
ver/26.2.x	26.2	25
ver/26.1.x	26.1.2	25
ver/1.21.11	1.21.11	21
ver/1.21.8	1.21.8	21

All four build, boot, and give the same command result. The patches carry context from the Minecraft sources they were cut against, so they cannot be shared across versions — see docs/versions.md for what actually differs and how to add a version.

---

Downloading

Every green build of a version branch publishes that version's server jar as a release, so there is one current jar per Minecraft version rather than something you have to build:

Minecraft	Download	Java
26.2	branch-26.2.jar	25
26.1.2	branch-26.1.2.jar	25
1.21.11	branch-1.21.11.jar	21
1.21.8	branch-1.21.8.jar	21

Each release is rolling: the jar is replaced by the next green build of its branch, and the release notes name the commit it came from. The repository is private, so the links need an account with access to it.

Building it yourself is below, and is the only option if you want a jar from a commit that is not the head of a version branch.

---

Building

Requirements: JDK 25, Git configured with a name and email, and a real Git clone (a source zip has no history, and the build reconstructs its sources from patches).

git clone https://github.com/MARVserver/Branch
cd Branch
./gradlew applyAllPatches      # Paper -> Folia -> Branch, about 3 minutes cold
./gradlew createPaperclipJar   # branch-server/build/libs/branch-paperclip-*.jar

These must be two separate invocations. On a fresh clone the module build files do not exist yet — applyAllPatches generates them — and Gradle resolves task names for the whole invocation up front, so ./gradlew applyAllPatches createPaperclipJar fails with Task 'createPaperclipJar' not found.

Useful during development:

./gradlew runDevServer                     # run without assembling a jar
./gradlew fixupMinecraftSourcePatches      # fold working changes into the patch commit
./gradlew rebuildMinecraftSourcePatches    # regenerate patch files from it

The edit-a-patch loop is described in CONTRIBUTING.md.

Running

Java 25 or newer:

java -Xmx4G --enable-native-access=ALL-UNNAMED -jar branch-paperclip-*.jar --nogui

Branch inherits Folia's plugin rules with one exception: only plugins declaring folia-supported: true in their plugin.yml load, and regions tick in parallel rather than concurrently — plugin code must not touch data belonging to another region. The exception is the Bukkit scheduler, which Folia disables and Branch has brought back; a synchronous task runs on the global region, and work that touches a region's own blocks or entities still has to be scheduled onto that region. Folia's README and the PaperMC documentation are required reading before running either platform.

Documentation

• docs/changes.md — every change Branch makes, and how each was verified
• docs/status.md — what works, what does not, and how it was measured
• docs/architecture.md — the Paper → Folia → Branch build chain
• docs/commands.md — the command inventory
• docs/roadmap.md — where the remaining work is, and what it costs
• CONTRIBUTING.md — patch conventions and the development loop

Licence and credit

Branch is GPL-3.0-or-later, inherited from Folia and Paper. See LICENSE and NOTICE.

Branch is a thin layer on other people's work. The region-threading engine is SpottedLeaf's, carried unmodified from Folia; the server underneath it is PaperMC's; and Canvas mapped out most of the territory this project is walking into. None of them endorse this fork.