?
Host a server
Modrinth App
Sign in
ModsPluginsData PacksShadersResource PacksModpacksServers
Settings
VelocityNavigator

VelocityNavigator

A production-grade Velocity proxy plugin that introduces absolute traffic control over your network through intelligent load balancing, circuit breaker resilience, Bedrock/Geyser support, and a highly context-aware /lobby system.

404
15
404
15

Compatibility

Minecraft: Java Edition

26.1.x
1.21.x
1.20.x

Platforms

Links

Report issues View source Join Discord server

Tags

Creators

Details

Licensed Apache-2.0
Published 9 months ago

VelocityNavigator Banner

[!IMPORTANT] Velocity-Only Proxy Plugin: VelocityNavigator runs exclusively on your Velocity proxy server (3.x). It will not load or function if installed on Bukkit, Spigot, Paper, Purpur, or Folia backend servers. Install the JAR on your Velocity proxy's plugins folder, not your backend servers.

VelocityNavigator v4.2 is a production-grade Velocity proxy plugin that introduces absolute traffic control over your network through intelligent load balancing, circuit breaker resilience, Bedrock/Geyser support, and a highly context-aware /lobby system.

No more funneling all new players into a single hub. No more sending players to offline servers. No more guessing which lobby they ended up on.

Detailed algorithm charts and visualizations can be found in the wiki/Routing-Algorithms.

What's New in v4.2

  • Hardened Security & Menu Selections โ€” Stale or forged lobby menu selections cannot bypass drain mode, capacity checks, or circuit breakers anymore.
  • Prometheus Boot Integration โ€” Exporter starts immediately during initial proxy boot when enabled.
  • Circuit Breaker Accuracy โ€” Restored true consecutive-failure tracking behavior for the breaker.
  • Redesigned Configuration (v6) โ€” The navigator.toml file has been completely redesigned with clean section banners and grouped documentation.
  • Unified Notifications โ€” Aligned admin join notifications with the global [update_checker].notify_admins configuration and preserved during config writes.
  • Improved Validation & Normalization โ€” Support for latency routing mode and mixed-case contextual group name matching.

v4.1 Features Included

  • Bedrock/Geyser Form GUI Support โ€” Seamless routing with Floodgate UUID mapping and format stripping. Bedrock players can use a native, interactive Form GUI (popup menu) to select their lobby. This GUI is highly configurable (supports custom titles, body text, and button formats) and can be toggled on/off using the use_gui_for_lobby setting.

    Bedrock Selector

  • /vn servers Dashboard โ€” Paginated diagnostics with CB, drain, and capacity status per lobby.

  • Legacy Color Code Converter โ€” Auto-detects and converts legacy color codes to MiniMessage syntax.

  • Levenshtein Config Validation โ€” Distance-based typo suggestions for TOML settings.

  • Self-Documenting Config โ€” Automatically populates TOML comments with direct wiki links.

  • First-Run Welcome & Upgrades โ€” Custom welcome message on fresh install and changelog summary on upgrades.

v4.0 Features Included

  • 7 Selection Algorithms โ€” least_players, random, round_robin, power_of_two (recommended), weighted_round_robin, least_connections, consistent_hash
  • Circuit Breaker โ€” Automatic failure detection with CLOSED โ†’ OPEN โ†’ HALF_OPEN state machine
  • Player Affinity โ€” Sticky sessions so players return to their previous lobby
  • Server Drain Mode โ€” Gracefully empty servers for maintenance with /vn drain
  • Connection Retry & Fallback Chain โ€” Configurable retry with priority-based fallback
  • Admin Update Notifications โ€” Automatic check on proxy start + admin join alerts
  • Per-Group Mode Override โ€” Different routing algorithms per contextual group

Why VelocityNavigator?

For Players

  • /lobby just works โ€” fast, reliable, with clear feedback messages.
  • Always routes to a healthy, reachable server.
  • Automatically places them into the best lobby immediately upon joining the network before they even finish authentication.
  • Sticky sessions mean players rejoin the lobby they were last on.

For Admins

  • Initial Join Balancing โ€” Bypasses Velocity's default static fallback engine to perfectly split initial proxy connection waves.
  • 7 routing algorithms โ€” From simple random to advanced power_of_two with 3-5x better tail latency.
  • Circuit Breaker โ€” Automatically stops routing to failing servers before players notice.
  • Server Drain Mode โ€” Safely empty lobbies for maintenance without kicking players.
  • Contextual lobby groups โ€” Different game servers can point to different lobby pools with automatic fallback loops.
  • Real-time health checks โ€” Async pings with configurable timeout, TTL caching, and ping coalescing to prevent backend storms.
  • Connection retry โ€” Automatically retries on connection failure with configurable fallback chain.
  • Anti-spam protection โ€” Pre-execution cooldown locks block macro abuse before the routing engine even fires.
  • Update notifications โ€” Checks for updates on startup and notifies admins when they join.

