diff --git a/games/Dots-Boxes-AI/README.md b/games/Dots-Boxes-AI/README.md new file mode 100644 index 00000000..d53adac8 --- /dev/null +++ b/games/Dots-Boxes-AI/README.md @@ -0,0 +1,85 @@ +# 🔲 Dots & Boxes AI - Advanced Version + +An advanced, beautifully colorized terminal-based implementation of the classic **Dots & Boxes** pen-and-paper game. Written in pure Python, it supports both local two-player matches and matches against a smart heuristic AI with three distinct difficulty levels. + +--- + +## 🚀 Features + +- 🎨 **Vibrant Terminal Styling**: Uses ANSI color escape codes for rendering player blocks, lines, points, and turns in eye-catching colors (Blue, Red, Yellow, Cyan, Green). +- 👥 **Multiple Game Modes**: + - **Player vs Player**: Battle locally against a friend. + - **Player vs AI**: Pit your skills against a computer opponent. +- 🧠 **Smart AI Opponent**: Features three AI levels utilizing custom decision-making heuristics: + - 🟢 **Easy**: Makes completely random moves. + - 🟡 **Intermediate**: Prioritizes completing a box and avoids leaving dangerous 3-sided boxes that would allow the player to score. + - 🔴 **Hard**: Scores all available moves dynamically, prioritizing game winning configurations, blocking player gains, and positioning itself strategically. +- 📏 **Custom Board Sizes**: Play on boards ranging from `2x2` up to `8x8` dots. +- ⚙️ **Accurate Ruleset**: Completing a box grants the scoring player an immediate **extra turn**! +- 🛡️ **Robust Validation**: Built-in protections against out-of-bounds coordinates, duplicate moves, invalid choices, and negative inputs. + +--- + +## 🛠️ Requirements + +- **Python 3.x** +- No external libraries are needed (uses standard Python library built-in modules: `random`, `time`). +- *Note: Works best in terminal environments that support ANSI color output.* + +--- + +## ▶️ How to Run + +1. Navigate to the game directory: + ```bash + cd games/Dots-Boxes-AI + ``` +2. Run the script: + ```bash + python Dots-Boxes-AI.py + ``` + +--- + +## 🎮 Gameplay Guide + +### Objective +Draw lines between adjacent dots on the grid. When a player draws the fourth line closing a `1x1` box, they score a point and earn another turn. The player with the most boxes filled when no more lines can be drawn wins! + +### Playing a Turn +1. The board is printed showing dots (`•`), drawn horizontal lines (`━━`), drawn vertical lines (`┃`), and completed boxes (`■`). +2. Input the line direction: `h` for horizontal or `v` for vertical. +3. Input the **Row** and **Column** coordinates of the line: + - For **Horizontal** lines: Row range is `0 to size`, Col range is `0 to size-1`. + - For **Vertical** lines: Row range is `0 to size-1`, Col range is `0 to size`. + +--- + +## 📸 Sample Board Render + +```text +• • • +┃■ ┃ +•━━• • + ┃ +• •━━• +``` + +*Note: In the actual terminal, the dots, lines, and boxes are dynamically colored blue for Player 1 and red for Player 2/AI.* + +--- + +## 📁 File Structure + +```text +Dots-Boxes-AI/ +├── Dots-Boxes-AI.py +└── README.md +``` + +--- + +## 👤 Author + +Contributed as part of GSSoC (GirlScript Summer of Code). +Repository: [python-mini-project](https://github.com/steam-bell-92/python-mini-project) diff --git a/games/Flipping-Toss/README.md b/games/Flipping-Toss/README.md new file mode 100644 index 00000000..ac62dc2c --- /dev/null +++ b/games/Flipping-Toss/README.md @@ -0,0 +1,96 @@ +# 🪙 Coin Flip Game (Flipping Toss) + +A simple, interactive, and beginner-friendly command-line game written in Python where players can toss a coin, predict the outcome (Heads or Tails), and track their prediction accuracy with detailed real-time statistics. + +--- + +## 🚀 Features + +- 🪙 **Interactive Coin Tossing**: Play as many rounds as you like. +- 🎯 **Prediction System**: Predict the result (`H` for Heads, `T` for Tails) before each toss. +- ⏳ **Flipping Animation**: Simulated delay to add anticipation and excitement to the toss. +- 📊 **Detailed Game Summary**: View full statistics upon quitting the game, including: + - Total tosses played + - Number of Heads and Tails + - Total correct predictions + - Percentage accuracy of your predictions +- 🛡️ **Robust Input Handling**: Handles invalid inputs gracefully with helpful warnings. + +--- + +## 🛠️ Requirements + +- **Python 3.x** +- No external libraries are needed (uses standard Python library built-in modules: `random`, `time`). + +--- + +## ▶️ How to Run + +1. Navigate to the game directory: + ```bash + cd games/Flipping-Toss + ``` +2. Run the script: + ```bash + python Flipping-Toss.py + ``` + +--- + +## 🎮 Gameplay Guide + +1. Start the game, and you will be asked: `Toss a coin? (y/n): `. +2. Enter `y` to play, or `n` to quit and see your stats. +3. If playing, guess the outcome by entering `H` (Heads) or `T` (Tails). +4. Wait for the flipping simulation to finish, and see if your prediction was correct! +5. When you decide to stop (`n`), a beautifully formatted **Game Summary** and your **Prediction Accuracy** will be displayed. + +--- + +## 📸 Sample Output + +```text +🪙 Coin Flip Game! 🪙 + +Toss a coin? (y/n): y +Predict the result (H/T): h +🪙 Flipping... +👑 Heads!! +🎉 Correct Prediction! + +Toss a coin? (y/n): y +Predict the result (H/T): t +🪙 Flipping... +👑 Heads!! +❌ Wrong Prediction! + +Toss a coin? (y/n): n +👋 Thanks for playing! See you next time! + +📊 GAME SUMMARY 📊 +🪙 Total Tosses: 2 +👑 Heads Count: 2 +🦅 Tails Count: 0 +🎯 Correct Predictions: 1 +📈 Prediction Accuracy: 50.00% + +✨ Thanks for playing! +``` + +--- + +## 📁 File Structure + +```text +Flipping-Toss/ +├── Flipping-Toss.py +└── README.md +``` + +--- + +## 👤 Author + +Contributed as part of GSSoC (GirlScript Summer of Code). +Repository: [python-mini-project](https://github.com/steam-bell-92/python-mini-project) diff --git a/games/War-Card-Game/README.md b/games/War-Card-Game/README.md new file mode 100644 index 00000000..a49d090e --- /dev/null +++ b/games/War-Card-Game/README.md @@ -0,0 +1,107 @@ +# ⚔️ War Card Game + +A classic two-player card game implemented in Python as an interactive command-line application. The game programmatically generates a standard 52-card deck, shuffles it, distributes it equally between two players, and pits their drawn cards against each other round-by-round. + +--- + +## 🚀 Features + +- 👥 **Multiplayer Experience**: Supports custom player names (or defaults to Player 1 and Player 2). +- 🎴 **Standard 52-Card Deck**: Fully represented with suits (Hearts, Diamonds, Clubs, Spades) and ranks (2 to Ace). +- 🔀 **Randomized Card Shuffling**: Utilizes Python's `random.shuffle` to ensure every game has unique card distributions. +- ⏱️ **Turn-by-Turn Control**: Players can choose to play round-by-round or stop mid-game. +- 📊 **Real-time Scoring**: Automatically tracks and updates scores after every round, displaying drawn cards and current standings. +- ⚖️ **Tie Handling**: Gracefully handles matching ranks (Tie) and continues standard gameplay. +- 🔁 **Replay System**: Option to play another game immediately without restarting the script. + +--- + +## 🛠️ Requirements + +- **Python 3.x** +- No external libraries are needed (uses standard Python library built-in modules: `random`). + +--- + +## ▶️ How to Run + +1. Navigate to the game directory: + ```bash + cd games/War-Card-Game + ``` +2. Run the script: + ```bash + python War-Card-Game.py + ``` + +--- + +## 🎮 Gameplay Guide + +1. Run the game and enter custom names for **Player 1** and **Player 2**. +2. The game will shuffle and distribute the cards. +3. For each round, enter `yes` (or `y`) to draw a card, or `no` (or `n`) to stop the game. +4. The player who draws the higher rank card wins the round and earns 1 point (Aces are high, numeric cards are their value). +5. The game continues until either player runs out of cards or a player chooses to stop. +6. A beautiful **Final Result** panel will declare the winner and display final scores. + +--- + +## 📸 Sample Output + +```text +===== Welcome to War Card Game ===== + +Enter Player 1 Name: Nishtha +Enter Player 2 Name: Antigravity + +Deck shuffled successfully! +Cards distributed equally to both players. + + +Do you want to play Round 1? (yes/no): y + +========== Round 1 ========== +Nishtha draws: King of Hearts +Antigravity draws: 4 of Spades +🏆 Round Winner: Nishtha +Current Score -> Nishtha: 1 | Antigravity: 0 + +Do you want to play Round 2? (yes/no): y + +========== Round 2 ========== +Nishtha draws: 8 of Diamonds +Antigravity draws: Jack of Clubs +🏆 Round Winner: Antigravity +Current Score -> Nishtha: 1 | Antigravity: 1 + +Do you want to play Round 3? (yes/no): no + +Game stopped by user. + +========== Final Result ========== +Nishtha: 1 points +Antigravity: 1 points + +🤝 The game ends in a Tie! + +🔄 Play again? (y/n): n +👋 Thanks for playing War Card Game! +``` + +--- + +## 📁 File Structure + +```text +War-Card-Game/ +├── War-Card-Game.py +└── README.md +``` + +--- + +## 👤 Author + +Contributed as part of GSSoC (GirlScript Summer of Code). +Repository: [python-mini-project](https://github.com/steam-bell-92/python-mini-project)