Leaf: a Paper fork aimed at performance with vanilla mechanics intact

A Paper fork with a stated trade-off

Leaf is a Paper fork designed to be customizable and high-performance, and the project description is blunter about the goal than most forks manage to be, describing itself as a fork focused on finding the balance between performance, vanilla mechanics and stability. That phrase is the whole positioning, and it is a narrowing of what other forks do.

The readme carries a warning box that a server owner should take literally. It says Leaf is a performance-oriented fork and that you should make sure to take backups before switching to it, and that everyone is welcome to contribute optimizations or report issues. The request for contributions is framed around optimizations specifically, which tells you the maintainers want the tuning work from outside rather than a feature wish list.

The feature list explains the technical shape. It is based on Paper for generic performance and a flexible API, with async pathfinding, mob spawning and entity tracker, and various optimizations blending from other forks and from the project's own work. It is fully compatible with Spigot and Paper plugins, it keeps dependencies up to date, and it allows all characters in usernames including Chinese and other characters, which is a real operational constraint for a server with an international audience. It also fixes some Minecraft bugs and supports mod protocols, and it is more customized, relying on features of Purpur.

Two items stand out as operations rather than features. The linear region file format is described as saving disk space, which matters because region files are the bulk of a world on disk. And the project integrates with the Sentry setup of Pufferfish, so errors coming from the server can be tracked in detail, which is described as maintenance friendly.

The project is Java, the default branch is ver/26.3, and the homepage is leafmc.one with a separate documentation site and a Discord server.

Building the distribution JAR and the patch model

Leaf is a Paper fork, which means the source is a patch set applied to an upstream tree rather than a standalone codebase. The build command is short.

./gradlew applyAllPatches && ./gradlew createPaperclipJar

Two Gradle tasks, apply the patches and then produce the Paperclip jar for distribution. The repository layout makes the Paperclip structure explicit. There is a build-data/ directory, a build.gradle.kts, a settings.gradle.kts, a gradle.properties, a leaf-server/ directory and a leaf-api/ directory, which are the server and API halves, a leaf-archived-patches/ directory for patches that are no longer applied, a licenses/ directory that carries the upstream licence texts, a gradle/ directory with the wrapper, and both gradlew and gradlew.bat. There is also a scripts/ directory, a codegraph.json, an AGENTS.md, a CONTRIBUTING.md and a .idea/ directory.

The presence of leaf-archived-patches/ is the detail that tells you how this project works in practice. A fork that accumulates patches cannot apply them forever, so patches get retired and parked in an archive, and the directory is a record of the project's history. A contributor reading that directory can see what Leaf changed and what it later reverted, which is the closest thing the repository has to a changelog of decisions.

The build-data/ directory is where the upstream Paper version being forked from is pinned, and the branch naming, ver/26.3, is version based rather than master based, so a server owner pins a release line.

The API surface plugin authors compile against

For a plugin author, the interesting part is the API, and the readme documents how to depend on it in both Gradle and Maven. The artifacts are published to a Leaf maven repository at maven.leafmc.one/snapshots/, and the coordinates are cn.dreeam.leaf with the artifact leaf-api.

The Gradle form adds the repository and declares the dependency as compileOnly, with a toolchain pinned to Java 25.

repositories {
  maven {
    url = uri("https://maven.leafmc.one/snapshots/")
  }
}

dependencies {
    compileOnly("cn.dreeam.leaf:leaf-api:26.3.local-SNAPSHOT")
}

java {
  toolchain.languageVersion.set(JavaLanguageVersion.of(25))
}

The Maven form is the same coordinates with the provided scope.

<dependency>
    <groupId>cn.dreeam.leaf</groupId>
    <artifactId>leaf-api</artifactId>
    <version>26.3.local-SNAPSHOT</version>
    <scope>provided</scope>
</dependency>

