Плагин конфликтует с модом: как найти причину

MAATRIX GAMES

Поставили новый плагин или мод, перезапустили сервер — и что-то поехало: то команды перестали работать, то мир крашится при заходе в конкретную локацию, то сервер вообще не стартует и сыпет ошибками в консоль. Первая мысль — «что-то с чем-то конфликтует», но дальше начинается самое неприятное: непонятно, с чем именно. Разберём методичный способ найти виновника, а заодно закроем частое заблуждение о том, что вообще может конфликтовать друг с другом на Minecraft-сервере.

Плагин с модом обычно не конфликтует — и вот почему

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

Моды (Forge, Fabric) переписывают код самой игры и требуют такого же мод-клиента у игрока. Плагины (Bukkit/Spigot/Paper API) работают поверх серверной логики и рассчитаны на ванильный клиент. Это две разные экосистемы с разным API и разным жизненным циклом — плагин физически не может «зацепиться» за внутренности мода, потому что не умеет его видеть. Разницу между этими подходами разбирали подробно в статье Forge, Fabric или Paper: что выбрать для сервера.

Есть исключение — гибридные сборки вроде Mohist, Magma или Arclight, которые запускают Forge-моды поверх Bukkit-совместимого ядра и позволяют одновременно ставить и моды, и плагины. Именно там прямой конфликт мод↔плагин реально возможен: оба лезут в одни и те же события, и гибридное ядро вынуждено как-то их совмещать, что не всегда получается чисто. Если у вас именно такая сборка — держите это в уме, но помните, что она сама по себе экспериментальна и менее стабильна, чем чистый Forge/Fabric или чистый Paper.

Если у вас обычный Paper — конфликтует плагин с плагином. Если Forge или Fabric — мод с модом. В подавляющем большинстве случаев проблема именно там, и дальше разберём диагностику для этого сценария, с поправкой на гибридные сборки где это уместно.

Читаем стектрейс: сервер сам называет виновника

Прежде чем что-то отключать вручную, загляните в лог — часто ответ уже там. Место, где искать, зависит от платформы:

• Paper/Spigot — logs/latest.log в корне сервера, ошибка при крашах плагина обычно начинается со строки вида Could not pass event X to plugin Y.
• Forge — logs/latest.log и отдельно crash-reports/crash-YYYY-MM-DD_HH.MM.SS-server.txt при полном падении.
• Fabric — тот же logs/latest.log, но с префиксом Fabric в трейсе и списком загруженных модов в начале файла.

Смотрите последние 100-150 строк перед падением:

tail -n 150 logs/latest.log

Ключевое, что нужно найти в стектрейсе — не саму ошибку (NullPointerException, ClassCastException и подобное — это симптом, не причина), а строку, где называется конкретный плагин или мод. У плагинов Bukkit/Paper это обычно явная фраза:

[Server thread/ERROR]: Could not pass event PlayerMoveEvent to WorldGuard v7.0.9 (is it up to date?)
Caused by: java.lang.NullPointerException
	at com.someplugin.SomeListener.onMove(SomeListener.java:42)

Здесь виден и плагин, у которого сработал листенер (WorldGuard), и класс, откуда пришла ошибка. Если в трейсе подряд фигурируют классы из двух разных плагинов (один вызывает API другого через Vault, ProtocolLib или похожие зависимости) — конфликт скорее всего именно между ними.

У модов (Forge/Fabric) трейс выглядит иначе — ищите строку at net.minecraftforge.fml... или Mixin apply failed (характерно для Fabric-модов с миксинами — это когда два мода патчат один и тот же метод игры и патчи пересекаются несовместимо). В крэш-репорте Forge отдельно есть секция "A detailed walkthrough of the error", где почти всегда явно назван мод-виновник или пара конфликтующих модов.

Если в логе тишина — сервер не падает, а просто ведёт себя странно (не срабатывают команды, дублируются эффекты, ломается генерация) — переходите сразу к следующему шагу, потому что не все конфликты дают трейс.

Бинарный поиск виновника: отключаем по одному

Когда лог не дал прямого ответа (или дал, но хочется убедиться), самый надёжный способ — методичный бинарный поиск. Идея простая: делите список подозреваемых пополам, отключаете половину, перезапускаете, смотрите — воспроизводится ли проблема. Так за log₂(N) перезапусков находится виновник даже среди полусотни плагинов или модов.

Порядок действий для плагинов на Paper/Spigot:

1. Остановите сервер.
2. Переместите половину .jar из plugins/ во временную папку (не удаляйте — просто выносите за пределы plugins/, чтобы сервер их не подхватил).
3. Запустите сервер, воспроизведите проблему.
4. Если баг пропал — виновник в отключённой половине, возвращайте её обратно частями. Если баг остался — виновник в оставшейся половине, отключайте её тем же способом.
5. Повторяйте, сужая круг подозреваемых, пока не останется 1-2 плагина.

mkdir plugins_disabled
mv plugins/{ChestShop,EssentialsX,LuckPerms}.jar plugins_disabled/

Для модов на Forge/Fabric процесс аналогичный — папка mods/ вместо plugins/. Разница: у модов чаще есть жёсткие зависимости друг от друга (многие требуют библиотечный мод вроде Fabric API), поэтому отключайте пачками с учётом зависимостей — иначе получите новый, посторонний краш «библиотека не найдена», который только запутает диагностику.

