VelocityNavigator

面向现代 Velocity 网络的高性能大厅路由、原生可视化选择器、自愈熔断机制、零依赖 NPC 以及实用的代理运维功能。
VelocityNavigator 消除了代理负载均衡中的盲目猜测。它不再盲目地循环连接,而是在路由任何玩家之前,持续评估后端健康状态、服务器容量、维护窗口、排空状态、生命周期状态以及地理延迟。
无论是运行双大厅社区还是拥有数十个区域后端的分布式企业级网络,VelocityNavigator 都能提供弹性且可解释的路由方案,实现无缝扩展。
通用单 JAR 架构:将完全相同的 JAR 文件安装到你的 Velocity 代理上,以及任何你想要部署 NPC、YAML 菜单、Java 库存选择器、PlaceholderAPI 值或后端 Redis 注册的 Paper、Spigot 或 Folia 后端上。无需任何额外的桥接插件。
1. 智能大厅路由与负载均衡

简单的轮询路由在生产环境中容易失效。断线、玩家分组以及异构的服务器硬件会导致严重的负载不平衡。VelocityNavigator 提供了 九种专为真实世界代理架构设计的专业路由策略:
- 两选一算法 (
power_of_two):分布式负载均衡的现代行业标准。随机选择两个候选大厅,并将玩家路由至负载较低的一个。在数学上消除了羊群效应和负载倾斜,且无需全局锁。
- 最少玩家数 (
least_players):将新连接直接路由到在线玩家最少的大厅。非常适合确保新玩家进入活跃且人口充实的环境。
- 加权轮询 (
weighted_round_robin):根据分配的服务器权重按比例分发流量。非常适合混合硬件部署(例如,将 3 倍于 8GB VPS 的玩家数量引导至 64GB 独立节点)。
- 一致性哈希 (
consistent_hash):使用带有虚拟节点的 Ketama 哈希环,将玩家 UUID 一致地映射到特定后端。提供确定性路由,同时在添加或移除服务器时仅平滑地重新分配部分键值。
- 延迟感知 Ping 路由 (
latency / ping):主动评估到每个后端的往返 Ping 值,并将传入玩家路由至延迟最低的响应节点。
- 最少连接数 (
least_connections):使用平滑处理的玩家数量和近期连接率对服务器进行评分,以分发突发流量。
- 地理位置路由 (
geo):根据玩家的国家代码和大洲代码,自动将国际玩家路由到区域后端集群。支持 MaxMind GeoLite2、IP-API 以及原生 GeoRestrict 集成。
- 顺序轮询 (
round_robin):在所有健康的候选后端之间进行严格的循环分发。
- 均匀随机 (
random):在所有可用的健康大厅中进行纯随机分发。
粘性会话与玩家亲和性
回归玩家讨厌每次切换世界时被扔进随机大厅。VelocityNavigator 提供了 可配置的玩家亲和性:
- 在可配置的时间窗口内记住玩家之前所在的大厅。
- 玩家在重新连接时会自动被路由回他们熟悉的大厅。
- 通过原子磁盘存储实现跨代理重启的全局持久化。
- 当首选大厅已满、处于排空状态或正在维护时,立即过期并绕过亲和性限制。
实时路由解释
需要诊断为何某位玩家被路由到特定大厅?运行 /vn debug player <username> 查看实时路由追踪:包括候选池发现、过滤规则(健康、容量、排空、维护、亲和性)、评分计算以及最终选定的目标。
2. 弹性自愈与熔断机制

