ВЕРСИИ (13)

### Added - Native Java dialogs for lobby selectors, party management, authentication, and backend YAML menus, including NPC menu entry points. New configurations select dialogs on supported clients and Paper backends, with inventory, sign, and chat or command fallbacks. - Configurable Java UI modes per feature and per YAML menu. Existing selector choices survive migration; Bedrock forms retain their existing behavior. - Expiring, single-use dialog actions bound to the player and backend, private authentication input forwarding, and visible-password warnings. - Cross-proxy language propagation across the UI bridge protocol, dynamically synchronizing proxy player locales to backend native Java dialogs and chest menus without requiring duplicate backend localization configuration. - Dynamic multi-language localization for native Java dialog controls (`Previous`, `Next`, `Refresh`, `Close`) supporting all 15 built-in locales and custom language packs. - Inline `{lang:key}` placeholder token resolution in backend custom menu YAML configuration for titles, item display names, and lore lines. - Configurable empty slot filler decoration (`fill_empty_slots` and `filler_material`) for backend chest menus. - Tests for UI protocol validation, callback/session binding, configuration migration, and pagination independent of chest dimensions; an optional Paper runtime dialog probe. ### Fixed - Reopening an authentication prompt no longer resets the authentication deadline.

### 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`, `list`, and `reload` ## New: Multi-Engine Database Storage Player affinity, authentication sessions, credentials, and other persistent data can now use multiple storage engines. • **SQLite**: Zero-configuration embedded storage with bundled drivers. • **MySQL & MariaDB**: High-throughput SQL storage backed by HikariCP connection pooling. • **PostgreSQL**: Designed for larger and multi-proxy network deployments. • **JSON Storage**: Lightweight file-based storage for smaller servers. • **Automatic Schema Migration**: Database tables and column upgrades are automatically applied during startup. ## New: Native Folia Support Full compatibility has been added for Folia's regionized multi-threading model. • Runtime Folia detection through MethodHandle reflection • Backend tasks use entity-owned region schedulers where required • Standard Bukkit scheduling is retained for Paper and Spigot • `plugin.yml` now declares `folia-supported: true` ## New: Maintenance & Graceful Evacuation Servers can now be taken offline without abruptly disconnecting active players. • Network-wide or individual server maintenance states • Safe evacuation to healthy destination servers • Maintenance restrictions apply to both Navigator routing and direct backend transfers • Custom kick messages and dynamic countdown badges ## New: Backend Update Checker Paper and Spigot backends now include their own update checker. • Periodic Modrinth API checks • Exponential backoff when HTTP 429 rate limits occur • Configurable interval through `update_check_interval_minutes` ## New: Version Mismatch Detection The proxy can now actively detect mismatched backend plugin versions. • Backend versions are compared during bridge HELLO handshakes • `/vn bridge` displays backend compatibility states: `✓ Up to date` `⚠ Outdated` `✗ Not detected` ## New: Backend bStats Telemetry Dedicated bStats support has been added for Paper and Spigot backends under plugin ID `32887`. Available charts include: • `folia_enabled` • `server_software` • `inventory_menu_enabled` • `handshake_enabled` • `refresh_enabled` • `redis_registration_enabled` ## New: Modular Configuration Architecture Configuration has been reorganized into cleaner dedicated files. • `storage.toml` • `geo.toml` • `auth.toml` • `motd.toml` • **Config Version 9** with automatic migration from v8 • All backups are stored in a dedicated `backups/` folder • Old backups are automatically pruned • Backend `config.yml` automatically migrates from version 1 to version 2 ## New: Administrative & Diagnostic Commands • `/vnavnpc` Manage NPC creation, actions, skins, glow, equipment, status, respawning, teleportation, removal, listing, and reloads. • `/vnavmenu` Manage custom backend menus. • `/vn config validate` Validates `navigator.toml` and the server registry while providing typo suggestions. • `/vn server dry-run` Tests server registration without writing changes to disk. • `/vn affinity clean` Removes expired sticky-session entries. • `/vn debug player <player>` Displays a live routing trace explaining why a player was sent to a specific server. ## Updated: Multi-Proxy Synchronization Multi-proxy synchronization has been expanded from v4.3. • HMAC-SHA256 verification for registration payloads • Timestamp freshness validation against replay attacks • Signature deduplication inside the freshness window • Host allowlisting with wildcard support ## Updated: NavigatorAPI The public developer API has been expanded. Developers can now access: • `pluginVersion()` • `server()` • `logger()` • `dataDirectory()` • `config()` • `bedrockHandler()` Casting `NavigatorAPIProvider.get()` to internal implementation classes is no longer required. ## Updated: Language Support VelocityNavigator now includes 15 bundled languages. • `en` • English • Updated • `ru` • Russian • Updated • `es` • Spanish • Updated • `fr` • French • Updated • `de` • German • Updated • `pt_br` • Brazilian Portuguese • Updated • `zh_cn` • Simplified Chinese • Updated • `ja` • Japanese • New • `it` • Italian • New • `ko` • Korean • New • `nl` • Dutch • New • `pl` • Polish • New • `tr` • Turkish • New • `ar` • Arabic • New • `hi` • Hindi • New ## Fixed • **Sign GUI Authentication**: Password entries are now forwarded directly to the proxy through the bridge channel where rate limiting and session validation apply. • **Brute-Force Protection**: Registration and login attempts are now rate-limited both globally and per account. • **`/vn connect` Token Bypass**: Manual server connections can no longer bypass menu-token validation. • **Geo Routing Context**: `geo_distance` groups now apply country affinity on initial connection just as they do through `/lobby`. • **Party Ghost Invites**: Invites from disconnected players or disbanded parties are immediately invalidated. • **Circuit Breaker Recovery**: Half-open requests that never complete correctly return the breaker to its open state after cooldown. • **Server Health Cache**: Running `clearCache()` during `/vn reload` no longer causes valid servers to appear missing or expose raw `CancellationException` errors. • **Fail-Closed Registration**: Empty `registration_secret` values now reject unsigned backend registrations instead of trusting them. • **Redis Subscriber Recovery**: Registration subscribers now respect `subscriber_timeout_ms` to recover cleanly from stalled connections. • **Authentication Reload Persistence**: Active sessions survive `/vn reload`. • **MOTD `{version}` Placeholder**: Now resolves the actual running plugin version rather than a hardcoded value. • **Command Permissions**: `/vn help` and `/vn version` can pass the outer Velocity permission gate without requiring administrator access. • **General Robustness**: Oversized semantic version values no longer crash parsing, expired cooldown entries are cleaned automatically, connection logs are capped, and skin lookups now deduplicate concurrent requests while closing HTTP resources correctly. ## Improved • **Uptime in `/vn status`**: Displays real-time proxy uptime. • **Menu Validation**: Invalid menu files are skipped with useful warnings instead of breaking the entire menu system. • **Configurable Menu Token Timeout**: Session token lifetime can now be configured between 5 and 3600 seconds, with a default of 60 seconds. • **Theme Uniformity**: Commands now consistently use VelocityNavigator's aqua accent and clean gray descriptions.

## [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 `&lt;player&gt;` 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/28341) (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!