Совет по экономии времени: если мир генерируется долго или на сервере есть игроки, которых не хочется постоянно дёргать, делайте бинарный поиск на копии сервера — склонируйте папку на тестовый инстанс или временный порт, а не мучайте продакшен перезапусками. Подробнее про то, как отличать сетевые сбои от логических ошибок плагина по логу — в статье про логи и краш-репорты.

Проверка версий — самая частая скрытая причина

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

Что проверять:

• Версия Minecraft. Плагин, собранный под 1.20.1, может формально загрузиться на 1.20.4 (Paper часто терпимо относится к минорным расхождениям), но внутренние API-вызовы, завязанные на изменившиеся классы игры, начнут падать там, где плагин обращается к новому или переименованному элементу.
• API-версия плагина (api-version в plugin.yml). Если она сильно отстаёт от версии сервера, часть событий может не долетать до плагина или долетать в устаревшем формате.
• Версия Forge/Fabric Loader, под которую собран мод — у модов эта привязка обычно строже, и несовпадение чаще даёт явную ошибку при старте, а не тихий баг в рантайме.
• Совместимость между зависимостями. Плагин A может требовать Vault не ниже определённой версии, а у вас стоит старая — тогда конфликт формально «между A и Vault», хотя выглядит как конфликт A с чем-то посторонним.

Проверить версию, под которую собран .jar, можно без распаковки — большинство репозиториев (SpigotMC, Modrinth, CurseForge) прямо в карточке файла указывают целевую версию игры и лоадера. Если скачивали .jar без сопроводительной информации — распакуйте архив (.jar — это тот же .zip) и загляните в plugin.yml или fabric.mod.json/mods.toml, где явно прописана целевая версия.

unzip -p ВашПлагин.jar plugin.yml | grep -E 'api-version|version'

Если после апдейта сервера на новую версию Minecraft что-то посыпалось массово — почти всегда это не конфликт, а именно рассинхрон версий. Отдельно тема автообновлений и того, почему слепо обновлять всё разом рискованно, разобрана в статье про автообновление модов на сервере.

Типичные конфликты между модами

Зная общую механику поиска, полезно понимать, какие конкретно виды конфликтов встречаются чаще всего у модов на Forge и Fabric:

• ID-коллизии — два мода регистрируют предметы, блоки или сущности под одинаковыми идентификаторами. После перехода на namespaced ID это стало реже, но всё ещё встречается у старых или редко обновляемых модов.
• Mixin-конфликты (в основном Fabric, но встречается и в Forge) — два мода патчат один и тот же метод ванильного кода через систему миксинов, и порядок применения патчей даёт непредсказуемый результат. В логе это выглядит как Mixin apply failed или краш сразу при загрузке класса.
• Конфликты конфигурации мира — два мода генерации (руды, биомы, структуры) пытаются занять одну и ту же нишу, из-за чего появляются артефакты рельефа или дублирующиеся структуры.
• Пересечение горячих клавиш и GUI-слоёв — редко валит сервер, но раздражает игроков: два мода вешают интерфейс на одну клавишу или перекрывают друг друга визуально.
• Несовместимые версии библиотечных модов — Fabric API, Cloth Config, Architectury должны быть строго определённой версии относительно требований самого капризного мода в сборке. Часто «конфликт двух модов» на деле решается просто обновлением общей библиотеки.

Модпак-платформы CurseForge и Modrinth частично решают эту проблему на этапе сборки, помечая известные несовместимости в описании модов — стоит проверять этот раздел перед добавлением нового мода в уже работающую сборку.

Типичные конфликты между плагинами

На стороне Bukkit/Spigot/Paper картина немного другая — конфликты чаще логические, а не технические:

• Несколько плагинов перехватывают одно и то же событие с разным приоритетом. Защита территории (WorldGuard) и кастомный плагин с своей системой прав могут по-разному решать, кто отменяет действие игрока — EventPriority в Bukkit API определяет порядок обработки, и если он выставлен неверно у одного из плагинов, второй может не успеть сработать вообще.
• Дублирующиеся команды. Два плагина регистрируют одинаковую команду (/tp, /home, /spawn) — сервер использует ту, что зарегистрировалась последней, и вторая молча перестаёт работать. Диагностируется командой /plugins в консоли.
• Общие зависимости с разными ожиданиями. Vault как прослойка для экономики — классический пример: если плагин экономики и плагин с правами рассчитаны на разное поведение API, транзакции могут задваиваться или теряться.
• Гонки на старте сервера (load order). Порядок загрузки определяется зависимостями в plugin.yml (depend/softdepend), но если плагин A использует API плагина B без явного указания зависимости, он может обратиться к ещё не загруженному B и упасть с NoClassDefFoundError.

Для точечной диагностики на Paper полезен встроенный профилировщик — команда /timings report (или более актуальный плагин Spark) показывает, какой плагин сколько времени тратит на обработку тика и событий. Это не всегда прямо указывает на конфликт, но быстро подсвечивает подозрительно тяжёлый плагин, если проблема скорее в производительности — тему TPS разбирали отдельно в статье про оптимизацию модов и TPS на Minecraft-сервере.

Частые вопросы