当后端崩溃或出现严重 TPS 下降时,标准代理会让玩家停留在超时界面上等待。VelocityNavigator 充当一个具备企业级防御系统的自愈式流量管理器:
- 三态断路器(
CLOSED ➔ OPEN ➔ HALF-OPEN):每个已注册的后端服务器都维护一个独立的断路器。当连接失败或 ping 超时超过您配置的阈值时,断路器会跳闸至 OPEN 状态,在玩家遭遇连接冻结之前立即切断对该服务器的玩家路由。经过一段冷却窗口后,它进入 HALF-OPEN 状态,通过金丝雀连接测试服务器健康状况,然后再恢复全量流量。
- 带抖动指数的退避算法:当断开的后端恢复时,重连尝试会以伪随机抖动的方式逐步退避。这防止了毁灭性的“惊群效应”,即数百名玩家同时涌入正在恢复的服务器。
- 连续多向量健康检查:活动的 ping 检测、TCP 套接字验证、MOTD 查询检查以及后端桥接心跳,使代理状态能够与真实的服务器状况保持持续同步。
- 零停机排空系统(
/vn drain <server>):安全地将大厅下线而无需踢出活跃玩家。排空中的服务器立即停止接收新加入者和 /lobby 转移请求,同时让现有玩家完成他们的游戏。一旦玩家数量归零,即可安全进行维护操作。
- 空大厅回退机制:如果池中的所有大厅都无法访问,VelocityNavigator 会优雅地将玩家引导至配置的回退服务器,或者提供一个友好且本地化的断开连接通知,而不是显示未格式化的网络异常。
3. 统一的视觉选择器
为所有 Minecraft 客户端平台提供一致导航体验:



- 原生 Java 对话框 (Minecraft 1.21.6+ & Paper 1.21.7+):
- 用于大厅选择、派对管理、认证和后端 YAML 菜单的简洁现代原生客户端对话框界面。
- 无箱子库存杂乱或物品闪烁:大厅作为带有分页和悬停提示的原生对话框按钮显示。
- 可配置的 UI 模式(
auto、dialog、inventory、sign、command、chat),并为旧版客户端和后端提供无缝自动回退。
- 内置安全性,使用绑定到玩家会话的过期一次性操作令牌。
- Java 箱子库存 GUI:
- 支持自定义行数(1–6 行)的多页分页。
- 感知状态的项目展示:为 Open(开放)、Full(满员)、Draining(排空中)、Maintenance(维护中)和 Offline(离线)大厅配置不同的材质、显示名称和描述文本。
- 实时玩家计数、容量计数器和动态描述文本占位符。
- 自动 GUI 刷新间隔,以便在菜单保持打开的同时保持玩家计数准确。
- 加密令牌验证以防止槽位注入和点击伪造攻击。
- 原生 Bedrock / Geyser 表单:
- 专为触摸和控制器导航设计的简洁原生 Floodgate/Geyser 对话框表单。
- 显示服务器显示名称、实时玩家计数、描述和自定义图标图片。
- 按下按钮即可直接切换服务器,无需笨拙的 Java GUI 模拟。
- 交互式 MiniMessage 聊天选择器:
- 轻量级、零 GUI 文本选择器,可从任何客户端访问。
- 使用丰富的 MiniMessage 样式格式化,悬停提示显示服务器详情,并支持单击连接命令。
- 所有选择器的单一服务器配置:
- 在配置中定义一次服务器元数据:
display_name、description、menu_order 和 show_in_menu。更改将立即同步到原生对话框、Java 库存、Bedrock 表单和聊天选择器。
4. 零依赖后端桥接与 NPC


