ServerSwitch — Velocity Proxy Plugin

Generic, config-driven server-switch commands for a Velocity proxy. Ships with /hub and /lobby (both pointing at a backend server named lobby), and lets admins add any number of additional aliases without touching code.

Project layout

src/main/java/network/tiki/serverswitch/
├── ServerSwitchPlugin.java             Composition root (@Plugin entry point)
├── config/
│   └── AliasConfig.java                Typed wrapper around config.yml (only class that parses YAML)
├── feature/
│   └── AliasCommandManager.java        Registers/unregisters one command per configured alias
└── command/
    ├── ServerSwitchCommand.java        Runs a single alias — sends the player to its target server
    └── ReloadCommand.java              /serverswitchreload

How the "generic aliases" part works

Velocity plugins register commands in code rather than declaring them in a static file (there's no plugin.yml equivalent). That turns out to be exactly what makes this generic for free: AliasCommandManager.apply(Map<String,String>) just loops over whatever's in config and registers one ServerSwitchCommand per entry. Adding a new alias is purely a config change — ServerSwitchPlugin, AliasCommandManager, and ServerSwitchCommand never need to change.

Config (config.yml)

aliases:
  hub: lobby
  lobby: lobby
  # skywars: skywars-1
  # events: event-server

Left side is the command name a player types (/hub); right side is the backend server's name exactly as registered in velocity.toml's [servers] section.

Runtime reload

Run /serverswitchreload after editing config.yml — it re-reads the file and calls AliasCommandManager.apply(...) again, which unregisters every alias command and re-registers the current set. No proxy restart needed, and this also picks up aliases that were added, removed, or repointed at a different server.

Grant serverswitch.reload through a permissions plugin (e.g. LuckPerms). Without one installed, only the console can run it.

Design decisions

SOLID

• SRP — AliasConfig only reads/writes YAML; AliasCommandManager only tracks which commands are registered; each ServerSwitchCommand only knows its own alias and target server.
• OCP — new aliases are added via config, never by touching AliasCommandManager or adding a new command class.
• DIP — everything depends on Velocity's ProxyServer/CommandManager interfaces, never on proxy-implementation classes.

Patterns used

• Command pattern — Velocity's SimpleCommand, one instance per alias.
• Registry — AliasCommandManager tracks and reconciles the live set of registered commands against config.
• Facade — AliasConfig hides YAML parsing and default-config bootstrap behind two methods (reload(), getAliases()).
• Composition root / manual DI — ServerSwitchPlugin wires the object graph once in onProxyInitialize.

Building

Requires JDK 25 and Gradle (no wrapper committed yet — see the note in the release workflow if you'd like to add one, same as the lobby plugin's setup).

gradle build

The shaded jar is produced at build/libs/ServerSwitch-1.0.0.jar — drop it into your Velocity proxy's plugins/ folder.

Releases

.github/workflows/release.yml mirrors the lobby plugin's setup: push a tag (git tag v1.2.0 && git push origin v1.2.0) or publish a GitHub release, and CI builds the jar with the tag's version baked in and attaches it to the release automatically.