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 server list MOTD rotations, cross-server party synchronization with full PlaceholderAPI expansions, Argon2id authentication with private Sign GUIs, multi-engine database storage, and native Folia multi-threading 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 proxy) 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/Folia, it boots backend NPCs, YAML menus, and PlaceholderAPI expansions.
• Zero Version Desyncs: Internal bridge protocol packets (MenuBridgeProtocol) and Redis payload serializers are guaranteed to be 100% binary-compatible across the entire network.
• Multi-Platform Support: Formally tested and compatible with Velocity 3.4.x, 3.5.x, and Velocity 4.0.0 on Java 17, 21, and 25.

New — Native Packet-Level NPC Server Selectors (/vnavnpc)

A completely new, zero-dependency in-game NPC server selector engine built natively into the backend bridge:

• Real Player-Model NPCs on 1.20.5+: Spawns genuine player models via direct packet transmission on Paper, Spigot, and Folia 1.20.5 through 1.21.x — real Mojang skins, full-size interaction hitboxes, held items, and smooth head rotation. Zero external plugins required (no Citizens, no ProtocolLib).
• Billboarded TextDisplay Holograms: Multi-line floating text labels billboarded (CENTER) so names and server stats face players cleanly from every direction without one-sided distortion.
• Scoreboard Team Glowing: Custom team glowing outline colors (/vnavnpc glow <id> <on|off> [color]) configured without interfering with player scoreboard setups.
• Packet-Level Netty Click Interception: Direct Netty channel handler captures clicks on fake players with built-in interaction range validation (6-block radius).
• Smart Click Actions & Conditional Routing: Configure NPCs to route players to servers, open backend YAML menus, run commands, or execute conditional permission routing (action:cond(perm=velocitynavigator.vip?server:vip-lobby|server:lobby)).
• Dynamic Proximity Head Tracking: NPCs rotate their heads toward the nearest player within 64 blocks smoothly on the player's scheduler.
• Paper 26.2 Mannequin & Folia Safety: Built with native support for Paper mannequin entities and Folia's regionized schedulers.
• Automatic Fallback for Older Servers: Automatically detects backends older than 1.20.5 and seamlessly uses an optimized armor-stand mannequin with Interaction hitboxes.
• Full In-Game Management (/vnavnpc): Comprehensive command tree with tab completion (create, action, skin, glow, hand, offhand, status, respawn, tp, remove, list, reload).

New — Full GeoIP Distance Routing Engine (geo.toml)

Route players to the lowest-latency lobby clusters based on physical geographic location:

• Geo-Distance Selection Mode (geo_distance): Calculates mathematical Great-Circle distance (Haversine formula) between player coordinates and server datacenter locations, automatically choosing the physically closest backend.
• Multiple GeoIP Providers: Native support for MaxMind GeoLite2 databases (.mmdb), real-time HTTP fallback via ip-api.com, and seamless GeoRestrict integration.
• VPN & ASN Detection: Built-in integration with GeoRestrict as a primary lookup source for proxy, VPN, and autonomous system verification.
• Country & Continent Affinity Overrides: Map specific countries or continents directly to designated lobby pools (geo_routing.affinity_countries).
• Thread-Safe Subnet Matching: High-performance in-memory IP cache with CIDR subnet matching for instantaneous routing decisions with zero main-thread impact.
• Contextual Initial Join Affinity: Regional affinity rules apply immediately during initial connection handshakes as well as /lobby commands.

New — Dynamic MOTD Subsystem & Configuration (motd.toml)

A standalone, multi-mode server list MOTD engine:

• Dynamic Server List Rotation: Configurable rotation engines supporting auto-rotating intervals (ROTATING), randomized selections (RANDOM), and sequential cycles (SEQUENTIAL) via motd.toml.
• Readable Multiline TOML Formatting: MOTD configuration uses clean, human-readable multiline TOML strings with comment preservation and automated version backups.
• Emergency Maintenance Overrides: Dedicated maintenance MOTD templates that automatically take over when global maintenance mode is enabled (override_motd_on_maintenance = true).
• MiniMessage & Gradient Styling: Rich text styling with native MiniMessage gradients, hex colors, font tags, and legacy color code (&a, &b) translation.
• Real-Time Placeholders: Embed dynamic network information including {online}, {max}, {maintenance_reason}, and {version}.
• Console & In-Game Administration: Dedicated command suite (/vn motd reload, /vn motd list, /vn motd add <text>, /vn motd remove <index>, /vn motd setmode <mode>).

New — Authentication & Defensive Security Engine (auth.toml)

