План развития

Документ описывает предполагаемое развитие CoolPackHelper после первого публичного релиза. Это продуктовый и архитектурный план, а не обещание сроков и не гарантия, что каждый эксперимент выйдет без изменений.

Обозначения статуса

• Условие релиза - необходимо завершить до признания текущей версии готовой.
• Запланировано - соответствует направлению продукта и имеет достаточно понятную архитектуру.
• Кандидат - полезно, но объём и приоритет ещё требуют проверки.
• Исследование - есть техническая, юридическая или продуктовая неопределённость; сначала нужен прототип.
• Отложено - намеренно не входит в ближайший этап.

Направление продукта

CoolPackHelper начинался как уведомление об отсутствующих модах. Долгосрочная цель шире: стать безопасной локальной рабочей областью для создания, распространения, объяснения и обслуживания Minecraft-сборок.

Мод должен помогать автору создавать воспроизводимую сборку, а игроку — понимать каждое предлагаемое изменение. Удобство не должно лишать игрока выбора или превращать конфигурацию сборки в неограниченный удалённый установщик.

Обязательные принципы

Каждый будущий модуль должен соблюдать следующие правила:

1. Явное согласие - установка, замена настроек, сетевая активность профиля и внешние ссылки должны быть видимыми и по возможности обратимыми.
2. Минимальные полномочия - сетевой функции передаются только необходимые данные, ключи остаются локальными.
3. Доверие не равно безопасности - платформа, репозиторий, CDN и хеш меняют уровень уверенности, но не доказывают безвредность.
4. Предпросмотр до применения - перед изменением файлов или настроек показывается список действий либо diff.
5. Копия до замены - изменение пользовательского файла или настройки получает ограниченный и понятный путь восстановления.
6. Никакого скрытого продвижения - пресеты и рекомендации BMP явно обозначаются, остаются необязательными и удаляемыми.
7. Локальная работа автора - создание и просмотр данных не должны требовать обязательного облачного аккаунта.
8. Доступный адаптивный UI - клавиатура, экранный диктор, подсказки, прокрутка, маленькие окна и большой GUI Scale входят в критерии релиза.
9. Данные со схемой - новой функции нужны версия формата, валидация, миграция и читаемый экспорт.
10. Никакого скрытого удалённого кода/конфига - удалённые манифесты должны проверяться и просматриваться, а содержимое не обходит обычные проверки.

Этап 0 - завершение и укрепление 1.0

Статус: условие релиза

Версия 1.0 создаёт основу:

• локализованные обязательные и рекомендуемые требования модов;
• адаптивные общий и подробный интерфейсы;
• несколько источников загрузки;
• защищённые сценарии Modrinth, CurseForge, GitHub Releases, прямого HTTPS и обычной страницы;
• проверка хеша, сети, размера, структуры JAR, mod ID и версии;
• резервные копии, история установки и откат;
• отдельное сканирование Modrinth/CurseForge;
• импорт метаданных и загрузка иконок;
• черновой машинный перевод;
• многооконная рабочая область автора;
• строгая схема, валидация и миграция.

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

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

Новые крупные подсистемы должны начинаться после стабилизации этой основы.

Этап 1 - общая система требований содержимого

Статус: запланировано

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

Ресурспаки

Планируемые возможности:

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

Шейдерпаки

Планируемые возможности:

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

Общая архитектура

Нужно выделить повторно используемые сервисы:

• идентичность содержимого и ограничения версий;
• разрешение источников и отображение доверия;
• безопасная загрузка ZIP/JAR и проверка путей;
• кеш метаданных/иконок;
• локализованные описания и ссылки;
• ограниченные резервные копии и журнал транзакций.

В интерфейсе всё равно должны остаться отдельные разделы «Моды», «Ресурспаки» и «Шейдеры». Один огромный смешанный список будет сложнее для игрока.

Этап 2 - стандартные настройки сборки

