Skip to main content

Setting up Velocity

Level: Advanced

When you want to connect multiple individual servers together, you need to use a "proxy server". Out of all the currently available options such as BungeeCord and Waterfall, Velocity is largely recommended as it has the most users and hence most available support.

This guide will go through how to set up Velocity together with the most popular paper based servers such as paper, pufferfish and purpur.

Step 1: Create the Minecraft server(s) you want to link together

  • Creeate the servers that you want to link together. You can find a detailed guide on how to do so here.

Note that all servers must be located on the same node to have proper stability. Although it is possible to use a proxy across different countries / providers, it will bring significant latency / stability issues and at worse will lead to players being disconnected.

Step 2: Create the Velocity server

  • Create a new server and select "Minecraft>Velocity" as the type. This will be our proxy server.

Step 3: Start the server

  • After the installation is completed, start the server for the first time to generate the necessary default configuration files.
  • After the server has been started, wait for it to complete generating the configuration files which will be indicated by the "Server marked as running" message.

Step 4: Open the configuration file

  • In the File Manager, open the velocity.toml configuration file.
  • Scroll down to the sections [servers] and [forced-hosts].
  • These are the sections that need to be modified in the next step for the proxy to work properly.

Step 5: Configure the proxy

  • In this example, I will be linking together two servers in the following configuration:
│ Proxy Server │
 │  server 1
 │  server 2
  • The server will be configured as follows:
    • server 1 will be called "lobby"
    • server 2 will be called "bedwars"
    • When connecting to the proxy server, the player should be sent to the "lobby" server by default, at which point the player will be able to be teleported to the other servers through teleportation gates (provided by plugins) or the /server [server name] command. Access to this command can be limited through permission plugins.
  • The final configuration to replicate this behaviour will look like this:

Step 6: Player data information forwarding

  • When players connect to a server behind a proxy, it must be set to offline mode which means information such as the UUID and player skin will not work.
  • This problem can be fixed through the forwarding options offered by velocity.
  • In the same configuration file from Step 4, modify the "player-info-forwarding-mode" to "modern".
player-info-forwarding-mode = "modern"

If you are running a server below version 1.13 or a non-paper based server (such as fabric servers for modded gameplay), "modern" information forwarding will not work.

Please refer to the alternative player forwarding methods that can be seen in velocity's information forwarding configuration page.

Step 7: Write down your forwarding secret

  • Open the forwarding.secret file
  • Take note of the forwarding secret present inside of the file, it will be necessary when configuring the minecraft servers that are being linked, do not share it with anyone.

Step 8: Configure the server(s)

  • Open the Minecraft server(s) file manager(s).
  • Open the file.
  • Set online-mode to false and save the changes.
  • Open the config folder.
  • Inside of the folder, open the paper-global.yml file.
  • Under proxies>velocity set both enabled and online-mode to true, then paste the forwarding secret from Step 7 into the secret field.
  • Save the changes

Step 9: Start the servers

  • Start the proxy server by clicking on the start button
  • Start the minecraft servers by clicking on the start button

If you are having trouble with this, you can open a support ticket here!
Feedback and suggestions regarding this article are welcome in our Discord server