Snap: Running Your Legacy BungeeCord Plugins on Velocity

You've got a Velocity server. You want to migrate from BungeeCord. But half your plugins don't have Velocity versions yet, and rewriting them feels like overkill. Snap is a Java adapter plugin that runs BungeeCord plugins directly on Velocity by translating API calls on the fly. It won't solve every compatibility problem, but for certain setups it might save you the painful work of replacing or rewriting plugins you still depend on.

What's Snap, Really?

Snap is a Velocity plugin that acts as a compatibility layer between two proxy architectures. It loads BungeeCord plugins inside Velocity and intercepts their API calls, converting them to Velocity equivalents in real time. Think of it as a live translator sitting between your legacy plugins and a modern proxy.

The origin story matters here. This maintainer, Phoenix616, started by trying to document the differences between BungeeCord and Velocity APIs. That spiraled into building an actual adapter that could load plugins from one proxy on the other. The result is clever in concept but carries real trade-offs: it works, but it's less efficient than native Velocity plugins because every single method call gets translated.

For a niche tool solving a specific problem, it's fairly active. 134 GitHub stars, recent maintenance, and the latest release (1.2-pre1) supports Velocity 3.3.0 with Bungee 1.20.x compatibility. The project is licensed under LGPL-3.0, so you can use it freely as long as you share any modifications back.

What Works (And What Definitely Doesn't)

Most basic proxy tasks work fine. Player connections, server switching, event listening, permissions checks - all there. The maintainer is refreshingly honest in the README: "Most of it (hopefully)." They're not overselling this thing.

But several features won't translate to Velocity at all:

• BungeeCord's built-in group and permissions system doesn't exist in Velocity. The project recommends using LuckPerms instead, which works on both.
• Reconnect server functionality. BungeeCord has this built-in; Velocity doesn't expose it.
• Scoreboard support. Velocity has no API for this, and Snap isn't building one.
• Some ProxyConfig settings return sensible defaults but aren't exact mirrors of Bungee behavior.
• Commands registered after a plugin loads might not show up in the command registry.
• Transfer detection only works if the server is in online mode.

If your plugin depends heavily on any of these features, Snap won't save you. Time to write a native Velocity plugin.

Here's where Snap gets practical: you can configure what happens when something isn't supported. Set `throw-unsupported-exception` to `true` (the default) and you'll see exceptions logged so you know exactly what broke. Set it to `false` and unsupported methods return default values instead, letting your plugins limp along.

Installing and Setting It Up

Installation is straightforward if you've worked with Velocity before.

First, grab the snap.jar file from the project's CI build system (linked on the releases page). It requires Java 17 or newer, so make sure your server meets that baseline.

# Drop snap.jar into your Velocity plugins folder
cp snap.jar /path/to/velocity/plugins/

# Create the Snap plugins directory
mkdir -p /path/to/velocity/plugins/Snap/

# Move your BungeeCord plugins there
cp /path/to/bungee/plugins/*.jar /path/to/velocity/plugins/Snap/

Restart Velocity (or reload the plugin), and Snap initializes, loads all the BungeeCord plugins from that folder, and logs any issues it encounters. If something doesn't load, the logs will tell you why.

One practical tip from testing: start with just Snap and one BungeeCord plugin. Confirm it loads. Then add more gradually. You'll catch incompatibility issues much faster than by dumping everything in at once and then wondering which plugin is causing the problem.

When You'd Use This

Snap makes sense in a few specific situations.

You've a BungeeCord plugin that's no longer maintained and doesn't have a Velocity equivalent. Maybe it's a legacy staff utility or a custom analytics module. Rewriting it feels wasteful. Snap lets you keep using it without a full rewrite.

You're migrating a network but don't want to migrate everything at once. Running Snap on your new Velocity server lets you bring old plugins over while you gradually write or find Velocity replacements.

You're running a test network and want to try Velocity without committing to migrating your entire plugin ecosystem yet.

What doesn't make sense: using this on production. The project itself warns against it without extensive testing. And even then, you're betting on experimental software. Most production networks are better off migrating properly.

If most of your plugins already have maintained Velocity versions, skip Snap entirely. Just migrate. You'll have fewer surprises and better performance.

Performance Trade-Offs and Gotchas

Translation adds overhead. Every API call gets caught and converted back and forth. For plugins making thousands of calls per second, you might see CPU impact. For normal plugins doing basic proxy work, probably not.

Connection handling is the trickiest part. Events might fire slightly differently than on BungeeCord. If your plugin does heavy manipulation of player connections or relies on specific event timing, you're better off rewriting it for Velocity instead of trying to make it work through Snap's translation layer.

There's also a scale ceiling. If you're running a massive network with thousands of concurrent players, Snap's inefficiency will compound. At that size, you're better off migrating properly.

Watch your CPU and memory during peak traffic. If you see spikes that correlate with plugin activity, it might be the translation layer struggling. That's your signal to either migrate the plugin or look for a Velocity alternative.

Real Alternatives

Your options for running old BungeeCord plugins on Velocity are actually pretty limited, which is why Snap exists in the first place.

Write a Velocity plugin. It's the right long-term choice and the future-proof path. Depending on complexity, it might only take a weekend.

Stay on BungeeCord or Waterfall. Velocity is faster and better-architected, but it's not the only option. If your entire plugin ecosystem is BungeeCord-dependent, staying there's valid until you're ready to migrate everything together.

Redesign around the missing functionality. Do you actually need that legacy plugin? Maybe a modern permissions system like LuckPerms solves your problems without the plugin. Maybe you can simplify your infrastructure.

Before You Install

Test this in a staging environment first. Run your plugins through every feature you care about. Then watch it for a week and look for odd behavior. Check logs regularly. Look for performance issues.

Understand the limitations going in. Snap works for certain plugins and certain use cases. Look, and it won't work for everything. The more your plugins depend on Bungee-specific features (especially permissions groups, scoreboard manipulation, or connection hijacking), the more likely Snap will disappoint you.

Don't run this in production without that staging testing phase. The project is explicit: this is experimental software. It solves a specific problem for specific people. And that might not solve your problem.

And if you're managing a Minecraft server network, you probably also have builders and players. They might appreciate minecraft.how's Block Search tool for tracking down specific materials, or the Nether Portal Calculator for planning infrastructure.