Полное руководство

CoolPackHelper - помощник для сборок, рассчитанный на две аудитории:

• Игроки получают понятное локализованное объяснение, если настроенные моды отсутствуют или имеют неподходящую версию, могут открыть официальные ресурсы проектов и установить поддерживаемые файлы через защищённый процесс.
• Авторы сборок получают внутриигровую рабочую область, в которой можно создать и проверить все требования без ручного редактирования JSON.

Руководство описывает версию для Minecraft 1.21.1 и NeoForge 21.1.x. Требуется Java 21.

Содержание

1. Назначение и термины
2. Установка
3. Сценарий игрока
4. Быстрый старт автора сборки
5. Внутриигровая рабочая область
6. Как определяется наличие мода
7. Интерфейс требований для игрока
8. Справочник конфигурации
9. Типы источников загрузки
10. Безопасность загрузки
11. Метаданные и ресурсы проекта
12. Сканирование Modrinth и CurseForge
13. Локализация
14. Черновой машинный перевод
15. Резервные копии, история и откат
16. Файлы и распространение сборки
17. Валидация, миграция и восстановление
18. Полные примеры
19. Решение проблем
20. Границы версии 1.0

1. Назначение и термины

Требование - настроенная автором сборки запись мода. Она может быть обязательной или рекомендуемой. CoolPackHelper проверяет включённые записи после того, как NeoForge дошёл до главного меню.

Ресурс проекта - ссылка, открываемая в браузере: страница проекта, репозиторий, баг-трекер, wiki, Discord, страница пожертвований и т. п. Наличие такой ссылки само по себе не разрешает автоматическую установку файла.

Источник загрузки описывает, как CoolPackHelper должен найти или открыть мод. Источник может разрешаться через API официальной платформы, указывать на asset в GitHub Releases, прямой HTTPS-файл либо оставаться обычной страницей.

Черновик окна - изменения внутри отдельного окна редактора. Кнопка сохранения этого окна применяет черновик к рабочей конфигурации в памяти. Сам coolpackhelper.json записывается отдельным действием «Сохранить конфигурацию» в верхней панели.

CoolPackHelper не заменяет зависимости NeoForge. Если загрузчик останавливает запуск до главного меню из-за отсутствующей жёсткой зависимости, клиентский экран требований ещё не может появиться. Мод предназначен для требований уровня сборки, при которых игра способна дойти до интерфейса и объяснить игроку дальнейшие действия.

2. Установка

Для игрока

1. Установите Minecraft 1.21.1.
2. Установите совместимую версию NeoForge 21.1.x.
3. Настройте запуск экземпляра на Java 21.
4. Поместите JAR CoolPackHelper в папку mods экземпляра.
5. Запустите Minecraft.

CoolPackHelper рассчитан прежде всего на клиентскую часть сборки. На выделенном сервере он может загрузиться, однако меню и инструменты автора там отключены; для показа клиентских подсказок серверу этот мод не требуется.

Для автора сборки

Один раз запустите рабочий экземпляр. Будут созданы:

• config/coolpackhelper.json - распространяемая конфигурация сборки;
• config/coolpackhelper.schema.json - JSON Schema для внешних редакторов.

Демонстрационные записи в новом конфиге отключены. Предупреждение не появится, пока автор не включит и не настроит хотя бы одно невыполненное требование.

3. Сценарий игрока

При открытии главного меню CoolPackHelper проверяет конфигурацию, вычисляет невыполненные требования и применяет выбранную политику показа.

Если требуется внимание, сначала открывается компактное окно поверх размытого главного меню. Элементы в заголовке позволяют закрыть или развернуть окно; двойное нажатие по заголовку также переключает компактный и полный режимы. В полном режиме доступны:

• фильтры «Все», «Обязательные» и «Рекомендуемые»;
• прокручиваемый список отсутствующих модов и неверных версий;
• кликабельная карточка каждого мода;
• компактное действие загрузки при наличии источника;
• открытие папки mods и повторная проверка;
• массовая установка подходящих файлов с доверенных платформ.

