new docs for project

2026-09-03 09:16:56 +03:00
parent f1a840174b
commit 00e7c957e4
34 changed files with 5323 additions and 0 deletions
@@ -0,0 +1,87 @@
+# modloader.h — ModLoader
+
+## Обзор
+
+`Minecraft_launcher` умеет ставить четыре модлоадера: Minecraft Forge, Fabric Loader, NeoForge и
+Quilt Loader. Заголовок `modloader.h` — общий словарь для всей этой части проекта: перечисление
+самих лоадеров, описание одной их сборки и функции перевода между перечислением и строковым
+ключом.
+
+Лоадеры взаимоисключающи: игра запускается ровно с одним профилем в `<gameDir>/versions`, поэтому в
+сборке лаунчера хранится один ключ лоадера, а не набор.
+
+Заголовок подключают [ModLoaderVersionService](ModLoaderVersionService.md),
+[ModLoaderInstaller](ModLoaderInstaller.md) и [LauncherBackend](LauncherBackend.md).
+
+## Типы
+
+| Имя | Вид | Описание |
+|-----|-----|----------|
+| `ModLoader` | `enum class` | Модлоадеры, которые лаунчер умеет ставить |
+| `LoaderVersionEntry` | `struct` | Одна сборка модлоадера под конкретную версию игры |
+
+### ModLoader
+
+| Значение | Ключ | Название | Описание |
+|----------|------|----------|----------|
+| `Forge` | `forge` | Minecraft Forge | Старейший загрузчик; ставится собственным установщиком, который собирает часть файлов на месте |
+| `Fabric` | `fabric` | Fabric Loader | Лёгкий загрузчик; профиль версии формируется из метаданных без запуска установщика |
+| `NeoForge` | `neoforge` | NeoForge | Ответвление Forge; ставится так же собственным установщиком |
+| `Quilt` | `quilt` | Quilt Loader | Ответвление Fabric; ставится так же, как Fabric |
+
+Перечисление объявлено как `enum class`, поэтому неявного приведения к целому нет.
+
+### LoaderVersionEntry
+
+| Поле | Тип | Описание |
+|------|-----|----------|
+| `loaderVersion` | `QString` | Версия самого лоадера — например `47.4.0`, `0.19.3` или `21.1.248` |
+| `gameVersion` | `QString` | Версия Minecraft, под которую эта сборка — например `1.20.1` |
+| `versionId` | `QString` | Предсказанный идентификатор профиля `versions/<id>`. У Forge пуст: он выясняется только после работы установщика |
+| `installerUrl` | `QUrl` | Адрес установщика; заполнен только у Forge и NeoForge |
+| `recommended` | `bool` | Сборка помечена авторами как рекомендуемая; по умолчанию `false` |
+| `stable` | `bool` | Сборка стабильна, а не тестовая; по умолчанию `true` |
+
+## Функции
+
+#### QString loaderKey(ModLoader loader)
+
+Строковый ключ лоадера: `forge`, `fabric`, `neoforge` или `quilt`. Один и тот же ключ используется
+в трёх местах — в интерфейсе, в имени файла кэша на диске и в поле `loader` файла
+`customBuilds.json`, — поэтому менять его нельзя без миграции сохранённых сборок.
+
+Объявлена `inline` в заголовке.
+
+#### QString loaderTitle(ModLoader loader)
+
+Человекочитаемое название лоадера для интерфейса: «Minecraft Forge», «Fabric Loader», «NeoForge»,
+«Quilt Loader». Объявлена `inline`.
+
+#### std::optional&lt;ModLoader&gt; loaderFromKey(const QString &key)
+
+Обратный перевод: ключ в перечисление. Возвращает `std::nullopt` для неизвестного ключа, в том
+числе для пустой строки — а пустая строка в сборке означает чистую ваниль без лоадера. Объявлена
+`inline`.
+
+## Зависимости
+
+Подключает `QString`, `QUrl` и `<optional>`. От классов проекта не зависит и сам подключается
+всюду, где речь идёт о модлоадерах.
+
+## Пример использования
+
+```cpp
+const auto loader = loaderFromKey(build.loader);
+if (!loader) {
+    // сборка без модлоадера — запускаем чистую ваниль
+    return;
+}
+
+qInfo() << "ставим" << loaderTitle(*loader)
+        << "версии" << entry.loaderVersion
+        << "под Minecraft" << entry.gameVersion;
+```
+
+---
+
+При создании этого документа использовался ИИ.