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.