VelocityNavigator

VelocityNavigator обеспечивает отказоустойчивую маршрутизацию игроков в крупных сетях Velocity, оценивая состояние бэкендов, их емкость и географическую задержку перед подключением.

VelocityNavigator избавляет от необходимости вручную настраивать балансировку нагрузки. Вместо слепого циклического переключения соединений, плагин непрерывно оценивает здоровье бэкендов, их вместимость, окна технического обслуживания, состояния слива (drain), жизненного цикла и географической задержки перед маршрутизацией каждого игрока.

Проект использует универсальную архитектуру Single-JAR: один и тот же файл устанавливается на прокси Velocity и на любые бэкенды (Paper, Spigot, Folia) для работы NPC, YAML-меню, инвентарных селекторов и значений PlaceholderAPI. Отдельные плагины-мосты не требуются.

Обычный round-robin часто дает сбои в продакшн-сетях из-за разницы в аппаратном обеспечении и группировки игроков. VelocityNavigator предлагает 9 специализированных стратегий:

• Power of Two Choices (power_of_two): выбирает два случайных лобби и направляет игрока в менее загруженное.
• Least Players (least_players): прямое направление в лобби с наименьшим количеством игроков.
• Weighted Round Robin (weighted_round_robin): распределение трафика пропорционально весу сервера (удобно для смешанного железа).
• Consistent Hashing (consistent_hash): использует кольцо Кетама для детерминированного сопоставления UUID игроков с бэкендами.
• Latency-Aware Ping Routing (latency / ping): оценка времени отклика и выбор узла с минимальной задержкой.
• Least Connections (least_connections): скоринг серверов на основе сглаженного количества игроков и скорости подключений.
• Geo-Location Routing (geo): автоматическое направление международных игроков к региональным кластерам (поддержка MaxMind GeoLite2, IP-API).
• Sequential Round Robin (round_robin): строгое циклическое распределение.
• Uniform Random (random): чисто случайное распределение по здоровым лобби.

Плагин поддерживает конфигурабельное «аффинити» игрока: система запоминает предыдущий лобби игрока в течение заданного времени и автоматически возвращает его туда при переподключении. Данные сохраняются атомарно на диске и переживают перезагрузку прокси.

VelocityNavigator выступает в роли диспетчера трафика с защитными системами корпоративного уровня:

• Трехсостоятельная цепь разрыва (CLOSED ➔ OPEN ➔ HALF-OPEN): если количество ошибок или таймаутов превышает порог, цепь переходит в состояние OPEN, мгновенно прекращая маршрутизацию на сервер до появления игроков на экране ожидания.
• Экспоненциальный откат с джиттером: предотвращает эффект «наводнения» при восстановлении бэкенда.
• Многовекторные проверки здоровья: активный пинг, проверка TCP-сокетов, запросы MOTD и проверка сигналов бэкенд-моста.
• Система слива (/vn drain <server>): безопасно выводит лобби из сети, прекращая прием новых игроков и переходы /lobby, пока текущие игроки не завершат сессию.
• Фолбеки пустых лобби: при недоступности всех лобби в пуле игроки направляются на резервный сервер или получают локализованное уведомление.

Плагин обеспечивает единый опыт навигации для всех платформ Minecraft:

• Нативные Java-диалоги (Minecraft 1.21.6+ & Paper 1.21.7+): современные интерфейсы без мерцания предметов и лишнего визуального шума.
• Java Chest Inventory GUI: многостраничный инвентарь с динамическим обновлением количества игроков и поддержкой криптографических токенов для защиты от клик-спуфинга.
• Нативные формы Bedrock / Geyser: специализированные диалоги для управления через сенсорные экраны и контроллеры.
• Интерактивный чат-селектор MiniMessage: легкий текстовый выбор с поддержкой богатого форматирования и подсказок при наведении.

В отличие от аналогов, плагин полностью самодостаточен и не требует Citizens или сторонних протокольных хаков:

• NPC без NMS: создание легковесных NPC на бэкендах, совместимых с Paper 1.16.5 — 26.3+ и Folia без привязки к версии кода.
• YAML-меню бэкенда: создание кастомных инвентарей напрямую в папке плагина без сторонних GUI-плагинов.
• Интеграция с PlaceholderAPI: доступ к данным прокси на бэкендах (например, %velocitynavigator_lobby%, %velocitynavigator_queue_position%).

Встроенные инструменты для работы сети:

• Очередь вместимости: игроки попадают в очередь на удерживающем сервере при перегрузке всех лобби с динамическим счетчиком и временем ожидания.
• Кросс-серверная группа: создание групп, управление приглашениями и автоматическое следование за лидером при переходе между мирами.
• Техническое обслуживание: глобальное или индивидуальное отключение бэкендов с кастомными причинами кика и интеграцией в MOTD.
• Кластеризация через Redis: синхронизация состояний цепей разрыва и липких сессий между несколькими узлами Velocity через Redis Pub/Sub.

Плагин включает современные механизмы защиты:

• Хеширование Argon2id: защита паролей с высокой защитой от перебора.
• Ограничение частоты запросов (Rate Limiting): блокировка попыток подбора паролей по аккаунтам и глобально.
• Карантин в лобби ожидания: изоляция неавторизованных игроков с полным ограничением действий.
• Нативные формы авторизации для Bedrock через Floodgate.
• Токены сессий: запоминание авторизованных игроков при быстрых переподключениях.

Инструменты для администраторов сети:

• HTML-панель управления: веб-интерфейс на выделенном порту со статистикой лобби, распределением маршрутов и метриками.
• Prometheus & Grafana: нативный эндпоинт /metrics для экспорта данных о задержках, очередях и сбоях.
• Валидация конфигурации: команды /vn config validate и /vn menu validate для глубокой проверки синтаксиса и логики перед применением.

Плагин поддерживает 15 встроенных языков, включая русский (ru). Пользовательские файлы могут быть добавлены в plugins/velocitynavigator/languages/.

1. Поместите VelocityNavigator-4.6.0.jar в папку plugins прокси Velocity.
2. Запустите прокси один раз для генерации конфигов, затем остановите его.
3. В файле plugins/velocitynavigator/navigator.toml укажите список лобби-серверов.
4. Выполните /vn config validate в консоли для проверки правильности настроек.
5. Запустите прокси и используйте команду /lobby в игре для проверки маршрутизации.

Для активации функций бэкенда (NPC, YAML-меню, инвентарные селекторы) скопируйте тот же JAR-файл в папку plugins каждого сервера Paper, Spigot или Folia.

[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