How Routing Works

Player runs /lobby
    โ†“
Player affinity check (return to previous lobby if sticky)
    โ†“
Contextual group resolution (if enabled)
    โ†“
Fallback to default lobbies (if contextual group is empty/offline)
    โ†“
Cycle pruning (remove current server if alternatives exist)
    โ†“
Drain filter (skip servers in drain mode)
    โ†“
Circuit breaker check (skip OPEN/circuit-tripped servers)
    โ†“
Async health checks (with TTL cache + ping coalescing)
    โ†“
Selection strategy (7 algorithms available)
    โ†“
Connection attempt with retry + fallback chain
    โ†“
Player is connected to the best available lobby

All server name matching is case-insensitive โ€” Lobby-1 and lobby-1 are treated identically.

Commands & Diagnostics

Command Permission Description
/lobby velocitynavigator.use Send to best available lobby
/vn reload velocitynavigator.admin Reload config live
/vn status velocitynavigator.admin Runtime status dashboard
/vn debug player <name> velocitynavigator.admin Preview routing for a player
/vn debug server <name> velocitynavigator.admin Inspect server health snapshot
/vn drain <server> velocitynavigator.admin Drain a server for maintenance
/vn undrain <server> velocitynavigator.admin Remove drain mode from a server
/vn drain status velocitynavigator.admin View all drained servers
/vn updatecheck velocitynavigator.admin Check for plugin updates
/vn servers velocitynavigator.admin Show paginated lobby server status dashboard
/vn version velocitynavigator.admin Display installed version

Quick Installation

  1. Install Velocity 3.x on your proxy server.
  2. Place the VelocityNavigator JAR into your proxy's plugins/ directory.
  3. Start the proxy once to auto-generate a highly-commented configuration file (navigator.toml).
  4. Edit plugins/velocitynavigator/navigator.toml to define your lobby servers and preferred routing strategies.
  5. Run /vn reload or restart your proxy to apply the configuration.

Permissions

Permission Default Description
velocitynavigator.use none* Allows players to use the primary /lobby command (and aliases like /hub). Default changed to "none" in v4.1.0.
velocitynavigator.admin false Access to all administrative diagnostic and maintenance commands (/vn).
velocitynavigator.bypass.cooldown false Bypasses the configured lobby command anti-spam cooldown timer.
velocitynavigator.bypasscooldown false Legacy alias for bypassing the lobby command cooldown timer.

Quick Config Example

# VelocityNavigator v4.2.0 Configuration

notify_on_startup = true
notify_admins_on_join = true

[commands]
primary = "lobby"
aliases = ["hub", "spawn"]
permission = "none"
admin_aliases = ["velocitynavigator", "vn"]
cooldown_seconds = 3
reconnect_if_same_server = false

[routing]
selection_mode = "power_of_two"
cycle_when_possible = true
balance_initial_join = true
max_retries = 2

default_lobbies = [
  { server = "lobby-1", max_players = 100, weight = 3 },
  { server = "lobby-2", max_players = 100, weight = 2 },
  { server = "lobby-3", max_players = 50, weight = 1 },
]

[routing.affinity]
enabled = true
stickiness = 0.7

[circuit_breaker]
enabled = true
failure_threshold = 3
cooldown_seconds = 30
half_open_max_tests = 1

[health_checks]
enabled = true
timeout_ms = 2500
cache_seconds = 60

[update_checker]
channel = "release"

[bedrock]
enabled = false
auto_detect = true
strip_advanced_formatting = true
affinity_use_java_uuid = true

[lobby]
no_server_strategy = "disconnect"
no_server_message = "<red>No lobby servers are currently available. Please try again later.</red>"
fallback_server = ""

Compatibility

  • Platform: Velocity only
  • Velocity: 3.x
  • Java: 17+

โšก Sponsored by Nexeu Hosting

nexeu-sponsor

Looking for high-performance, reliable, and affordable hosting for your Minecraft server proxy? Check out Nexeu Hosting! Premium hardware, instant setup, and 24/7 support.

๐Ÿ‘‰ Get Premium Hosting at nexeu.zip

Documentation & Links

Telemetry

bStats

VelocityNavigator Icon
Built with care by DemonZ Development
Premium Minecraft infrastructure, engineered for scale.