VelocityNavigator

VelocityNavigator v4.1 is a production-grade Velocity proxy plugin that delivers 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.

What's New in v4.1

• Bedrock/Geyser Support — Seamless Bedrock player routing with Floodgate UUID mapping and format stripping
• /vn servers Dashboard — Paginated diagnostics with CB, drain, and capacity status per lobby
• Legacy Color Code Converter — Auto-detects and converts &/§ codes to MiniMessage in auto/legacy/minimessage modes
• Levenshtein Config Validation — Typo auto-correction with suggestions for all TOML enum keys
• Self-Documenting Config — Every TOML key gets rich comments + wiki anchors on write/migration
• First-Run Welcome & Upgrades Digest — Console dashboard on fresh install, release notes on upgrades
• Periodic Update Checker — Scheduled checks with exponential 429 backoff (up to 4 hours)
• Empty Lobby Fallbacks — Configurable disconnect or fallback_server strategy
• Permission Default Change — /lobby defaults to "none" for immediate out-of-the-box use

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, configurable via [routing.affinity]
• Server Drain Mode — Gracefully empty servers for maintenance with /vn drain
• Connection Retry & Fallback Chain — Configurable retry with priority-based fallback groups
• 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 placed into the best lobby the moment they join the network, before authentication even completes.
• 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–5× 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

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

Quick Config Example

# VelocityNavigator v4.1.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 (not Bukkit/Spigot/Paper backends)
• Velocity: 3.x
• Java: 17+

⚡ Sponsored by Nexeu Hosting

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

• GitHub Repository: View Source
• Quick Start Guide: Read Here
• Configuration Guide: Read Here
• Routing Algorithms: Read Here
• Algorithm Visualizations: Read Here
• Contextual Routing Guide: Read Here
• Circuit Breaker: Read Here
• Initial Join Balancing: Read Here
• Operations Runbook: Read Here
• Troubleshooting Guide: Read Here
• FAQ: Read Here
• Migration Guide (v3 to v4): Read Here

Telemetry

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