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,145 @@
+# launcherpaths.h — LauncherPaths
+
+## Обзор
+
+`Minecraft_launcher` хранит собственные данные отдельно от папки игры: настройки, профили, описания
+сборок, архивы содержимого `.minecraft`, скачанные сборки Java и кэши каталогов. Пространство имён
+`LauncherPaths` — единственное место, где эти пути вычисляются.
+
+Собственная папка `galeonLauncher` лежит рядом со стандартной `.minecraft`, а не в системном
+каталоге данных приложения: так все файлы лаунчера остаются там же, где сама игра, и переносятся
+вместе с ней.
+
+К этому заголовку обращается почти каждый сервис проекта — везде, где нужно прочитать или записать
+файл в папке лаунчера.
+
+## Пространства имён
+
+`LauncherPaths` группирует функции, возвращающие абсолютные пути, и одну функцию создания корневой
+папки. Состояния у пространства имён нет: все функции вычисляют путь заново при каждом вызове.
+
+## Функции
+
+### Корневые каталоги
+
+#### QString containerDir()
+
+Родительская папка, в которой лежит `.minecraft`, а рядом с ней — `galeonLauncher`. От неё
+отсчитываются и папка игры по умолчанию, и корень данных лаунчера.
+
+#### QString rootDir()
+
+Корень данных лаунчера — `<containerDir>/galeonLauncher`.
+
+#### QString defaultMinecraftDir()
+
+Стандартная папка игры. Используется, когда пользователь не задал свою в настройках.
+
+#### bool ensureRootExists(QString *error = nullptr)
+
+Создаёт папку лаунчера, если её ещё нет. Вызывается при каждом запуске и перед каждой записью.
+
+Возвращает `false` и заполняет `error`, если папку не удалось создать или в неё не пишется. Все
+остальные функции пространства имён только считают строки и в этом смысле не могут завершиться
+неудачей — проверять доступность каталога нужно этой функцией.
+
+### Файлы состояния
+
+#### QString settingsFile()
+
+Файл настроек запуска: папка игры, путь к Java, память, аргументы JVM, размер окна.
+
+#### QString profilesFile()
+
+Файл профилей игрока.
+
+#### QString customBuildsFile()
+
+`<root>/customBuilds.json` — пользовательские сборки.
+
+#### QString legacyCustomBuildsFile()
+
+`<root>/versions.json` — как сборки назывались до переименования. Читается один раз при миграции и
+больше ни для чего не нужен.
+
+### Сборки и их архивы
+
+#### QString buildStorageDir()
+
+`<root>/builds` — архивы содержимого `.minecraft`, по одному на сборку.
+
+#### QString buildDir(int buildId)
+
+`<root>/builds/<id>` — папка одной сборки: её архив и, у сезонных, скачанный пак с описанием
+установленной ревизии.
+
+#### QString seasonalStateFile(int buildId)
+
+`<root>/builds/<id>/season.json` — какая ревизия сезонной сборки установлена и какие файлы она
+принесла. Список файлов нужен, чтобы при обновлении убрать те, что из сборки ушли.
+
+### Java
+
+#### QString javaDir()
+
+`<root>/java` — сборки Java, скачанные лаунчером. Каждая в своей подпапке, имя подпапки —
+идентификатор сборки из каталога.
+
+#### QString javaCatalogFile()
+
+Слепок каталога доступных сборок Java с отметкой времени.
+
+#### QString javaDownloadDir()
+
+Каталог, куда качаются архивы Temurin до распаковки.
+
+### Кэши и загрузки
+
+#### QString cacheDir()
+
+`<root>/cache` — данные, которые можно удалить без потерь.
+
+#### QString versionManifestFile()
+
+Слепок манифеста версий Mojang с отметкой времени.
+
+#### QString seasonalCatalogFile()
+
+Слепок каталога сезонных сборок с отметкой времени.
+
+#### QString loaderCacheFile(const QString &loaderKey)
+
+Слепок списка версий одного модлоадера. Параметр `loaderKey` принимает значения `forge`, `fabric`,
+`neoforge` и `quilt` — те же ключи, что возвращает `loaderKey()` из [modloader.h](modloader.md).
+
+#### QString loaderDownloadDir()
+
+Каталог, куда качаются `installer.jar` модлоадеров.
+
+#### QString runtimeDir()
+
+Каталог, куда качается `authlib-injector` — библиотека, подменяющая сервер авторизации при входе
+через Ely.by.
+
+## Зависимости
+
+Единственный подключаемый заголовок — `QString`. Пространство имён не зависит ни от одного класса
+проекта, поэтому его можно подключать откуда угодно без риска циклических зависимостей.
+
+## Пример использования
+
+```cpp
+QString error;
+if (!LauncherPaths::ensureRootExists(&error)) {
+    qWarning() << "папка лаунчера недоступна:" << error;
+    return;
+}
+
+QFile file(LauncherPaths::customBuildsFile());
+if (file.open(QIODevice::WriteOnly))
+    file.write(document.toJson());
+```
+
+---
+
+При создании этого документа использовался ИИ.