Карточка открывает подробное локализованное описание, технические требования, авторов, лицензию, иконку и ресурсы проекта. GitHub, Discord, Patreon, wiki, страница проекта и другие ссылки кликабельны и используют стандартное подтверждение Minecraft перед открытием браузера. Адреса http(s)://, написанные автором прямо в описании, также извлекаются в список ресурсов. Источник загрузки не запускается скрытно, а переходит в интерфейс проверки CoolPackHelper.

После установки файлов Minecraft нужно перезапустить: NeoForge не может подключить новый мод к уже работающему процессу.

4. Быстрый старт автора сборки

1. Откройте меню NeoForge «Моды».
2. Нажмите CoolPackHelper Editor. Стандартная кнопка конфигурации у CoolPackHelper открывает ту же рабочую область.
3. В основных настройках задайте постоянный ID сборки, название, версию, политику показа и язык.
4. Откройте «Моды и загрузки».
5. Создайте записи вручную, импортируйте локальные JAR либо выполните отдельное сканирование платформы.
6. Для каждой включённой записи проверьте способ обнаружения, категорию, описания, метаданные и источники.
7. Откройте предпросмотр требований и проверьте обычный, компактный и маленький оконный режимы.
8. Исправьте все ошибки валидатора.
9. Сохраните черновики открытых окон, затем нажмите «Сохранить конфигурацию» в верхней панели.
10. Добавьте config/coolpackhelper.json в экспорт сборки.

Не включайте автоматически созданный или найденный сканером черновик без проверки. Статус «Не найдено» означает отсутствие точного совпадения конкретного JAR, а не гарантированное отсутствие проекта на платформе.

5. Внутриигровая рабочая область

Редактор работает как небольшая IDE/оконная среда внутри игры:

• инструменты и документы модов открываются в самостоятельных окнах;
• окна перетаскиваются за заголовок и изменяются за края;
• двойной клик по заголовку разворачивает или восстанавливает окно;
• окно можно свернуть, восстановить и закрыть;
• вкладки на нижней панели можно закрывать без открытия и переносить в нужном порядке;
• вкладку можно закрепить, защитив её позицию и случайное закрытие;
• одновременно можно редактировать несколько модов;
• прокрутка сохраняет доступность элементов при большом GUI Scale и низком разрешении.

Два уровня сохранения

Это принципиально важное различие:

1. «Сохранить» внутри окна применяет документ к рабочей конфигурации. После успешного сохранения окно закрывается без повторного предупреждения. Сообщение появляется только при новых неприменённых изменениях.
2. «Сохранить конфигурацию» проверяет всю рабочую область и записывает применённые изменения в config/coolpackhelper.json.

Статус сверху различает несохранённые черновики окон, применённую, но ещё не записанную конфигурацию и полностью сохранённое состояние. При выходе показывается подтверждение, соответствующее реальной ситуации.

Основные настройки

Здесь задаются:

• ID, имя и версия сборки;
• политика автоматического показа;
• использование языка игры либо фиксированной локали;
• фиксированный и резервный языки;
• максимальное число пакетов резервных копий установок.

Моды и загрузки

Список поддерживает поиск и сортировку. Документ отдельного мода разделён на четыре вкладки:

• Основное - название, mod ID, диапазон версий, маска файла, включение и категория;
• Описания - отдельный текст для каждой локали и создание чернового машинного перевода;
• Загрузки - любое число источников; сначала показываются базовые поля, расширенные параметры целостности открываются отдельно;
• Метаданные - иконка, авторы, лицензия, главная страница, исходный код, issues, wiki, Discord и пожертвования, а также импорт с платформ.

Новая ссылка создаётся как временный черновик. Отмена удаляет только эту новую ссылку и не затрагивает остальные изменения документа.

Остальные инструменты

• Переводы меню - все настраиваемые надписи экрана требований для каждой локали.
• Импорт папки mods - чтение локальных метаданных NeoForge и создание отключённых записей.
• Сканирование Modrinth - поиск точных совпадений по SHA-1.
• Сканирование CurseForge - поиск по нормализованным fingerprint; нужен одобренный 3rd Party API key.
• История установок - просмотр, откат и удаление уже откаченных записей.
• Предпросмотр требований - реальный интерфейс, который увидит игрок.
• Валидация - список ошибок с переходом по нажатию к нужному моду и разделу.

