FXGL Hero Game

2D игра на Java с использованием фреймворка FXGL.

Учебный проект для изучения разработки игр на Java.

🚀 Quick Start

Требования

• Java 17 или выше
• Gradle 8.x (включён в проект как gradlew)

Запуск

./gradlew run

Управление

• W — вверх
• A — влево
• S — вниз
• D — вправо

Собирайте монеты, избегайте стен.

---

📚 Пошаговый гайд разработки

Этот проект создан поэтапно. Изучайте коммиты последовательно, чтобы понять процесс разработки.

Этап 1: Настройка проекта

Что сделано:

• Создан Gradle проект с плагинами application и java
• Добавлен плагин org.openjfx.javafxplugin для JavaFX
• Подключена зависимость FXGL 17.3
• Настроены Java 17 и репозитории

Файлы:

• build.gradle — конфигурация сборки
• settings.gradle — имя проекта

Ключевые настройки в build.gradle:

java {
    sourceCompatibility = JavaVersion.VERSION_17
    targetCompatibility = JavaVersion.VERSION_17
}

javafx {
    version = '17'
    modules = ['javafx.controls', 'javafx.fxml', 'javafx.swing']
}

dependencies {
    implementation 'com.github.almasb:fxgl:17.3'
}

---

Этап 2: Создание основного класса игры

Что сделано:

• Создан класс FxglGameApp, наследующий GameApplication
• Реализованы методы жизненного цикла FXGL:
  • initSettings() — настройки окна (800x600, заголовок)
  • initGame() — инициализация игрового мира
  • initInput() — обработка ввода
  • initPhysics() — коллизии
  • initUI() — отображение счёта

Файлы:

• src/main/java/com/example/fxglgame/FxglGameApp.java

Жизненный цикл FXGL:

initSettings() → initGame() → initInput() → initPhysics() → initUI() → игровой цикл

---

Этап 3: Система сущностей (Entity Factory)

Что сделано:

• Создан EntityType — enum с типами сущностей (PLAYER, COIN, WALL)
• Создан GameEntityFactory — фабрика для создания сущностей
• Реализованы методы создания:
  • newPlayer() — игрок (синий квадрат 40x40)
  • newCoin() — монета (жёлтый круг)
  • newWall() — стена (серый прямоугольник)

Файлы:

• src/main/java/com/example/fxglgame/EntityType.java
• src/main/java/com/example/fxglgame/GameEntityFactory.java

Аннотация @Spawns:

@Spawns("player")
public Entity newPlayer(SpawnData data) {
    return entityBuilder(data)
            .type(EntityType.PLAYER)
            .bbox(new HitBox(BoundingShape.box(40, 40)))
            .view(new Rectangle(40, 40, Color.DODGERBLUE))
            .with(new PlayerComponent())
            .collidable()
            .build();
}

---

Этап 4: Компонент игрока и движение

Что сделано:

• Создан PlayerComponent — компонент управления игроком
• Реализовано движение через translateX/Y (без PhysicsComponent)
• Добавлены флаги направления (up, down, left, right)
• Ограничение перемещения в пределах поля

Файлы:

• src/main/java/com/example/fxglgame/PlayerComponent.java

Движение в onUpdate():

@Override
public void onUpdate(double tpf) {
    double dx = 0, dy = 0;
    if (left)  dx -= SPEED;
    if (right) dx += SPEED;
    if (up)    dy -= SPEED;
    if (down)  dy += SPEED;

    entity.translateX(dx * tpf);
    entity.translateY(dy * tpf);
}

---

Этап 5: Обработка ввода (Input)

Что сделано:

• Использован UserAction для обработки клавиш
• onAction() вызывается каждый кадр при зажатой клавише
• onActionEnd() вызывается при отпускании

Файлы:

• FxglGameApp.java — метод initInput()

Пример:

getInput().addAction(new UserAction("Up") {
    @Override protected void onAction()    { pc().setUp(true);  }
    @Override protected void onActionEnd() { pc().setUp(false); }
}, KeyCode.W);

---

Этап 6: Коллизии и сбор монет

Что сделано:

• Реализована коллизия PLAYER ↔ COIN в initPhysics()
• При столкновении монета удаляется, счёт увеличивается
• Добавлен спавн новых монет

Файлы:

• FxglGameApp.java — метод initPhysics()

Коллизия:

onCollisionBegin(EntityType.PLAYER, EntityType.COIN, (p, coin) -> {
    coin.removeFromWorld();
    inc("score", +10);
    spawnRandomCoin();
});

---

Этап 7: UI и отображение счёта

Что сделано:

• Создан текстовый элемент счёта
• Реализовано绑定 с property через textProperty().bind()
• Счёт обновляется автоматически

Файлы:

• FxglGameApp.java — метод initUI()

Binding:

Text scoreText = getUIFactoryService().newText("Score: 0", Color.OLIVEDRAB, 22.0);
scoreText.textProperty().bind(
        getWorldProperties().intProperty("score").asString("Score: %d")
);
addUINode(scoreText);

---

Этап 8: Стены и препятствия

Что сделано:

• Добавлены стены по периметру поля
• Созданы внутренние препятствия
• Метод spawnWall() для удобного создания стен

Файлы:

• FxglGameApp.java — метод initGame() и spawnWall()

---

📁 Структура проекта

fxgl-game/
├── src/main/java/com/example/fxglgame/
│   ├── FxglGameApp.java      # Точка входа, игровой цикл
│   ├── EntityType.java       # Типы сущностей
│   ├── GameEntityFactory.java # Фабрика сущностей
│   └── PlayerComponent.java  # Компонент игрока
├── build.gradle              # Конфигурация Gradle
├── settings.gradle           # Настройки проекта
├── .gitignore                # Игнорируемые файлы
└── README.md                 # Эта документация

---

🔍 Как смотреть коммиты

В терминале

Последние 5 коммитов:

git log -n 5 --oneline

Подробно с изменениями:

git show <commit-hash>

История конкретного файла:

git log --follow src/main/java/com/example/fxglgame/FxglGameApp.java

Разница между коммитами:

git diff <commit1> <commit2>

На GitHub

1. Откройте репозиторий на GitHub
2. Кнопка "Commits" над списком файлов — вся история
3. Клик по коммиту — изменения с подсветкой
4. Кнопка <> (Browse files) — просмотр файлов на момент коммита

---

🎯 Идеи для развития

1. Враги — добавить компонент преследования игрока
2. Анимации — спрайты вместо геометрических фигур
3. Звуки — музыка и эффекты (FXGL поддерживает)
4. Уровни — загрузка карт из файлов
5. Босс — большой враг с несколькими фазами
6. Способности — ускорение, прыжки, атака

---

📦 Сборка

# Собрать JAR
./gradlew build

# Запустить JAR
java -jar build/libs/fxgl-game-1.0.0.jar

---

📄 Лицензия

Учебный проект. FXGL лицензируется под Apache 2.0.