faraz_ardeh/HW-04-JAVA-KNIGHT
1
0
Fork 0
forked from AdvancedProgramming1404/HW-04-JAVA-KNIGHT
Code Pull Requests 1 Activity

Java Knight

Browse Source
This commit is contained in:
faraz_ardeh
2026-07-12 19:20:33 +03:30
parent 78d4bedb08
commit a527c5bcfa
67 changed files with 1742 additions and 254 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+174 -154
View File
@@ -1,175 +1,195 @@
# Fourth Assignment - Java Knight ⚔️
A turn-based RPG with Roguelike elements which can be run in the terminal.
# Java Knight ⚔️
### **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 battle these monsters, recover the unique key from each monster type, and finally slay the Dragon to break the curse and restore peace to Javanest!*
A turn-based, roguelike-inspired RPG that runs entirely in the terminal, written
in Java for the fourth Advanced Programming assignment.
### **Introduction**
Welcome to **Java knight**, a turn-based RPG inspired by Roguelike games! In this assignment, you will develop a **text-based role-playing game (RPG)**. This project is designed to rigorously test your understanding of **Object-Oriented Programming (OOP) principles**.
⚠️ **REQUIREMENT:** You **must** utilize all the OOP concepts you have learned so far—including *Inheritance, Interfaces, Abstract Classes, Encapsulation, Polymorphism, Overloading, and Overriding*. It is extremely important that you use everything in its right place. Your design and architecture will be graded based on how well you apply these principles to avoid code duplication and maintain a clean structure.
🎯 **Your goal is not just to complete the assignment but to learn and apply OOP effectively!**
### **What is a Turn-Based Game?**
In this combat system, two sides - which are usually the player's side and the enemy's side - attack each other in turns. The side which is not attacking can perform actions to avoid or deflect the enemy's attack.
### **Core Mechanics:**
- **Turn-based combat** – Players and monsters take turns attacking each other.
- **Character classes with Unique Traits** – Players can choose from archetypes like **Knight, Assassin, or Wizard**, each starting with distinctly different base stats.
- **Unified Mana/Stamina System** – All player classes use a unified resource (Mana/Stamina) to perform actions.
- **Standardized Action Set** – Every player character has exactly 5 specific actions available during their turn.
- **Experience & Leveling System** – Earn XP based on enemy strength to automatically level up and increase your base stats.
- **Progression System** – You cannot fight the Dragon immediately. You must farm enemies for a chance to drop their specific key, collect all three, and grow stronger first.
> *For centuries, the land of Javanest lived in peace, until a magical Dragon
> plunged it into darkness, cursing its people into monsters and scattering the
> three keys to its lair among them. Battle the cursed creatures, recover the
> Goblin, Skeleton and Vampire keys, grow strong, and slay the Dragon to break
> the curse and restore peace to Javanest!*
---
## Tasks 📝
### 1️⃣ Step 1: Fork & Setup 🍴
1. **Fork** this repository and clone it to your local machine.
```bash
git clone https://git.meshcomp.ir/AdvancedProgramming1404/HW-04-JAVA-KNIGHT.git
```
2. Create a new branch named `develop` and switch to it.
```bash
git checkout -b develop
```
### 2️⃣ Step 2: Implement the Class Hierarchy 🌲
A well-structured OOP hierarchy is crucial. Avoid duplicating code by placing shared logic in abstract classes.
- **Entities & Locations:** You have `Entity`, `Item`(Bonus) , and `Location`.
- **Players:** `Player` is an abstract class implementing `Entity`. Subclasses: `Wizard`, `Knight`, `Assassin`.
- **Base Stat Differences:** Each class must have distinct starting stats. For example:
- **Knight:** Highest Base Damage.
- **Wizard:** Highest Max Health (HP).
- **Assassin:** Highest Max Stamina/Mana.
- **Enemies:** `Enemy` is an abstract class implementing `Entity`. Subclasses: `Skeleton`, `Goblin`, `Vampire`, and **`Dragon`**.
- **The Boss:** Even though `Dragon` is the final boss, it **must** be a subclass of `Enemy` to inherit common combat properties, while possessing extremely high stats and unique mechanics.
- **Item (Bonus):** `Consumable`, `Armor`, `Weapon` are abstract classes implementing `Item`. example :
- KnightArmor extends Armor - you can add more subclasses of Armor for extra score
- Sword extends Weapon - you can add more subclasses of Weapon for extra score
- Flask extends Consumable - you can add more subclasses of Consumable for extra score
![structure](Readme_Pictures/structure.png)
### 3️⃣ Step 3: Implement Player & Monster Methods 🏹
**Player Actions (The Rule of Five):**
Every player class **must** implement exactly the following 5 actions (You can use an interface like `ICombatActions`). Every action (except Light Attack) consumes a specific amount of Mana/Stamina. The **Special Ability** must consume the *highest* amount of Mana compared to the others.
1. **Light Attack:** Deals moderate damage and costs **NO Mana**. (Note: If the player runs out of Mana/Stamina, this is the ONLY action they can perform.)
2. **Heavy Attack:** Deals high damage, medium Mana cost.
3. **Defend:** Completely blocks or significantly reduces the damage of the enemy's *next* strike. Medium Mana cost.
4. **Heal:** Restores a portion of the player's HP. Medium-high Mana cost.
5. **Special Ability:** A unique class-based ultimate move (Highest Mana cost):
- **Wizard** 🧙‍♂️: Casts a devastating spell that damages the enemy while simultaneously replenishing some HP.
- **Assassin** 🗡️: Turns invisible, dodging the next incoming attack completely and guaranteeing a *Critical Hit* on their next turn.
- **Knight** ⚔️: Performs a shield bash that stuns the enemy, forcing them to skip their next turn while dealing heavy damage.
**Monster Abilities:**
- **Goblin** 👹: High critical hit chance but low health.
- **Skeleton** ☠️: Can resurrect once per battle with 50% HP.
- **Vampire** 🦇: Lifesteal 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.
🔹 Make sure each entity **prints messages** when performing actions. example output (while in combat) :
```bash
You chose to FIGHT!
[Ser Duncan - 45/45 HP | 40/40 Mana]
[Goblin - 30/30 HP]
## Table of Contents
1. [How to Compile & Run](#how-to-compile--run)
2. [How to Play](#how-to-play)
3. [Classes, Enemies & Stats](#classes-enemies--stats)
4. [Project Structure](#project-structure)
5. [OOP Principles Used](#oop-principles-used)
6. [Bonus Features](#bonus-features)
---
Your Turn:
1. Light Attack | 2. Heavy Attack (-8 Mana) | 3. Defend (-6 Mana) | 4. Heal (-12 Mana) | 5. Shield Bash (-15 Mana)
```
## How to Compile & Run
The project is a standard Maven project. You need **JDK 21+** installed.
### Using Maven (recommended)
```bash
→ Chose: Light Attack
⚔️ Ser Duncan (Knight) used Light Attack! (0 Mana)
Goblin took 10 damage!
Goblin has 20/30 HP remaining.
Ser Duncan Mana: 40/40
```
```
Goblin's Turn :
👹 Goblin used Critical Strike!
💥 Critical hit! Ser Duncan took 20 damage!
Ser Duncan has 25/45 HP remaining.
```
🔹 *Narrative Console:* Use ANSI escape codes to print colorful narrative logs (e.g., Red for damage, Blue for Mana usage, Green for healing).
### 4️⃣ Step 4: Implement the Game Loop & Progression 🎮
1. **The Core Loop:** The game starts with the player entering a location. A random standard enemy (`Goblin`, `Skeleton`, or `Vampire`) spawns immediately.
2. **Player Choices:** Before engaging, 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.
- **3. Go to the Castle to fight the Dragon:** *(Note: This option must remain strictly hidden or locked until the player has successfully collected all 3 keys).*
3. **The Key Drop Logic (RNG Gatekeeping):**
- When the player defeats an enemy, there is a **specific percentage chance (e.g., 20%)** 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.
- The player **must collect all 3 distinct keys** to unlock Option 3 and enter the Castle.
4. **Post-Combat Recovery:** After each successful battle, the player's HP and Mana bars must automatically replenish (either fully or partially) to their base amounts so they are ready for the next encounter.
5. **Experience & Leveling System:**
- Defeating an enemy grants **XP**. The amount of XP must scale proportionally to the enemy's power level.
- Upon reaching an XP threshold, the player levels up. **Leveling up must automatically increase the player's Max HP and Max Stamina/Mana**, making them strong enough to eventually face the Dragon.
6. **Final Boss Fight:** Once the 3 Keys are obtained and the player chooses to go to the Castle, they will face the Dragon. Defeating the Dragon breaks the curse, resulting in **Victory**. Dying at any point results in **Game Over**.
🔹 Example game loop structure:
```java
while (player.isAlive() && enemy.isAlive())
player.attack(enemy);
if (enemy.isAlive()) {
enemy.attack(player);
}
}
cd Java-Knight
mvn compile
mvn exec:java -Dexec.mainClass=org.project.Main
```
### Using plain `javac` / `java`
```bash
cd Java-Knight
# compile every source file into the target/classes folder
find src/main/java -name "*.java" > sources.txt
javac -d target/classes @sources.txt
### 5️⃣ Step 5: Extra Features & Bonus Tasks ⭐
*(Optional for extra credit)*
# run it
java -cp target/classes org.project.Main
```
✅ **Dynamic Economy & Merchant System:** Implement coins that drop from enemies. Add a "Visit Merchant" option to the main loop where players can spend coins to buy specific weapons, armors, or consumables.
✅ **Multiple Weapons & Inventory:** Players can buy, store, and swap between multiple weapons or use consumables mid-combat.
✅ **Multiplayer/Party Mode:** Allow multiple players to team up and fight multiple enemies together. The Dragon's breath attack will damage the entire party simultaneously.
✅ **PvP Mode:** Implement a **Player vs. Player** combat system.
### 6️⃣ Step 6: Write a Comprehensive README 📄
As the final mandatory step of your development, you must replace the default `README.md` with your own comprehensive documentation. Your README should include:
- A brief introduction to the game.
- How to compile and run your project from the terminal.
- An explanation of the classes, design patterns, and OOP principles you used.
- A brief guide on how to play (controls, stats, classes).
> The game uses ANSI colour codes, so run it in a real terminal (macOS Terminal,
> Linux shell, Windows Terminal) for the intended colourful output.
---
## Evaluation Criteria ⚖
## How to Play
| **Criteria** | **Points** |
|-------------------------------------------------------------|------------|
| Proper use of OOP principles | **50** |
| Working combat mechanics, Leveling System & Enemy abilities | **20** |
| Clear and Comprehensive `README.md` | **20** |
| Code readability, documentation, and comments | **10** |
| Meaningful, interactive, & colored console outputs | **10** |
| Inventory (item) and Merchant System (bonus) | **20** |
| Other Extra features (bonus tasks) | **20** |
| **Total Score** | **150** |
1. **Name your hero** and **pick a class** (Knight, Wizard, or Assassin).
2. You wander into a random **location** and a random standard enemy appears.
For each encounter you choose:
- **1. Fight** – enter turn-based combat.
- **2. Move** – skip this enemy and travel somewhere new.
- **3. Visit the Merchant** – spend coins on potions, a weapon, or repairs.
- **4. Go to the Castle** – *only appears once you hold all 3 keys* – fight
the Dragon.
3. **Combat is turn-based.** On your turn you pick one of five actions. Only
**Light Attack** is free; the rest cost Mana/Stamina, and the class
**Special** costs the most. If you run out of Mana, you can still Light
Attack.
## Tips 🚀
- **Follow OOP principles**: Avoid redundant code by using inheritance properly. Think carefully about what belongs in an abstract class vs. a specific subclass. Make sure you use overriding and overloading correctly.
- **Test your code**: Run different scenarios (fighting, running out of mana, leveling up, dying) to ensure everything works as expected.
- **Ask for help**: If you're stuck, reach out to your classmates or mentors.
| # | Action | Cost | Effect |
|---|---------------|-----------|--------|
| 1 | Light Attack | 0 | Moderate damage |
| 2 | Heavy Attack | 8 | Double damage |
| 3 | Defend | 6 | Blocks ~75% of the next hit |
| 4 | Heal | 12 | Restores 40% of max HP |
| 5 | Special | 15 | Unique class ultimate |
| 6 | Use Item | – | Drink a potion from your inventory |
## Submission ⌛
- **Deadline**: Submit your assignment before **21 Ordibehesht (May 11th, 2026)**.
- **Submission Format**: Push your code to your forked repository, create a PR, and ensure your comprehensive `README.md` is included in the root directory.
4. **Winning a fight** grants **XP** (scaled to the enemy's power), **coins**,
and a chance to drop that species' **key**. Your HP and Mana are then fully
restored.
5. **Leveling up** automatically raises your Max HP, Max Mana and base damage.
6. Collect **all 3 keys**, go to the Castle, and defeat the **Dragon** to win.
Dying at any point is **Game Over**.
![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.
---
## Classes, Enemies & Stats
### Player Classes
Each class has deliberately different starting stats, so they play differently.
| Class | HP | Mana | Base Dmg | Weapon | Special ability |
|------------|----|------|----------|-------------|-----------------|
| **Knight** ⚔️ | 50 | 40 | **8 (highest)** | Iron Sword | **Shield Bash** – heavy damage + stuns the enemy (skips its next turn) |
| **Wizard** 🧙 | **65 (highest)** | 45 | 5 | Oak Staff | **Arcane Blast** – heavy damage AND heals the caster |
| **Assassin** 🗡️ | 45 | **55 (highest)** | 6 | Twin Dagger | **Vanish** – dodges the next attack + guarantees a crit on the next strike |
### Enemies
| Enemy | HP | Ability | Key |
|------------|-----|---------|-----|
| **Goblin** 👹 | 30 | 40% chance to land a **critical hit** (double damage) | Goblin Key |
| **Skeleton** ☠️ | 40 | **Resurrects once** per battle at 50% HP | Skeleton Key |
| **Vampire** 🦇 | 48 | **Lifesteal** – heals for 50% of the damage it deals | Vampire Key |
| **Dragon** 🐉 | 160 | **True damage** – fiery breath ignores armor *and* the Defend stance | — |
Standard enemies each have a **25% chance** to drop their key, and only **one key
per species** can ever drop (once you have the Goblin Key, no other Goblin will
drop one).
---
## Project Structure
```
org.project
├── Main.java // entry point – builds the world, starts the game
├── Game.java // the game controller / main loop
├── Merchant.java // bonus shop system
├── entity
│ ├── Entity.java // interface every combatant implements
│ ├── players
│ │ ├── ICombatActions.java // interface: the 5 required actions
│ │ ├── Player.java // abstract base for all heroes
│ │ ├── Knight.java / Wizard.java / Assassin.java
│ └── enemies
│ ├── Enemy.java // abstract base for all monsters
│ ├── KeyType.java // enum of the three keys
│ ├── Goblin.java / Skeleton.java / Vampire.java / Dragon.java
├── item
│ ├── Item.java // interface for anything ownable/sellable
│ ├── weapons (Weapon abstract → Sword, Dagger, Staff, GreatAxe)
│ ├── armors (Armor abstract → KnightArmor, LeatherArmor, Robe)
│ └── consumables (Consumable abstract → Flask, ManaPotion)
├── location
│ └── Location.java // a place that spawns random enemies
└── util
├── ConsoleColors.java // ANSI colour helpers
└── Dice.java // random-number helpers
```
---
## OOP Principles Used
This project was designed around the seven principles the assignment asks for:
- **Encapsulation** – all fields are `private`/`protected` with getters. HP, Mana
and XP can only be changed through methods like `takeDamage`, `heal` and
`gainXP`, which enforce their own rules (clamping to max, capping at zero,
leveling up).
- **Inheritance** – shared logic lives in abstract base classes so it isn't
duplicated. `Player` holds the HP/Mana bars, leveling, inventory and four of
the five actions; `Knight`, `Wizard` and `Assassin` only add what's unique.
Same idea for `Enemy` → its four monster subclasses, and for
`Weapon`/`Armor`/`Consumable` → their concrete items.
- **Interfaces** – `Entity` is the contract every combatant obeys, which is what
lets the combat loop treat a Knight and a Dragon identically. `ICombatActions`
guarantees every player class implements exactly the five required actions.
`Item` unifies weapons, armor and consumables so the merchant can sell any of
them.
- **Abstract classes** – `Player`, `Enemy`, `Weapon`, `Armor` and `Consumable`
are all abstract: they provide shared state/behaviour but can't be instantiated
on their own, forcing subclasses to fill in the specifics (e.g.
`Player.specialAbility` is abstract).
- **Polymorphism** – the whole game loop is polymorphic. `Game` only ever calls
`Player`/`Enemy`/`Entity` methods; the correct `specialAbility`, `attack` or
`takeDamage` runs depending on the real object. Each enemy overrides `attack`
to add its signature move.
- **Overriding** – subclasses override base behaviour, e.g. `Skeleton` overrides
`takeDamage` to resurrect, `Vampire`/`Goblin`/`Dragon` override `attack`, and
every player class overrides `specialAbility`.
- **Overloading** – `takeDamage(int)` vs `takeDamage(int, boolean)` in `Player`.
The second, overloaded version ignores defenses and is how the Dragon's breath
bypasses armor and shields. The `Sword` also overloads its constructor.
---
## Bonus Features
- **Coins & Merchant system** – enemies drop coins; the Merchant sells Health
Flasks, Mana Potions, a stronger **Great Axe**, and can **repair** armor.
- **Inventory & consumables** – potions can be bought, stored and used mid-combat
(action 6).
- **Durable armor** – armor loses durability as it absorbs hits and eventually
breaks, until repaired at the merchant.
- **Colourful narrative console** – ANSI colours (red for damage, blue for mana,
green for healing) make the combat log easy to read.
---
*Born of God and Void. You shall seal the blinding light that plagues their
dreams. You are the Vessel. You are the Java Knight.*