Maze Game (Java 21)

Консольный генератор и решатель лабиринтов
Под капотом — алгоритм Прима и «Рекурсивное деление» для генерации,
DFS / алгоритм Дейкстры для поиска пути, ASCII‑рендер и строгий CI.

---

📑 Содержание

1. О проекте
2. Алгоритмы
   1. Генерация
   2. Решение
3. Архитектура кода
4. Сборка и запуск
5. CLI режим
6. Профили сборки
7. Тесты и покрытие
8. Статический анализ
9. Расширение функциональности
10. CI/CD
11. Часто задаваемые вопросы
12. Roadmap
13. Содействие
14. Лицензия

---

О проекте

Maze Game — это небольшая демонстрация чистой архитектуры и алгоритмов на графах, написанная полностью на Java 21. Приложение умеет:

• генерировать лабиринт заданного размера двумя популярными способами;
• на лету решать его разными стратегиями;
• выводить карту и путь в читаемом ASCII‑формате;
• легко расширяться за счёт паттерна Strategy и иммутабельных моделей;
• поддерживать высокое качество кода благодаря строгому CI‑пайплайну (линтеры + тесты + покрытие).

Проект подходит в качестве:

• учебного пособия по алгоритмам (DFS, Dijkstra, Prim, Recursive Division);
• примера много‑модульного Maven‑проекта с полным набором анализа;
• стартовой точки для собственных экспериментов с генерацией/решением лабиринтов.

---

Алгоритмы

Генерация

Алгоритм	Сложность	Особенности
Прима	O(E log V) (с очередью)	Получается обычно более извилистый лабиринт с длинным основным коридором.
Recursive Division	O(H×W)	Делит область стенами до базового квадранта. Даёт «пещерный» стиль с длинными прямыми.

Каждый алгоритм реализует контракт

public interface GenerationStrategy {
    Maze generate(Coordinate size);
}

и регистрируется через GeneratorContext.

Решение

Алгоритм	Сложность	Класс
DFS	O(V + E)	FirstSearchSolvingStrategy
Алгоритм Дейкстры	O((V + E) log V)	DijkstraSolvingStrategy

За выбор отвечает SolverContext. Добавить A*? — достаточно пары классов.

---

Архитектура кода

labyrinth
 ├─ data          # иммутабельные модели: Cell, Coordinate, Maze
 │                 # + CoordinateValidator
 ├─ generator      # GenerationStrategy + реализации + утилиты
 ├─ solver         # SolvingStrategy + реализации
 ├─ renderer       # ASCII‑отрисовщик (Renderer, StringRenderer)
 └─ handler        # Обёртки над Scanner и System.out
Main.java          # запускает пайплайн

Ключевые приёмы

• Strategy pattern — позволяет подменять алгоритмы без переписывания кода.
• Immutability — все модели неизменяемы (Java records или final поля).
• Fail‑fast validation — проверяем входные данные сразу, чтобы не ловить NPE позже.
• Lombok — убирает шаблонный код (@Getter, @UtilityClass и т. д.).
• Log4j2 — унифицированный вывод логов (можно изменить конфиг в src/main/resources).

Диаграмма зависимостей (облегчённая):

Input ─┐
       v
   [Main] → GeneratorContext → GenerationStrategy*
       |                          ^
       └─────→ SolverContext ─────┘
                          |
                          v
                    SolvingStrategy*

---

Сборка и запуск

Минимальные версии: JDK 21, Maven 3.9+.

# 1. Клонируем
git clone https://github.com/<user>/MazeGameJava.git
cd MazeGameJava

# 2. Собираем с проверками, тестами и покрытием
mvn clean verify

# 3. Запускаем
java -cp target/classes io.github.therad445.Main
#    └ или fat‑jar:
mvn -Pfat package
java -jar target/mazegame-1.0.0.jar

Параметры Maven

Профиль	Назначение	Команда
default	обычная сборка + тесты	mvn verify
fat	создаёт self‑contained jar (maven‑shade‑plugin)	mvn -Pfat package
ci	без интерактивного ввода, читаем параметры из env	mvn -Pci test

