minecraft-launcher/doc/cpp/minecraftversion.md

# minecraftversion.h — MinecraftVersion и VersionLoader

## Обзор

Каждая версия Minecraft описывается файлом `versions/<id>/<id>.json` — в нём главный класс,
аргументы запуска, список библиотек, индекс ресурсов и требуемая версия Java. Файлы образуют
цепочку: профиль модлоадера наследуется от версии игры через поле `inheritsFrom`, а та, в свою
очередь, может наследоваться дальше.

Заголовок `minecraftversion.h` даёт две вещи: структуры, описывающие версию в разобранном виде, и
пространство имён `VersionLoader` — чтение, разворачивание цепочки наследования и работа с
установленными версиями на диске.

Заголовок подключают [GameLauncher](GameLauncher.md) (собирает из версии командную строку),
[VersionInstaller](VersionInstaller.md) (по списку библиотек понимает, что качать) и
[LauncherBackend](LauncherBackend.md) (проверяет комплектность и удаляет версии).

## Типы

| Имя | Вид | Описание |
|-----|-----|----------|
| `MinecraftLibrary` | `struct` | Одна библиотека из `client.json` с уже разрешёнными правилами |
| `MinecraftVersion` | `struct` | `client.json`, «схлопнутый» по всей цепочке `inheritsFrom` |

### MinecraftLibrary

| Поле | Тип | Описание |
|------|-----|----------|
| `name` | `QString` | Maven-координаты, например `org.lwjgl:lwjgl:3.3.1:natives-windows` |
| `path` | `QString` | Путь относительно `.minecraft/libraries` |
| `url` | `QString` | Откуда качать, если файла нет; может быть пустым — тогда файл должен уже лежать на месте |
| `sha1` | `QString` | Контрольная сумма для проверки скачанного |
| `size` | `qint64` | Размер в байтах; `0` — неизвестен |
| `native` | `bool` | Библиотека распаковывается в `natives`, а не кладётся в classpath |
| `extractExclude` | `QStringList` | Префиксы путей внутри архива, которые не распаковываются |

### MinecraftVersion

| Поле | Тип | Описание |
|------|-----|----------|
| `id` | `QString` | Имя папки в `versions`, оно же значение аргумента `--version` |
| `mainClass` | `QString` | Главный класс, который запускает java |
| `type` | `QString` | `release`, `snapshot` или `modified`; идёт в `--versionType` |
| `assetIndexId` | `QString` | Идентификатор индекса ресурсов для `--assetIndex` |
| `assetsKind` | `QString` | Поле `assets` версии: `legacy`, `pre-1.6` либо тот же идентификатор |
| `clientJarPath` | `QString` | Абсолютный путь к `<id>.jar`; может лежать у родительской версии |
| `javaMajor` | `int` | Требуемая мажорная версия Java; по умолчанию `8` |
| `jvmArgs` | `QStringList` | Аргументы JVM ещё с неподставленными подстановками вида `${...}` |
| `gameArgs` | `QStringList` | Аргументы игры, тоже с неподставленными подстановками |
| `libraries` | `QList<MinecraftLibrary>` | Библиотеки версии с уже применёнными правилами |
| `loggingArgument` | `QString` | Аргумент вида `-Dlog4j.configurationFile=${path}` |
| `loggingConfigPath` | `QString` | Абсолютный путь к xml-конфигурации журнала; пуст, если конфигурации нет |
| `supportsQuickPlay` | `bool` | Версия 1.20 и новее понимает `--quickPlayMultiplayer` — так лаунчер подключается к серверу сразу при запуске |
| `hasCustomResolutionArgs` | `bool` | Версия принимает аргументы размера окна |

Метод `isValid()` возвращает `true`, когда заполнены и `id`, и `mainClass`: именно этим проверяется
успешность чтения версии.

## Функции

Пространство имён `VersionLoader`.

#### QStringList installedVersions(const QString &gameDir)

Версии, реально установленные в `<gameDir>/versions`: есть и папка, и файл `<id>.json`. Одной
только папки недостаточно — она остаётся после неудачной установки.

#### QStringList dependentsOf(const QString &gameDir, const QString &versionId)

Установленные профили, у которых `inheritsFrom` равен `versionId`. Без базовой версии они не
запустятся, поэтому список показывается пользователю перед удалением версии.

#### qint64 installedSize(const QString &gameDir, const QString &versionId)

Размер `<gameDir>/versions/<id>` в байтах; `0`, если папки нет. Используется в предупреждении об
удалении — версия весит десятки мегабайт, и стоит показать, сколько освободится.

#### bool remove(const QString &gameDir, const QString &versionId, QString \*error)

Сносит `<gameDir>/versions/<id>`. Отсутствие папки считается успехом. При неудаче возвращает
`false` и заполняет `error`.

Библиотеки и ресурсы в `libraries/` и `assets/` не трогаются: они общие для всех версий.

#### MinecraftVersion load(const QString &gameDir, const QString &versionId, const QSet&lt;QString&gt; &features, QString \*error)

Читает версию и разворачивает всю цепочку `inheritsFrom` в один объект. Параметр `features` —
набор включённых возможностей, влияющих на применение правил (например, запрошен ли пользовательский
размер окна).

При ошибке возвращает объект, у которого `isValid()` даёт `false`, и заполняет `error`.

#### bool rulesAllow(const QJsonArray &rules, const QSet&lt;QString&gt; &features = {})

Стандартный алгоритм Mojang для блоков `rules`: правила применяются по порядку, побеждает последнее
совпавшее. Используется и для библиотек, и для аргументов запуска.

#### QString nativeClassifier()

Классификатор нативных библиотек для текущей машины: `natives-windows`, `natives-macos-arm64`,
`natives-linux` и подобные. По нему из списка библиотек отбираются те, что нужно распаковать.

#### QString osName()

Имя операционной системы в терминах Mojang — оно подставляется в правила и аргументы.

#### QString osArch()

Архитектура в терминах Mojang.

## Зависимости

Подключает `QJsonArray`, `QList`, `QSet`, `QString` и `QStringList` — только Qt Core. От классов
проекта не зависит.

## Пример использования

```cpp
QString error;
const MinecraftVersion version = VersionLoader::load(gameDir, versionId, features, &error);
if (!version.isValid()) {
    emit launchError(error);
    return;
}

QStringList classpath;
for (const MinecraftLibrary &library : version.libraries) {
    if (!library.native)
        classpath << gameDir + "/libraries/" + library.path;
}
classpath << version.clientJarPath;
```

---

При создании этого документа использовался ИИ.