MCCompatibilityChecker

Русский | English | Español | Tiếng Việt | Português | Türkçe | Indonesia | 中文

Автоматическая диагностика конфликтов модов Minecraft. Скрипт сам запускает игру, ловит вылеты, читает краш-логи, находит виновный мод и изолирует его — в цикле, пока сборка не заработает.

Работает через Legacy Launcher (наследник TLauncher). Запуск игры и обнаружение вылетов — через GUI лаунчера; анализ ошибок — по стандартным логам Fabric/Forge/Minecraft.

Зачем

Собрал 200 модов, запустил — краш. Открыл лог — стена текста. Убрал мод наугад — другой краш. Знакомо?

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

На выходе — список виновников и рабочая сборка.

Статус проекта

Текущая версия — активная разработка (experimental).

• На текущий момент обработка крупных кластеров несовместимостей может быть нестабильна.
• Для больших сборок рекомендуется сначала сделать резервную копию mods и использовать отчёты/логи после каждого прогона.

Как работает

Диагностика проходит в несколько этапов. Каждый следующий включается, только если предыдущий не решил проблему:

1. Базовый Анализ — читает краш-лог, ищет кандидатов в тексте ошибки и изолирует их в dependency-priority порядке
2. Mixin-анализ — парсит ошибки Mixin apply failed и @Mixin target not found, определяет source- и target-мод, проверяет каждый за 1–2 запуска
3. Наслоение — убирает все моды, оставляет core-библиотеки, добавляет остальные слоями (по уровням зависимостей, экспоненциальными батчами). При вылете батча — triage и Изоляция внутри батча
4. Изоляция — fallback: dependency-aware уровни, экспоненциальные/бинарные пробы на ранних уровнях и линейная Изоляция на поздних
5. Recovery — если 3+ «виновника» дали одну и ту же Mixin-ошибку, скрипт проверяет, не были ли они ложными, и ищет настоящий root-cause

Подробное описание алгоритма — в doc/Алгоритм.md.

Требования

• Windows (используется Win32 UI Automation)
• PowerShell 5.1+
• Legacy Launcher (llaun.ch)
• Minecraft с Fabric или Forge

Dev-зависимости

• PSScriptAnalyzer (модуль PowerShell, нужен для checker.ps1)
• Python 3.x (нужен для проверки локализаций через tools/Check-Localization.py)
• Pester (модуль PowerShell, нужен для тестов checker.ps1, если не используется -NoPester)

Установка PSScriptAnalyzer:

Install-Module PSScriptAnalyzer -Scope CurrentUser

Быстрый старт

1. Клонируйте репозиторий или скачайте архив из последнего релиза:

   git clone https://github.com/Artemonim/MCCompatibilityChecker.git
   

2. Скопируйте config.ini в config.local.ini и укажите путь к папке с модами:

   [Paths]
   GameModsDir=%APPDATA%\.tlauncher\legacy\Minecraft\game\mods

3. Откройте Minecraft Launcher.

4. Напишите ./run.ps1 или ./run.ps1 -verbose в PowerShell-консоль.

5. Наведите мышку на кнопку запуска клиента в лаунчере.

6. Нажмите Enter чтобы отправить консольную команду и Чекер получил бы координаты кнопки.

Конфигурация

Настройки задаются в config.ini (дефолты) и config.local.ini (ваши переопределения, игнорируется git).

Параметр	Описание
GameModsDir	Папка с модами, которую использует игра
StorageModsDir	Основное хранилище модов (опционально)
LogPath	Путь к лог-файлу лаунчера (пусто — автоподбор)
LauncherExePath	Путь к исполняемому файлу лаунчера (пусто — подключиться к запущенному)
EnableMixinAnalysis	Включить этап Mixin-анализа (по умолчанию: true)
EnableLayering	Включить Наслоение и субтрактивную Изоляцию (по умолчанию: true)
EnableRecovery	Включить Recovery фантомных виновников (по умолчанию: true)
Language	Язык консольных сообщений ([Localization].Language). Если пусто: авто из языка ОС, fallback en

