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.

---

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 the 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 64 GB dedicated node than an 8 GB 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 redistributing only a fraction of keys when servers are added or removed.
• Latency-Aware Ping Routing (latency / ping): Actively evaluates round-trip pings to each backend and assigns incoming players to the lowest-latency, responsive node.
• Least Connections (least_connections): Tracks active concurrent connection workflows to prevent saturated servers from receiving connection spikes during peak join rushes.
• 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 is 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, and 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:

• 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 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 1.21.x 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. Enterprise Security & Authentication Engine

Protect your proxy network with modern defensive security:

• Argon2id Password Hashing: State-of-the-art password security with configurable memory cost, iterations, and parallelism. Includes seamless, backward-compatible verification for legacy SHA-256 databases.
• Brute-Force Rate Limiting: Built-in login attempt tracking and temporary IP lockouts stop password guessing before it impacts network performance.
• 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: Secure session persistence remembers authenticated players across quick reconnects or proxy transfers 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:

Language	Code	Language	Code	Language	Code
English	en	Spanish	es	German	de
French	fr	Russian	ru	Portuguese (BR)	pt_br
Chinese (Simp.)	zh_cn	Japanese	ja	Korean	ko
Italian	it	Dutch	nl	Polish	pl
Turkish	tr	Arabic	ar	Hindi	hi

• 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.5.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

1. Run /vn config validate from the console to verify your configuration.
2. 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

Command	Permission	Description
/vn health	velocitynavigator.admin	Consolidated proxy diagnostics and circuit health overview
/vn servers	velocitynavigator.admin	Paginated table of server health, capacity, drain, and circuits
/vn debug player <player>	velocitynavigator.admin	Live trace explaining routing decisions for a specific player
/vn drain <server>	velocitynavigator.admin	Toggle drain mode to safely evacuate backends without kicks
/vn maintenance [server] [on/off]	velocitynavigator.admin	Toggle network-wide or per-server maintenance mode
/vn affinity clean	velocitynavigator.admin	Manually purge expired sticky session mappings
/vn bridge status	velocitynavigator.admin	Display detected Paper/Folia backend bridge connections
/vn config validate	velocitynavigator.admin	Audit configuration files for syntax or typo errors
/vn menu validate	velocitynavigator.admin	Validate custom menu items, slots, and materials
/vn reload	velocitynavigator.admin	Hot-reload all configurations, menus, and language packs

Player Commands

Command	Permission	Description
/lobby or /hub	none (configurable)	Route the player to the best available healthy lobby
/menu	none (configurable)	Open the interactive server selector
/party	none (configurable)	Access the cross-server party management system

---

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 – 1.21.x+
  • Spigot 1.16.5 – 1.21.x+
  • Folia 1.20.x – 1.21.x+
• 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 the DemonZ Discord

---

Sponsored by Nexeu Hosting

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