Статус: запланировано, высокий риск неудобной/разрушительной работы

Авторам часто нужно распространять задуманный порядок ресурспаков и разумно распределённые клавиши. Это можно реализовать нативно, без обязательного Default Options, а совместимость импорта/экспорта добавить позднее.

Снимок порядка ресурспаков

Предлагаемый путь автора:

1. Расставить ресурспаки обычным интерфейсом Minecraft.
2. Нажать «Сохранить текущий профиль ресурспаков».
3. Проверить включённые паки, порядок, несовместимые элементы и зависимости.
4. Сохранить именованный профиль в распространяемых данных CoolPackHelper.

Предлагаемый путь игрока:

1. Сравнить профиль автора со своим текущим состоянием.
2. Увидеть, что включится, выключится и переместится.
3. Применить одним действием.
4. При необходимости восстановить прежнее состояние.

Снимок управления и options

Нельзя бездумно копировать весь авторский options.txt. Безопаснее хранить явный список выбранных параметров:

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

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

Совместимость с Default Options

Нативный профиль должен оставаться основным форматом. Позднее можно добавить адаптер импорта/экспорта Default Options, если мод установлен, но без жёсткой зависимости и без перезаписи его данных без подтверждения.

Этап 3 - защищённые манифесты и CDN

Статус: кандидат / исследование безопасности

CDN полезен для доступности и трафика, но имя CDN не подтверждает автора файла. Формулировка «скачано через наш CDN» не должна становиться обходом защиты.

Полезная архитектура - подписанный версионированный манифест распространения:

• постоянный ID и версия сборки;
• неизменяемые ID содержимого;
• точный размер и SHA-256/SHA-512;
• разрешённые зеркала/CDN origin;
• срок действия и версия схемы;
• необязательные ID проекта/версии платформы;
• подпись, проверяемая ключом, закреплённым в конфиге сборки либо доверенном хранилище CoolPackHelper.

CDN доставляет байты, а подписанный манифест подтверждает, какими байты должны быть. Все существующие проверки сети, редиректов, размера, архива, ID и версии продолжают работать.

Открытые вопросы:

• кто управляет ключами и выполняет ротацию;
• как отозвать скомпрометированный аккаунт автора;
• поддерживать ли общественные и self-hosted манифесты;
• нужен ли журнал прозрачности изменений;
• срок кеша и работа без сети;
• стоимость и rate limits;
• как не централизовать чужие сборки в инфраструктуре BMP.

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

Этап 4 - идентичность сборки и Discord

Статус: кандидат

Discord Rich Presence

Возможные данные:

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

Требования приватности:

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

Название и иконка окна

Автор сможет задать название окна сборки и необязательную иконку, а игрок - отключить их. Локальные assets проверяются, при выключении возвращаются стандартные значения, особенности ОС считаются best effort. Брендирование не должно скрывать предупреждения Minecraft/NeoForge или имитировать другой продукт.

Этот этап может разрабатываться независимо после стабилизации 1.0, но не должен задерживать управление содержимым.

Этап 5 - повторно используемые пресеты автора

Статус: отложено до стабилизации форматов содержимого/профилей

Пресеты ускорят начало проекта, объединяя популярные моды, ресурспаки, шейдеры, описания и стандартные настройки.

Локальные пресеты

Первый безопасный вариант:

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

Курируемый каталог

Позднее необязательный каталог может предлагать категории: базовый UI, производительность, карты, просмотр рецептов, доступность и локализация. При применении нужно разрешить совместимые версии, а затем сохранить lock/snapshot для воспроизводимости.

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

Безопасность пресетов

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

Этап 6 - диагностика сборки и граф зависимостей

Статус: кандидат

Возможные инструменты автора:

• визуальный граф зависимостей модов;
• поиск отсутствующих и несовместимых зависимостей до экспорта;
• обнаружение повторных embedded libraries и mod ID;
• сравнение требований с реальной папкой mods;
• устаревшие URL, неверные хеши, недоступные версии и временные ссылки;
• подсказки client-only/server-only/unknown;
• читаемый отчёт здоровья сборки;
• сравнение двух версий сборки с перечнем файлов и настроек.

Факты должны быть отделены от эвристик. «Вероятно клиентский» не означает «можно безопасно удалить с сервера».

Этап 7 - создание серверной версии

Статус: исследование / поздний этап

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

Предлагаемый процесс:

1. Просканировать моды и конфигурацию выбранного клиентского экземпляра.
2. Разделить элементы на client-only, server-only, both и unknown по метаданным NeoForge/платформы, курируемым исключениям и графу зависимостей.
3. Показать основания и уверенность каждого решения.
4. Потребовать выбора автора для неизвестных/противоречивых записей.
5. Собирать в новую папку, никогда не изменяя исходный экземпляр.
6. Добавить выбранные config, scripts, datapacks, стандартные настройки и библиотеки.
7. Соблюдать лицензии распространения и правила платформ.
8. Создать манифест, отчёт исключений, предупреждения и чек-лист запуска.
9. При возможности выполнить локальный headless smoke test и сохранить логи.

Один успешный запуск не доказывает готовность сервера к production. Сеть, права, резервные копии, производительность, безопасность и хостинг остаются ответственностью администратора.

Этап 8 - автоматическое создание списка изменений сборки

Статус: исследование / очень далёкий этап

В будущей версии CoolPackHelper сможет создавать структурированный changelog, сравнивая новую сборку с заранее сохранённым снимком предыдущего релиза. Это должен быть не сырой diff папок, а понятное игроку объяснение изменений и машиночитаемая история того, из чего был собран релиз.

Предлагаемый процесс

1. Завершить и проверить релиз, например 1.0.
2. Нажать «Создать снимок релиза» и указать постоянный ID/версию сборки.
3. CoolPackHelper собирает поддерживаемые сведения и записывает локальный версионированный снимок.
4. Автор обычным образом разрабатывает следующее обновление.
5. Для 1.1 создаётся новый снимок, а 1.0 выбирается основой сравнения.
6. Автор просматривает добавления, удаления, обновления и изменения с низкой уверенностью.
7. Добавляет человеческие пояснения, объединяет шумные записи, скрывает неважные файлы и выбирает публичный уровень подробности.
8. Генерируется Markdown для игроков и полный JSON-отчёт для автоматизации/аудита.
9. Проверенный changelog сохраняется вместе со снимком нового релиза, чтобы дальнейшие сравнения использовали подтверждённую историю.

Автор обязательно подтверждает результат. CoolPackHelper способен обнаружить изменившийся скрипт или рецепт, но не всегда может понять игровой замысел конкретной строки.

Содержимое снимка

Если формат безопасно поддерживается, снимок может включать:

• mod ID, название, версию, имя файла, размер и хеш;
• ресурспаки, шейдеры, датапаки, их метаданные и порядок;
• выбранные конфиги с нормализованными смысловыми значениями;
• KubeJS startup/server/client scripts и другие поддерживаемые каталоги скриптов;
• ID рецептов и нормализованные входы, выходы, условия и операции;
• теги, loot tables, advancements, worldgen и выбранные реестры датапаков;
• профили управления/options;
• изменения требований, источников, метаданных и локализаций CoolPackHelper;
• состав серверной сборки после появления соответствующего модуля.

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

Категории изменений

Отчёт должен различать:

• добавленные, удалённые и обновлённые моды;
• неизменившуюся версию мода при другом хеше JAR;
• изменение Minecraft, загрузчика или версии сборки;
• добавление, удаление, включение, выключение и перестановку паков/шейдеров;
• созданные, удалённые, переименованные и изменённые скрипты;
• добавленные, удалённые и семантически изменённые рецепты;
• добавленные, удалённые и изменённые ключи конфигурации;
• подавленные нормализатором изменения форматирования и порядка;
• изменившиеся бинарные/неизвестные файлы без смыслового объяснения;
• ручные заметки автора и предупреждения о несовместимости.

