VelocityNavigator

High-performance lobby routing, native visual selectors, self-healing circuit breakers, zero-dependency NPCs, and practical proxy operations for modern Velocity networks.

VelocityNavigator takes the guesswork out of proxy load balancing. Instead of blindly cycling connections, it continuously evaluates backend health, server capacity, maintenance windows, drain states, lifecycle status, and geographic latency before routing a single player.

Whether running a two-lobby community or a multi-proxy enterprise network with dozens of regional backends, VelocityNavigator delivers resilient, explainable routing that scales effortlessly.

Universal Single-JAR Architecture: Install the exact same JAR on your Velocity proxy and on any Paper, Spigot, or Folia backend where you want NPCs, YAML menus, Java inventory selectors, PlaceholderAPI values, or backend Redis registration. Zero separate bridge plugins required.

1. Intelligent Lobby Routing & Balancing

Simple round-robin routing breaks in production networks. Disconnections, player grouping, and varied server hardware create severe load imbalances. VelocityNavigator provides nine specialized routing strategies designed for real-world proxy architectures:

• Power of Two Choices (power_of_two): The modern industry standard for distributed load balancing. Selects two candidate lobbies at random and routes to the one with lower load. Mathematically eliminates herd behavior and load skew without requiring global locks.
• Least Players (least_players): Routes new connections directly to the lobby with the fewest online players. Ideal for ensuring new players land in active, populated environments.
• Weighted Round Robin (weighted_round_robin): Distributes traffic proportionally across backends according to assigned server weights. Perfect for mixed hardware deployments (e.g. directing 3x more players to a 64GB dedicated node than an 8GB VPS).
• Consistent Hashing (consistent_hash): Uses a Ketama hash ring with virtual nodes to consistently map player UUIDs to specific backends. Provides deterministic routing while smoothly re-distributing only a fraction of keys when servers are added or removed.
• Latency-Aware Ping Routing (latency / ping): Actively evaluates round-trip ping to each backend and assigns incoming players to the lowest-latency responsive node.
• Least Connections (least_connections): Scores servers using smoothed player counts and recent connection rates to distribute burst traffic.
• Geo-Location Routing (geo): Automatically routes international players to regional backend clusters based on player country and continent codes. Supports MaxMind GeoLite2, IP-API, and native GeoRestrict integration.
• Sequential Round Robin (round_robin): Strict cyclic distribution across all healthy candidate backends.
• Uniform Random (random): Pure random distribution across available healthy lobbies.

Sticky Sessions & Player Affinity

Returning players hate being thrown into a random lobby every time they switch worlds. VelocityNavigator provides configurable player affinity:

• Remembers a player's previous lobby within a configurable time window.
• Automatically routes players back to their familiar lobby upon reconnecting.
• Fully persistent across proxy restarts with atomic on-disk storage.
• Instant expiration bypass when the preferred lobby is full, draining, or undergoing maintenance.

Live Route Explanations

Need to diagnose why a player routed to a specific lobby? Run /vn debug player <username> to view the real-time routing trace: candidate pool discovery, filter rules (health, capacity, drain, maintenance, affinity), scoring calculations, and the selected winner.

2. Resilient Self-Healing & Circuit Breakers

When a backend crashes or suffers severe TPS drops, standard proxies leave players waiting on timeout screens. VelocityNavigator acts as a self-healing traffic manager with enterprise-grade defensive systems:

• Three-State Circuit Breaker (CLOSED ➔ OPEN ➔ HALF-OPEN): Each registered backend server maintains an independent circuit breaker. When connection failures or ping timeouts exceed your configured threshold, the circuit trips OPEN, instantly cutting off player routing to that server before players experience connection freezes. After a cool-down window, it enters HALF-OPEN to test server health with canary connections before resuming full traffic.
• Exponential Backoff with Jitter: When disconnected backends recover, reconnect attempts back off progressively with pseudo-random jitter. This prevents the devastating "thundering herd" effect where hundreds of players flood a recovering server simultaneously.
• Continuous Multi-Vector Health Checks: Active ping checks, TCP socket verification, MOTD query checks, and backend bridge heartbeats keep proxy state continuously synchronized with real server conditions.
• Zero-Downtime Drain System (/vn drain <server>): Safely take lobbies offline without kicking active players. Draining servers immediately stop receiving new joins and /lobby transfers while existing players finish their games. Once player count reaches zero, maintenance can be performed safely.
• Empty Lobby Fallbacks: If every lobby in a pool becomes unreachable, VelocityNavigator gracefully directs players to a configured fallback server or provides a friendly, localized disconnect notice instead of an unformatted network exception.

3. Unified Visual Selectors

Deliver a consistent navigation experience across every Minecraft client platform:

• Native Java Dialogs (Minecraft 1.21.6+ & Paper 1.21.7+):
  • Clean, modern native client dialog interfaces for lobby selectors, party management, authentication, and backend YAML menus.
  • Zero chest inventory clutter or item flickering: lobbies appear as native dialog buttons with pagination and hover tooltips.
  • Configurable UI modes (auto, dialog, inventory, sign, command, chat) with seamless automatic fallbacks for older clients and backends.
  • Built-in security with expiring, single-use action tokens bound to the player session.
• Java Chest Inventory GUI:
  • Multi-page pagination with customizable row sizes (1–6 rows).
  • State-aware item presentation: configure distinct materials, display names, and lore for Open, Full, Draining, Maintenance, and Offline lobbies.
  • Live player counts, capacity counters, and dynamic lore placeholders.
  • Automatic GUI refresh intervals so player counts stay accurate while menus remain open.
  • Cryptographic token validation to prevent slot injection and click-spoofing attacks.
• Native Bedrock / Geyser Form:
  • Clean, native Floodgate/Geyser dialog forms designed specifically for touch and controller navigation.
  • Displays server display names, live player counts, descriptions, and custom icon images.
  • Direct server switching on button press without clunky Java GUI emulation.
• Interactive MiniMessage Chat Selector:
  • Lightweight, zero-GUI text selector accessible from any client.
  • Formatted with rich MiniMessage styling, hover tooltips showing server details, and single-click connection commands.
• One Server Configuration for All Selectors:
  • Define server metadata once in your configuration: display_name, description, menu_order, and show_in_menu. Changes immediately synchronize across Native Dialogs, Java Inventory, Bedrock Forms, and Chat selectors.

4. Zero-Dependency Backend Bridge & NPCs

Unlike other proxy navigators that require separate Spigot plugins, protocol hacks, or heavy dependencies like Citizens, VelocityNavigator is completely self-contained:

• Single Universal JAR: The exact same JAR file placed on Velocity runs on Paper, Spigot, and Folia backends.
• Zero-NMS Packet NPCs:
  • Spawn lightweight, high-performance NPCs on backend servers without version-locked NMS code.
  • Compatible across Paper 1.16.5 through 26.3 and Folia out of the box.
  • Fetch custom player skins by username or Mojang texture properties.
  • Configure flexible click actions: connect to a server, open a custom menu, or execute proxy/backend commands.
  • Manage NPCs in-game with /vn npc create <id> <name>, /vn npc skin <id> <player>, and /vn npc delete <id>.
