VelocityNavigator

# VelocityNavigator !(https://raw.githubusercontent.com/DemonZ-Development/VelocityNavigator/main/assets/hero-banner.png?v=7) Velocity's `try` list is useful for fallbacks, but it is not a load balancer: while the first lobby is available, most players are sent there. VelocityNavigator chooses a lobby for initial joins and `/lobby` requests using live health, capacity, maintenance state, and the routing mode you select. It is comfortable on a two-lobby proxy and has room to grow into multi-proxy networks without making the basic setup complicated. > Download the current JAR with the **Download** button on this Modrinth page. It always runs on Velocity; the same file can also be installed on Paper or Spigot when you want the Java inventory selector. ## Version 4.4.0 Version 4.4 separates the name players see from the server ID Velocity uses. A backend registered as `lobby1` can now appear as **Main Lobby 1** in the Java inventory, clickable chat menu, and Bedrock form. Configure the presentation in `gui.toml`: ```toml "lobby1" = { display_name = "Main Lobby 1", description = "Events, portals, and network help", menu_order = 10, show_in_menu = true } "staff-lobby" = { display_name = "Staff Lobby", menu_order = -1, show_in_menu = false } ``` The real IDs stay in `velocity.toml`. Routing, health checks, callbacks, secure menu tokens, and connection requests continue to use those IDs. Also included in 4.4: - shared descriptions, ordering, and visibility across all three selectors - reusable Java item styles for full, draining, offline, and in-game servers - configurable inventory sizes from two to six rows, with navigation kept in the reserved bottom row - `/vn menu validate` for unknown IDs, duplicate labels, slot conflicts, materials, and placeholders - one Java 17-bytecode JAR verified on Velocity 3.4.x, 3.5.x, and 4.0.0 ## Routing !(https://raw.githubusercontent.com/DemonZ-Development/VelocityNavigator/main/assets/marketplace/01-smart-routing.png?v=2) | Mode | Good fit | |---|---| | `least_players` | Straightforward balancing for a small pool | | `power_of_two` | A fast default for busy networks | | `weighted_round_robin` | Lobbies with different capacities | | `consistent_hash` | Keeping players on a familiar lobby | | `latency` | Choosing by proxy-to-backend response time | | `least_connections` | Routing by recent connection load | | `round_robin` / `random` | Simple deterministic or random rotation | A candidate can be excluded when it is offline, full, drained, circuit-broken, or in a disallowed lifecycle state. Fallback pools and contextual groups let different game modes return players to the right hub. Initial joins use the same checks as `/lobby`, so the balance begins before players run a command. ## Player selectors ### Java inventory !(https://raw.githubusercontent.com/DemonZ-Development/VelocityNavigator/main/assets/java-inventory-selector.png?v=1) The optional Paper/Spigot bridge renders a paginated chest menu. `gui.toml` controls its row count, filler, icons, fixed slots, navigation buttons, refresh interval, item names, lore, and state styles. ### Bedrock form !(https://raw.githubusercontent.com/DemonZ-Development/VelocityNavigator/main/assets/bedrock-selector.png?v=2) Geyser/Floodgate players can use a native form. If neither GUI is installed, VelocityNavigator can fall back to the clickable Java chat selector. Display names, descriptions, ordering, and visibility stay consistent between all three. The screenshots above are from running Minecraft clients. ## Installation choices !(https://raw.githubusercontent.com/DemonZ-Development/VelocityNavigator/main/assets/marketplace/02-universal-jar.png?v=2) | Setup | What you get | |---|---| | Velocity only | Routing, initial-join balancing, chat selector, Bedrock forms, health checks, parties, queues, commands, and metrics | | Velocity plus backend bridge | Everything above, plus the Java inventory selector and optional backend Redis registration | | Multiple Velocity proxies plus Redis | Shared health, circuit-breaker, affinity, and backend-state information | A proxy-only installation is fully supported. Put the JAR on a backend only when that server needs bridge features. Startup logs state whether the file is running in **VELOCITY PROXY** or **BACKEND GUI BRIDGE** mode. ## Optional network features !(https://raw.githubusercontent.com/DemonZ-Development/VelocityNavigator/main/assets/marketplace/05-optional-systems.png?v=2) - **Parties:** invites, member management, private chat, and leader-follow transfers - **Capacity queue:** position updates and automatic connection when a lobby opens - **Redis sync:** shared routing state between Velocity proxi