launcher/README.md

# ZernMC Launcher

**ZernMC Launcher** — это полностью самописный Minecraft-лаунчер, созданный с нуля.  
Клиент написан на **Java**, серверная часть — на **Python (FastAPI)**.

## Основные особенности

- Написан полностью с нуля, без использования готовых решений
- Удобная загрузка и обновление сборок прямо с сервера ZernMC
- Чистый и относительно читаемый код как клиента, так и сервера
- Графический интерфейс на **JavaFX** (по умолчанию) + **TUI** (режим `--cli`)
- Поддержка **прокси-режима** через свой сервер при проблемах с внешними ресурсами (Fabric/Forge Maven, Mojang и т.д.), обход блокировок через выбор домена и SNI
- Поддержка загрузчиков **Fabric**, **Forge**, **NeoForge** и ванильных версий (установка через встроенный JRE)
- Ротационные логи в стиле Minecraft: `latest.log` + архивы `.log.gz`
- Инкрементальное обновление JavaFX и автообновление лаунчера
- Подпись exe самоподписным сертификатом Zern.cc (jsign/Authenticode)
- Полное отсутствие рекламы и телеметрии
- Не собирает никаких данных о пользователе
- Работает «из коробки»: достаточно распаковать архив и запустить `zernmc.exe`
- Есть система аккаунтов и проходок

## Состав дистрибутива

В архиве `ZernMC-win-<версия>.zip`:

- `zernmc.exe` — основная версия с GUI (JavaFX)
- `zernmc-cli.exe` — консольная версия (TUI)
- `zernmc-cli-jfx.exe` — консоль + JavaFX UI
- `lib/jre21` — встроенный JRE 21
- `lib/javafx` — модули JavaFX 23.0.1

Bootstrap-модуль встроен прямо в `.exe`, отдельный jar рядом не нужен.

## Чего пока нет в лаунчере

- Готовых пресетов оптимизации JVM (настраиваются Java и выделенная память)
- Поддержки Quilt, LabyMod и других лоадеров
- Кастомных модов (UI, спавнеры, DPI, карточки)
- Сайта для лаунчера и сервера (текущий требует переделки)
- Трекинга наигранного времени (обновление раз в час вместо минуты)

## Что планируется доработать в ближайшее время

- **UI мод** — переписать мод на UI: красивое главное меню, анимации, анимированный задний фон, эмбиент звуки, интерактивность, урезание ванильных элементов до используемых
- **GUI мод** — привести в единый стиль с главным меню
- **Мод на спавнеры** — кастомные спавнеры с лимитами (5-15 спавнов), отслеживание спавнов вокруг, замена на базовый спавнер при достижении предела с эффектами и звуками, данжи «временного парадокса» с процедурной генерацией этажей, минибоссы, лут
- **DPI мод** — отслеживание не-ZernMC лаунчеров, защита от форков с выпиленной проверкой, уведомления админу в Telegram с технической информацией
- **Сайт** — полноценный сайт для лаунчера и сервера
- **Система карточек** — дроп случайных карточек (обучена на датасете скинов CS2), просмотр, продажа, крафт, обмен между игроками, внутриигровая валюта «йоны», начисление йонов на баланс, обмен йонов на предметы, вывод йонов в отдельный предмет, анимации и эффекты
- **Web API** — OpenAPI документация, уровни доступа к API (например, получение списка игроков требует проходку)
- **Трекинг наигранного времени** — обновление каждую минуту вместо часа для нормальных графиков игроков
- Генерацию команды запуска Minecraft
- Стабильную работу автообновления лаунчера
- Полноценные настройки
- **Улучшенный античит / ClientChecker** — проверка подлинности клиента при подключении к серверу, без нужного клиента не пустит; поставляется вместе с лаунчером, не общедоступный. Хеш-проверка всех папок и файлов сборки при каждом запуске — при несовпадении одного хеша все моды переустанавливаются. Игнорируются только: логи, ресурспаки, шейдеры, сейвы, личные файлы. Защита от подмены libs и лоадеров (Meteor и аналоги), проверка целостности модов через хеши. В перспективе — защита от Mixin-атак (перехват логики других модов), сбор отчёта о текущей сборке и сравнение с базовой
- **Баг-фиксы сервера:** подключить `admin_router` в `main.py`, исправить импорты ролей (`ROLE_USER` и др. не существуют в `roles.py`), добавить эндпоинт `/auth/pass/activate`, убрать дубли импортов (`TTLCache`, `Response`)
- Улучшение прокси-режима
- Стабильность и производительность серверной части
- Общую надёжность загрузки файлов с сервера

