VelocityNavigator

Added

- Added Halloween easter egg.

Fixed

- Enforce authentication on every proxy backend transfer, including requests initiated by other commands or plugins. Pending players can enter only the configured holding server; an unavailable authentication service blocks admission. - Preserve account login failures and lockouts across disconnects. Successful authentication and expiry still clear them. - Read the [settings] layout emitted by the authentication file writer and shown in the setup guide. Authentication enablement, hashing, holding-server selection, and session settings now override main-file values correctly; legacy [auth] and flat layouts remain supported. - Keep repeated Redis circuit snapshots from restarting cooldowns or resetting half-open probes. Transition timestamps reject stale state after recovery, including transitions within the same clock millisecond. - Include contextual fallback-chain lobbies in health inspection so routing can select healthy static backups. - Verify legacy SHA-256 credentials with their original algorithm and upgrade them to Argon2id after a successful login when Argon2id is configured.

Improved

- Verify Argon2id records using their encoded version and cost parameters, with limits on memory, iterations, parallelism, salt length, and hash length. Reject malformed credential records without opening a session. - Preserve the existing Redis circuit state fields for older peers and add transition timestamps for upgraded peers. - Correct descriptions of hashing costs, account lockouts, proxy-local sessions, and the player-load scoring used by least_connections.

[4.5.1] - 2026-09-18

Small patch release fixing server routing for backend NPCs and menus, plus compatibility updates for Paper 26.3+.

Fixed

- NPC & Menu Routing: Resolved an issue where clicking a backend NPC or YAML menu targeting a server (like server:survival) failed with “Selection unavailable” if that server wasn't listed in default_lobbies. You can now route players directly to any server registered in Velocity's velocity.toml from backend NPCs and menus. - Documentation: Fixed a typo in the command reference tables where /lobby menu was incorrectly listed as /menu.

Added / Improved

- Paper & Folia 26.3+ Compatibility: Updated internal packet handling (NPC entity spawning, head rotation packets, and Netty channel interception) to support Paper, Spigot, and Folia 26.3+ runtimes.

VelocityNavigator v4.5.0

VelocityNavigator v4.5.0 is our most comprehensive release to date, introducing a unified universal JAR architecture, a zero-dependency packet NPC engine, global GeoIP distance routing, dynamic MOTD rotations, cross-server party synchronization, expanded PlaceholderAPI support, Argon2id authentication, multi-engine storage, and native Folia support.

New: Universal Single-JAR Architecture

• Dual-Descriptor Deployment: VelocityNavigator now compiles as a single universal fat JAR containing both velocity-plugin.json for Velocity and plugin.yml for Paper, Spigot, and Folia backends. • Automatic Runtime Adaptation: When installed on Velocity, the JAR boots the proxy routing core. When installed on Paper, Spigot, or Folia, it automatically loads backend NPCs, YAML menus, and PlaceholderAPI integrations. • Zero Version Desyncs: Internal bridge protocol packets through MenuBridgeProtocol and Redis payload serializers remain binary-compatible across the entire network. • Multi-Platform Support: Formally tested with Velocity 3.4.x, 3.5.x, and Velocity 4.0.0 running on Java 17, 21, and 25.

New: Native Packet-Level NPC Server Selectors

A completely new in-game NPC server selector engine has been added directly into the backend bridge with zero external dependencies. • Real Player-Model NPCs on 1.20.5+: Spawns genuine player models using direct packet transmission on Paper, Spigot, and Folia 1.20.5 through 1.21.x. • Supports Mojang skins, full-size interaction hitboxes, held items, and smooth head rotation. • No Citizens, ProtocolLib, or version-locked NMS dependency is required. • Billboarded TextDisplay Holograms: Multi-line floating labels automatically face nearby players for cleaner visibility from every direction. • Scoreboard Team Glowing: NPC glow colors can be configured through /vnavnpc glow <id> <on|off> [color] without interfering with existing player scoreboard teams. • Packet-Level Netty Click Interception: Direct Netty handlers detect interactions with fake players while enforcing a configurable 6-block interaction range. • Smart Click Actions & Conditional Routing: NPCs can connect players to servers, open custom menus, run commands, or execute permission-based routing. • Example: action:cond(perm=velocitynavigator.vip?server:vip-lobby|server:lobby) • Dynamic Proximity Head Tracking: NPCs smoothly rotate toward the nearest player within 64 blocks. • Paper 26.2 Mannequin & Folia Safety: Native support has been added for Paper mannequin entities and Folia's regionized scheduler system. • Automatic Legacy Fallback: Servers older than 1.20.5 automatically fall back to optimized armor-stand mannequins with Interaction hitboxes. • Full In-Game Management: /vnavnpc now supports create, action, skin, glow, hand, offhand, status, respawn, tp, remove, list, and reload.

