Skip to content

Commit 1ec4586

Browse files
thembaxaba157thembaxaba157
authored
Update README.md
1 parent fc6e3c4 commit 1ec4586

File tree

1 file changed

+145
-61
lines changed

1 file changed

+145
-61
lines changed

‎README.md‎

Lines changed: 145 additions & 61 deletions
Original file line numberDiff line numberDiff line change
@@ -1,95 +1,179 @@
1-
things used/will be used so far
2-
- sqlite
3-
- junit and mockito for testing
4-
- sementic versioning and workflows
5-
- json for words
1+
# 🎮 Hangman CLI Game
62

3+
[![Java](https://img.shields.io/badge/Java-17+-brightgreen.svg)](https://www.oracle.com/java/)
4+
[![SQLite](https://img.shields.io/badge/SQLite-Database-blue.svg)](https://www.sqlite.org/)
5+
[![Tests](https://img.shields.io/badge/JUnit%20%2B%20Mockito-Test-yellow.svg)](https://junit.org/)
6+
[![Versioning](https://img.shields.io/badge/Semantic-Versioning-blueviolet.svg)](https://semver.org/)
7+
[![CI/CD](https://img.shields.io/badge/GitHub%20Actions-Automation-lightgrey)](https://github.com/yourname/hangman/actions)
78

9+
A feature-rich command-line Hangman game written in **Java**. It uses **SQLite** for persistent storage, **JSON** for word categories, and follows **Semantic Versioning** with **GitHub Actions** for automated testing and releases.
810

9-
10-
# Hangman Game - Rules & Mechanics
11+
---
1112

1213
## 📌 Overview
13-
The Hangman game is a word-guessing game where players try to complete a hidden word by guessing letters. Players can earn **points** for correct guesses and **scores** for winning rounds. Points can be used to **buy hints**, while scores determine leaderboard rankings.
14+
15+
This CLI game challenges users to guess words across various categories and difficulties. It includes:
16+
- Scoring and point mechanics
17+
- Persistent user accounts
18+
- Hints using point currency
19+
- Top 5 leaderboard system
20+
- Word categories from JSON
21+
22+
---
23+
24+
## 🚀 Features
25+
26+
- 🎯 Word selection by category and difficulty
27+
- 💰 Points system for hints
28+
- 🏆 Scores awarded only for wins
29+
- 📊 Persistent data in SQLite
30+
- 🔁 User management (create/load/delete/view)
31+
- 🧠 Hint types: reveal letter, extra attempt, reveal fact
32+
- 🧪 Unit tested using JUnit & Mockito
33+
- 📦 JSON-based word list (with descriptions and hints)
1434

1535
---
1636

17-
## 🎯 Objectives
18-
- Correctly guess all the letters of a word before running out of attempts.
19-
- Earn **points** for each correct guess.
20-
- Earn **scores** by completing words.
21-
- Spend **points** to buy hints if stuck.
22-
- Maintain a **streak** for bonus rewards.
37+
## 🗂️ Tech Stack
38+
39+
| Purpose | Technology |
40+
|----------------|----------------------|
41+
| Language | Java 17+ |
42+
| Database | SQLite (via JDBC) |
43+
| Word Storage | JSON (words.json) |
44+
| Input Handling | Scanner (CLI) |
45+
| Testing | JUnit + Mockito |
46+
| CI/CD | GitHub Actions |
47+
| Versioning | Semantic Versioning |
48+
49+
---
50+
51+
## 🏗 Architecture
52+
53+
```
54+
Main.java
55+
|
56+
v
57+
Hangman.java
58+
├── GameState enum
59+
├── UserSession (manages users)
60+
├── WordManager (loads JSON, selects words)
61+
└── GameSession (executes game loop)
62+
├── Uses HintSystem, InputHandler, DisplayManager
63+
└── Updates Score & Points via SQLite
64+
```
2365

2466
---
2567

26-
## 🏆 Score & 💰 Points System (Independent)
27-
| **Action** | **Effect on Points** | **Effect on Score** |
28-
|-------------------------------------|--------------------------------|---------------------------------|
29-
| Guess a correct letter | +1 (Easy), +2 (Medium), +3 (Hard) | No effect |
30-
| Guess a wrong letter | No effect | No effect |
31-
| Complete the word (Win) | No effect | +Total Points Earned for the Round |
32-
| Lose the round | No effect | No effect |
33-
| Win multiple games in a row | No effect | +Win Streak Bonus |
68+
## 🎮 Game Mechanics
69+
70+
### 💰 Points vs. 🏆 Scores
71+
72+
| Action | Points | Scores |
73+
|-------------------------|----------------|---------------|
74+
| Correct guess | +1 to +3 | — |
75+
| Complete word (win) | — | +total points |
76+
| Use hint | −3 to −5 | — |
77+
| Lose round | 0 | 0 |
78+
79+
- Points = Currency for hints, carried between games
80+
- Scores = Only earned when winning; used for leaderboard
3481

35-
📌 **Points** = Earned per letter guessed correctly (used to buy hints).
36-
📌 **Scores** = Only awarded when the player **wins a round** (used for leaderboard ranking).
82+
### 🛒 Hint Types
83+
84+
| Hint | Cost (Points) |
85+
|------------------------|---------------|
86+
| Reveal a letter | 5 |
87+
| Reveal fact about word | 3 |
88+
| Add extra guess | 4 |
3789

3890
---
3991

40-
## 🎮 Game Flow
41-
1️⃣ **Main Menu**: Play Game | Pick User | View Stats | Exit.
42-
2️⃣ **Pick User** (Load | Delete | Create).
43-
3️⃣ **Play** → Pick **Category** → Pick **Difficulty** → Start Game.
44-
4️⃣ **Guess Letters**: Earn points per correct guess.
45-
5️⃣ **Win or Lose**: Win to earn a score. Losing gives no points.
46-
6️⃣ **Continue?**: Stay in the same difficulty to keep your current score.
47-
7️⃣ **Use Points for Hints** (Optional).
92+
## 📂 Word Format (JSON)
93+
94+
Sample `words.json`:
95+
96+
```json
97+
{
98+
"Animals": {
99+
"description": "Creatures in the animal kingdom",
100+
"easy": [
101+
{ "word": "cat", "hint": "Purrs and meows" }
102+
],
103+
"medium": [
104+
{ "word": "giraffe", "hint": "Tallest land animal" }
105+
]
106+
}
107+
}
108+
```
48109

49110
---
50111

51-
## 🛒 Hint System (Uses Points)
52-
| **Hint Type** | **Cost (Points)** |
53-
|---------------------------------|------------------|
54-
| **Reveal a random letter** | 5 Points |
55-
| **Shows the fact about the word** | 3 Points |
56-
| **Remove a wrong letter choice** | 4 Points |
112+
## 🛠 Installation & Running
113+
114+
### Prerequisites
115+
116+
- Java 17+
117+
- Maven
118+
119+
### Run the game
120+
121+
```bash
122+
mvn compile exec:java -Dexec.mainClass="com.example.Main"
123+
```
57124

58-
📌 **Players can buy hints anytime using available points.**
59-
📌 **Points do NOT reset between games (carry over).**
125+
### Run tests
126+
127+
```bash
128+
mvn test
129+
```
60130

61131
---
62132

63-
## 🔥 Streak & Challenge Bonuses
64-
- **Win Streak Bonus** → Consecutive wins increase the score multiplier.
65-
- **Difficulty Progression Bonus** → Switching to a harder difficulty grants a +10% initial score boost.
66-
- **"Almost Win" Compensation** → If a player is **90% close to winning**, they get 50% of their potential score.
133+
## 🧠 How the Game Works
134+
135+
1. Start from a CLI main menu.
136+
2. Create or load a user.
137+
3. Pick a category and difficulty.
138+
4. Play by guessing letters.
139+
5. Use hints (points are deducted).
140+
6. Win to earn score and leaderboard rank.
67141

68142
---
69143

70-
## 📜 Game Rules
71-
1️⃣ **If a player wins and continues without changing category/difficulty, the score carries over.**
72-
2️⃣ **Players only earn a score if they win the round.**
73-
3️⃣ **Points are earned per letter and used for hints.**
74-
4️⃣ **Switching difficulty resets the score but keeps points.**
75-
5️⃣ **Players lose after exceeding maximum incorrect guesses.**
76-
6️⃣ **Leaderboard is based on score, not points.**
144+
## 🏆 Leaderboard & Stats
145+
146+
- SQLite stores:
147+
- `players` (user info)
148+
- `scores` (per game)
149+
- `points` (hint currency)
150+
- `Top 5` users by highest score shown at any time
77151

78152
---
79153

80-
## 🎯 Future Expansions
81-
- **Multiplayer Mode** with shared word pools.
82-
- **Timed Challenges** (Earn more points for faster completion).
83-
- **Daily Words & Streak Tracking**.
154+
## 📈 Future Features
155+
156+
- Multiplayer mode (via sockets or REST)
157+
- Daily challenge words
158+
- Game streaks and badges
159+
- Visual frontend (JavaFX or web)
160+
- Export/import word sets
84161

85162
---
86163

87-
## 🛠️ Developer Notes
88-
- **`GameSession`** → Runs gameplay loop, handles score & points.
89-
- **`WordPicker`** → Selects a word based on category & difficulty.
90-
- **`DisplayManager`** → Handles UI output (static methods).
91-
- **`InputHandler`** → Manages user input.
92-
- **`DatabaseManager` (Future)** → Stores leaderboard & user data (SQLite).
164+
## 🤝 Contributing
165+
166+
```bash
167+
# Fork, then:
168+
git checkout -b feat/my-feature
169+
git commit -m "Add new feature"
170+
git push origin feat/my-feature
171+
# Open a pull request
172+
```
93173

94174
---
95175

176+
## 📄 License
177+
178+
This project is licensed under the MIT License.
179+

0 commit comments

Comments
 (0)