Velocity Proxy Setup Guide

🌐 Introduction to Velocity

Velocity is a high-performance, scalable proxy server for Minecraft, designed to manage multiple backend servers (e.g., lobby, survival, minigames) under a single IP. It offers seamless server switching, advanced security features, and support for both premium and cracked clients. This guide provides a comprehensive, step-by-step process to configure Velocity, ensuring optimal performance for your Minecraft network.

Benefits of Velocity:
- Low-latency connections with modern forwarding protocols.
- Scalability for large networks with thousands of players.
- Robust security with encrypted player data forwarding.
- Compatibility with Minecraft versions 1.7.2 and above.

🤔 Why Choose Velocity?

Velocity stands out among other proxy solutions like BungeeCord and Waterfall due to its modern design and performance optimizations. Here’s how it compares and why it might be the best choice for your Minecraft network:

Benefits Compared to Other Proxies:
- Superior Performance: Velocity leverages modern Java features and optimized forwarding protocols, offering lower latency and higher throughput compared to BungeeCord’s older architecture.
- Enhanced Security: With built-in encrypted player data forwarding, Velocity provides stronger security out of the box, surpassing Waterfall’s reliance on manual configuration for similar features.
- Broader Compatibility: Supports Minecraft versions from 1.7.2 to the latest releases, while some alternatives like Waterfall may lag in supporting newer versions without additional patches.
- Active Development: Backed by the PaperMC team, Velocity receives regular updates and community support, unlike BungeeCord, which has seen slower development in recent years.
- Scalability: Designed to handle thousands of players with minimal resource usage, outperforming older proxies in large-scale network setups.

⚙️ 1. Install and Start the Velocity Server

Download the latest Velocity JAR file from PaperMC. Ensure you have Java 11 or later installed, as Velocity requires it for optimal performance.

java -jar velocity.jar

Run the server once to generate essential configuration files, including velocity.toml and forwarding.secret, in the server directory.

Ensure your server has sufficient memory (e.g., 512MB–1GB for Velocity) and is hosted on a machine with a stable network connection.

📝 2. Configure `velocity.toml`

The velocity.toml file, located in the Velocity root directory, controls the proxy’s core settings. Below are the key configurations to set up your proxy.

🔌 Bind Address and Port

bind = "0.0.0.0:27090"

Set the IP and port for Velocity to listen on. Use 0.0.0.0 to bind to all network interfaces, and replace 27090 with your preferred port (default Minecraft port is 25565).

Ensure the port is open in your firewall and forwarded in your router if hosting externally.

🔐 Online Mode

online-mode = false

- true: Restricts connections to premium Minecraft accounts, verifying them with Mojang’s servers.
- false: Allows both premium and cracked (non-premium) clients to connect, ideal for inclusive servers.

Set to false only if you have additional authentication plugins (e.g., AuthMe) on backend servers.

📦 Player Info Forwarding

player-info-forwarding = "modern"

Configures how player data (UUIDs, skins, etc.) is forwarded to backend servers:
- "modern": Uses Velocity’s secure forwarding for Minecraft 1.13+.
- "legacy": Required for Minecraft 1.7.2–1.12.2.
- "none": Disables forwarding (not recommended).

Use "modern" unless supporting older Minecraft versions.

🖥️ Backend Server List

[servers]
lobby = "127.0.0.1:25565"
survival = "127.0.0.1:25566"
minigames = "127.0.0.1:25567"
try = ["lobby", "survival", "minigames"]

Define your backend servers with their numerical IPs and ports. The try list specifies the order in which Velocity attempts to connect players to servers on join. Use DNS Lookup to find numerical IPs for remote servers.

Use 127.0.0.1 for local servers; replace with actual IPs for remote servers. Avoid using domain names directly.

🚫 TOML does not support comments in this section. Ensure clean formatting.

🌟 MOTD (Message of the Day)

motd = "&6Welcome to Your Minecraft Network!&r\nJoin our &bcommunity&r today!"

Customize the server’s Message of the Day displayed in the Minecraft server list. Use & for color codes and \n for line breaks.

Keep the MOTD concise to ensure compatibility with Minecraft clients.

📊 Player Limits and Compression

show-max-players = 1000
compression-level = 4
compression-threshold = 256

- show-max-players: Sets the maximum player count displayed in the server list.
- compression-level: Controls packet compression (1–9, higher values reduce bandwidth but increase CPU usage).
- compression-threshold: Minimum packet size (in bytes) to compress (default: 256).