6. Как определяется наличие мода

Проверяются только записи, у которых enabled не равен false.

Предпочтительный способ: modId

Если указан modId, CoolPackHelper ищет точный ID в списке реально загруженных NeoForge-модов. Это наиболее надёжный способ.

• ID отсутствует → MISSING/«Не установлен».
• ID присутствует, versionRange пуст → требование выполнено.
• ID присутствует, версия не входит в диапазон → WRONG_VERSION.

Если указан modId, похожее имя JAR не считается выполнением требования. Так повреждённый, отключённый или посторонний файл не скрывает проблему загрузки.

Резервный способ: filePattern

filePattern становится самостоятельным детектором только при пустом modId. Проверяются имена обычных файлов непосредственно в mods:

• * — любое количество символов;
• ? — один символ;
• регистр не учитывается.

Пример: private-addon-1.21.1-*.jar.

Совпадение имени не подтверждает, что мод загрузился, и не позволяет надёжно проверить его версию. Используйте modId, если JAR содержит корректные метаданные NeoForge.

Диапазоны версий

versionRange использует Maven-синтаксис:

Ориентируйтесь на версию, которую показывает NeoForge. Публичное название релиза и версия внутри JAR могут различаться.

7. Интерфейс требований для игрока

category управляет визуальным смыслом записи:

• REQUIRED - красный акцент и подпись обязательного мода;
• RECOMMENDED - янтарный акцент и подпись рекомендуемого мода.

Обе категории носят информационный характер: игрок может закрыть окно. Поэтому в описании рекомендуемого мода полезно объяснить, что именно будет потеряно при отказе.

Подробный интерфейс адаптивен. На широком экране описание/технические данные и ресурсы расположены в двух колонках. На узком экране блоки становятся вертикальными. Длинное описание и большой список ссылок прокручиваются независимо.

Для Modrinth, CurseForge, GitHub, GitLab, Discord, Patreon, Ko-fi, Boosty, Open Collective, PayPal, YouTube, Reddit, Buy Me a Coffee и wiki отображаются компактные узнаваемые отметки. Неизвестный сайт получает нейтральную отметку WEB/URL.

Политики показа

Однократный показ отмечается только после закрытия показанного игроку экрана. Состояние хранится вне config, поэтому тестовое состояние автора не должно экспортироваться вместе со сборкой.

8. Справочник конфигурации

Текущая версия схемы — 5. Рекомендуется внутриигровой редактор, но JSON остаётся читаемым и пригодным для контроля версий.

Корневой объект

Неизвестные поля считаются ошибками. Это намеренно: опечатка в параметре безопасности или обнаружения не должна игнорироваться незаметно.

pack

downloads

maxBackupBatches принимает значения от 1 до 100, по умолчанию 10. Очистка выполняется после успешной установки, старые пакеты удаляются целиком.

Запись мода

Для полезной проверки требуется хотя бы modId или filePattern. Автоматическая загрузка необязательна, но у включённого требования желательно оставить хотя бы страницу с инструкцией получения файла.

projectLinks

• homepage — главная страница;
• source — исходный код;
• issues — баг-трекер;
• wiki — документация;
• discord — сообщество;
• donations — массив { "label": "…", "url": "https://…" }.

Эти ссылки отображаются как кликабельные ресурсы, но не дают разрешения на автоматическую установку.

Запись источника

У ссылки должен быть хотя бы один из параметров: url, downloadUrl или projectId.

9. Типы источников загрузки

Modrinth

Минимальная рекомендуемая настройка:

{
  "label": "Modrinth",
  "type": "MODRINTH",
  "projectId": "ftb-quests",
  "url": "https://modrinth.com/mod/ftb-quests"
}