New: GeoIP Distance Routing Engine

VelocityNavigator can now route players to geographically closer lobby clusters using physical distance calculations. • Geo-Distance Mode (`geo_distance`): Uses the Haversine formula to calculate Great-Circle distance between a player location and configured datacenter coordinates. • Multiple GeoIP Providers: Native support for MaxMind GeoLite2 databases, ip-api.com, and GeoRestrict integration. • VPN & ASN Detection: GeoRestrict can act as a primary lookup source for VPN, proxy, and autonomous system detection. • Country & Continent Affinity Overrides: Specific countries or continents can be mapped directly to selected lobby pools. • Thread-Safe Subnet Matching: High-performance in-memory IP caching and CIDR subnet matching provide fast routing decisions without blocking the main thread. • Initial Join Affinity: Regional routing is applied immediately during the first connection handshake as well as through /lobby.

New: Dynamic MOTD System

A standalone server-list MOTD engine has been added through motd.toml. • Dynamic MOTD Rotation: Supports ROTATING, RANDOM, and SEQUENTIAL display modes. • Readable TOML Formatting: MOTDs can use clean multiline TOML strings while preserving comments and configuration structure. • Maintenance Overrides: Dedicated maintenance MOTDs automatically replace standard MOTDs when global maintenance is enabled. • MiniMessage Styling: Supports gradients, hex colors, font tags, and legacy color code translation. • Real-Time Placeholders: Available placeholders include {online}, {max}, {maintenance_reason}, and {version}. • Live Administration: MOTDs can be managed using /vn motd reload, /vn motd list, /vn motd add, /vn motd remove, and /vn motd setmode.

New: Authentication & Defensive Security

The authentication system has been substantially expanded with stronger hashing, quarantine handling, and native Java and Bedrock interfaces. • Argon2id Password Hashing: Powered by BouncyCastle with configurable memory cost, iterations, and parallelism. • Legacy SHA-256 Support: Existing password databases can still authenticate users and automatically upgrade stored credentials. • Interactive Sign GUI for Java: Java players can enter passwords privately through an in-game sign interface instead of public chat. • Native Floodgate Forms: Bedrock players receive modal login and registration forms through Floodgate. • Holding Lobby Quarantine: Unauthenticated players can be restricted to a holding server with movement, interaction, building, item usage, and chat locked until authentication succeeds. • Brute-Force Protection: Global and per-account limits trigger a five-minute lockout after repeated failed attempts. • Bridge-Authenticated Sign Sessions: Authentication submissions pass through validated internal bridge sessions to prevent spoofing. • Reload-Persistent Sessions: Active authentication sessions survive proxy reloads without forcing connected users to log in again.

New: Cross-Server Party & Team Engine

VelocityNavigator now includes complete proxy-wide party management with Java and Bedrock interfaces. • Party Roles: Supports LEADER, OFFICER, and MEMBER. • Promotion & Demotion: Players can be promoted or demoted through /party promote and /party demote. • Custom Party Names: Party names support MiniMessage formatting and colors. • Leader Follow: Members can automatically follow the party leader during server transfers. • Public & Private Parties: Parties can be opened or closed using /party open and /party close. • Dual Platform GUIs: Bedrock players receive native Cumulus forms while Java players receive inventory-based menus.

PlaceholderAPI Support

• %velocitynavigator_party_in_party% • %velocitynavigator_party_name% • %velocitynavigator_party_leader% • %velocitynavigator_party_size% • %velocitynavigator_party_max_size% • %velocitynavigator_party_is_leader% • %velocitynavigator_party_role% • %velocitynavigator_party_is_open% • %velocitynavigator_party_members% • %velocitynavigator_ping% • %velocitynavigator_lobby% • EssentialsX integration placeholders are also supported.

New: Custom Backend Menu System

