HW-04-JAVA-KNIGHT/README.md

# 🛡️ Java‑Knight RPG

<p align="center">
<img src="image_gen_cf601188-a1ec-4039-a520-50a411356240_0.png" width="100%">
</p>

<p align="center">
<img src="image_gen_e236b208-47dd-4dda-86a6-cb69f5c3f12f_0.png" width="160">
</p>

A console‑based fantasy RPG written entirely in pure Java.

Fight monsters, explore mythical locations, manage your inventory, unlock abilities and defeat the Dragon of Valhalla.

---

# 📚 Table of Contents

- Overview
- Core Features
- Player Classes
- Systems & Managers
- Items & Equipment
- Combat System
- Locations
- Boss Fight
- Project Structure
- How to Run
- Future Improvements
- Example Output
- Author

---

# ⚔️ Overview

Java‑Knight is a modular **turn‑based RPG engine** built with Java and object‑oriented design.

The project focuses on:

- Clean OOP architecture
- Modular manager systems
- Expandable combat mechanics
- Class‑based gameplay
- Status effect system
- Inventory & equipment system

The **GameLoop** controls the main gameplay cycle including player actions, combat resolution and movement between locations.

---

# 🧩 Core Features

## 🎮 Gameplay Loop

The **GameLoop** manages:

- Player creation
- Class selection
- Location movement
- Enemy spawning
- Combat handling
- Inventory usage

Locations are interconnected and enemies spawn dynamically.

---

# 🧙 Player Classes

Each class has its own stats, armor and special ability.

| Class | Ability | Description |
|------|------|------|
| Knight | Guardian Oath | Heals and increases damage |
| Wizard | Arcane Storm | Powerful magic attack |
| Assassin | Poison Dagger | Poison damage and burst attack |

---

# 🛠 Systems & Managers

The architecture separates game logic into managers.

| Manager | Responsibility |
|------|------|
| ActionDecisionManager | Handles combat decisions |
| InventoryManager | Equipment & item usage |
| ManaCostManager | Mana cost calculations |
| SpecialAbilityManager | Executes abilities |
| StatusEffectManager | Applies burn, poison, freeze |
| TotalAttackCalculator | Calculates final damage |

This modular design keeps the **GameLoop clean and maintainable**.

---

# ⚗️ Items & Equipment

## ⚔ Weapons

- Sword
- Dagger

Weapons can receive special effects.

---

## 🌫 Weapon Effects

| Effect | Description |
|------|------|
| BurnEffect | Damage over time |
| FreezeEffect | Slows or freezes target |
| PoisonEffect | Gradual HP drain |

---

## 🛡 Armor

Each class uses its own armor type.

Examples:

- KnightArmor
- WizardArmor
- AssassinArmor

Armor increases defense and survivability.

---

## 🧴 Consumables

Consumables are located in:

```
org.project.item.consumables
```

Available items:

- **HealFlask** → restores HP  
- **ManaFlask** → restores MP  

These can be used during gameplay from the **Inventory menu**.

---

# 🧠 Combat System

Combat is **turn‑based**.

Each round:

1. Status effects update  
2. Player action  
3. Enemy AI action  

Features:

- Damage calculation system
- Defense mechanics
- Status effects
- Ability cooldowns
- Mana system
- XP rewards
- Key drop system

---

# 🗺 Locations

| Location | Description |
|------|------|
| Valhalla | Starting realm |
| Elysium | Sacred plains |
| Niflheim | Frozen undead land |
| Castle | Dragon battlefield |

Moving between locations spawns enemies:

- Goblin
- Skeleton
- Vampire

---

# 🐉 Boss Fight

To unlock the final boss you must collect:

- GoblinKey
- SkeletonKey
- VampireKey

After collecting all keys you can trigger:

```
Fight Dragon
```

Defeat the **Dragon of Valhalla** to win the game.

---

# 🎨 Console Colors

ANSI colors are used for better terminal visuals.

```java
Colors.RED    = "\u001B[31m";
Colors.GREEN  = "\u001B[32m";
Colors.YELLOW = "\u001B[33m";
Colors.CYAN   = "\u001B[36m";
Colors.RESET  = "\u001B[0m";
```

Example:

```
Guardian Oath: Sir Duncan heals +5 HP and gains 50% increased damage.
```

---

# 🧩 Project Structure

```
org.project
 ┣ abilities
 ┃ ┣ ArcaneStorm.java
 ┃ ┣ GuardianOath.java
 ┃ ┣ PoisonDagger.java
 ┃ ┗ SpecialAbility.java
 ┣ combat
 ┃ ┣ AttackResult.java
 ┃ ┗ TotalAttackCalculator.java
 ┣ entity
 ┃ ┣ players
 ┃ ┗ enemies
 ┣ item
 ┃ ┣ armors
 ┃ ┣ weapons
 ┃ ┗ consumables
 ┣ managers
 ┃ ┣ InventoryManager.java
 ┃ ┣ ActionDecisionManager.java
 ┃ ┣ ManaCostManager.java
 ┃ ┣ SpecialAbilityManager.java
 ┃ ┗ StatusEffectManager.java
 ┣ weaponEffects
 ┃ ┣ BurnEffect.java
 ┃ ┣ FreezeEffect.java
 ┃ ┗ PoisonEffect.java
 ┣ location
 ┃ ┗ Location.java
 ┣ Colors.java
 ┣ GameLoop.java
 ┗ Main.java
```

---

# 🚀 How to Run

Compile the project:

```
javac -d out src/main/java/org/project/Main.java
```

Run the game:

```
java -cp out org.project.Main
```

---

# 💬 Example Console Output

```
====== JAVA KNIGHT ======
Choose class:
1. Knight   (HP:150 MP:80 DMG:12)
2. Wizard   (HP:80 MP:200 DMG:10)
3. Assassin (HP:90 MP:120 DMG:15)

1
==== GAME MENU ====
Location: Valhalla
Enemy: vampire{MAX_HP : 90 | MAX_MP : 80 | XP_REWARD : 80 | BASE_DAMAGE : 12 | personalArmor = vampire armor | Type: MEDIUM | Defense: 16 | Durability: 30/30}

1. Fight
2. Inventory
3. Move
0. Exit

1
⚔ COMBAT STARTED! ⚔
==== YOUR TURN ====
Sir Duncan-> HP: 150 | MP: 80 | level: 1 | XP: 0
Vampire-> HP: 90 | MP: 80


Choose attack type:

1.lightAttack
2.heavyAttack
3.heal
4.defend
5.ability
6.shielBash
7.inventory
2
Vampire got 34 damage


==== ENEMY TURN ====

enemy random choose action: lightAttack
Sir Duncan got 17 damage
```

---

# 🧠 Future Improvements

- Multiple enemies per location
- Save / Load system
- More consumables
- More classes
- Advanced enemy AI
- Graphical version (JavaFX / LWJGL)

---

# 🧑‍💻 Author

Created by **Mohammadreza Ashrafian**

2026

⚔️ *May your code be strong and your armor unbreakable.*