## Важная информация перед использованием

### Управление в лаунчере (TUI)

Консольные версии (`zernmc-cli.exe`, а также режим `--cli`) используют **текстовый интерфейс (TUI)**:

- `W` / `S` (или `Ц` / `Ы`) или `↑` / `↓` — перемещение по меню
- `ENTER` — выбор пункта
- `ESC` или пункт «Назад» — возврат назад

Если вы случайно кликнули мышкой в окне лаунчера и он «заморозился» — просто нажмите **любую клавишу** на клавиатуре.

Основная версия `zernmc.exe` запускает графический интерфейс JavaFX.

### Расположение сборок

Все установленные сборки хранятся в папке:
- **Windows**: `%USERPROFILE%\.zernmc\instances`
- **Linux**: `~/.zernmc\instances`

Если сборка не удаляется корректно — удалите папку вручную.

### Логи

Логи лаунчера пишутся в файл `latest.log` рядом с исполняемым файлом; старые логи архивируются в `.log.gz` (в стиле Minecraft).

## Как скачать и запустить

Скачать последнюю версию можно по ссылкам:

**Скачать лаунчер:**
- https://api.zernmc.ru/launcher/download/latest
- https://api.zernmc.online/launcher/download/latest

**Инструкция:**
1. Скачайте zip-архив
2. Распакуйте в удобную папку (например `C:\ZernMC`)
3. Запустите `zernmc.exe` (или `zernmc-cli.exe` для консольного режима)
4. Войдите в аккаунт и нажмите **«Начать игру»**

### Установка первой сборки

Если у вас ещё нет сборок:
1. Выберите **«Установить новую сборку»**
2. Выберите тип сборки:
   - **ZernMC** — готовые сборки с нашего сервера
   - **Модовый загрузчик** — Fabric / Forge / NeoForge
   - **Ваниль** — чистая версия от Mojang

**Рекомендация:** Не используйте кириллицу в названии сборки! (science 1.0.0-1.0.5)

## Возможные проблемы и решения

### «Error: Invalid or corrupt jarfile» при запуске exe
Перекачайте архив целиком из https://api.zernmc.ru/launcher/download/latest и распакуйте заново — старые версии (до 1.0.16.17) были повреждены подписью и не запускаются.

### Проблемы с загрузкой ассетов
Иногда лаунчер неправильно определяет Asset Index.
**Решение:**
1. Запустите версию и посмотрите в логах, какой `.json` файл он пытается загрузить.
2. Скопируйте правильный файл из `assets/indexes/` и переименуйте его в нужное имя.

### Forge / NeoForge
Работает через установщики лоадеров. Если у вас нет внешнего доступа к Maven-репозиториям — используйте прокси-режим.

### Прокси-режим
Если нет доступа к Fabric/Forge Maven или серверам Mojang — лаунчер пытается использовать наш сервер как прокси. Если и к нему нет доступа — загрузка может не работать.

## Как сообщить об ошибке (Issue)

1. Скопируйте весь текст ошибки из логов (`latest.log`)
2. Укажите, что вы делали перед ошибкой
3. Укажите версию лаунчера
4. Создайте Issue на GitHub

## Разработка (для желающих помочь)

```bash
git clone https://github.com/SashegDev/launcher
```
Откройте `launcher/launcher/pom.xml`
отредактируйте пути для билда, так как сейчас - он рассчитан на разработку только на своём сервере
```bash
mvn clean package
```
можете начинать!

**Сборка exe на Linux требует:** `jsign` (`~/tools/jsign/jsign.jar`), файлы сертификата в `/root/cert/codesign/`, встроенный JRE в `~/launcher/jre/jre21`.

### Благодарность
- Glitch135 — за бета-тест лаунчера и фидбеки

Буду рад помощи в разработке!
Особенно приветствуется помощь с:

- Улучшением генерации команды запуска
- Добавлением поддержки Quilt / LabyMod
- Стабилизацией серверной части
- Вообще улучшением клиента