与其他需要单独 Spigot 插件、协议黑客或像 Citizens 这样重型依赖项的代理导航器不同,VelocityNavigator 完全自包含:
- 单个通用 JAR:放置在 Velocity 上的完全相同的 JAR 文件可在 Paper、Spigot 和 Folia 后端上运行。
- 零 NMS 数据包 NPC:
- 在后端服务器上生成轻量级、高性能的 NPC,无需版本锁定的 NMS 代码。
- 开箱即用兼容从 Paper 1.16.5 到 26.3 以及 Folia 的所有版本。
- 通过用户名或 Mojang 纹理属性获取自定义玩家皮肤。
- 配置灵活的点击动作:连接到服务器、打开自定义菜单或执行代理/后端命令。
- 在游戏中管理 NPC,使用
/vn npc create <id> <name>、/vn npc skin <id> <player> 和 /vn npc delete <id>。
- 后端 YAML 菜单 (
plugins/VelocityNavigator/menus/*.yml):
- 在后端构建完整的自定义库存菜单,无需第三方 GUI 插件。
- 可配置的槽位网格、材质、自定义模型数据、头颅拥有者和声音。
- 多动作执行:服务器转移、命令、广播消息、子菜单、分页和关闭。
- PlaceholderAPI 桥接:
- 在任何后端访问实时代理值:
%velocitynavigator_lobby%、%velocitynavigator_party_leader%、%velocitynavigator_party_size%、%velocitynavigator_server_status_<server>% 和 %velocitynavigator_queue_position%。
5. 内置代理系统与社交功能

VelocityNavigator 包括生产就绪的网络工具,消除了对臃肿第三方附加组件的需求:
- 容量排队系统:
- 在玩家激增时绝不拒绝玩家。当所有路由的大厅达到容量上限时,玩家将进入指定保留服务器的优雅排队队列。
- 显示动态动作栏和标题倒计时,提供实时排队位置和预计等待时间。
- 为 VIP 和管理员提供优先级绕过权限(
velocitynavigator.queue.priority)。
- 跨服务器组队系统:
- 完整的队伍管理功能:
/party create、/party invite <player>、/party join、/party leave、/party kick 以及 /party disband。
- 队长跟随:当队伍队长切换到大厅或小游戏时,所有在线的队伍成员会自动一起转移。
- 私有的跨代理队伍聊天(
/party chat <message>)以及开放/仅邀请的队伍模式切换。
- 网络与单服务器维护:
- 切换全网维护或锁定单个后端服务器(
/vn maintenance set <server> true)。
- 支持丰富 MiniMessage 和颜色格式化的自定义踢出理由。
- 基于权限的绕过功能(
velocitynavigator.bypass.maintenance),便于管理员进行测试。
- 动态 MOTD 集成,显示维护徽章和倒计时。
6. 多代理集群与 Redis 同步
在 BGP Anycast IP 或 DNS 轮询背后运行多个 Velocity 代理?VelocityNavigator 通过 Redis 提供内置的分布式集群功能:
- 跨代理健康与电路同步:断路器跳闸状态和后端健康快照在每个代理节点间以毫秒级速度同步。
- 集群级玩家亲和性:粘性会话在代理之间持久化,确保返回的玩家无论连接到哪个代理,都能正确连接到大厅。
- 动态服务器注册:后端可以通过 Redis Pub/Sub 动态宣布自身存在,在启动时向代理池注册,在关闭时注销,无需编辑代理配置文件。
- 经过身份验证且通道隔离:使用可配置的通道和键前缀的安全 Redis 身份验证,适用于多网络环境。
7. 安全与认证引擎

利用现代防御性安全性保护您的代理网络:
- Argon2id 密码哈希:使用固定的 64 MiB 内存成本、三次迭代和四个并行度。验证传统的加盐 SHA-256 凭据,并在配置了 Argon2id 且登录成功后将其升级。
- 暴力破解速率限制:按账户跟踪失败次数,实施临时账户锁定和全局尝试次数限制,从而限制密码猜测。重新连接到同一代理时会保留账户锁定状态。
- 等候大厅隔离:未认证的玩家被隔离在一个轻量级的等候大厅中。在认证成功之前,完全禁止玩家移动、方块交互、物品栏访问以及聊天命令(除
/login 和 /register 外)。
- 原生 Bedrock 认证表单:通过 Floodgate 连接的 Bedrock 玩家将收到原生的模态对话框用于注册和密码输入,而不是在开放的聊天中输入密码。
- 过期的会话令牌:代理本地的会话会在短时间内记住已认证的玩家,以便他们快速重新连接到同一代理,TTL 可在配置中设定。
8. 实时运维与可观测性


- 嵌入式 HTML 运维仪表板:
- 内置轻量级 Web 仪表板,运行在其专用的端口上。
- 实时大厅状态表,显示活跃玩家数量、最大容量、延迟和电路健康状况。
- 可视化路由分布图表、粘性会话计数器和加入/离开指标。
- 通过 HTTP Bearer Token 身份验证进行安全保护。
- Prometheus 与 Grafana 指标:
- 原生
/metrics 端点开箱即用地导出 Prometheus 指标:路由计数、电路跳闸、健康检查延迟、队伍数量和队列深度。
- 直接导入 Grafana 以实现 24/7 网络监控。
- 动态 MiniMessage MOTD 轮换:
- 动态 MOTD 管理器支持随机、顺序或按计划时间窗口的轮换。
- 嵌入动态玩家数量、自定义十六进制颜色、渐变和维护状态行。
- 自文档化配置与验证:
/vn config validate 执行深层语法和语义检查,并提供基于莱文斯坦距离的拼写错误建议。
/vn menu validate 在玩家遇到损坏的菜单之前,审计 GUI 项目槽位、材质、重复键和占位符。
9. 全球本地化

开箱即用部署 15 种捆绑语言翻译:
| 语言 |
代码 |
语言 |
代码 |
语言 |
代码 |
| English |
en |
Spanish |
es |
German |
de |
| French |
fr |
Russian |
ru |
Portuguese (BR) |
pt_br |
| Chinese (Simp.) |
zh_cn |
Japanese |
ja |
Korean |
ko |
| Italian |
it |
Dutch |
nl |
Polish |
pl |
| Turkish |
tr |
Arabic |
ar |
Hindi |
hi |
- 可以添加自定义
.properties 文件到 plugins/velocitynavigator/languages/ 目录,无需重新编译。
- 支持通过
/vn reload 实现完全热重载。
10. 多引擎存储架构
将玩家数据、粘性会话和认证凭据存储在与您基础设施相匹配的存储引擎中:
- 纯 JSON 文件:简单、零配置的存储方案,适用于小型网络。
- SQLite:嵌入式 SQL 数据库,无需配置或外部数据库服务器。
- MySQL & MariaDB:高性能数据库存储,支持 HikariCP 连接池和自动架构迁移。
- PostgreSQL:用于大型网络部署的稳健企业级数据库后端。
11. 快速入门指南
在五分钟之内即可上手运行:
- 下载
VelocityNavigator-4.6.0.jar 并将其放入 Velocity 代理的 plugins/ 目录中。
- 启动一次代理以生成默认配置文件,然后停止代理。
- 打开
plugins/velocitynavigator/navigator.toml 并列出你的大厅服务器(名称需与 velocity.toml 中的匹配):
[routing]
selection_mode = "power_of_two"
balance_initial_join = true
default_lobbies = ["lobby-1", "lobby-2", "lobby-3"]
[routing.fallback]
strategy = "disconnect"
message = "<red>所有大厅当前已满或正在维护。</red>"
[health]
check_interval_seconds = 5
timeout_millis = 2000
circuit_breaker_threshold = 3
circuit_breaker_reset_seconds = 30
- 从控制台运行
/vn config validate 以验证你的配置。
- 启动代理并在游戏中输入
/lobby 来测试路由功能!
想要添加后端功能? 将完全相同的 JAR 文件复制到每个 Paper、Spigot 或 Folia 后端的 plugins/ 文件夹中,以便在这些服务器上启用 NPC、YAML 菜单或 Java 物品栏选择器。
12. 命令与权限参考
管理命令
| 命令 |
权限 |
描述 |
/vn health |
velocitynavigator.admin |
聚合代理诊断信息和电路健康状况概览 |
/vn servers |
velocitynavigator.admin |
分页显示服务器健康状态、容量、排水状态和电路信息 |
/vn debug player <player> |
velocitynavigator.admin |
实时追踪特定玩家的路由决策过程 |
/vn drain <server> |
velocitynavigator.admin |
切换排水模式,安全疏散后端服务器而不踢出玩家 |
/vn maintenance [server] [on/off] |
velocitynavigator.admin |
切换全网或单服务器的维护模式 |
/vn affinity clean |
velocitynavigator.admin |
手动清除过期的粘性会话映射 |
/vn bridge status |
velocitynavigator.admin |
显示检测到的 Paper/Folia 后端桥接连接状态 |
/vn config validate |
velocitynavigator.admin |
审计配置文件是否存在语法或拼写错误 |
/vn menu validate |
velocitynavigator.admin |
验证自定义菜单项、槽位和材质 |
/vn reload |
velocitynavigator.admin |
热重载所有配置、菜单和语言包 |
玩家命令
| 命令 |
权限 |
描述 |
/lobby 或 /hub |
none (可配置) |
将玩家路由到最佳可用且健康的大厅 |
/lobby menu |
none (可配置) |
打开交互式服务器选择器 |
/party |
none (可配置) |
访问跨服务器小队管理系统 |
13. 兼容性矩阵

- 代理平台:
- Velocity 3.4.x (Java 17+)
- Velocity 3.5.x (Java 21+)
- Velocity 4.0.0 (Java 25)
- 后端平台(可选桥接):
- Paper 1.16.5 – 26.3+
- Spigot 1.16.5 – 26.3+
- Folia 1.20.x – 26.3+
- 生态系统集成:
- GeyserMC & Floodgate(原生 Bedrock 表单及 Floodgate UUID 转换)
- PlaceholderAPI(丰富的后端占位符)
- GeoRestrict & MaxMind GeoLite2(地理路由)
- Prometheus & Grafana(指标监控)
14. 文档与社区支持

由 Nexeu Hosting 赞助

高性能、经济实惠的 Minecraft 托管服务,配备高端 NVMe 硬件、DDoS 防护以及 24/7 技术支持。
VelocityNavigator

High-performance lobby routing, native visual selectors, self-healing circuit breakers, zero-dependency NPCs, and practical proxy operations for modern Velocity networks.
VelocityNavigator takes the guesswork out of proxy load balancing. Instead of blindly cycling connections, it continuously evaluates backend health, server capacity, maintenance windows, drain states, lifecycle status, and geographic latency before routing a single player.
Whether running a two-lobby community or a multi-proxy enterprise network with dozens of regional backends, VelocityNavigator delivers resilient, explainable routing that scales effortlessly.
Universal Single-JAR Architecture: Install the exact same JAR on your Velocity proxy and on any Paper, Spigot, or Folia backend where you want NPCs, YAML menus, Java inventory selectors, PlaceholderAPI values, or backend Redis registration. Zero separate bridge plugins required.
1. Intelligent Lobby Routing & Balancing

Simple round-robin routing breaks in production networks. Disconnections, player grouping, and varied server hardware create severe load imbalances. VelocityNavigator provides nine specialized routing strategies designed for real-world proxy architectures:
- Power of Two Choices (
power_of_two): The modern industry standard for distributed load balancing. Selects two candidate lobbies at random and routes to the one with lower load. Mathematically eliminates herd behavior and load skew without requiring global locks.
- Least Players (
least_players): Routes new connections directly to the lobby with the fewest online players. Ideal for ensuring new players land in active, populated environments.
- Weighted Round Robin (
weighted_round_robin): Distributes traffic proportionally across backends according to assigned server weights. Perfect for mixed hardware deployments (e.g. directing 3x more players to a 64GB dedicated node than an 8GB VPS).
- Consistent Hashing (
consistent_hash): Uses a Ketama hash ring with virtual nodes to consistently map player UUIDs to specific backends. Provides deterministic routing while smoothly re-distributing only a fraction of keys when servers are added or removed.
- Latency-Aware Ping Routing (
latency / ping): Actively evaluates round-trip ping to each backend and assigns incoming players to the lowest-latency responsive node.
- Least Connections (
least_connections): Scores servers using smoothed player counts and recent connection rates to distribute burst traffic.
- Geo-Location Routing (
geo): Automatically routes international players to regional backend clusters based on player country and continent codes. Supports MaxMind GeoLite2, IP-API, and native GeoRestrict integration.
- Sequential Round Robin (
round_robin): Strict cyclic distribution across all healthy candidate backends.
- Uniform Random (
random): Pure random distribution across available healthy lobbies.
Sticky Sessions & Player Affinity
Returning players hate being thrown into a random lobby every time they switch worlds. VelocityNavigator provides configurable player affinity:
- Remembers a player's previous lobby within a configurable time window.
- Automatically routes players back to their familiar lobby upon reconnecting.
- Fully persistent across proxy restarts with atomic on-disk storage.
- Instant expiration bypass when the preferred lobby is full, draining, or undergoing maintenance.
Live Route Explanations
Need to diagnose why a player routed to a specific lobby? Run /vn debug player <username> to view the real-time routing trace: candidate pool discovery, filter rules (health, capacity, drain, maintenance, affinity), scoring calculations, and the selected winner.
2. Resilient Self-Healing & Circuit Breakers

When a backend crashes or suffers severe TPS drops, standard proxies leave players waiting on timeout screens. VelocityNavigator acts as a self-healing traffic manager with enterprise-grade defensive systems:
- Three-State Circuit Breaker (
CLOSED ➔ OPEN ➔ HALF-OPEN): Each registered backend server maintains an independent circuit breaker. When connection failures or ping timeouts exceed your configured threshold, the circuit trips OPEN, instantly cutting off player routing to that server before players experience connection freezes. After a cool-down window, it enters HALF-OPEN to test server health with canary connections before resuming full traffic.
- Exponential Backoff with Jitter: When disconnected backends recover, reconnect attempts back off progressively with pseudo-random jitter. This prevents the devastating "thundering herd" effect where hundreds of players flood a recovering server simultaneously.
- Continuous Multi-Vector Health Checks: Active ping checks, TCP socket verification, MOTD query checks, and backend bridge heartbeats keep proxy state continuously synchronized with real server conditions.
- Zero-Downtime Drain System (
/vn drain <server>): Safely take lobbies offline without kicking active players. Draining servers immediately stop receiving new joins and /lobby transfers while existing players finish their games. Once player count reaches zero, maintenance can be performed safely.
- Empty Lobby Fallbacks: If every lobby in a pool becomes unreachable, VelocityNavigator gracefully directs players to a configured fallback server or provides a friendly, localized disconnect notice instead of an unformatted network exception.
3. Unified Visual Selectors
Deliver a consistent navigation experience across every Minecraft client platform:



- Native Java Dialogs (Minecraft 1.21.6+ & Paper 1.21.7+):
- Clean, modern native client dialog interfaces for lobby selectors, party management, authentication, and backend YAML menus.
- Zero chest inventory clutter or item flickering: lobbies appear as native dialog buttons with pagination and hover tooltips.
- Configurable UI modes (
auto, dialog, inventory, sign, command, chat) with seamless automatic fallbacks for older clients and backends.
- Built-in security with expiring, single-use action tokens bound to the player session.
- Java Chest Inventory GUI:
- Multi-page pagination with customizable row sizes (1–6 rows).
- State-aware item presentation: configure distinct materials, display names, and lore for Open, Full, Draining, Maintenance, and Offline lobbies.
- Live player counts, capacity counters, and dynamic lore placeholders.
- Automatic GUI refresh intervals so player counts stay accurate while menus remain open.
- Cryptographic token validation to prevent slot injection and click-spoofing attacks.
- Native Bedrock / Geyser Form:
- Clean, native Floodgate/Geyser dialog forms designed specifically for touch and controller navigation.
- Displays server display names, live player counts, descriptions, and custom icon images.
- Direct server switching on button press without clunky Java GUI emulation.
- Interactive MiniMessage Chat Selector:
- Lightweight, zero-GUI text selector accessible from any client.
- Formatted with rich MiniMessage styling, hover tooltips showing server details, and single-click connection commands.
- One Server Configuration for All Selectors:
- Define server metadata once in your configuration:
display_name, description, menu_order, and show_in_menu. Changes immediately synchronize across Native Dialogs, Java Inventory, Bedrock Forms, and Chat selectors.
4. Zero-Dependency Backend Bridge & NPCs


Unlike other proxy navigators that require separate Spigot plugins, protocol hacks, or heavy dependencies like Citizens, VelocityNavigator is completely self-contained:
- Single Universal JAR: The exact same JAR file placed on Velocity runs on Paper, Spigot, and Folia backends.
- Zero-NMS Packet NPCs:
- Spawn lightweight, high-performance NPCs on backend servers without version-locked NMS code.
- Compatible across Paper 1.16.5 through 26.3 and Folia out of the box.
- Fetch custom player skins by username or Mojang texture properties.
- Configure flexible click actions: connect to a server, open a custom menu, or execute proxy/backend commands.
- Manage NPCs in-game with
/vn npc create <id> <name>, /vn npc skin <id> <player>, and /vn npc delete <id>.
- Backend YAML Menus (
plugins/VelocityNavigator/menus/*.yml):
- Build full custom inventory menus on backends without third-party GUI plugins.
- Configurable slot grids, materials, custom model data, skull owners, and sounds.
- Multi-action execution: server transfer, commands, broadcast messages, submenus, pagination, and close.
- PlaceholderAPI Bridge:
- Access real-time proxy values on any backend:
%velocitynavigator_lobby%, %velocitynavigator_party_leader%, %velocitynavigator_party_size%, %velocitynavigator_server_status_<server>%, and %velocitynavigator_queue_position%.
5. Built-in Proxy Systems & Social Features

VelocityNavigator includes production-ready networking tools that eliminate the need for bloated third-party add-ons:
- Capacity Queue System:
- Never turn players away during player spikes. When all routed lobbies reach capacity, players enter a graceful queue in a designated holding server.
- Displays dynamic actionbar and title countdowns with live queue position and estimated wait time.
- Priority bypass permissions (
velocitynavigator.queue.priority) for VIPs and staff.
- Cross-Server Party System:
- Complete party management:
/party create, /party invite <player>, /party join, /party leave, /party kick, and /party disband.
- Leader Follow: When the party leader switches lobbies or minigames, all online party members are automatically transferred together.
- Private cross-proxy party chat (
/party chat <message>) and open/invite-only party toggles.
- Network & Per-Server Maintenance:
- Toggle network-wide maintenance or lock individual backends (
/vn maintenance set <server> true).
- Custom kick reasons with rich MiniMessage and color formatting.
- Permission-based bypass (
velocitynavigator.bypass.maintenance) for administrative testing.
- Dynamic MOTD integration showing maintenance badges and countdowns.
6. Multi-Proxy Clustering & Redis Sync
Running multiple Velocity proxies behind a BGP Anycast IP or DNS round-robin? VelocityNavigator provides built-in distributed clustering via Redis:
- Cross-Proxy Health & Circuit Synchronization: Circuit breaker trip states and backend health snapshots synchronize in milliseconds across every proxy node.
- Cluster-Wide Player Affinity: Sticky sessions persist across proxies, ensuring returning players connect to the correct lobby regardless of which proxy receives their connection.
- Dynamic Server Registration: Backends can announce themselves dynamically over Redis Pub/Sub, registering with proxy pools on boot and unregistering on shutdown without editing proxy configuration files.
- Authenticated & Channel-Isolated: Secure Redis authentication with configurable channels and key prefixes for multi-network environments.
7. Security & Authentication Engine

Protect your proxy network with modern defensive security:
- Argon2id Password Hashing: Uses fixed costs of 64 MiB memory, three iterations, and four lanes. Verifies legacy salted SHA-256 credentials and upgrades them after a successful login when Argon2id is configured.
- Brute-Force Rate Limiting: Per-account failure tracking, temporary account lockouts, and a global attempt limit restrict password guessing. Reconnecting to the same proxy preserves account lockouts.
- Holding Lobby Quarantine: Unauthenticated players are isolated in a lightweight holding lobby. Player movement, block interactions, inventory access, and chat commands (outside
/login and /register) are completely restricted until authentication succeeds.
- Native Bedrock Auth Forms: Bedrock players via Floodgate receive native modal dialogs for registration and password entry instead of typing passwords into open chat.
- Expiring Session Tokens: Proxy-local sessions remember authenticated players across quick reconnects to the same proxy within a configurable TTL.
8. Real-Time Operations & Observability


- Embedded HTML Operations Dashboard:
- Built-in lightweight web dashboard running on its own dedicated port.
- Real-time lobby status table showing active player counts, max capacity, latency, and circuit health.
- Visual routing distribution charts, sticky session counters, and join/leave metrics.
- Secured via HTTP Bearer Token authentication.
- Prometheus & Grafana Metrics:
- Native
/metrics endpoint exports Prometheus metrics out of the box: routing counts, circuit trips, health check latency, party counts, and queue depth.
- Import directly into Grafana for 24/7 network monitoring.
- Dynamic MiniMessage MOTD Rotation:
- Dynamic MOTD manager supporting Random, Sequential, or Scheduled Time-Window rotations.
- Embed dynamic player counts, custom hex colors, gradients, and maintenance status lines.
- Self-Documenting Configuration & Validation:
/vn config validate performs deep syntax and semantic checks with Levenshtein distance typo suggestions.
/vn menu validate audits GUI item slots, materials, duplicate keys, and placeholders before players encounter broken menus.
9. Global Localization

Deploy globally with 15 bundled language translations out of the box:
| Language |
Code |
Language |
Code |
Language |
Code |
| English |
en |
Spanish |
es |
German |
de |
| French |
fr |
Russian |
ru |
Portuguese (BR) |
pt_br |
| Chinese (Simp.) |
zh_cn |
Japanese |
ja |
Korean |
ko |
| Italian |
it |
Dutch |
nl |
Polish |
pl |
| Turkish |
tr |
Arabic |
ar |
Hindi |
hi |
- Custom
.properties files can be added to plugins/velocitynavigator/languages/ with zero recompilation.
- Full hot-reloading with
/vn reload.
10. Multi-Engine Storage Architecture
Store player data, sticky sessions, and auth credentials in the storage engine that matches your infrastructure:
- Plain JSON Files: Simple, zero-setup storage for small networks.
- SQLite: Embedded SQL database with zero configuration or external database servers required.
- MySQL & MariaDB: High-performance database storage with HikariCP connection pooling and automatic schema migrations.
- PostgreSQL: Robust enterprise database backend for large network deployments.
11. Quick Start Guide
Get up and running in under five minutes:
- Download
VelocityNavigator-4.6.0.jar and place it into your Velocity proxy's plugins/ directory.
- Start the proxy once to generate default configuration files, then stop the proxy.
- Open
plugins/velocitynavigator/navigator.toml and list your lobby servers (matching names in velocity.toml):
[routing]
selection_mode = "power_of_two"
balance_initial_join = true
default_lobbies = ["lobby-1", "lobby-2", "lobby-3"]
[routing.fallback]
strategy = "disconnect"
message = "<red>All lobbies are currently full or undergoing maintenance.</red>"
[health]
check_interval_seconds = 5
timeout_millis = 2000
circuit_breaker_threshold = 3
circuit_breaker_reset_seconds = 30
- Run
/vn config validate from the console to verify your configuration.
- Start the proxy and type
/lobby in-game to test routing!
Adding backend features? Copy the exact same JAR into the plugins/ folder of each Paper, Spigot, or Folia backend where you want NPCs, YAML menus, or the Java inventory selector.
12. Command & Permission Reference
Administrative Commands
| Command |
Permission |
Description |
/vn health |
velocitynavigator.admin |
Consolidated proxy diagnostics and circuit health overview |
/vn servers |
velocitynavigator.admin |
Paginated table of server health, capacity, drain, and circuits |
/vn debug player <player> |
velocitynavigator.admin |
Live trace explaining routing decisions for a specific player |
/vn drain <server> |
velocitynavigator.admin |
Toggle drain mode to safely evacuate backends without kicks |
/vn maintenance [server] [on/off] |
velocitynavigator.admin |
Toggle network-wide or per-server maintenance mode |
/vn affinity clean |
velocitynavigator.admin |
Manually purge expired sticky session mappings |
/vn bridge status |
velocitynavigator.admin |
Display detected Paper/Folia backend bridge connections |
/vn config validate |
velocitynavigator.admin |
Audit configuration files for syntax or typo errors |
/vn menu validate |
velocitynavigator.admin |
Validate custom menu items, slots, and materials |
/vn reload |
velocitynavigator.admin |
Hot-reload all configurations, menus, and language packs |
Player Commands
| Command |
Permission |
Description |
/lobby or /hub |
none (configurable) |
Route player to the best available healthy lobby |
/lobby menu |
none (configurable) |
Open the interactive server selector |
/party |
none (configurable) |
Access the cross-server party management system |
13. Compatibility Matrix

- Proxy Platforms:
- Velocity 3.4.x (Java 17+)
- Velocity 3.5.x (Java 21+)
- Velocity 4.0.0 (Java 25)
- Backend Platforms (Optional Bridge):
- Paper 1.16.5 – 26.3+
- Spigot 1.16.5 – 26.3+
- Folia 1.20.x – 26.3+
- Ecosystem Integrations:
- GeyserMC & Floodgate (Native Bedrock forms and Floodgate UUID translation)
- PlaceholderAPI (Rich backend placeholders)
- GeoRestrict & MaxMind GeoLite2 (Geographic routing)
- Prometheus & Grafana (Metrics monitoring)
14. Documentation & Community Support

Sponsored by Nexeu Hosting

High-performance, affordable Minecraft hosting with premium NVMe hardware, DDoS protection, and 24/7 technical support.
评论 0
登录后参与评分
还没有评论,来抢沙发吧