Adjust compression-level based on your server’s CPU and network capacity. Higher values improve bandwidth efficiency but may impact performance.

🧭 Forced Hosts

[forced-hosts]
"lobby.yourdomain.com" = ["lobby"]
"survival.yourdomain.com" = ["survival"]

Routes players connecting via specific domains to designated servers. Leave empty if not using subdomains.

Ensure DNS records are set up correctly if using forced hosts. Test with ping or a DNS lookup tool.

🔑 3. Set Up `forwarding.secret`

Create a secure key for player data forwarding to ensure encrypted communication between Velocity and backend servers. Use a random string/password generator like BitWarden to create a strong password.

xL9E!aaW#7Ef29pQ

Replace the contents of forwarding.secret with your generated key. Save this key securely, as it’s required for backend server configuration.

Use a unique key for each Velocity instance to prevent unauthorized access. Avoid sharing this key publicly.

🔧 4. Configure Backend Servers

Each backend server (e.g., running PaperMC, Spigot, or Fabric) must be configured to work with Velocity. This guide uses PaperMC as an example, but the principles apply to other server software.

📝 Edit `server.properties`

online-mode=false

Disable online mode to allow Velocity to handle authentication. This is mandatory for proxy setups.

Ensure each backend server uses a unique port to avoid conflicts.

🛠️ Edit `paper-global.yml`

Location:
- Older Paper versions: Root folder (paper.yml)
- Newer Paper versions: config/paper-global.yml

proxies:
  velocity:
    enabled: true
    online-mode: false
    secret: "xL9E!aaW#7Ef29pQ"

Configure the Velocity proxy settings:
- enabled: true: Enables Velocity forwarding.
- online-mode: false: Matches Velocity’s online-mode setting.
- secret: Must match the key in forwarding.secret.

✅ Verify:
- enabled is set to true.
- online-mode aligns with Velocity’s configuration.
- The secret is identical to forwarding.secret.

🔌 Compatibility with Other Server Software

For Spigot or Fabric servers:
- Spigot: Edit spigot.yml and set bungeecord: true for legacy forwarding or configure Velocity forwarding similarly to Paper.
- Fabric: Install a mod like FabricProxy Lite and configure it with the same secret.
- Purpur: Edit purpur.yml and set velocity: true for modern forwarding or configure it similarly to Paper.
- Waterfall: Use waterfall.yml to set online-mode: false and secret to match Velocity’s configuration.
- BungeeCord: Edit bungee.yml and set online-mode: false and secret to match Velocity’s configuration.
- NeoForge: Install a mod like NeoVelocity and configure it with the same secret.

Ensure all backend servers use the same forwarding mode (modern or legacy) as Velocity.

🔁 5. Repeat for All Backend Servers

Apply the backend configuration steps to each server in your network (e.g., lobby, survival, minigames). Ensure each server has:
- A unique port and IP in velocity.toml.
- Consistent online-mode and secret settings.
- Compatible server software (Paper, Spigot, or Fabric with appropriate mods).

Test connections to each server individually before launching the proxy to ensure proper configuration.

▶️ 6. Startup Order

To ensure a smooth network launch:
1. Start all backend servers (e.g., lobby, survival, minigames).
2. Start the Velocity proxy server.

Velocity will not connect players to backend servers that are offline, so always start backend servers first.

🔄 7. Switching Between Servers (Worlds)

Velocity allows players to seamlessly switch between backend servers (often referred to as "worlds" in Minecraft) without disconnecting from the proxy. This is achieved using commands or plugins that facilitate server switching. Below, we outline the methods to enable and manage server switching in your Velocity network.

🚀 Using Velocity’s Built-in Commands

Velocity provides a native command to switch players between servers defined in velocity.toml. The primary command is:

/server <server-name>

For example, to switch to the "lobby" server:

/server lobby

Players can view available servers using:

/glist

This command lists all servers and the number of players connected to each.

Ensure players have the permission velocity.command.server to use the /server command. This is granted by default but can be restricted using a permissions plugin.

🛠️ Enhancing Switching with Plugins

For a more user-friendly experience, you can install plugins on your Velocity proxy to enhance server switching. Popular options include:

LuckPerms: Manage permissions across all servers to control who can switch to specific servers. Install on Velocity and all backend servers, and configure cross-server permission syncing. Download from Official Website.
ServerSelectorX: Provides a GUI menu for players to switch servers by clicking items in an inventory. Download from SpigotMC.
BungeeGuard: Adds extra security for server switching when using legacy forwarding. Download from SpigotMC.