Семантические адаптеры

Полезному changelog нужны анализаторы форматов, а не один универсальный парсер:

• нормализация JSON/JSON5/TOML/YAML/properties;
• консервативный анализ JavaScript KubeJS с извлечением рецептов;
• чтение Minecraft recipes/tags/loot tables из датапаков;
• необязательные адаптеры CraftTweaker и других популярных систем скриптов;
• адаптеры конкретных модовых конфигов только при понятном и сопровождаемом формате.

Динамические скрипты - сложная граница. Код может условно создавать рецепты, читать внешнее состояние или генерировать ID во время запуска. Статический анализ обязан помечать неполный и эвристический результат. В будущем контролируемый режим инструментирования сможет наблюдать регистрации во время отдельного dev-запуска, но CoolPackHelper не должен выполнять неизвестные скрипты вне нормальной среды игры только ради changelog.

Уменьшение шума и шаблоны

Автору понадобятся include/exclude-правила и безопасные значения по умолчанию:

• игнорировать timestamps, комментарии, форматирование, кеш-ключи и известные runtime-значения;
• объединять сотни похожих изменений рецептов в проверяемую сводку;
• группировать Gameplay, Content, Performance, Fixes, Configuration и Technical;
• заменять внутренние ID локализованными названиями;
• выбирать краткий пользовательский или полный технический отчёт;
• настраивать версионированный Markdown-шаблон с плейсхолдерами;
• экспортировать JSON для лаунчера, сайта и CI;
• сохранять ручные пояснения после повторного сканирования через постоянные ID изменений.

Целостность и хранение

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

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

Перенос на другие версии и загрузчики

Статус: кандидат после стабильной 1.0

Поддержка другой версии Minecraft должна быть отдельной протестированной веткой релизов, а не простой заменой номера. Порты Fabric/Quilt/Forge потребуют собственных способов обнаружения, метаданных, интеграции UI и проверки JAR. Общие модули уменьшат дублирование, но совместимость всегда указывается для конкретного артефакта.

Направление архитектуры

Будущие изменения должны сохранять границы модулей:

• core schema - версионированные данные автора и миграции;
• inventory - анализ локальных модов, паков, шейдеров и options;
• requirements - вычисление выполнения и статуса;
• metadata - импорт с платформ и кеш;
• resolver - разрешение платформенных, репозиторных и прямых источников;
• security - URI, DNS, редиректы, хеши, архив и идентичность;
• transactions - временная запись, атомарное применение, копия, журнал и откат;
• profiles - порядок ресурспаков и выбранные настройки/клавиши;
• snapshots - нормализованные версионированные снимки релизов и основы сравнения;
• diff/reporting - семантические адаптеры, проверка результата, шаблоны changelog и экспорт;
• workspace UI - создание и валидация;
• player UI - предпросмотр, согласие, объяснение и восстановление.

Каждый новый тип содержимого должен использовать общий слой безопасности и транзакций, а не создавать второй загрузчик.

Предлагаемый порядок

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

Явно не является целью

CoolPackHelper не должен становиться:

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

Как принимать решения о новых функциях

Перед переносом кандидата в запланированную работу нужно ответить:

1. Решает ли функция регулярно встречающуюся проблему автора или игрока?
2. Понимает ли игрок последствия и может ли их отменить?
3. Можно ли использовать существующие слои безопасности и транзакций?
4. Появляются ли ключи, отслеживание, лицензии или проблемы распространения?
5. Версионирован и переносим ли формат данных?
6. Можно ли проверить функцию на чистом и намеренно повреждённом экземпляре?
7. Реально ли сопровождать её между версиями Minecraft и загрузчиков?

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