Доступные локали сейчас: en, ru. Подготовлены заглушки под: tr_TR, pt_BR, vi, es_ES, id_ID, zh-CN. Поиск crash-окна лаунчера по умолчанию автоматически собирает паттерны из scripts/locales/*.psd1 (Ui.CrashWindowTitlePatterns). Сейчас в комплекте есть шаблоны Something broke..., Something went wrong... и Что-то сломалось.... Для новых языков достаточно добавить этот список в соответствующий locale-файл. Если у вас другой заголовок окна лаунчера, можно явно задать CrashWindowTitlePatterns в [Profile:<name>] и запустить с -Profile <name>.

Основные параметры запуска

.\run.ps1 -Help          # Краткая справка
.\run.ps1 -HelpFull      # Полная техническая справка

Флаг	Описание
-LauncherExePath <path>	Путь к лаунчеру (если не указан в конфиге)
-NoLegacy	Не сохранять изолированные моды — удалять
-GameLegacy	Хранить копии изолированных модов в папке игры
-DryRun	Показать, что будет сделано, без реального выполнения
-Verbose	Подробные логи (в консоль и MCCC.log)
-UseLinearIsolation	Линейный поиск вместо бинарного (медленнее, но проще)
-NoCache	Отключить session cache (повторно проверять даже ранее успешные конфигурации)
-OutcomeTimeoutSeconds <sec>	Время ожидания исхода после нажатия Play (по умолчанию: 60)
-ThoroughStabilityCheck	Увеличить окно проверки стабильности запусков
-AutoHandleFabricDialog <bool>	Авто-маршрутизация Fabric-диалогов без missing deps в debug pipeline
-IgnoreModIds <id1,id2,...>	Игнорировать указанные mod id в compatibility cleanup
-Profile <name>	Применить профиль из [Profile:<name>] в config.ini / config.local.ini
-Update <path>	Режим обновления: обрабатывает якорный .jar из StorageModsDir и все .jar новее/равные по LastWriteTime

Режим обновления (-Update)

Запуск:

.\run.ps1 -Update "D:\ModsStorage\SomeMod-1.5.0.jar"

Что делает режим:

• На старте выполняет проверочный запуск игры.
• Если сразу получен crash/no-launch: показывает модальный выбор Устранить / Отмена.
  • Устранить -> запускает стандартный пайплайн Auto-Run-LegacyLauncher.ps1.
  • Отмена -> завершает update-режим без изменений.
• Если получен Fabric-диалог с missing dependencies: показывает модальный выбор Устранить / Отмена.
  • Устранить -> запускает стандартный пайплайн Auto-Run-LegacyLauncher.ps1.
  • Отмена -> завершает update-режим без изменений.
• Берёт из StorageModsDir якорный файл и все .jar с LastWriteTime >= anchor.
• Делит кандидаты на 2 группы:
  • replaceable — для мода найдена старая версия (в StorageModsDir и/или GameModsDir), значит есть rollback.
  • new-only — старых версий не найдено.
• Сначала применяет только replaceable-батч:
  • старые версии переносит/бэкапит в Updated/<MinecraftVersion>,
  • в игре удаляет старые версии и копирует новые.
• После replaceable-батча делает post-check:
  • прицельный rollback по логам,
  • затем rollback-наслоение (1, 2, 4, ...),
  • затем минимизацию (по одной старой версии), чтобы оставить минимально нужный набор.
• Затем добавляет new-only-батч (моды без доступного rollback).
• После new-only-батча выполняется post-check запуска:
  • при неуспешном запуске предлагается переход в стандартный пайплайн Auto-Run-LegacyLauncher.ps1,
  • при успешном запуске без активного rollback-набора update-режим завершается без дополнительного финального перезапуска.

Проверка скриптов и локализаций

checker.ps1 проверяет:

• PowerShell-скрипты через PSScriptAnalyzer
• ассеты локализации через tools/Check-Localization.py
• Write-Verbose/debug-only строки считаются служебными, остаются на английском и не входят в coverage локализации

Примеры:

.\checker.ps1             # Полная проверка (включая локали)
.\checker.ps1 -NoLocales  # Пропустить проверку локалей
.\checker.ps1 -NoPester   # Пропустить тесты Pester
.\checker.ps1 .\scripts\Shared-FileOps.ps1  # Проверить только указанный файл/путь

Поведение при отсутствии Python:

• По умолчанию это ошибка (чекер завершится с кодом ошибки), чтобы не пропустить поломку системы локализации.
• Если вы не работаете с локализацией, используйте -NoLocales.

Структура проекта

├── run.ps1                  # Точка входа
├── config.ini               # Конфигурация по умолчанию
├── checker.ps1              # Линтер + проверка локализаций
├── scripts/
│   ├── Auto-Run-LegacyLauncher.ps1      # Оркестратор: запуск, мониторинг, цикл
│   ├── Auto-Run-LegacyLauncher.Update.ps1 # Режим обновления (anchor + newer jars)
│   ├── Check-Mod-Compatibility.ps1      # Базовый Анализ
│   ├── Analyze-MixinErrors.ps1          # Mixin-анализ
│   ├── Layer-Mods.ps1                   # Наслоение
│   ├── Isolate-Incompatible-Mod.ps1     # Изоляция (fallback)
│   ├── Recover-PhantomCulprits.ps1      # Recovery
│   └── Shared-*.ps1                     # Общие модули
├── tools/
│   ├── Analyze-JarDependencies.ps1      # Поиск зависимостей внутри JAR-файлов модов
│   ├── Analyze-JarDependencyMap.ps1     # Построение полной карты зависимостей и отчётов
│   ├── Check-Localization.py            # Валидация файлов локализации
│   ├── Count-ModMinecraftVersions.py    # Подсчёт модов по версиям Minecraft
│   ├── Find-SuspiciousDuplicateMods.py  # Поиск подозрительных дубликатов модов
│   └── Restore-ModsFromLog.ps1          # Восстановление модов из лога изоляции
└── doc/
    └── Алгоритм.md                      # Детальное описание алгоритма

Куда деваются изолированные моды

По умолчанию изолированные моды перемещаются в папку Legacy внутри StorageModsDir (или GameModsDir, если хранилище не задано). Это позволяет легко восстановить их вручную, если результат диагностики вас не устроит.

Флаг -NoLegacy удаляет моды безвозвратно. Флаг -GameLegacy дополнительно сохраняет копию в папке игры.

Финальный отчёт (Summary)

После завершения скрипт выводит отчёт: время работы, список виновников по этапам, восстановленные моды (если был Recovery) и текущий список изолированных модов.

Ограничения

• Работает только с Legacy Launcher (GUI-автоматизация привязана к его интерфейсу)
• Только Windows (Win32 API для управления окнами)
• Диагностика требует многократных запусков игры — на больших сборках это может занять значительное время
• При крупных кластерах несовместимостей возможны нестабильные прогоны и ранний fallback/остановка диагностики
• Recovery-этап пока экспериментальный, но включён по умолчанию ([Stages].EnableRecovery=true)

Поддержка

Если вам нравится этот проект, вы можете поддержать автора на Sponsr.