The compileOnly and provided scopes are the correct choice here, because the API is supplied by the server at runtime, and bundling it would produce a version conflict the moment the server updates. The local-SNAPSHOT suffix tells you these are development builds published continuously rather than tagged releases, which matters if you pin a plugin to a specific Leaf version and the server updates underneath you.

The group id cn.dreeam.leaf and the Dreeam donation link in the readme point at the wider Chinese Minecraft server ecosystem the project belongs to, alongside the QQ group and the KeYi and Mirai forks in the credits.

Where the patches come from

The credits section is unusually long, and it is worth reading as a map of the ecosystem Leaf draws on. The three named upstreams are Gale, from the original repo at GaleMC, Pufferfish, and Purpur. Then there is a long expandable list of forks Leaf takes patches from, among them KeYi and its backup, Mirai, Petal, Carpet Fixes, Akarin, Slice, Parchment, Leaves, Kaiiju, Plazma, SparklyPaper, Polpot, Matter, Luminol, Nitori, Moonrise for 1.21.1 and Sakura.

The style of the credit is worth noting. The readme says the project includes some patches taken from these forks, that if these projects had not existed Leaf would not have become what it is. So the upstream project does not reimplement their work, it borrows it, and the credit list is the closest thing to a patch provenance record.

The names also indicate the lineage of the fork ecosystem in general, with several of these projects themselves forking each other.

Leaf is also built for a specific audience, and the readme says so in the topic list and the feature set. The Chinese and other character support in usernames is not a side detail but a reflection of where a large share of the users are, and the same applies to the Dreeam branding and the sponsor list in the special thanks section, which lists commercial server hosts and YourKit, a Java and.NET profiling tool.

Where Leaf is the wrong tool

Three cases argue against it. The first is a server whose plugins depend on Paper behaviours Leaf has changed. The compatibility claim is that Leaf is fully compatible with Spigot and Paper plugins, but that is a claim about the plugin API surface, not about every behavioural quirk a plugin might rely on, and a fork whose stated purpose is optimisation will have changed some of them. A server with a large custom plugin set is exactly where that risk lives, and the readme's own warning about backing up is the recognition of it.

The second case is a player community that wants the extra configuration exposed. The feature list is written in terms of what Leaf does for the operator, async pathfinding, a linear region file format, Sentry error tracking, and it leans on Purpur's features rather than exposing a large set of new knobs. A server owner who wants a fine grained performance control panel is looking for Purpur or a fork that offers one, and Leaf's pitch is that it finds the balance for you.

The third case is a small server that does not need it. The async pathfinding, the mob spawning and the entity tracker work are aimed at servers with many entities and many players, and the linear region file format saves disk space that a small world does not have. Running a fork for a server with twenty players adds an upstream you now depend on without a corresponding benefit.

There is a general point about the fork model itself. Every Paper fork is a maintenance commitment, because a fork has to track upstream Paper releases, apply its patches to each new version, and deal with the cases where a patch no longer applies. The existence of leaf-archived-patches/ and the ver/26.3 branch naming show that work happening, and the presence of a bStats badge and a Discord server show an active project, but a server that swaps its server software has taken on that commitment rather than the upstream maintainers.

On the state of the project, the release list shows ver-1.21.11 from 2026-09-12 alongside ver-26.2 and ver-26.3 both dated 2026-10-15, and the last push was on 2026-10-15.

Editorial conclusion

Leaf suits a Minecraft server owner who has hit a performance ceiling on a vanilla Paper server, wants a fork that keeps vanilla mechanics, and is willing to treat the server as a system that needs backups and a plan for rollbacks. It does not suit a server that depends on a plugin relying on behaviour Leaf has changed, and it does not suit a player community that wants the fork's extra configuration exposed. Before you switch, back up the world and the plugin set as the readme's warning asks, check the API documentation for what Leaf changes relative to Paper, and note that the last push was on 2026-10-15 with the newest release ver-26.3 from the same day.

Frequently asked questions

Official sources

1. Issues
2. Project website
3. README
4. Releases
5. Winds-Studio/Leaf on GitHub