---

CLI режим

Программа общается с пользователем последовательно:

Введите размер лабиринта (ширина высота):
20 10
Введите координаты старта (x y):
1 1
Введите координаты финиша (x y):
18 8

После чего выводит:

Генератор: Prim
+---+---+---+...
| S |   |   |
+---+---+---+
...
|   |   | F |
+---+---+---+

Решатель: DFS
. . * * * ...
...

Решатель: Dijkstra
. . * * * ...
...

Ошибки ввода ловятся и поясняются (CoordinateValidator).

---

Профили сборки

• prod — отключает подробное логирование, дебаг‑настройки и отчёты.
• benchmark — добавляет JMH‑модуль (в разработке).
• coverage — генерирует отчёт JaCoCo HTML (открывается в браузере).

---

Тесты и покрытие

• JUnit 5 + AssertJ — удобные утверждения типа assertThat(list).isSorted().
• Покрытие JaCoCo: сборка падает, если <counter type="LINE" missed="0"> < 80 %.
• Тестируются:
  • валидация координат;
  • корректность генерации (границы, связность);
  • нахождение пути (наличие и минимальная длина);
  • ASCII‑рендер.

Запуск отдельно:

mvn test
mvn jacoco:report   # отчёт в target/site/jacoco

---

Статический анализ

Инструмент	Правила	Fail‑threshold
Checkstyle	Google Java Style + custom	0 ошибок
PMD 7	Security, Performance, Style	0 ошибок
SpotBugs + FindSecBugs	баг‑паттерны, уязвимости	Low + Medium + High
Modernizer	поиск устаревших API	0 ошибок

Все плагин‑репорты агрегируются в Maven Site:

mvn site
open target/site/index.html

---

Расширение функциональности

Новая стратегия генерации

public class MyMazeGenerator implements GenerationStrategy {
    @Override
    public Maze generate(Coordinate size) {
        // Ваша магия…
    }
}

GeneratorContext context = new GeneratorContext();
context.setMazeGeneratorStrategy(new MyMazeGenerator());
Maze maze = context.generateMaze(new Coordinate(50, 50));

Новый решатель

1. Реализовать SolvingStrategy.
2. При желании — добавить эвристику (например, A*).
3. Зарегистрировать в SolverContext.

Не забудьте тесты и описание в README 😉

---

CI/CD

• GitHub Actions
  • Триггеры: push, pull_request, schedule (еженедельно).
  • Job build:
    • mvn --batch-mode verify -Pci
    • Проверка стиля и покрытие.
  • Job release (тег v*):
    • пакуем fat‑jar,
    • генерируем Changelog,
    • публикуем в «Releases».

X‑платформенный кешатор Maven позволяет сократить время до ±40 с.

---

Часто задаваемые вопросы

Почему Java 21? Можно ли на 17?

Да, минимально требуется 17 (LTS), но примеры используют records и pattern‑matching for switch, поэтому рекомендую 21.

Как изменить символы отрисовки?

Поменяйте константы в StringRenderer (VERTICAL_WALL, HORIZONTAL_WALL, PATH).

Приложение тормозит на 10 000×10 000

Используйте профили benchmark / JMH, попробуйте оптимизировать структуру Cell (битовые флаги вместо enum) или перейти с ArrayList на массивы примитивов.

---

Roadmap

• A* и IDA* решатели
• Генератор Kruskal
• Web‑рендер на Spring Boot + Thymeleaf
• JMH‑бенчмарки
• Dockerfile и GHCR image
• Авто‑документация через Javadoc‑site

---

Содействие

PR‑ы и Issues приветствуются!
Перед отправкой:

mvn clean verify

Убедитесь, что все линтеры зелёные и тесты проходят.

Формат коммитов — conventional commits. Вопросы — в Discussions или Telegram канал @MazeGameJava.

---

Лицензия

MIT © 2025 therad445
Используйте, модифицируйте, распространяйте — только оставьте ссылку на оригинал.