• Backend YAML Menus (plugins/VelocityNavigator/menus/*.yml):
  • Build full custom inventory menus on backends without third-party GUI plugins.
  • Configurable slot grids, materials, custom model data, skull owners, and sounds.
  • Multi-action execution: server transfer, commands, broadcast messages, submenus, pagination, and close.
• PlaceholderAPI Bridge:
  • Access real-time proxy values on any backend: %velocitynavigator_lobby%, %velocitynavigator_party_leader%, %velocitynavigator_party_size%, %velocitynavigator_server_status_<server>%, and %velocitynavigator_queue_position%.

5. Built-in Proxy Systems & Social Features

VelocityNavigator includes production-ready networking tools that eliminate the need for bloated third-party add-ons:

• Capacity Queue System:
  • Never turn players away during player spikes. When all routed lobbies reach capacity, players enter a graceful queue in a designated holding server.
  • Displays dynamic actionbar and title countdowns with live queue position and estimated wait time.
  • Priority bypass permissions (velocitynavigator.queue.priority) for VIPs and staff.
• Cross-Server Party System:
  • Complete party management: /party create, /party invite <player>, /party join, /party leave, /party kick, and /party disband.
  • Leader Follow: When the party leader switches lobbies or minigames, all online party members are automatically transferred together.
  • Private cross-proxy party chat (/party chat <message>) and open/invite-only party toggles.
• Network & Per-Server Maintenance:
  • Toggle network-wide maintenance or lock individual backends (/vn maintenance set <server> true).
  • Custom kick reasons with rich MiniMessage and color formatting.
  • Permission-based bypass (velocitynavigator.bypass.maintenance) for administrative testing.
  • Dynamic MOTD integration showing maintenance badges and countdowns.

6. Multi-Proxy Clustering & Redis Sync

Running multiple Velocity proxies behind a BGP Anycast IP or DNS round-robin? VelocityNavigator provides built-in distributed clustering via Redis:

• Cross-Proxy Health & Circuit Synchronization: Circuit breaker trip states and backend health snapshots synchronize in milliseconds across every proxy node.
• Cluster-Wide Player Affinity: Sticky sessions persist across proxies, ensuring returning players connect to the correct lobby regardless of which proxy receives their connection.
• Dynamic Server Registration: Backends can announce themselves dynamically over Redis Pub/Sub, registering with proxy pools on boot and unregistering on shutdown without editing proxy configuration files.
• Authenticated & Channel-Isolated: Secure Redis authentication with configurable channels and key prefixes for multi-network environments.

7. Security & Authentication Engine

Protect your proxy network with modern defensive security:

• Argon2id Password Hashing: Uses fixed costs of 64 MiB memory, three iterations, and four lanes. Verifies legacy salted SHA-256 credentials and upgrades them after a successful login when Argon2id is configured.
• Brute-Force Rate Limiting: Per-account failure tracking, temporary account lockouts, and a global attempt limit restrict password guessing. Reconnecting to the same proxy preserves account lockouts.
• Holding Lobby Quarantine: Unauthenticated players are isolated in a lightweight holding lobby. Player movement, block interactions, inventory access, and chat commands (outside /login and /register) are completely restricted until authentication succeeds.
• Native Bedrock Auth Forms: Bedrock players via Floodgate receive native modal dialogs for registration and password entry instead of typing passwords into open chat.
• Expiring Session Tokens: Proxy-local sessions remember authenticated players across quick reconnects to the same proxy within a configurable TTL.

8. Real-Time Operations & Observability

• Embedded HTML Operations Dashboard:
  • Built-in lightweight web dashboard running on its own dedicated port.
  • Real-time lobby status table showing active player counts, max capacity, latency, and circuit health.
  • Visual routing distribution charts, sticky session counters, and join/leave metrics.
  • Secured via HTTP Bearer Token authentication.
• Prometheus & Grafana Metrics:
  • Native /metrics endpoint exports Prometheus metrics out of the box: routing counts, circuit trips, health check latency, party counts, and queue depth.
  • Import directly into Grafana for 24/7 network monitoring.
• Dynamic MiniMessage MOTD Rotation:
  • Dynamic MOTD manager supporting Random, Sequential, or Scheduled Time-Window rotations.
  • Embed dynamic player counts, custom hex colors, gradients, and maintenance status lines.
• Self-Documenting Configuration & Validation:
  • /vn config validate performs deep syntax and semantic checks with Levenshtein distance typo suggestions.
  • /vn menu validate audits GUI item slots, materials, duplicate keys, and placeholders before players encounter broken menus.

9. Global Localization

Deploy globally with 15 bundled language translations out of the box:

• Custom .properties files can be added to plugins/velocitynavigator/languages/ with zero recompilation.
• Full hot-reloading with /vn reload.

10. Multi-Engine Storage Architecture

Store player data, sticky sessions, and auth credentials in the storage engine that matches your infrastructure:

• Plain JSON Files: Simple, zero-setup storage for small networks.
• SQLite: Embedded SQL database with zero configuration or external database servers required.
• MySQL & MariaDB: High-performance database storage with HikariCP connection pooling and automatic schema migrations.
• PostgreSQL: Robust enterprise database backend for large network deployments.

11. Quick Start Guide

Get up and running in under five minutes:

1. Download VelocityNavigator-4.6.0.jar and place it into your Velocity proxy's plugins/ directory.
2. Start the proxy once to generate default configuration files, then stop the proxy.
3. Open plugins/velocitynavigator/navigator.toml and list your lobby servers (matching names in velocity.toml):

[routing]
selection_mode = "power_of_two"
balance_initial_join = true
default_lobbies = ["lobby-1", "lobby-2", "lobby-3"]

[routing.fallback]
strategy = "disconnect"
message = "<red>All lobbies are currently full or undergoing maintenance.</red>"

[health]
check_interval_seconds = 5
timeout_millis = 2000
circuit_breaker_threshold = 3
circuit_breaker_reset_seconds = 30

4. Run /vn config validate from the console to verify your configuration.
5. Start the proxy and type /lobby in-game to test routing!

Adding backend features? Copy the exact same JAR into the plugins/ folder of each Paper, Spigot, or Folia backend where you want NPCs, YAML menus, or the Java inventory selector.

12. Command & Permission Reference

Administrative Commands

Player Commands

13. Compatibility Matrix

• Proxy Platforms:
  • Velocity 3.4.x (Java 17+)
  • Velocity 3.5.x (Java 21+)
  • Velocity 4.0.0 (Java 25)
• Backend Platforms (Optional Bridge):
  • Paper 1.16.5 – 26.3+
  • Spigot 1.16.5 – 26.3+
  • Folia 1.20.x – 26.3+
• Ecosystem Integrations:
  • GeyserMC & Floodgate (Native Bedrock forms and Floodgate UUID translation)
  • PlaceholderAPI (Rich backend placeholders)
  • GeoRestrict & MaxMind GeoLite2 (Geographic routing)
  • Prometheus & Grafana (Metrics monitoring)

14. Documentation & Community Support

• Official Website: demonz.org
• Complete Wiki & Documentation: GitHub Wiki Documentation
• Issue Tracker: GitHub Issues
• Discord Community: Join DemonZ Discord

Sponsored by Nexeu Hosting

High-performance, affordable Minecraft hosting with premium NVMe hardware, DDoS protection, and 24/7 technical support.