MCLGuard — античит: как работает и настройка

Как работает

MCLGuard анализирует поведение игроков на сервере в реальном времени и реагирует на признаки читов. Кратко о движке:

Источники данных. Движение, бой и работа с блоками разбираются из Bukkit-событий (главный поток). CPS, Timer, BadPackets и тайминг копания — из сетевого слоя (PacketEvents).
VL (Violation Level). Каждая проверка при срабатывании добавляет игроку VL. При достижении порога применяется наказание, а VL со временем затухает (vl-decay-seconds), если нарушений больше нет.
Оповещения по порогу. Стафф в чате, Discord и отчёт в каталог отправляются только при достижении порога VL — чтобы не засорять чат промежуточными флагами. Полный поток срабатываний виден по /mclguard verbose.
Общий бан-лист (сетевой эффект). Авто-баны серверов складываются в общий список; при входе игрока плагин предупреждает стафф, если игрок забанен на нескольких серверах. Бесплатно для всех активных лицензий.
ИИ-анализ инцидентов (второй эшелон). Когда VL добивает до порога, плагин отправляет компактную числовую сводку по игроку (CPS, стабильность кликов, дельты движения, углы обзора, пинг) в каталог, а тот просит нейросеть вынести вердикт: чит / подозрительно / чисто, тип чита, вероятность и понятную причину. Это не замена мгновенным проверкам — это второй взгляд, который отсекает ложные срабатывания из-за лагов и даёт стаффу объяснение. Настраивается в разделе ai.
Устойчивость. Если сетевой слой PacketEvents не поднялся на нестандартной сборке — плагин не падает: пакетные проверки (Timer/BadPackets) отключаются, остальной детект работает. Статус виден в /mclguard info.
Связь с каталогом. При старте и раз в 30 минут плагин сверяет лицензию с каталогом (heartbeat), получает актуальный тариф, удалённые настройки из кабинета и сведения о новой версии.

Публичную статистику защиты можно получить программно — GET /api/anticheat/stats.php.

Что детектит

Категория	Проверки
Движение	Fly, Speed, NoFall, Jesus (вода), InvalidMove, Velocity (anti-KB)
Бой	Reach, KillAura (угол + мульти-аура), AutoClicker (CPS + стабильность)
Мир	Nuker, FastBreak, Scaffold
Пакеты	Timer (balance-метод), BadPackets

Пороговые значения подобраны консервативно — приоритет минимуму ложных срабатываний. Чувствительность каждой проверки настраивается в разделе checks.

Тарифы FREE и PRO

Возможность	FREE	PRO
Все детекты (движение / бой / мир / пакеты)	✅	✅
Алерты стаффу в чат, kick, ALERT_ONLY, COMMAND	✅	✅
Общий бан-лист / репутация игроков	✅	✅
Discord-webhook	—	✅
Встроенный авто-бан (`action: BAN`)	—	✅
Веб-статистика нарушений в кабинете	—	✅
ИИ-анализ инцидентов	со своим ключом OpenRouter	✅ встроенный

На тарифе FREE наказание BAN автоматически деградирует до KICK. Discord-webhook и отчёты в веб-панель на FREE не отправляются. ИИ-анализ на PRO работает «из коробки» (токен предоставляет каталог), а на FREE — если вы укажете свой ключ OpenRouter в ai.token.

Установка

Добавьте сервер в каталог (если ещё не добавлен) на mclisting.ru.

Получите лицензионный ключ в личном кабинете владельца, раздел «Античит». Бесплатная FREE-лицензия тоже выдаётся ключом.

Скачайте MCLGuard-*.jar из кабинета и положите в папку plugins/ сервера.

Запустите сервер один раз — создастся plugins/MCLGuard/config.yml.

Впишите ключ в license.key и перезапустите сервер (или выполните /mclguard reload).

Совместимость: Bukkit / Spigot / Paper, версии Minecraft 1.8–1.21. PacketEvents вшит в jar — сторонних зависимостей ставить не нужно.

Лицензия и ключ

Ключ обязателен, даже для бесплатного тарифа FREE. Без указанного и принятого каталогом ключа плагин считает лицензию неактивной и не запускает проверки. Так каждая защита привязана к конкретному зарегистрированному серверу.

Ключ имеет вид MCLG-XXXXXXXX-XXXXXXXX-XXXX и привязан к IP:port вашего сервера в каталоге — его нельзя расшарить между серверами.
Плагин сверяет ключ при старте и раз в 30 минут (heartbeat).
Если каталог временно недоступен, но лицензия ранее была валидной — плагин продолжает работать в течение офлайн-грейса (offline-grace-minutes, по умолчанию 720 мин). При холодном старте без связи с каталогом или с отклонённым/пустым ключом защита не активируется.
Текущий статус лицензии всегда виден по команде /mclguard info.