To install a plugin, place the plugin’s JAR file in the plugins folder of your Velocity proxy directory and restart the proxy.

Ensure plugins are compatible with Velocity. Check the plugin’s documentation for Velocity-specific versions or configurations.

🔧 Configuring a Server Selector GUI

Using a plugin like ServerSelectorX, you can create a custom GUI for server switching. Below is an example configuration for ServerSelectorX (config.yml):

menus:
    main:
        title: "&6Choose a Server"
        size: 27
        items:
        lobby:
            material: GRASS_BLOCK
            name: "&bLobby"
            slot: 10
            command: "server lobby"
        survival:
            material: DIAMOND_PICKAXE
            name: "&2Survival"
            slot: 12
            command: "server survival"
        minigames:
            material: GOLDEN_SWORD
            name: "&eMinigames"
            slot: 14
            command: "server minigames"

This configuration creates a menu with clickable items that run the /server command to switch to the specified server. Players can open the menu using:

/ssx open main

Customize the material, name, and slot to match your server’s theme and layout. Ensure the command matches the server names defined in velocity.toml.

🔐 Permissions for Server Switching

Use a permissions plugin like LuckPerms to control access to server switching. Example LuckPerms commands to grant access to specific servers:

/lpv user <player> permission set velocity.command.server.lobby true
    /lpv user <player> permission set velocity.command.server.survival true

These commands allow the specified player to switch to the "lobby" and "survival" servers. To restrict access to certain servers, omit the corresponding permission.

Run LuckPerms commands from the Velocity proxy console or as an operator in-game. Ensure LuckPerms is installed on both the proxy and backend servers for seamless permission syncing.

🌐 Automatic Server Switching

You can automate server switching based on specific conditions using plugins or custom scripts. For example:

Fallback Server: Configure Velocity to send players to a fallback server (e.g., "lobby") if their current server goes offline. Edit velocity.toml:

try = ["lobby", "survival", "minigames"]

The first server in the try list acts as the fallback.

Event-Based Switching: Use a plugin like RedisVelocity to switch players based on events (e.g., game completion in minigames).

Test automatic switching thoroughly to ensure players are redirected correctly without disrupting their experience.

⚠️ Troubleshooting Server Switching

Players can’t switch servers: Verify that the server names in commands or plugins match those in velocity.toml, and check for permission issues with LuckPerms.
GUI menu not appearing: Ensure the plugin (e.g., ServerSelectorX) is installed on the Velocity proxy, not backend servers, and that the configuration is valid.
Connection errors during switching: Confirm that backend servers are online and that their IPs and ports are correctly configured in velocity.toml.

Check the Velocity proxy logs for errors during server switching. For additional help, join our Discord community.

🛡️ 8. Security and Performance Best Practices

🔒 Use a Firewall: Restrict access to backend server ports (e.g., 25565, 25566) to only the Velocity proxy’s IP.
🔑 Secure the Secret Key: Store forwarding.secret in a secure location and avoid reusing keys across servers.
📈 Optimize Compression: Adjust compression-level based on your server’s hardware and network bandwidth.
🔌 Monitor Performance: Use plugins like LuckPerms for cross-server permissions and monitor lag with tools like Spark..
🔄 Regular Backups: Back up configuration files and server data to prevent loss during updates or crashes.

Consider using a DDoS-protected hosting provider to enhance network security.

🛠️ 9. Troubleshooting Common Issues

⚠️ Players can’t connect to backend servers: Verify that backend server IPs and ports in velocity.toml are correct and servers are running.
🔐 Authentication errors: Ensure forwarding.secret matches the secret in paper-global.yml and that online-mode settings are consistent.
📉 High latency: Check compression settings and server hardware. Lower compression-level if CPU usage is high.
🌐 Domain routing issues: Confirm DNS records for forced hosts are correctly configured using a tool like DNS Lookup.

Check the Velocity console logs and backend server logs for detailed error messages. Join our Discord for real-time support.

🤝 Contributors

PokeDB: Developed and designed the website
Alino10: Provided creative ideas and invaluable support ( dealt with my crash-outs Respect )

📊 Velocity Configuration Effort Breakdown

This chart illustrates the estimated effort required for each step in setting up a Velocity proxy for Minecraft, highlighting the critical tasks involved in configuring the proxy and backend servers for optimal performance.

📊 Configuration and Code Composition

This chart illustrates the proportional contribution of each configuration and code type used in this Velocity proxy setup guide, highlighting the technologies and formats critical to configuring and presenting the proxy setup.

✅ Velocity Proxy Setup Guide for Minecraft