Spvelocity — a Paper / Spigot plugin that downloads and launches a Velocity proxy

What is it?

Spvelocity is a Paper / Spigot plugin that automatically:

1. Downloads a Velocity jar from a given URL
2. Starts Velocity in a separate process
3. Lets you control it in-game / from console with /proxy start|stop|status

Perfect for quick network testing, CI pipelines, or ad-hoc test servers.

Features

• Auto-download of velocity.jar on the very first /proxy start
• Works on Paper / Spigot 1.12 – latest (built against the 1.21.4 API)
• Requires only Java 11+, recommended Java 17 or 21
• Runs in a background thread – won’t block the main server
• Stops Velocity automatically when the Paper server stops
• Simple configuration via plugins/Spvelocity/config.yml

Requirements

• A Paper or Spigot server
  (1.12 – latest, built against Paper-1.21.4)
• Java 11 or newer (Velocity itself needs 11+)
• Internet access the first time you run /proxy start (to download Velocity)

Getting started (pre-built jar)

1. Download spvelocity-<version>-shaded.jar from the Releases page
2. Drop it into <server>/plugins
3. Start your Paper / Spigot server with Java 17 / 21 etc.
4. Run in-game or in console:

   /proxy start
   

   → velocity.jar is downloaded to plugins/Spvelocity/proxy/ and booted on port 25577

Building from source

git clone https://github.com/<YOUR-USER>/spvelocity.git
cd spvelocity
mvn clean package    # produces target/spvelocity-*-shaded.jar

Configuration — config.yml

velocity:
  download-url: "https://api.papermc.io/v2/projects/velocity/versions/3.3.0-SNAPSHOT/builds/261/downloads/velocity-3.3.0-SNAPSHOT-261.jar"
  jar-name: "velocity.jar"
  port: 25577

• Copy the download URL from PaperMC’s downloads page:
  https://papermc.io/downloads#Velocity
• Stable versions (3.2.0, etc.) keep the same URL.
• For SNAPSHOTs you may want a script that queries the API for the latest build or update the URL manually.

Commands & permissions

How it works

1. SpvelocityManager checks whether plugins/Spvelocity/proxy/velocity.jar exists
2. If not, it downloads it via Apache Commons IO from the configured URL
3. Runs java -jar velocity.jar --port <port> through ProcessBuilder
4. Redirects proxy output to the Paper console
5. When the Paper server shuts down, the child process is destroyed via destroy()

License

MIT License — see LICENSE for details.
Fork, modify, redistribute, enjoy!