Настройка `config.yml`

Файл создаётся при первом запуске в plugins/MCLGuard/config.yml. Полный справочник ниже, а вот он целиком:

# --- Лицензия ---
license:
  key: "ВСТАВЬТЕ_КЛЮЧ_СЮДА"       # обязателен даже для FREE
  api-url: "https://mclisting.ru/api/anticheat"
  offline-grace-minutes: 720

# --- Обновления ---
update:
  notify: true
  auto-download: false

# --- Оповещения ---
alerts:
  format: "&8[&bMCLGuard&8] &f{player} &7нарушил &e{check} ..."
  cooldown-ms: 1500
  discord-webhook: ""          # только PRO

# --- Наказания ---
punishments:
  default-threshold: 20
  action: KICK                # KICK | BAN | COMMAND | ALERT_ONLY
  kick-message: "&cОтключён античитом MCLGuard\n&7Причина: &f{check}"
  ban-duration-minutes: 0    # для action: BAN, 0 = навсегда
  ban-reason: "&cЗабанен античитом MCLGuard\n&7Причина: &f{check}"
  command: "kick {player} MCLGuard: {check}"
  vl-decay-seconds: 30

# --- Проверки (enabled + чувствительность) ---
checks:
  fly:          { enabled: true, max-ascension: 0.42 }
  speed:        { enabled: true, max-horizontal: 0.36 }
  nofall:       { enabled: false }
  jesus:        { enabled: true }
  invalid-move: { enabled: true }
  velocity:     { enabled: true, min-percent: 15 }
  reach:        { enabled: true, max-distance: 3.15 }
  killaura:     { enabled: true, max-angle: 75.0 }
  autoclicker:  { enabled: true, max-cps: 20, check-consistency: true }
  nuker:        { enabled: true, max-blocks-per-tick: 3 }
  fastbreak:    { enabled: true }
  scaffold:     { enabled: true }
  timer:        { enabled: true, max-rate: 1.06 }
  badpackets:   { enabled: true }

# --- Общий бан-лист / репутация ---
reputation:
  enabled: true
  min-servers: 2
  contribute: true

# --- ИИ-анализ инцидентов (второй эшелон) ---
ai:
  enabled: false                # требует PRO ИЛИ свой ai.token
  token: ""                     # ключ OpenRouter для FREE; на PRO оставьте пустым
  min-vl: 15                     # с какого суммарного VL запускать анализ
  cooldown-seconds: 30           # кулдаун анализа на одного игрока
  mode: REPORT                  # REPORT (оповестить) | AUTOPUNISH (ещё и наказать)
  autopunish-probability: 0.9    # порог вероятности для AUTOPUNISH

# --- Прочее ---
settings:
  respect-bypass-permission: true
  movement-grace-ticks: 20
  log-to-file: true
  report-to-catalog: true

license

Параметр	По умолч.	Описание
`key`	—	Лицензионный ключ. Обязателен, в т.ч. для FREE.
`api-url`	.../api/anticheat	Адрес API каталога. Менять не нужно.
`offline-grace-minutes`	720	Сколько минут работать, если каталог недоступен (после ранее валидной проверки).

alerts

Параметр	По умолч.	Описание
`format`	—	Формат сообщения стаффу. Плейсхолдеры: `{player} {check} {vl} {type} {info}`.
`cooldown-ms`	1500	Антиспам: не чаще одного оповещения на игрока+проверку за N мс.
`discord-webhook`	пусто	Discord-webhook. Работает только на PRO; пусто = выключено.

punishments

Параметр	По умолч.	Описание
`default-threshold`	20	Общий VL, при котором применяется наказание (переопределяется у отдельных проверок).
`action`	KICK	`KICK` — кик; `BAN` — встроенный бан + кик (только PRO, иначе KICK); `COMMAND` — своя команда из консоли; `ALERT_ONLY` — только оповестить.
`kick-message`	—	Текст кика. Плейсхолдеры `{check}` и др.
`ban-duration-minutes`	0	Для `action: BAN` — срок бана в минутах (0 = навсегда).
`ban-reason`	—	Причина бана.
`command`	—	Команда для `action: COMMAND`. Подставляются `{player}`, `{check}`.
`vl-decay-seconds`	30	Через сколько секунд без нарушений VL игрока сбрасывается.

checks

У каждой проверки есть enabled (вкл/выкл); у части — параметр чувствительности. Чем «строже» значение, тем агрессивнее детект (и выше риск ложных срабатываний).