Если versionId не задан, CoolPackHelper запрашивает последнюю версию с отметками NeoForge и Minecraft 1.21.1, выбирает основной JAR и получает официальный размер и хеши. При наличии versionId разрешается конкретная версия.

CurseForge

Для автоматического разрешения через API нужны projectId, fileId и локально сохранённый одобренный CurseForge 3rd Party API key. API-ключ никогда не берётся из распространяемого конфига.

Чтобы установка у игрока не требовала локального ключа, автор может заранее указать официальный downloadUrl на *.forgecdn.net, действующий хеш, а желательно также имя и размер. Если автор проекта запретил сторонние загрузки, CoolPackHelper соблюдает ограничение и оставляет только переход на страницу.

GitHub Releases

Установить можно только asset из GitHub Release. Страница репозитория, архив ветки, Actions artifact или произвольный raw-файл остаются обычной страницей. Требуется SHA-256: он может быть взят из официальных метаданных релиза GitHub либо указан автором сборки.

GitHub имеет уровень Repository, а не Platform. Игрок получает предупреждение и должен проверить владельца и репозиторий.

Прямой HTTPS

Для установки нужны:

• HTTPS;
• безопасное имя .jar;
• SHA-256 или SHA-512;
• публичный адрес, прошедший сетевые проверки.

Источник получает уровень Unverified, исключается из массовой установки и требует отдельного решения игрока.

Обычная страница

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

10. Безопасность загрузки

Процесс установки намеренно строже обычного открытия ссылки.

До и во время загрузки CoolPackHelper:

1. определяет тип настроенного источника;
2. показывает источник, назначение, уровень доверия и предупреждение;
3. требует HTTPS для удалённых файлов;
4. запрещает логин/пароль в URL и нестандартные HTTPS-порты;
5. разрешает DNS и блокирует loopback, private, link-local, multicast и reserved-адреса;
6. самостоятельно проверяет каждый редирект, максимум пять;
7. ограничивает платформенные источники ожидаемыми официальными хостами;
8. сначала записывает временный файл .part;
9. ограничивает размер 512 MiB и сверяет заявленный/ожидаемый размер;
10. проверяет самый сильный доступный ожидаемый хеш;
11. открывает JAR как ZIP и проверяет пути и структуру;
12. требует метаданные NeoForge;
13. проверяет ожидаемый mod ID и диапазон версии;
14. только после всех проверок атомарно переносит файл в mods.

В массовую установку попадают только успешно разрешённые элементы уровня PLATFORM. GitHub и прямые файлы проверяются игроком по отдельности.

Границы защиты:

• совпавший хеш доказывает целостность, а не безвредность;
• доверие к платформе снижает риск произвольной ссылки, но не является абсолютной гарантией отсутствия вредоносного кода;
• скачанный файл не выполняется в текущем процессе;
• перед его загрузкой NeoForge требуется перезапуск;
• для воспроизводимости автору лучше использовать официальные ID и неизменяемые версии файлов.

11. Метаданные и ресурсы проекта

Импорт доступен во вкладке «Метаданные» документа мода и в связанных путях редактирования источника.

Импорт Modrinth

Введите project ID, slug или URL проекта. API-ключ не нужен.

Импорт CurseForge

Введите числовой project ID и одобренный 3rd Party API key. Токен со страницы автора не является тем же типом ключа и часто приводит к HTTP 401/403.

Предпросмотр импорта

Платформа может предоставить:

• название проекта;
• английское краткое описание;
• URL иконки;
• авторов;
• лицензию;
• главную страницу, исходный код, issues, wiki, Discord и пожертвования, если платформа их возвращает;
• ID, полезные для источника загрузки.

Режим «Заполнить пустые» сохраняет уже исправленные автором значения. «Заменить» применяет импортированный снимок целиком. Перед сохранением обязательно просмотрите текст и адреса.

Иконки намеренно разрешены только с официальных CDN Modrinth и CurseForge. Ответ ограничен 4 MiB, разрешение — 2048×2048. Поддерживаются PNG, JPEG, GIF и WebP. После временной ошибки адрес повторяется позднее, а не запрашивается непрерывно.

