Waterfall Minecraft Proxy: Architecture, Features, and Its Legacy

Waterfall is a BungeeCord fork that's no longer maintained. Before you install it, you should know: the maintainers recommend switching to Velocity instead. That said, understanding Waterfall's design and why it existed teaches you something real about how large-scale Minecraft networks operate. If you're managing a proxy setup or developing server plugins, there's still value in knowing what Waterfall was trying to solve.

What Waterfall Was

BungeeCord is the industry standard for connecting multiple Minecraft servers together. A single proxy server sits in front of your actual game servers and routes players between them. But BungeeCord's codebase wasn't designed for the scale some admins needed. Waterfall was a fork created by the PaperMC team (the same group behind Paper, the hugely popular server software) to build a proxy that didn't sacrifice performance for stability.

The project focused on three things:

• Stability - code that's testable and doesn't lag under load
• Features - more functionality than canonical BungeeCord, added faster
• Scalability - handling thousands of concurrent players on modern hardware

It sounds straightforward now, but at the time, BungeeCord's upstream maintainers weren't accepting contributions at the pace the community wanted. Waterfall existed because the fork was faster and more willing to experiment.

Why the Fork Happened (And What It Says About Open Source)

This is the interesting part. BungeeCord is open source, but it moves cautiously. The Waterfall maintainers basically said: "We can do this faster." They forked the project, kept merging upstream changes, but also added their own patches. This let them ship features and fixes while still tracking BungeeCord's core updates.

It wasn't hostile or contentious. It was pragmatic.

The Minecraft server admin community had real scaling problems, and the fork let them solve them without waiting for upstream consensus. This is how open source actually works sometimes - not everyone waiting for permission.

How Waterfall Worked Under the Hood

Like BungeeCord, Waterfall sat between players and your backend servers. When a player connects, Waterfall handles the login and decides which server to route them to. It manages server switches, chat, movement, and all the proxy logic. The difference was in the details: better performance under concurrent load, cleaner code structure, and a more active API.

For plugin developers, Waterfall provided a clean JavaDocs API and Maven/Gradle artifacts. You could build plugins using:

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

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

Or with Gradle:

repositories {
 maven {
 url 'https://repo.papermc.io/repository/maven-public/'
 }
}

dependencies {
 compileOnly 'io.github.waterfallmc:waterfall-api:1.21-R0.3-SNAPSHOT'
}

This API was one of Waterfall's selling points - it was actively documented and kept in sync with releases, unlike some proxy projects where the API docs lag behind the code.

Installation and Compilation

Running Waterfall required Java 8 or higher (pretty standard). You'd download the JAR file from papermc.io/downloads, drop it in a folder, and run it. Configuration was straightforward YAML.

If you wanted to compile from source, Waterfall kept the build simple:

git clone https://github.com/PaperMC/Waterfall.git
cd Waterfall./waterfall b

That command handled pulling dependencies, running tests, and building the JAR. The compiled binary ended up in Waterfall-Proxy/bootstrap/target/. Clean. No unnecessary ceremony.

What Made Waterfall Different From Plain BungeeCord

Performance wasn't just marketing speak. Waterfall's patches focused on reducing proxy overhead. Some highlights:

• Better handling of concurrent player connections without thread pooling bottlenecks
• Smarter buffer management to reduce garbage collection pauses
• More efficient packet handling, especially for large player counts
• Testable code - the maintainers actually wrote unit tests, which BungeeCord didn't always prioritize

If you were running a network with 5,000+ concurrent players, this mattered. If you had 200 players, you wouldn't notice much difference.

The project also responded faster to security issues and compatibility updates when new Minecraft versions dropped. PaperMC had resources and motivation to move quickly.

Why Waterfall Got Archived

PaperMC didn't abandon Waterfall lightly. They created something better: Velocity. Velocity isn't a fork of BungeeCord - it's a completely new proxy written from scratch. It's designed for modern Java, has better performance, cleaner plugin APIs, and more active development.

The Waterfall maintainers made an official announcement: use Velocity instead. They're maintaining it, improving it, and it's where the Minecraft server proxy ecosystem is heading. After a period where both projects existed, they decided to put Waterfall into archive mode.

This wasn't a failure. It was the authors recognizing that the next generation of their own software was better, and being honest with the community about it.

What This Means for Your Server Setup

If you're building a new proxy network today, don't use Waterfall. Use Velocity. It's actively maintained, performs better, and you'll get bug fixes and security updates.

If you're curious about how Minecraft proxies work at a deeper level, Waterfall's codebase and architecture still have educational value. Reading through the patches and understanding why they were needed teaches you real things about proxy performance.

And if you're already running Waterfall on a stable network? Migration to Velocity is straightforward, and the PaperMC team provides guidance for it. The config formats are different but not drastically so.

One practical tip: if you're customizing your server list with MOTD text (the message that shows when players see your server in the multiplayer menu), tools like our MOTD Creator can help you format that properly for your proxy. Waterfall and Velocity both respect standard MOTD formatting.

Learning From Waterfall's Story

Waterfall matters not because you should use it today, but because it represents something important in open source. A team recognized a real problem, forked a project, proved they could solve it better, and then gracefully transitioned to a successor when the next evolution became clear.

It didn't die because it was bad. But it succeeded so well that its creators built something better to replace it, and had the integrity to tell people to use that instead.

Plus, if you're building anything with Minecraft server infrastructure - perhaps searching for block behavior or trying to understand how complex game mechanics work - you'll find references to Waterfall in forums and documentation. Understanding its role in the ecosystem helps you understand the whole landscape.

Need to figure out Minecraft blocks for your proxy or server? The Block Search tool is surprisingly useful when you're debugging proxy issues or understanding why certain blocks cause problems with packet routing.