Проверка	Параметр	По умолч.	Смысл
`fly`	`max-ascension`	0.42	Макс. вертикальная скорость без прыжка/полёта.
`speed`	`max-horizontal`	0.36	Блоков/тик по горизонтали сверх допустимого.
`nofall`	`enabled`	false	Выключена по умолчанию — возможны ложные срабатывания на нестандартной геометрии.
`jesus`	`enabled`	true	Хождение по воде.
`invalid-move`	`enabled`	true	Телепорты / NaN / невозможные дельты.
`velocity`	`min-percent`	15	% ожидаемого нокбэка, ниже которого — флаг (anti-KB).
`reach`	`max-distance`	3.15	Дистанция атаки (ванилла ~3.0).
`killaura`	`max-angle`	75.0	Угол до цели, выше которого удар невозможен.
`autoclicker`	`max-cps`, `check-consistency`	20, true	Кликов/сек; низкая дисперсия интервалов = автокликер.
`nuker`	`max-blocks-per-tick`	3	Ломает слишком много блоков за тик.
`fastbreak`	`enabled`	true	Слишком быстрое разрушение блоков.
`scaffold`	`enabled`	true	Ставит блоки под собой на скорости.
`timer`	`max-rate`	1.06	Множитель ускорения игрового времени клиента.
`badpackets`	`enabled`	true	Мусорные / невозможные пакеты.

reputation

Параметр	По умолч.	Описание
`enabled`	true	Проверять входящих игроков по общему бан-листу и предупреждать стафф.
`min-servers`	2	Минимум РАЗНЫХ серверов, забанивших игрока, чтобы показать предупреждение.
`contribute`	true	Сообщать о своих авто-банах в общий список (участие в сетевом эффекте).

ai ИИ-анализ

Второй эшелон детекта. LLM вызывается только на пороговый инцидент (не на каждый пакет), с кулдауном на игрока и часовым лимитом на стороне каталога — поэтому это дёшево и не нагружает сервер.

Параметр	По умолч.	Описание
`enabled`	false	Включить ИИ-анализ. Требует тариф PRO или непустой `token`.
`token`	—	Свой ключ OpenRouter для FREE. На PRO оставьте пустым — токен предоставляет каталог, в jar он не хранится.
`min-vl`	15	Минимальный суммарный VL игрока, начиная с которого запускается анализ.
`cooldown-seconds`	30	Кулдаун между ИИ-анализами одного игрока (защита от спама запросами).
`mode`	REPORT	`REPORT` — только оповестить стафф вердиктом; `AUTOPUNISH` — при уверенном чите ещё и наказать (действием из `punishments`).
`autopunish-probability`	0.9	Порог вероятности [0.0–1.0] для `AUTOPUNISH`: наказываем при `probability ≥ порога`.

Вердикт ИИ приходит стаффу в чат, в Discord (PRO) и в violations.log. ИИ — вспомогательный слой: окончательные пороги и мгновенные проверки остаются за движком VL.

settings и update

Параметр	По умолч.	Описание
`settings.respect-bypass-permission`	true	Не проверять игроков с правом `mclguard.bypass`.
`settings.movement-grace-ticks`	20	Тиков после входа/телепорта, в течение которых проверки движения молчат.
`settings.log-to-file`	true	Логировать нарушения в `violations.log`.
`settings.report-to-catalog`	true	Слать статистику нарушений в каталог (только PRO, для веб-панели).
`update.notify`	true	Уведомлять админов о новой версии при входе и в консоли.
`update.auto-download`	false	Скачивать новую версию в `plugins/update/` (применится после перезапуска).

Часть порогов и проверок можно переопределять удалённо из личного кабинета — такие оверрайды приходят вместе с проверкой лицензии и имеют приоритет над локальным config.yml.

Команды и права

Команда /mclguard (алиасы /mclac, /guard, /ac):

Подкоманда	Действие
`alerts`	Вкл/выкл получение оповещений о нарушениях.
`verbose`	Показывать все срабатывания (не только по порогу).
`violations <ник>`	История нарушений игрока.
`check`	Состояние проверок.
`info`	Статус лицензии, тариф, состояние пакетного слоя, версия.
`reload`	Перечитать `config.yml`.

Право	По умолч.	Описание
`mclguard.admin`	op	Полный доступ к командам.
`mclguard.alerts`	op	Получать оповещения о нарушениях.
`mclguard.bypass`	false	Полное игнорирование проверок (админы/стафф).
`mclguard.notify.attach`	op	Оставаться в списке оповещений между входами.

Вопросы по подключению — поддержка. Разработчикам интеграций — публичный API мониторинга.

MCLGuard — античит