12. Сканирование Modrinth и CurseForge

Проверки разделены намеренно: каждая отвечает на вопрос о конкретной платформе распространения.

Локальная подготовка

CoolPackHelper перебирает обычные .jar в mods, пропускает собственный файл, читает до 1 MiB метаданных NeoForge/Forge и извлекает название, mod ID, версию, описание и домашнюю страницу, если они есть.

Проверка Modrinth

• вычисляется SHA-1 каждого JAR;
• хеши отправляются пакетами не более 100 в endpoint поиска version files;
• ключ не требуется.

Проверка CurseForge

• вычисляется нормализованный MurmurHash2 fingerprint CurseForge без пробельных байтов;
• fingerprint отправляются пакетами не более 100;
• требуется одобренный CurseForge 3rd Party API key.

Содержимое JAR не отправляется — только хеши/fingerprint.

Значения статусов

• Найдено - платформа вернула точное совпадение файла.
• Не найдено - точный хеш/fingerprint отмечен как несовпавший.
• Неизвестно - достоверного ответа нет, обычно из-за сети, прав ключа или ответа API.

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

13. Локализация

В моде два уровня переводов.

Тексты конкретной сборки

menu.translations принадлежит автору сборки и управляет формулировками интерфейса требований. Каждая локаль может переопределить только нужные поля — пропущенное поле возьмётся из цепочки резервных языков.

menu.language.mode:

• GAME - использовать язык, выбранный в Minecraft;
• FIXED - всегда использовать fixedLanguage.

Порядок поиска каждого поля:

1. полная выбранная локаль, например pt_br;
2. общий код языка, например pt;
3. fallbackLanguage;
4. встроенный английский.

Та же цепочка применяется к descriptions. Старое одиночное поле description остаётся последним простым резервом.

Поддерживаемые плейсхолдеры в соответствующих строках: {required}, {recommended}, {installed}, {current}, {total}, {count}, {mod} и {value}. Не удаляйте плейсхолдер, обязательный для конкретного поля.

Системные тексты CoolPackHelper

Кнопки редактора, подсказки, ошибки и предупреждения безопасности находятся в assets/cph/lang/en_us.json и ru_ru.json. Это ресурсы самого мода, а не конфиг сборки. Для нового системного языка нужен ресурс-пак либо вклад в проект.

14. Черновой машинный перевод

Автоперевод сейчас помогает с описаниями модов. Результат никогда не заменяет текст скрытно: сначала открывается редактируемый предпросмотр, затем автор явно сохраняет его.

Кнопка помощи объясняет настройку и открывает официальную страницу сервиса. «Проверить подключение» проверяет endpoint и ключ, не переводя описание.

Правила приватности и ключей:

• отправляется только выбранное описание;
• ключ живёт только в памяти, пока автор явно не разрешит локальное сохранение;
• сохранённые ключи находятся в local/coolpackhelper/author-settings.json;
• ключи не записываются в конфиг сборки и журнал;
• редирект с учётными данными на другой origin блокируется;
• MyMemory передаёт текст в query URL, поэтому не используйте его для чувствительных данных.

Машинный перевод — черновик. Названия, термины, форматирование и плейсхолдеры нужно проверить вручную.

15. Резервные копии, история и откат

Успешные установки объединяются в пакеты. Перед заменой существующего JAR CoolPackHelper перемещает его в отдельную папку пакета внутри local/coolpackhelper/backups.

Журнал находится в local/coolpackhelper/installations.json. Экран истории позволяет:

• увидеть дату и установленные файлы;
• откатить активный пакет;
• восстановить заменённые файлы;
• удалить запись после уже выполненного отката.

downloads.maxBackupBatches хранит последние успешные пакеты: по умолчанию 10, допустимо 1..100. После следующей успешной установки старые записи и их папки удаляются целиком.

Откат касается файлов, изменённых CoolPackHelper. Это не общий снимок экземпляра и не отмена произвольных ручных изменений.

16. Файлы и распространение сборки

Проверка перед релизом:

1. Задайте постоянный ID и настоящую версию сборки.
2. Удалите либо оставьте отключёнными все демонстрационные записи.
3. Проверьте mod ID и диапазоны версий в чистом экземпляре.
4. Испытайте каждую запись в выполненном и невыполненном состоянии.
5. Вручную проверьте каждый внешний URL и хеш.
6. Добавьте понятное локализованное описание каждому обязательному моду.
7. Проверьте fallback и хотя бы один неанглийский язык Minecraft.
8. Проверьте полный, компактный и маленький оконный интерфейсы.
9. Испытайте загрузку на копии экземпляра.
10. Испытайте откат.
11. Сохраните, перезапустите игру и убедитесь, что редактор читает те же данные.
12. Экспортируйте только распространяемый конфиг, без локального состояния автора/игрока.

17. Валидация, миграция и восстановление

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

Проверяются, в частности:

• неизвестные JSON-поля;
• отсутствие данных обнаружения;
• дублирующиеся ID/маски в применимых случаях;
• категории, политики и режимы языка;
• Maven-диапазоны;
• формат URL;
• недопустимый хост иконки;
• обязательные параметры разных типов источников;
• имя файла, размер и формат хеша;
• обязательные плейсхолдеры локализованных строк.

При ошибке запуска открывается отдельный экран конфигурации вместо обычного списка требований. Исправьте нужное поле в редакторе или JSON и нажмите «Проверить снова» — перезапуск обычно не требуется.

Старые поля автоматически переносятся в схему 5: showOnlyOnce, requiredMods, menu.defaultLanguage, projectUrl и одиночный downloadUrl. До миграции оригинал копируется как coolpackhelper.json.v<старая-версия>.bak.

Сохранение редактора атомарно. Существующий файл предварительно копируется в coolpackhelper.json.bak.

18. Полные примеры

Обычное требование Modrinth

{
  "$schema": "coolpackhelper.schema.json",
  "schemaVersion": 5,
  "pack": {
    "id": "example-adventure",
    "name": "Example Adventure",
    "version": "1.0.0"
  },
  "showPolicy": "UNTIL_RESOLVED",
  "downloads": {
    "maxBackupBatches": 10
  },
  "menu": {
    "language": {
      "mode": "GAME",
      "fixedLanguage": "ru_ru",
      "fallbackLanguage": "en_us"
    },
    "translations": {
      "en_us": {
        "title": "Example Adventure requirements",
        "description": "Install the missing components before joining a world.",
        "summary": "Required: {required} · Recommended: {recommended}"
      },
      "ru_ru": {
        "title": "Требования Example Adventure",
        "description": "Установите недостающие компоненты перед входом в мир.",
        "summary": "Обязательных: {required} · Рекомендуемых: {recommended}"
      }
    }
  },
  "mods": [
    {
      "enabled": true,
      "category": "REQUIRED",
      "name": "FTB Quests",
      "modId": "ftbquests",
      "versionRange": "[2101.1.0,)",
      "filePattern": "ftb-quests-*.jar",
      "descriptions": {
        "en_us": "Provides the quest book and progression used by this pack.",
        "ru_ru": "Добавляет книгу заданий и систему прогрессии этой сборки."
      },
      "projectLinks": {
        "homepage": "https://modrinth.com/mod/ftb-quests",
        "source": "https://github.com/FTBTeam/FTB-Quests",
        "issues": "https://github.com/FTBTeam/FTB-Quests/issues"
      },
      "authors": ["FTB Team"],
      "license": "All Rights Reserved",
      "links": [
        {
          "label": "Modrinth",
          "type": "MODRINTH",
          "projectId": "ftb-quests",
          "url": "https://modrinth.com/mod/ftb-quests"
        }
      ]
    }
  ]
}

В примере сохранён filePattern как полезная информация для экспорта, но при наличии modId проверка выполняется именно по modId.

Приватный/внеплатформенный мод с прямым файлом