VelocityNavigator now includes fully customizable YAML-based menus for Paper and Spigot servers. • Create unlimited menus inside menus/*.yml • Configure slots, materials, CustomModelData, skull owners, and sounds • Link menus together using nested menu actions such as menu:games • Execute proxy or backend commands directly from menu items • Route players to individual servers or lobby clusters • Use live refresh through @refresh:N • Use pagination through @page:N • Disable unavailable items with @disabled • Default main, games, and lobbies menus are generated automatically • /vnavmenu includes open, add, remove, title, rows

[4.4.0] - 2026-07-20

Added

- Added verified Velocity 4.0.0 support while retaining the Java 17 bytecode and Velocity 3.4 API baseline used by Velocity 3.4.x and 3.5.x installations. A Java 25/API 4/Adventure 5 compatibility build and a Velocity 4.0.0 startup smoke test now guard the same JAR in CI. - Added optional per-server display_name values in gui.toml. A name such as lobby1 in velocity.toml can now appear as Main Lobby 1 in the Java inventory, Java chat selector, and Bedrock form. - Added optional per-server description, menu_order, and show_in_menu values. Descriptions are available through {description}, explicit menu order is shared by all selectors, and hidden entries remain eligible for automatic routing. - Added selector placeholders for presentation and diagnostics: {server} and {display_name} resolve to the configured alias, {server_id} exposes the raw Velocity server ID, and {description} resolves to the shared menu description. - Added /vn menu validate to audit selector server IDs, duplicate display names, slots, material-identifier syntax, and curly-brace placeholders before players open a menu. - Added global Java inventory styles for [states.full], [states.draining], [states.offline], and [states.in_game], each with optional material, name, and lore overrides.

Changed

- Inventory navigation controls are now kept in the reserved bottom row for every supported layout.rows value. This prevents an automatic server item from occupying a custom control slot and silently hiding that control. - Bedrock sort_mode = "name" now sorts by the displayed alias instead of the raw server ID. - Explicit nonnegative menu_order values are the primary order in Java inventory, Java chat, and Bedrock selectors. Unset values keep the existing candidate order; Bedrock uses its configured sort_mode to resolve equal ordering values. - show_in_menu = false removes a server from all three selectors without draining it or removing it from automatic routing. - Blank or missing aliases fall back to the raw server ID. Selector changes are applied by /vn reload; no proxy restart or navigator.toml schema migration is required. - Display aliases are presentation-only. Inventory targets, one-time token allowlists, chat callbacks, Bedrock response mapping, health lookups, and connection requests continue to use the raw registered server ID. - Java inventory state styles are applied after availability is resolved. A per-server name or lore remains final; otherwise the matching state template is used before the localized default. For unavailable entries, a per-server unavailable_material remains final, followed by the state material and global unavailable fallback. Healthy entries keep their per-server/global normal material. - gui.toml now uses config_version = 2; navigator.toml remains at config version 8.

Not included

- Localized per-language display names are not part of 4.4.0. Existing language packs still control shared selector templates and status text. ---

[4.3.0] - 2026-07-14

Advanced proxy systems

- Added native parties with /party invite, accept, deny, kick, leave, and disband, private /p chat, and leader-follow synchronization on ServerConnectedEvent. - Added a virtual lobby-capacity queue with action-bar position updates, asynchronous slot polling, automatic connection, /queue leave, and optional initial-join holding_server support. - Added a dependency-free Redis RESP client for vn:servers:register dynamic registration and cross-proxy circuit-breaker, health-cache, backend-state, and affinity synchronization. - Added backend MOTD lifecycle parsing for markers such as [STATE:IN_GAME]; routing only uses configured allowed states. - Geographic-routing integrations and BungeeCord/Waterfall compatibility remain deferred and are not part of v4.3.0. - Added optional server management: /vn server add game writes only to velocity.toml, while /vn server add lobby also persists lobby metadata in servers.toml and activates it immediately without reload. - Added /vn server remove and /vn server list, overwrite protection, custom Velocity-config paths, IPv4/hostname/IPv6 parsing, and atomic configuration writes. - Expanded gui.toml Bedrock controls with enable/fallback switches, sorting, button limits, visibility toggles, and title/content/button overrides with color conversion. - Added backend config.yml switches for the bridge, inventory channel, handshake, refresh, delay, title length, and fallback material.

Added

- Configurable language packs — explicit en, ru, es, fr, de, pt_br, and zh_cn selection plus arbitrary custom codes. Built-in changes rewrite active text; player locale is never auto-detected. - Separate `gui.toml` — rows, materials, fillers, refresh interval, navigation slots, and per-server fixed slot/material/name/lore overrides. - Universal Java inventory selector — the same 4.3.0 JAR runs in Velocity proxy or Paper/Spigot bridge mode and announces its mode at startup. - Pagination, live refresh, and unavailable indicators for Java inventory menus. - /vn bridge status reports detected backend bridge versions and last-seen times. - Universal bridge integration tests cover proxy-open, backend-click, navigation, handshake, and proxy-selection flows. - Exponential backoff with jitter for connection retries — each retry waits progressively longer with a small random jitter to avoid thundering-herd reconnects. - Player affinity persistence — unexpired sticky-session mappings are now saved to disk and restored across proxy restarts. - /vn health command — consolidated one-shot diagnostics: routing mode, lobby count, circuit-breaker states, drained servers, cache sizes, and affinity entry count in a single screen. - HTML operations dashboard — a separate HTTP server on its own port serving a live lobby table, routing distribution chart, affinity map, config summary, recent routing events, and joins/leaves-since-start counters. Disabled by default and authenticated via a bearer-token login flow. - velocity-plugin.json descriptor — modern Velocity plugin metadata alongside the existing @Plugin annotation. - New reproducible marketplace brand system with a plugin icon, hero banner, social card, nine feature panels, platform-specific listing copy, meaningful alt text, and a visual feature overview in the wiki. - Built the backend bridge against the Spigot API 1.16.5 baseline without version-specific NMS.

Changed

- Dashboard documentation now distinguishes the universal 127.0.0.1 loopback example from provider addresses and explains allocated ports, container binds, and browser URLs. - The official wiki URL is now built in. startup.wiki_url is no longer written or accepted as a custom documentation target, and legacy entries are removed during configuration normalization. - Language documentation now explains structural test coverage, custom packs, and how native speakers can contribute new or improved translations. - routing.use_menu_for_lobby replaces use_chat_menu_for_lobby; the old key remains a compatible alias. - Selector mode/fallback lives in navigator.toml, language in messages.toml, GUI presentation in gui.toml, and managed lobby metadata in servers.toml. The plugin/config versions are 4.3.0/v8. - MiniMessage, classic &/§, &#RRGGBB, and Bungee-style hex colors are accepted in configurable text. - Server health cache keys are now normalized to lowercase. Mixed-case server names no longer produce duplicate cache entries. - Consistent hash ring uses a thread-local MessageDigest instead of allocating one per lookup. Throughput on consistent_hash mode improves by roughly 3–4× under load. - RoutePlanner now builds a Map<String, LobbyEntry> once per planning call instead of scanning the lobby list linearly per candidate. - Config reload now uses a dedicated ReentrantLock instead of synchronized(this). Admin commands and event subscribers no longer contend on the same monitor during a reload. - Bedrock form text stripping now matches legacy color codes case-insensitively. &C and &L are now stripped alongside &c and &l. - Update checks are now silent by default — no startup log line, no periodic console message. /vn updatecheck still works for manual checks. Set update_checker.silent = false in navigator.toml to restore the old behavior. - Config version bumped to 8. Adds the final 4.3.0 advanced-system, managed-server, selector, dashboard, and Redis settings. Older configs are auto-migrated and backed up; network-facing systems remain disabled by default.

Fixed

- Party commands now expose explicit /party status and /party chat <message> paths, while /p <message> and multiword messages use Velocity raw-command parsing. - Escaped MiniMessage entities such as <player> are no longer mistaken for the legacy &l bold color code. - Dashboard API version data now comes from the plugin metadata instead of a hardcoded prerelease string. - Redis RESP parsing on the Velocity proxy now enforces line, bulk, array, total-frame, and nesting limits before allocation or recursion. - Backend Redis lifecycle registration now rejects oversized response lines instead of allowing peer-controlled heap growth. - Dashboard bearer credentials are accepted only through the Authorization header. The browser login keeps the token in memory and never places it in URLs or persistent browser storage. - MetricsService.active() and statusLine() are now volatile. Reader threads (Prometheus exporter, /vn status) no longer risk seeing stale values after a config reload. - PrometheusExporter.start() now clears the server reference if start() throws. Previously the next stop() call would operate on an unstarted server. - UpdateChecker now uses the non-deprecated JsonParser.parseString(...) and the nextAllowedCheck read-modify-write is guarded by a synchronized block to prevent duplicate 429 retries under concurrency. - ConfigManager's generated navigator.toml header box no longer overflows on the bStats URL line. - Empty if branch in applyLoadedConfiguration removed — round-robin reset logic is now a single positive check.

Added

- Embedded Prometheus Exporter & Admin Panel — Built-in HTTP server exposing real-time metrics (/metrics) on routing distributions, pings, CB statuses, and connection events. - Grafana Dashboard Setup Command — /vn setup grafana auto-generates a premium, pre-configured Grafana telemetry dashboard configuration JSON file. - Interactive Selector Menus — Native Bedrock Form GUI (via Geyser/Floodgate integration) and clickable Java Chat Selector Menu with hover tooltips displaying health and latencies. - Ping-Based Routing Strategy (`latency`) — Dynamically select the server with the lowest ping latency to optimize player connections.

Fixed

- Hardened Java and Bedrock lobby menu selections so stale or manually forged choices cannot bypass drain mode, circuit breakers, capacity checks, or configured lobby pools. - Started the Prometheus exporter during initial proxy boot when enabled, not only after /vn reload. - Restored true consecutive-failure behavior for the circuit breaker. - Preserved update notification settings during config rewrites and aligned admin join notifications with [update_checker].notify_admins. - Accepted the documented latency routing mode in config validation and migration normalization. - Normalized contextual group names consistently so mixed-case mappings continue to route. - Aligned Maven artifact version, Velocity plugin metadata, and user-facing docs for the 4.2.0 release.

Changed

- Config version bumped to 6. The generated navigator.toml has been completely redesigned with section banners, grouped documentation, and a friendlier layout. Existing configs are auto-migrated and backed up.

[4.1.0] — 2026-05-26

Added

- Bedrock/Geyser Player Support — Soft-dependency integration with Geyser and Floodgate. Strips advanced Kyori Component formatting (gradients, hover, click actions) to display beautifully on Bedrock clients, and maps authentic Java UUIDs for player affinity tracking. - First-Run Experience Polish — Beautiful console-printed welcome dashboard on fresh installs. Detects plugin upgrades and showcases a clean release notes changelog digest. - `/vn servers` Diagnostics Command — Elegant paginated status dashboard for all configured lobbies, complete with player count/max capacity limits, circuit breaker state tracking, and drain statuses. - Configurable Dashboard Colors — Customizable status tags/colors for /vn servers supporting full hex, RGB, and MiniMessage styling in navigator.toml. - Typo Auto-Correction & Levenshtein Validation — Dynamic typo detection on config reload/load using Levenshtein distance metrics (e.g., suggesting "least_players" for "leadt_players"). - Self-Documenting Configuration Keys — The entire navigator.toml file comments are dynamically populated on generation/migration, pointing users to the exact section anchor of the official Wiki page. - Automatic Legacy Color Code Converter — Seamlessly matches and converts all 22 standard & and § legacy formatting codes to MiniMessage syntax on load (supports "auto" with one-time warnings, "minimessage", or "legacy" modes). - Periodic Update Checker with Backoff — Recurring scheduled task loop to check for updates with exponential backoff on HTTP 429 errors (scales dynamically up to 4 hours). - Empty Lobby Routing Fallbacks — Customizable degradation strategies ("disconnect" or "fallback_server") when all primary lobby options are offline or circuit-broken. - Permission Default Change — Standardized /lobby default command permission changed to "none" for immediate out-of-the-box adoption. Existing migration preserves existing admin-defined configurations safely.

[4.0.0] — 2026-05-01

Added

- Power of Two selection algorithm (power_of_two) — picks two random candidates, selects the one with fewer players. Near-optimal distribution at O(1) cost. - Weighted Round Robin selection algorithm (weighted_round_robin) — interleaved WRR that distributes traffic proportionally to server weights. - Least Connections selection algorithm (least_connections) — selects the server with the lowest exponential moving average (EMA) of connection load and rate. - Consistent Hash selection algorithm (consistent_hash) — deterministic player-to-server mapping using a consistent hash ring with 150 virtual nodes and SHA-256 hashing. Provides session affinity. - LobbyEntry format — servers can be configured as plain strings or inline tables with max_players and weight fields. Backward compatible with plain strings. - Per-lobby max-player cap — servers at their max_players capacity are automatically excluded from routing. - Circuit Breaker — automatic server failure detection with CLOSED → OPEN → HALF_OPEN state machine. Unhealthy servers are excluded from routing until they recover. - Server Drain Mode — /vn drain <server>, /vn undrain <server>, /vn drain status commands for graceful server maintenance. - Connection Retry with Fallback — automatic retry on connection failure with configurable max_retries. Shows retry message with <attempt>/<max> placeholders. - Per-Group Selection Mode Override — contextual routing groups can specify their own mode, overriding the global selection_mode. - Fallback Priority Chain — ordered fallback groups when a contextual group's servers are all unavailable. - Player Affinity Routing — sticky sessions with configurable stickiness probability (0.0–1.0). Players tend to return to their previous lobby. - Graceful Degradation — when all health checks fail, fall back to a configured degradation mode (default: random) instead of showing "No lobby found". - Geo-Based Routing (experimental) — stub implementation for geo-based lobby routing using MaxMind GeoLite2 Country database. - Routing Metrics API — new NavigatorAPI methods: getRoutingDistribution(), getHealthCheckLatencies(), getCircuitBreakerStatuses(). - Connection Rate Tracking — sliding window (60-second) connection rate tracker used by least_connections mode. - Server Load Tracking — EMA-based server load tracker used by least_connections mode. - Routing Stats — per-server connection counts with 60-second reset, shown in /vn status. - Enhanced /vn status dashboard — now shows circuit breaker status, drained servers, and routing distribution. - `/vn updatecheck` command — manually check for updates (replaces recurring auto-update check). - Startup update notification — one-time update check 5 seconds after proxy start. - Admin join update notification — players with velocitynavigator.admin permission are notified in-game when they join if an update is available. Controlled by notify_admins_on_join config. - `<player>` placeholder — new placeholder available in all message templates. - `<attempt>` and `<max>` placeholders — available in messages.retrying. - `messages.retrying` config — new message template for connection retry notifications. - `notify_on_startup` config — suppress startup update notification. - `notify_admins_on_join` config — enable/disable in-game admin update notification on join. - Health check cache purge — expired cache entries are automatically purged every 60 seconds. - `getCachedOnlineServers()` method — synchronous cached player count access for initial join balancing (replaces blocking .join() call). - Config version field — CURRENT_VERSION set to 4. Auto-migration from v3 configs with .bak backup.

Changed

- Removed `.join()` blocking call in onPlayerChooseInitialServer — replaced with synchronous cache lookup. Falls through to Velocity's built-in try list on cold start. - Round-robin state only resets when lobby topology changes — applyLoadedConfiguration() now compares previous and current lobby lists before resetting. - Contextual groups — changed from Map<String, List<LobbyEntry>> to Map<String, GroupConfig> where GroupConfig contains servers and optional mode. - UpdateChecker — removed recurring schedule; now runs a single check on startup. Removed enabled, notifyConsole, startupDelaySeconds fields. - ConfigManager — reads both plain strings and inline tables for lobby entries (backward compatible). Writes inline tables when max_players or weight is non-default. - MessageFormatter — added player, attempt, max to allowed placeholders. - `noLobbyFound` message — now includes (<reason>) placeholder by default. - `ServerCandidate` record — now includes effectiveWeight and emaLoad fields. - `RouteDecision` — provides ordered candidate list for retry fallback.

Fixed

- Blocking `.join()` in event handler — onPlayerChooseInitialServer no longer blocks the event loop with .join() calls. Uses cached data synchronously instead. - Round-robin reset on every reload — round-robin counter is now only reset when the lobby topology actually changes, preventing unnecessary redistribution on config reload. - Health check cache memory leak — expired cache entries are now purged every 60 seconds. - Permission node inconsistency — velocitynavigator.bypasscooldown now also checks velocitynavigator.bypass.cooldown for consistency.

Deprecated

- `velocitynavigator.bypasscooldown` permission — use velocitynavigator.bypass.cooldown instead. The legacy name still works as a fallback.

Removed

- `update_checker.enabled` config field — the update checker now always runs on startup. - `update_checker.notifyConsole` config field — update notifications are always logged to console. - `update_checker.startupDelaySeconds` config field — startup delay is fixed at 5 seconds. - Recurring update check schedule — replaced by one-time startup check and /vn updatecheck. ---

[3.0.0] — 2026-04-10

New Features

- Initial Join Balancing — Players are now load-balanced the moment they connect to the proxy, not just when they run /lobby. Configurable via balance_initial_join in navigator.toml. - Developer API — Third-party plugins can now hook into VelocityNavigator via NavigatorAPI and NavigatorAPIProvider. Preview routes, inspect server health, and read routing config programmatically. - Three Routing Modes — Choose between least_players, round_robin, and random selection algorithms. - Contextual Routing — Route players to game-specific lobbies (e.g., BedWars lobby) based on which server they are leaving. - Self-Documenting Config — The generated navigator.toml now includes rich inline comments explaining every setting and routing mode, with links to full documentation.

Reliability

- Async Health Checks — Ping candidate lobbies before routing to ensure they are alive. Configurable timeout and caching. - Ping Coalescing — Multiple simultaneous /lobby requests share the same CompletableFuture ping, preventing network storms on high-traffic proxies. - Pre-Execution Cooldown Locking — The anti-spam cooldown is applied before command execution begins, preventing macro-based abuse from bypassing the lock. - Graceful Failover — If all contextual lobbies are offline, the plugin falls back to the default lobby pool instead of showing an error (configurable).

Telemetry & Updates

- bStats Integration — Anonymous usage telemetry via [bStats](https://bstats.org/plugin/velocity/Velocity%20Navigator/2… (plugin ID: 28341). - Modrinth Update Checker — Automatic version checking during startup with configurable release channel (release, beta, alpha).

Admin Tools

- /vn reload — Hot-reload navigator.toml without restarting the proxy. - /vn status — View runtime status (version, routing mode, health checks, bStats, update checker). - /vn version — Check installed vs. latest version. - /vn debug player <name> — Preview the routing decision for a specific player. - /vn debug server <name> — Inspect a server's real-time health snapshot. - Full tab-completion for all admin commands.

Configuration

- Automatic Migration — Seamless migration from v1/v2 configs with backup generation. - Field-Level Validation — Invalid config values are corrected with warnings, never crashes. - MiniMessage Support — All player-facing messages support MiniMessage rich text formatting.

VelocityNavigator v2.0.0-Stable is here!

This is a major milestone release. We have completely refactored the codebase to meet enterprise standards, focusing on stability, speed, and user experience.

What's New?

🔄 Modrinth Native:* The update checker now queries the Modrinth API directly. 🛡️ Crash-Proof Config:* We added strict type-safety checks. A typo in your config file will no longer crash the plugin. ⚡ Smart Timeouts: Server pings now timeout after 2.5 seconds*, preventing a single laggy server from freezing your command usage. 📢 Better Feedback:* Players now receive specific error messages (e.g., "Server Full", "Whitelisted") instead of the command just doing nothing. 🐛 Bug Squashing:* Fixed constructor initialization errors and improved debug logging.

How to Update

1. Stop your proxy. 2. Delete your old VelocityNavigator.jar. 3. Upload the new v2.0.0-Stable JAR. 4. (Recommended) Backup and delete your old navigator.toml to let the new crash-proof version generate. 5. Start the proxy!

Highly Customizable Config:

The plugin now uses a more organized, nested navigator.toml file with a custom header.

Automatic Config Updater:

The plugin will automatically detect and upgrade old configuration files to the new format, preserving user settings.

Optional Command Aliases:

Server owners can now define which command aliases (like /hub or /spawn) they want to use in the config file.

Reconnect to Spawn:

If a player uses a lobby command while already in a lobby, they are now re-connected to that lobby's spawn instead of just seeing a message. For the next update, you can focus on the suggestions we just discussed: - Permission Support. - Fully Customizable Messages. - Smart Server Selection.

Hey everyone, here's the first release of VelocityNavigator! This is a simple plugin that lets you use / lobby, /hub, or /spawn to send players to your lobby server. You can even set up multiple lobbies in the config for it to choose from!