Ērūca is a hand-drawn 2D side-scrolling puzzle adventure game built entirely from scratch using Java and JavaFX.
Inspired by classic adventure and puzzle games like Machinarium, players take on the role of a small, gentle caterpillar who is bullied and pushed out of her tree by others. Stranded on the damp forest ground, she must navigate the dangerous forest micro-world, solve environmental puzzles, interact with insect NPCs, and climb her way back to the top to achieve her ultimate dream of pupating into a beautiful butterfly.
- Custom Engine: Built purely in Java (JDK 25) and JavaFX (v21) without external game engines. Features a custom delta-time physics loop, collision detection, and rendering system.
- Hand-Drawn Art Style: Original 2D graphics and frame-by-frame sprite animations.
- Puzzle Solving: 4 levels requiring logical thinking, environmental interaction, and timing.
- Interactive Inventory: A dynamic 3-slot inventory system supporting Drag-and-Drop item crafting and world-dropping.
- Story Rich: Features engaging dialogue bubbles, NPC quests, and custom intro/outro cinematic sequences.
For detailed information about playing the game or understanding its underlying architecture, please refer to the provided documentation files:
The game fully supports custom keybindings (configurable in the Settings menu). The default controls are:
- W / S - Climb Up/Down // Stand Up/Down (on vertical surfaces)
- A / D - Move Left // Move Right
- E - Interact (Talk to NPCs, pick up items)
- ESC - Pause Game / Open Menu
- Mouse drag in inventory - grab items from inventory and place them in world or combine with another item
- Java: JDK 21 or higher
- Maven: Installed and configured in your environment
Clone the repository and run the game using the Maven JavaFX plugin:
git clone [https://gitlab.fel.cvut.cz/B252_B0B36PJV/lokveolg.git](https://gitlab.fel.cvut.cz/B252_B0B36PJV/lokveolg.git)
cd lokveolg
mvn clean javafx:run
To run the game with developer diagnostic logs enabled, add the debug flag:
mvn clean javafx:run -Djavafx.args=--debug
- Language: Java 25
- GUI / Graphics: JavaFX 21
- Build Tool: Maven
Core Architecture Patterns:
- State Machine: Manages transitions between gameplay, menus, and cinematic cutscenes.
- Game Loop: Decouples the progression of game time (delta-time) from user input and rendering frame rates.
- Factory: Programmatically assembles and populates specific map layouts and entities.
- Background Tasks (Multithreading): Utilizes javafx.concurrent.Task and daemon threads to process asynchronous enemy AI logic without blocking the main render thread.
Author: Olga Lokvencová
Course: Programming in Java (B0B36PJV)
Institution: CTU in Prague, Faculty of Electrical Engineering (FEL ČVUT)