{
  "enabled": true,
  "category": "REQUIRED",
  "name": "Studio Gameplay Addon",
  "modId": "studio_gameplay_addon",
  "versionRange": "[1.4.2]",
  "descriptions": {
    "en_us": "Adds the custom gameplay systems required by this pack.",
    "ru_ru": "Добавляет уникальные игровые механики, необходимые сборке."
  },
  "projectLinks": {
    "homepage": "https://example.org/studio-addon",
    "discord": "https://discord.gg/example"
  },
  "links": [
    {
      "label": "Official studio download",
      "type": "DIRECT",
      "url": "https://example.org/studio-addon",
      "downloadUrl": "https://downloads.example.org/studio-addon-1.4.2.jar",
      "fileName": "studio-addon-1.4.2.jar",
      "sizeBytes": 1234567,
      "sha256": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
    }
  ]
}

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

Только страница

{
  "label": "Инструкция автора",
  "type": "PAGE",
  "url": "https://example.org/how-to-install"
}

19. Решение проблем

Экран требований не появляется

• Убедитесь, что запись включена.
• Проверьте, что showPolicy не равен NEVER.
• Для однократной политики измените pack.version либо удалите локальное состояние во время теста.
• Убедитесь, что требование действительно не выполнено.
• Помните, что жёсткая ошибка зависимости NeoForge может остановить игру раньше интерфейса CoolPackHelper.

Мод считается отсутствующим, хотя JAR лежит в папке

• Проверьте реальный загруженный mod ID, а не имя файла или slug сайта.
• Посмотрите latest.log: возможно, JAR не загрузился.
• При использовании filePattern оставьте modId пустым и проверьте wildcard.

Неверная версия

• Сравните показанную установленную версию с Maven-диапазоном.
• Проверьте круглые и квадратные скобки.
• Не угадывайте внутреннюю версию по названию релиза.

CurseForge возвращает 401 или 403

• Нужен одобренный CurseForge 3rd Party API key.
• Токен панели автора ему не равен.
• Вставьте ключ снова без пробелов по краям.
• Убедитесь, что ключу доступны fingerprint/file endpoints.

Сканирование CurseForge работает, а файл не скачивается

Автор проекта мог запретить загрузку сторонними клиентами, либо в источнике нет точного file ID. Оставьте ссылку на официальную страницу.

Прямая ссылка или GitHub открывается только как страница

• Прямому источнику нужен SHA-256 или SHA-512.
• GitHub должен вести на asset релиза и иметь SHA-256 из конфига или официальных метаданных.
• Назначение должно иметь безопасное имя JAR и использовать HTTPS.

Иконка не появляется

• Разрешены только официальные CDN Modrinth/CurseForge.
• Размер — не более 4 MiB, разрешение — не более 2048×2048.
• После временной ошибки подождите минимум минуту.
• Повторно импортируйте метаданные, если платформенный URL устарел.

Не работает перевод

• Запустите «Проверить подключение».
• Проверьте провайдера и endpoint.
• Проверьте ключ и квоту DeepL/Google/закрытого LibreTranslate.
• MyMemory — публичный сервис, который может временно ограничивать запросы.
• Не каждый провайдер поддерживает все локали Minecraft.

Редактор продолжает писать, что конфиг не сохранён

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

Восстановление после неудачной правки

• Предыдущая версия редактора находится в config/coolpackhelper.json.bak.
• Копия до миграции называется coolpackhelper.json.vN.bak.
• Исправьте текущий файл и нажмите «Проверить снова».
• Во время тестирования политик не переносите local/coolpackhelper/state.json в чистый экземпляр.

20. Границы версии 1.0

CoolPackHelper 1.0 управляет только требованиями модов. В эту версию пока не входят установка и порядок ресурспаков/шейдеров, пресеты управления/options, Discord Rich Presence, брендирование окна игры, создание серверной версии сборки и повторно используемые пресеты содержимого. Эти направления возможны в будущих модулях, но их исключение из 1.0 упрощает аудит и поддержку первого релиза.

Текущая сборка предназначена для NeoForge 1.21.1. Не рассчитывайте на совместимость с Forge, Fabric, Quilt, другой версией Minecraft или другим загрузчиком без отдельного порта.