🎴 Nim-San: The Strategic Duel

🎮 How to Play

1. Start the game:

   python3 main.py

2. Game Setup:

   • Enter a seed number to generate random pile sizes
   • Choose between Normal or Misère rules
   • Select who makes the first move

3. Gameplay:

   • On your turn, choose a pile (1-3) and number of coins to remove
   • Watch as the computer responds with optimal moves
   • Observe the nim-sum calculation to understand position evaluation

4. Victory Conditions:

   • Normal: Take the last coin to win
   • Misère: Force the computer to take the last coin

🎯 Example Game

╔══════════════════════════════════════════════════════════╗
║                   🎴 NIM-SAN 🎴                         ║
║              The Strategic Duel                         ║
╚══════════════════════════════════════════════════════════╗

Initial piles: (5, 4, 7)

Current piles:
  Pile indices:    1    2    3
                 |    |    |  
                 |    |    |  
                 |    |    |  
                 |    |    |  
                 |    |    |  
  Counts:        ( 5) ( 4) ( 7)

Your move (remove from exactly ONE pile).
Choose pile to remove from (1-3): 1
How many to remove from pile 1 (1-5): 3

🤖 Computer removes 2 from pile 3.

"Where mathematics meets strategy in a battle of wits against the perfect opponent"

🎯 Overview

Nim-San is an elegant terminal implementation of the classic mathematical game Nim, where two players strategically remove coins from three stacks. Play against an unbeatable AI that leverages game theory principles for optimal play. Experience the beauty of combinatorial game theory in a visually stunning terminal interface.

✨ Features

• 🎮 Perfect Opponent - Computer plays optimally using Sprague-Grundy theorem
• 🌈 Beautiful Terminal UI - Colorful, animated interface with visual coin stacks
• ⚡ Two Game Modes - Choose between Normal and Misère rules
• 🧠 Real-time Analysis - See nim-sum calculations and position evaluation
• 🎯 Strategic Depth - Learn winning strategies through gameplay
• 🚀 Zero Dependencies - Pure Python, no external libraries required

🎲 Game Rules

Normal Play

• Objective: Be the player to take the last coin
• Players take turns removing any number of coins from exactly one stack
• The player who takes the final coin wins

Misère Play

• Objective: Force your opponent to take the last coin
• Same move rules, but the player who takes the final coin loses
• Adds an extra layer of strategic complexity

🧮 Mathematical Foundation

Nim-San implements optimal play using:

• Grundy Numbers: Each pile's Grundy number equals its size
• Nim-Sum (XOR): Binary exclusive OR of pile sizes determines winning positions
• Sprague-Grundy Theorem: Provides the theoretical foundation for perfect play
• Game Tree Analysis: Computer evaluates all possible moves to maintain optimal strategy

Winning Strategy

• Normal Play: Always leave your opponent with a nim-sum of 0
• Misère Play: Special endgame adjustments while maintaining optimal midgame play

🚀 Installation

# Clone the repository
git clone https://github.com/your-username/nim-san.git
cd nim-san

# Run directly (no installation required)
python3 nim_san.py

Requirements: Python 3.6+ (no external dependencies)

📁 Project Structure

nim-san/
├── nim_san.py          # Main game executable
├── gui.py              # Terminal interface and graphics
├── computer_engine.py  # Optimal AI implementation  
├── models.py           # Data structures and game state
└── README.md           # This file

🏆 Learning Opportunity

Nim-San isn't just a game—it's a mathematical playground where you can:

• Understand fundamental game theory concepts
• Learn about impartial games and winning strategies
• Develop strategic thinking and pattern recognition
• See mathematical theory applied in real-time decision making

🤝 Contributing

Contributions are welcome! Feel free to:

• Report bugs and suggest features
• Improve the AI algorithms
• Enhance the terminal graphics
• Add new game modes or variations

📜 License

This project is open source and available under the MIT License.

🎓 Educational Value

Nim-San serves as an excellent educational tool for:

• Computer Science: Algorithm design, game theory, AI implementation
• Mathematics: Combinatorial game theory, binary arithmetic, strategic thinking
• Game Development: State management, user interface design, opponent AI

💡 Pro Tips

• Watch the nim-sum display to understand why the computer makes certain moves
• In Misère mode, pay special attention when piles approach size 1
• Try different starting configurations to see how strategy changes
• Study the computer's moves to improve your own gameplay

---

"In the game of Nim, every move tells a story of mathematical beauty and strategic depth. Will you uncover its secrets?" 🎴

---

Ready to challenge the perfect opponent?

python3 nim_san.py

Embrace the strategic duel of Nim-San!