Assignment-4/README.md

# Java Knight ⚔️
Welcome to **Java Knight**, a turn-based RPG with Roguelike elements which can be run in the terminal.

### Prologue: The Legend of Javanest 📜
*For centuries, the land of Javanest lived in peace, until a magical Dragon attacked, plunging the realm into absolute darkness. With a wicked curse, the Dragon transformed the innocent people into horrific monsters: Goblins, Skeletons, and Vampires. Retreating to its impenetrable Castle, the Dragon divided the three keys to its lair and hid them among these cursed creatures. Now, it is your duty to step up and save the land! You must navigate through dangerous encounters, recover the unique key from each monster type, and slay the Dragon to break the curse and restore peace to Javanest!*

---

## How The Game Works 🎮

- **The Core Loop:** The game starts with the player spawning at his camp. He can then choose to:
    - **1. Enter the portal:** Which  will lead either to a random standard location (`Forest`, `Graveyard`, or `Crypt`), or to the Dragon's castle based on the player's choice.
    - **2. Visit the Merchant:** To buy and store Weapons, Armors and different Consumables.


- **Player Choices:** Before engaging in a fight and after spawning at a random location, the player is presented with the following options:
    - **1. Fight the enemy:** Enter the turn-based combat sequence.
    - **2. Move to another location:** Skip the current enemy and spawn a new random one.
        - **Going to the Castle to fight the Dragon:** The player may enter the Dragon's castle only if he has all 3 unique keys.


- **The Key Drop Logic (RNG Gatekeeping):**
    - When the player defeats an enemy, there is a **specific percentage chance** that it will drop the unique key associated with its species (Goblin Key, Skeleton Key, Vampire Key).
    - **One Key Per Species:** Once a player obtains a specific key (e.g., Goblin Key), subsequent enemies of that same type (other Goblins) will **never** drop a key again.


- **Experience & Leveling System:**
    - Defeating an enemy grants **XP** and some **Coins**. The amount of XP and Coins scale proportionally to the enemy's power level.
    - Upon reaching an XP threshold, the player levels up. **Leveling up automatically increases the player's Max HP and Max Stamina**, making them strong enough to eventually face the Dragon.


- **Post-Combat Recovery:** After each successful battle, the player has the choice to either continue fighting enemies, or to return to his camp to recover HP and Stamina.


- **Final Boss Fight:**  Once all three unique keys are collected, the player can unlock the Castle gates to face the Dragon. Defeating the Dragon breaks the curse, resulting in **Victory**. Dying at any point results in **Game Over**.

---

## Core Mechanics ⚙️

- **Turn-based combat** – The player and monsters take turns attacking each other or defending themselves. Each entity performs one of these 4 possible moves during their turn:
    - **1. Light Attack:** Deals basic damage, no Stamina cost.
    - **2. Heavy Attack:** Deals high damage, medium Stamina cost.
    - **3. Defend:** Completely blocks the enemy's *next* strike, medium Stamina cost.
    - **4. Special Ability:** A unique class-based ultimate move, high Stamina cost (available only to the player and the final boss).

   In addition to these moves, the player can also use consumables mid-fight without using their turn.


- **Character classes with Unique Traits** – Players can choose from archetypes like **Knight, Assassin, or Wizard**, each starting with distinctly different base stats:
     - **Knight** ⚔️: Highest Base Damage.
         - **Special:** Performs a shield bash that stuns the enemy, forcing them to skip their next turn while dealing heavy damage.
     - **Assassin** 🗡️: Highest Max Stamina.
         - **Special:** Turns invisible, dodging the next incoming attack completely and guaranteeing a Critical Hit on their next turn.
     - **Wizard** 🧙‍♂️: Highest Max Health (HP).
         - **Special:** Casts a devastating spell that damages the enemy while simultaneously replenishing some HP.
       
       
- **Monsters' Attributes:** 
    - **Goblin** 👹: High heavy attack chance but low health.
    - **Skeleton** 💀: Can resurrect once per battle with 50% HP.
    - **Vampire** 🧛‍♂️: Life steal ability – a portion of the damage it deals to the player is added back to its own health.
    - **Dragon (Final Boss)** 🐉: Immune to normal defense. Its fiery breath bypasses shields and deals massive damage.

---

## OOP Principles Used 📋

This project is made using Object-Oriented Programming (OOP) Principles. Here is a brief explanation of how and where these concepts are applied:

### 1️⃣ Encapsulation
**Encapsulation** means restricting direct access to an object's internal data by using `private` (or in some cases `protected`) modifiers, and requiring all access and interactions to happen through public methods.

For example, variables like `hp`, `stamina`, or armor's `durability` cannot be directly viewed or changed by external classes. Instead, we use getter/setter methods to access these variables and methods like `takeDamage()`, `spendStamina()` and `reduceDurability()` to handle the logic.


### 2️⃣ Inheritance
**Inheritance** means deriving new classes from existing ones, allowing child classes to automatically contain fields and methods from its parent class without rewriting duplicate code.

We use inheritance when we want a class to include the general logic of another class, but with some of its features defined more specifically. 

For example, `Knight`, `Assassin` or `Wizard` all inherit the general mechanics of the `Player` class, but each subclass specifies its own unique base stats and special abilities. 


### 3️⃣ Abstraction
**Abstraction** means defining a class's base structure, while leaving the specific execution details for later.

We can achieve and use abstraction in two ways:

- **1. Through Abstract Classes:** For example, `Player` and `Enemy` classes are abstract. They contain the base structure and important logic needed, but each subclass define its own unique details in its own way (like `specialAbility()` for `Player` subclasses and `choice()` for `Enemy` subclasses).


- **2. Through Interfaces:** For example, The `Entity` interface acts as a strict contract which ensures that any implementing class (like `Player` and `Enemy`) MUST include behaviors like `lightAttack()`, `defend()` and any methods mentioned in the interface. This allows the game to handle players and monsters the same way.


### 4️⃣ Polymorphism
**Polymorphism** means different objects responding differently to the exact same method call. Java automatically figures out which specific version of the method to run at runtime based on the object's active subclass type.

For example, when the combat loop executes `player.specialAbility(enemy);`, Java automatically determines which version to execute: the Knight’s shield, the Assassin’s strike, or the Wizard’s spell.

![structure](Readme_Pictures/structure.png)

---

## Additional Features ⭐

- ### Merchant System & Inventory Management:
  Coins you earn from defeated enemies can be spent at the Camp merchant to purchase, store, and use different Weapons, Armors, and Consumables like Healing Flasks and Stamina Potions!

- ### Enhanced Console UX: 
  ANSI escape codes are used to provide color-coded narrative output.

---

## How To Run And Play 🕹️

1. **Fork** this repository and clone it to your local machine:
```
git clone https://git.meshcomp.ir/Soroush/Assignment-4.git
````
2. **Open** the project folder in your preferred Java IDE.


3. **Run** the `Main.java` class and enjoy the game!

![cover](Readme_Pictures/image.png)
###### - Born of God and Void. You shall seal the blinding light that plagues their dreams. You are the Vessel. You are the Java Knight.