Waterfall: a BungeeCord fork that reached end of life in favour of Velocity

The fork exists to expose upstream changes faster

Waterfall is a fork of the BungeeCord server teleportation suite, and the documentation frames it as a principles fork rather than a code fork in the usual sense. The stated reason is that upstream does not accept many contributions intended to better the ecosystem, so the fork exists to allow changes to reach a wider audience more quickly.

That is the whole strategic claim, and it is worth holding in mind when reading the rest of the documentation. Waterfall was not started to replace BungeeCord with a different design. It was started because contribution throughput was the problem.

The fork relationship was intended to stay close. The documentation says Waterfall will still track upstream BungeeCord and merge changes as needed, and the repository layout reflects that literally: a BungeeCord directory sits alongside a BungeeCord-Patches directory, with a .gitmodules entry at the top level. The upstream code is present, and the changes are kept as a separate patch set.

That structure explains both the strengths and the limits of the project. Changes are easy to review because they are isolated as patches rather than entangled with upstream, and the fork can absorb upstream improvements without rewriting its own history. It also means every upstream change has to be merged and reconciled by hand, which is work that grows as the divergence accumulates.

The project's stated focus areas are three: stability, achieved by making the code base testable and discouraging practices that lead to proxy lag; features, with the aim of including more than canonical BungeeCord; and scalability, meaning the ability to handle a large number of concurrent players given a reasonably modern CPU, memory and a good network connection.

End of life is stated plainly at the top of the readme

The first thing in the documentation is a caution block, and it is unambiguous. The project has reached end of life and is no longer maintained. The block directs users to transition to Velocity, and links to an announcement on the PaperMC forums.

The repository metadata agrees. It is not archived, so the code is still readable and cloneable, but the last push was on 2026-09-22 and the only listed release is a downloads entry from 2018-10-29. Nothing here is under active development, and the documented direction of travel is away from the project rather than towards it.

This changes how the project should be read. A fork that is end of life is no longer a place to send contributions, and the project's invitation to open a pull request is a leftover from when that made sense. What remains useful is the accumulated knowledge: the reasoning behind the fork, the stability work, and the API patches that plugins were built against.

For an operator running a legacy estate, the practical question is not whether Waterfall is good but whether the alternative is worth the migration. The documentation makes that choice for you, which is an unusual amount of clarity for a project in this position.

Running a proxy needs Java 8 and a jar from the downloads page

For server administrators the setup is minimal. You download a copy of Waterfall.jar from the PaperMC homepage, and the only stated requirement is Java 8 or above. There is no configuration guide, no dependency list and no build step in that section, because a BungeeCord-style proxy is configured through its own config file rather than through documentation here.

That brevity is a signal about the audience. The document is written for people who already run one of these proxies and know the conventions of the format, which is also why the plugin developer section can assume familiarity with a Maven repository block without explanation.

For anyone starting from zero, the missing piece is the tutorial, and it is not in this repository. The path to a working proxy runs through the jar, a config file, and knowledge of the legacy backend server protocol.

Building from source is a separate path with a longer toolchain list. The build instructions state that compiling Waterfall needs JDK8, git, bash, maven and an internet connection, and that you clone the repository and run a build script:

<repository>
    <id>papermc</id>
    <url>https://repo.papermc.io/repository/maven-public/</url>
</repository>

The resulting jar is placed under the Waterfall-Proxy bootstrap target directory. The build is Gradle based at the top level, with build.gradle.kts, a gradlew wrapper and a pom.xml alongside it, and the scripts directory holds the helper that the build command invokes.

Plugin authors consumed waterfall-api from the PaperMC Maven repository

The plugin developer section is the most technical part of the documentation, and it shows how a fork exposes its API surface to third party plugins without forcing them onto the fork's own build.

The Maven repository is the PaperMC public repository, declared as:

<dependency>
    <groupId>io.github.waterfallmc</groupId>
    <artifactId>waterfall-api</artifactId>
    <version>1.21-R0.3-SNAPSHOT</version>
    <scope>provided</scope>
</dependency>

The artifact itself is the waterfall-api module, with a snapshot version and a provided scope, meaning the plugin compiles against it but does not bundle it:

The Gradle equivalent is offered as an alternative, with the same repository URL and the dependency declared as compileOnly.

Two things are worth drawing out. The provided and compileOnly scopes are the correct choice for a proxy API, since the proxy supplies the implementation at runtime and bundling it would cause conflicts. And the API is reached through a Maven repository rather than through a jar download, which means plugin builds resolve it the same way they resolve any other dependency, a small detail that removes an entire class of version drift problems.

The plugin API is not a copy of upstream BungeeCord's. The documentation points to the API patches directory for the differences and to the PaperMC javadocs for the reference documentation, so a plugin author needs to read the patches to know what Waterfall actually changed.

What a principles fork gets right and where it costs you

The strongest argument for the fork model is testability. The stability goal is described as achievable by making the code base testable and discouraging practices that lead to proxy lag, and that is a concrete engineering programme rather than a slogan. A proxy sits between every player and every backend server, so a lag spike in the proxy is a lag spike for everyone at once, and the practices that cause it are exactly the kind of thing a test suite can pin down.

The second argument is governance. When upstream will not merge the changes you think the ecosystem needs, forking is the only route. That was a reasonable position for PaperMC to take with a large and technically capable server operator community, and the paper it belongs to, Waterfall and the Paper server software, came from the same organisation.

The cost is equally concrete. Every divergence is a merge conflict waiting for the next upstream release. The fork has to track upstream, reconcile patches, and release a jar that plugin authors can depend on, and the version scheme, 1.21-R0.3-SNAPSHOT, encodes a Minecraft version in the artifact coordinates. That last detail is the sharpest constraint. The API version is tied to the game version, so every Minecraft update is a new API coordinate, and a plugin supporting several versions needs several coordinates or a compatible range.

Velocity answers this differently, by being a different architecture rather than a patched fork of the same one. That is the difference that matters for anyone still running Waterfall: the successor project is not a drop-in continuation of the fork's approach, so the migration is real work rather than a jar swap.

MIT licensed code with a profiler sponsorship and a forum community

The licence is MIT and the licence text sits at the root as LICENSE.txt, which leaves the code free to read, modify and redistribute with only the notice retained. Nothing about the licence has changed to reflect the end of life status, so the permissive terms remain available to anyone picking the source up, though the practical value of a maintained fork of it is another matter.

The project also carries the usual PaperMC civic furniture: a Discord invite, a link to the PaperMC forums, a CONTRIBUTING.md file, and a CI badge pointing at the namespace OSS program that provides open source licences and infrastructure to projects in that ecosystem.

One sponsorship is called out specifically. YourKit, the maker of Java and .NET profilers, grants the project an OSS licence for its profiling tools, and the project thanks them for it. That detail is a small window into how a performance-focused proxy project was actually worked on: the proxy needs a profiler to chase the lag it exists to prevent, and the profiler licence removes that cost.

The top-level layout tells the same story about the fork mechanics. Alongside the usual files sit a scripts directory, a gradle directory, the gradlew wrapper, and the BungeeCord and BungeeCord-Patches directories that hold upstream and the changes applied on top of it.

Editorial conclusion

Waterfall suits an operator of an existing legacy proxy estate who wants to understand why a fork existed and how it diverged from BungeeCord, and it remains a usable reference for the API patches it carries. It does not suit anyone starting a new deployment, because the project is end of life and unmaintained and its own documentation points to Velocity. Before touching it, read the announcement linked from the readme, confirm your backend servers still speak the legacy BungeeCord protocol, and plan the move rather than adding to the fork.

Frequently asked questions

Official sources

1. License: MIT
2. PaperMC/Waterfall on GitHub
3. Project website
4. README
5. Releases