Proxy-side authentication engine with military-grade hashing, holding-server quarantine, and native interfaces for both Java and Bedrock clients:

• Argon2id Password Hashing: State-of-the-art password security powered by BouncyCastle with configurable memory cost, iterations, and parallelism.
• Legacy SHA-256 Verification: Automatic backward-compatible password verification and upgrade path for pre-existing password databases.
• Interactive Sign-Board GUI for Java: Java players receive an interactive in-game sign prompt to enter passwords privately without typing in open chat, with automatic command fallback.
• Native Floodgate Bedrock Forms: Bedrock players via Floodgate receive native modal dialog forms for registration and password input.
• Holding Lobby Physical Quarantine: Unauthenticated players are confined to a holding server with movement, interaction, block breaking/placing, item pickup/drop, and chat locked down until authentication succeeds (with optional blindness effect).
• Brute-Force Rate Limiting: Global and per-account failure counters trigger an automatic 5-minute lockout with player notifications upon repeated failed logins.
• Bridge-Authenticated Sign Sessions: Sign submissions route directly over the internal proxy-backend bridge channel with token validation to prevent spoofing.
• Reload-Persistent Sessions: In-memory and persistent session tokens survive proxy reloads without forcing online players to log in again.

New — Cross-Server Party & Team Engine (/party)

Complete proxy-wide party management with dual Bedrock & Java interfaces and full backend synchronization:

• Party Hierarchy & Roles: LEADER, OFFICER, and MEMBER roles with promotion and demotion (/party promote, /party demote).
• Custom Party Names & Formatting: Rename parties (/party rename <name>) with MiniMessage and color support.
• Leader Follow: Party members automatically follow the party leader when transferring between lobbies or game servers.
• Open & Invite-Only Modes: Public or private join toggles (/party open, /party close).
• Dual Platform GUIs: Dedicated /party menu with native Bedrock Cumulus modal forms and Java Edition chest inventories.
• Complete PlaceholderAPI Expansion: Real-time team and party values exposed on all Paper/Spigot backends:
  • %velocitynavigator_party_in_party% (true / false)
  • %velocitynavigator_party_name% (Party / team display name)
  • %velocitynavigator_party_leader% (Leader username)
  • %velocitynavigator_party_size% and %velocitynavigator_party_max_size%
  • %velocitynavigator_party_is_leader% (true / false)
  • %velocitynavigator_party_role% (LEADER, OFFICER, MEMBER)
  • %velocitynavigator_party_is_open% (true / false)
  • %velocitynavigator_party_members% (Formatted comma-separated member list for tablists/scoreboards)
  • %velocitynavigator_ping%, %velocitynavigator_lobby%, and EssentialsX integration placeholders.

New — Custom Menu System (Backend)

Fully customizable YAML-based menus on Paper/Spigot servers. Create your own server selectors, minigame menus, or any interactive GUI:

• Create unlimited custom menus in menus/*.yml files
• Items with configurable slots, materials, custom model data, skull owners, and sounds
• Nested menus — link directly to submenus (menu:games)
• Command execution — execute proxy or backend commands on click (cmd:/command)
• Server routing — send players to specific lobby clusters
• Live item refresh (@refresh:N) and pagination (@page:N) for large networks
• Disabled items (@disabled) for greyed-out coming-soon placeholders
• Default starter menus (main, games, lobbies) auto-generated on first run
• /vnavmenu command with 7 subcommands (open, add, remove, title, rows, list, reload)

New — Multi-Engine Database Storage (storage.toml)

Choose where your player affinity, sessions, and credentials live:

• Embedded SQLite: Zero-configuration embedded database with native driver bundling
• MySQL & MariaDB: High-throughput database storage with HikariCP connection pooling
• PostgreSQL: Enterprise SQL database storage for multi-proxy architectures
• Plain JSON Files: Lightweight, zero-setup file storage for smaller communities
• Automatic Schema Migrations: Tables and column upgrades applied automatically on boot

New — Folia Support

Full compatibility with Folia's regionized multi-threaded architecture:

• Runtime Folia detection via MethodHandle reflection
• Backend task scheduling uses entity-owned region threads on Folia
• Gracefully falls back to standard Bukkit schedulers on Paper/Spigot
• plugin.yml declares native folia-supported: true

New — Maintenance & Graceful Evacuation

Take servers offline without disrupting player gameplay:

• Network-wide or per-server maintenance states (maintenance global on|off, /vn maintenance [server] [on/off])
• Safe player evacuation to healthy eligible destination lobbies without kicks
• Maintenance blocks direct backend transfers as well as Navigator routing
• Custom kick reasons and dynamic countdown badges

New — Backend Update Checker

Independent update checker for Paper/Spigot servers:

• Periodically checks Modrinth API for new releases
• Exponential backoff on HTTP 429 rate limits
• Configurable interval via update_check_interval_minutes

New — Version Mismatch Detection

Proxy continuously monitors backend bridge compatibility:

• Compares backend plugin versions against the proxy version during HELLO handshakes
• /vn bridge displays ✓ (up to date), ⚠ (outdated), or ✗ (not detected) per backend

New — Backend bStats Telemetry

Dedicated metrics telemetry for Paper/Spigot backends (plugin ID 32887):

• Custom charts: folia_enabled, server_software, inventory_menu_enabled, handshake_enabled, refresh_enabled, redis_registration_enabled

New — Modular Configuration Architecture

• Separated Config Files: Dedicated storage.toml, geo.toml, auth.toml, and motd.toml for clean organization
• Config Version 9: Automatic migration from legacy v8 configs
• Organized Backup Folder: All version backups stored in a dedicated backups/ subfolder
• Automatic Backup Pruning: Only the latest backup per file is retained — stale backups are cleaned automatically
• Backend Config Auto-Migration: config.yml auto-migrated from v1 to v2 on first boot

New — Administrative & Diagnostic Commands

Command	Description
/vnavnpc	In-game NPC management (create, action, skin, glow, hand, offhand, status, respawn, tp, remove, list, reload)
/vnavmenu	Custom menu management (open, add, remove, title, rows, list, reload)
/vn config validate	Runtime validation of navigator.toml and server registry with typo suggestions
/vn server dry-run	Validate a server add operation without writing to disk
/vn affinity clean	Purge expired sticky-session entries
/vn debug player <player>	Live trace explaining routing decisions for a specific player

Updated — Multi-Proxy Synchronization

Extended from v4.3:

• HMAC-SHA256 signature verification on registration payloads
• Timestamp freshness validation to prevent replay attacks
• Signature deduplication within the freshness window
• Host allowlisting with wildcard support

Updated — NavigatorAPI

Expanded developer API:

• Access pluginVersion(), server(), logger(), dataDirectory(), config(), bedrockHandler() directly
• No need to cast NavigatorAPIProvider.get() to internal implementation classes

Updated — Language Packs (15 Languages)

Expanded from 7 to 15 fully bundled languages:

Code	Language	Status
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 Board GUI authentication: Password entries are forwarded to the proxy over the bridge channel where rate limiting and session validation apply, resolving failures on proxy-only auth setups.
• Brute-force protection: Registration and login attempts are rate limited per account and globally; repeated failures lock the account for five minutes with informative lockout messages.
• /vn connect token bypass: Connecting to a server manually no longer bypasses menu-token validation; backend menu selections use dedicated authenticated selection tokens.
• Geo routing for contextual groups: geo_distance groups receive country affinity on the initial join, matching /lobby behavior.
• Party ghost invites: Invites sent by players who leave, are kicked, or whose party is disbanded are invalidated immediately.
• Circuit breaker half-open recovery: If half-open probe requests never complete, the breaker trips back open after the cooldown instead of remaining stuck in half-open state.
• Server health cache invalidation: clearCache() during /vn reload no longer reports servers as nonexistent or leaks raw CancellationException to callers.
• Fail-closed dynamic registration: A blank registration_secret rejects all incoming backend registrations instead of trusting unsigned announcements.
• Redis subscriber timeouts: The registration subscriber applies subscriber_timeout_ms so stalled connections recover automatically.
• Auth sessions across reload: In-memory authentication sessions survive /vn reload without forcing players to re-authenticate.
• {version} MOTD placeholder: Dynamically resolves the real plugin version instead of a hardcoded string.
• Command permissions: /vn help and /vn version pass Velocity's outer permission gate without granting admin privileges.
• Robustness: Version parts that overflow an int no longer crash SemanticVersion; cooldown maps purge expired entries; connection logs are capped; skin cache deduplicates in-flight lookups and cleanly closes HTTP connections.

Improved

• Uptime in /vn status: Real-time proxy running time display
• Menu Validation: Invalid menu files are skipped with actionable warnings instead of breaking menu loading
• Configurable Menu Token Timeout: Adjust session timeout (5–3600 seconds, default 60)
• Theme Uniformity: Commands consistently use VelocityNavigator's signature aqua accent with clean gray descriptions