{"id":50284586,"url":"https://github.com/alivaezii/mastermindgame","last_synced_at":"2026-05-28T01:31:54.151Z","repository":{"id":322661307,"uuid":"1089647064","full_name":"alivaezii/mastermindgame","owner":"alivaezii","description":"Mastermind Classic Game","archived":false,"fork":false,"pushed_at":"2025-12-13T10:19:43.000Z","size":1155,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-12-14T04:51:26.971Z","etag":null,"topics":["agile-development","agile-methodology","cicd","docker","game-development","mastermind-game","python-3"],"latest_commit_sha":null,"homepage":"https://www.hcw.ac.at/studium-weiterbildung/studienangebot/technisches-management-master","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/alivaezii.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"docs/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-04T16:13:03.000Z","updated_at":"2025-12-13T10:19:47.000Z","dependencies_parsed_at":null,"dependency_job_id":"75bf99a6-46e0-41d4-ad59-7fdf2a7a68fb","html_url":"https://github.com/alivaezii/mastermindgame","commit_stats":null,"previous_names":["alivaezii/mastermindgame"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/alivaezii/mastermindgame","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alivaezii%2Fmastermindgame","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alivaezii%2Fmastermindgame/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alivaezii%2Fmastermindgame/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alivaezii%2Fmastermindgame/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/alivaezii","download_url":"https://codeload.github.com/alivaezii/mastermindgame/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alivaezii%2Fmastermindgame/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33590884,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-27T02:00:06.184Z","response_time":53,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agile-development","agile-methodology","cicd","docker","game-development","mastermind-game","python-3"],"created_at":"2026-05-28T01:31:53.412Z","updated_at":"2026-05-28T01:31:54.143Z","avatar_url":"https://github.com/alivaezii.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\r\n  \u003cimg src=\"https://github.com/user-attachments/assets/a83fa991-3602-42a3-94ad-959f7e553b5a\" width=\"820\"\u003e\r\n\u003c/p\u003e\r\n\r\n\u003cbr\u003e\r\n\r\n# 🎮 Mastermind Game (Python)\r\n\r\nA complete implementation of the classic **Mastermind** logic game with both **command-line** and **graphical user interface (GUI)** options. Features multiple game modes, scoring system, and persistent leaderboard. Built to demonstrate clean software design, testing, and CI/CD automation principles using Python.\r\n\u003cbr\u003e\r\n[Mastermind Wikipedia (Game)](https://de.wikipedia.org/wiki/Mastermind_(Spiel))\r\n\r\n---\r\n\r\n## 🛠 Tech Stack \u0026 Tools\r\n\r\n\u003cp align=\"left\"\u003e\r\n\r\n  \u003cimg src=\"https://img.shields.io/badge/Python-3.10-blue?logo=python\u0026logoColor=white\" /\u003e\r\n  \u003cimg src=\"https://img.shields.io/badge/Conda-Environment-44A833?logo=anaconda\u0026logoColor=white\" /\u003e\r\n  \u003cimg src=\"https://img.shields.io/badge/CLI-Application-black?logo=terminal\u0026logoColor=white\" /\u003e\r\n  \u003cimg src=\"https://img.shields.io/badge/GUI-Tkinter-orange?logo=python\u0026logoColor=white\" /\u003e\r\n  \u003cimg src=\"https://img.shields.io/badge/Test-Pytest-0A9EDC?logo=pytest\u0026logoColor=white\" /\u003e\r\n  \u003cimg src=\"https://img.shields.io/badge/Code%20Style-Black-black?logo=python\u0026logoColor=white\" /\u003e\r\n  \u003cimg src=\"https://img.shields.io/badge/Linter-Flake8-7A83F7?logo=python\u0026logoColor=white\" /\u003e\r\n  \u003cimg src=\"https://img.shields.io/badge/Imports-Isort-47848F?logo=python\u0026logoColor=white\" /\u003e\r\n  \u003cimg src=\"https://img.shields.io/badge/CI/CD-GitHub%20Actions-2088FF?logo=githubactions\u0026logoColor=white\" /\u003e\r\n  \u003cimg src=\"https://img.shields.io/badge/Docker-Containerized-2496ED?logo=docker\u0026logoColor=white\" /\u003e\r\n  \u003cimg src=\"https://img.shields.io/badge/PyPI-Package-blue?logo=pypi\u0026logoColor=white\" /\u003e\r\n\r\n\u003c/p\u003e\r\n\r\n\u003c/p\u003e\r\n\r\n## 🚀 Quick Start\r\n\r\n### 1. Create and activate environment\r\n```bash\r\nconda env create -f environment.yml\r\nconda activate mastermind\r\n```\r\n\r\n### 2. Install the package\r\n```bash\r\npip install -e .\r\n```\r\n\r\n### 3. Play the game\r\n\r\n**🎨 GUI Mode (Recommended)**\r\n```bash\r\n# Launch the graphical interface\r\npython -m mastermind.gui.app\r\n\r\n# Or directly\r\npython src/mastermind/gui/app.py\r\n```\r\n\r\n**💻 Command-Line Mode**\r\n```bash\r\n# Player vs Computer (default)\r\nmastermind\r\n\r\n# Player vs Computer with custom settings\r\nmastermind --mode pvc --max-attempts 10\r\n\r\n# Player vs Player mode\r\nmastermind --mode pvp --max-attempts 8\r\n\r\n# Custom rules\r\nmastermind --length 5 --alphabet ABCDEF --no-duplicates --max-attempts 12\r\n```\r\n\r\n### 4. Run tests\r\n```bash\r\npytest\r\n```\r\n\r\n---\r\n\r\n## 🐳 Docker Support (CLI Only)\r\n\r\nThis project includes an official Docker image for the **CLI version**\r\nof Mastermind.\r\n\r\n[![Docker Image](https://img.shields.io/docker/pulls/alivaezii/mastermindgame?logo=docker)](https://hub.docker.com/repository/docker/alivaezii/mastermindgame)\r\n![Image Size](https://img.shields.io/docker/image-size/alivaezii/mastermindgame/1.0.0)\r\n![Version](https://img.shields.io/badge/version-1.0.0-blue)\r\n![Multi-stage](https://img.shields.io/badge/docker-multistage-blue)\r\n![Build](https://img.shields.io/badge/build-passing-brightgreen)\r\n![Base Image](https://img.shields.io/badge/base-python%3A3.11--slim-blue)\r\n![Interface](https://img.shields.io/badge/interface-CLI--only-lightgrey)\r\n![Security](https://img.shields.io/badge/security-scanned-brightgreen)\r\n\r\n\r\n\r\n\r\n\r\n### Pull from Docker Hub\r\n\r\n\r\n``` bash\r\ndocker pull alivaezii/mastermindgame:1.0.0\r\n\r\n```\r\n\r\n### Run the game in Docker\r\n\r\n``` bash\r\ndocker run --rm -it alivaezii/mastermindgame:1.0.0\r\n```\r\n\r\n### Run with custom arguments\r\n\r\n``` bash\r\ndocker run --rm -it alivaezii/mastermindgame:1.0.0 --mode pvc --max-attempts 12\r\ndocker run --rm -it alivaezii/mastermindgame:1.0.0 --no-duplicates --length 5\r\n```\r\n\r\n### Build locally (optional)\r\n\r\n``` bash\r\ndocker build -t mastermindgame .\r\n```\r\n\r\n\r\n### Pull from GitHub Container Registry (GHCR)\r\n\r\n[![GHCR](https://img.shields.io/badge/GHCR-Container%20Image-2088FF?logo=github\u0026logoColor=white)](https://github.com/users/alivaezii/packages/container/package/mastermindgame)\r\n\r\n\r\n``` bash\r\ndocker pull ghcr.io/alivaezii/mastermindgame:1.0.0\r\n```\r\n###  Run the Mastermind CLI from GHCR\r\n\r\n``` bash\r\ndocker run --rm -it ghcr.io/alivaezii/mastermindgame:1.0.0\r\n```\r\n\r\nℹ Notes\r\n\r\nThe container includes only the CLI version of Mastermind.\r\nThe GUI cannot run inside Docker because Tkinter requires access to a local window server.\r\n\r\n---\r\n\r\n## 🎯 Features\r\n\r\n### Dual Interface\r\n\r\n**🎨 Graphical User Interface (GUI)**\r\n- Beautiful color-based visual interface using Tkinter\r\n- Interactive color selection with clickable buttons\r\n- Visual feedback with bulls (●) and cows (○) indicators\r\n- Scrollable guess history\r\n- High scores leaderboard with professional table layout\r\n- Intuitive navigation between screens\r\n- Modern dark theme with vibrant colors\r\n\r\n**💻 Command-Line Interface (CLI)**\r\n- Traditional text-based gameplay\r\n- Perfect for terminal enthusiasts\r\n- Lightweight and fast\r\n\r\n### Game Modes\r\n\r\n**Player vs Computer (PvC)**\r\n- Computer generates a random secret code\r\n- Player tries to guess the code\r\n- Default mode\r\n\r\n**Player vs Player (PvP)**\r\n- Player 1 sets a secret code (hidden input in CLI, visual in GUI)\r\n- Player 2 tries to guess the code\r\n- Great for playing with friends!\r\n\r\n### Scoring System\r\n\r\n- **Win**: Base score of 100 + bonus for remaining attempts (10 points each)\r\n- **Loss**: 0 points\r\n- Scores are automatically saved to `scores.json`\r\n- Top 5 scores displayed after each game\r\n\r\n**Example Scoring:**\r\n- Win in 3/10 attempts: 100 + (7 × 10) = **170 points**\r\n- Win in 10/10 attempts: 100 + (0 × 10) = **100 points**\r\n- Loss: **0 points**\r\n\r\n### Configurable Rules\r\n\r\n- **Code length**: Default 4, customizable via `--length`\r\n- **Alphabet**: Default \"012345\", customizable via `--alphabet`\r\n- **Duplicates**: Allowed by default, disable with `--no-duplicates`\r\n- **Max attempts**: Default 10, customizable via `--max-attempts`\r\n\r\n\r\n## 🎮 Mastermind Game: UI Overview\r\n\r\nBelow is a complete overview of the Mastermind game's graphical interface, showing all major gameplay states:\r\n\r\n1. **Start Screen \u0026 Settings**\r\n2. **In-Game Screen (Player vs Computer)**\r\n3. **Winning Screen**\r\n4. **Game Over Screen**\r\n\r\n\r\n\u003cp align=\"center\"\u003e\r\n  \u003cimg src=\"docs/photo-grid.png\" alt=\"Mastermind Game Screenshots\" style=\"max-width: 100%; height: auto;\"\u003e\r\n\u003c/p\u003e\r\n\r\n\r\n---\r\n\r\n## 🧪 Testing \u0026 Code Quality\r\n\r\nThis project follows a lightweight yet strict **Testing and Quality Policy**:\r\n\r\n| Area | Tool | Purpose |\r\n|------|------|----------|\r\n| **Testing** | `pytest` + `pytest-cov` | Unit \u0026 CLI tests, min. 85% coverage |\r\n| **Formatting** | `black` + `isort` | Code formatting \u0026 import sorting |\r\n| **Linting** | `flake8` | Static code analysis |\r\n| **Pre-commit** | `pre-commit` | Auto-runs all checks before pushing |\r\n| **CI/CD** | GitHub Actions | Multi-version tests (Python 3.10 \u0026 3.11) |\r\n\r\n📄 For full details: [Quality \u0026 CI/CD Policy](./docs/Quality_Testing_CICD_Policy.md)\r\n\r\n---\r\n\r\n## 📂 Project Structure\r\n\r\n```\r\nmastermindgame/\r\n│\r\n├── src/mastermind/\r\n│   ├── __init__.py          # Package exports\r\n│   ├── engine.py            # Core rules and validation logic\r\n│   ├── game.py              # Game state management\r\n│   ├── scoreboard.py        # Scoring and persistence\r\n│   ├── cli.py               # Command-line interface\r\n│   └── gui/                 # Graphical user interface (Sprint 3)\r\n│       ├── __init__.py\r\n│       ├── app.py           # Main GUI application controller\r\n│       ├── utils.py         # Color-symbol mapping utilities\r\n│       ├── screens/         # All game screens\r\n│       │   ├── start.py     # Game configuration screen\r\n│       │   ├── secret.py    # PvP secret selection\r\n│       │   ├── gameboard.py # Main gameplay interface\r\n│       │   ├── gameover.py  # Results \u0026 scoring\r\n│       │   └── highscores.py # Leaderboard display\r\n│       └── widgets/         # Reusable UI components\r\n│           ├── colorpicker.py # Color selection widget\r\n│           └── row.py       # Guess row display\r\n│\r\n├── tests/\r\n│   ├── test_engine.py       # Engine unit tests\r\n│   ├── test_game.py         # Game class tests\r\n│   ├── test_scoreboard.py   # Scoreboard tests\r\n│   ├── test_cli.py          # CLI integration tests\r\n│   └── test_gui_utils.py    # GUI utilities tests\r\n│\r\n├── scores.json              # Persistent scoreboard (auto-created)\r\n├── environment.yml          # Conda environment\r\n├── pyproject.toml           # Project configuration\r\n└── .github/workflows/ci.yml # CI/CD pipeline\r\n```\r\n\r\n---\r\n\r\n## 🏗️ Architecture\r\n\r\nThe codebase is organized into clean, testable modules:\r\n\r\n- **`engine.py`**: Pure functions for game rules (`Rules`, `validate_guess`, `score`)\r\n- **`game.py`**: `Game` class encapsulating game state and logic, supporting both PvC and PvP modes\r\n- **`scoreboard.py`**: Score calculation and JSON persistence (`ScoreEntry`, `calculate_score`, `save_score`, `load_scores`, `top_scores`)\r\n- **`cli.py`**: Command-line user interface, completely decoupled from game logic\r\n- **`gui/`**: Graphical user interface (Sprint 3)\r\n  - **MVC Architecture**: Clean separation of Model (Game), View (screens/widgets), Controller (app navigation)\r\n  - **Color Mapping**: Translates visual colors to game engine symbols\r\n  - **Reusable Widgets**: ColorPicker and GuessRow components\r\n  - **No Logic Duplication**: GUI calls existing Game and scoreboard functions\r\n\r\nThis separation makes the codebase easy to extend (e.g., adding a web interface) without modifying core logic.\r\n\r\n---\r\n\r\n## 📖 Usage Examples\r\n\r\n### Basic Game (PvC)\r\n```bash\r\nmastermind\r\n```\r\n\r\n### Player vs Player\r\n```bash\r\nmastermind --mode pvp\r\n```\r\n\r\n### Hard Mode (no duplicates, limited attempts)\r\n```bash\r\nmastermind --no-duplicates --max-attempts 5\r\n```\r\n\r\n### Custom Alphabet\r\n```bash\r\nmastermind --alphabet RGBYOP --length 6\r\n```\r\n\r\n---\r\n\r\n## ⚙️ Continuous Integration (CI)\r\n\r\nAll commits and pull requests trigger an automated workflow that performs:\r\n\r\n1. Environment setup via **Conda**\r\n2. Auto-formatting using **isort** and **black**\r\n3. Linting with **flake8**\r\n4. Running **pytest** for all unit and CLI tests\r\n5. Enforcing **coverage ≥ 85%**\r\n\r\nIf all stages pass, the build turns ✅ green in GitHub Actions.\r\n\r\n---\r\n\r\n## 🤝 Contributing\r\n\r\n1. Fork this repository  \r\n2. Create a new branch: `feature/my-feature`  \r\n3. Run local quality checks before committing:\r\n   ```bash\r\n   isort . \u0026\u0026 black . \u0026\u0026 flake8 . \u0026\u0026 pytest\r\n   ```\r\n4. Submit a Pull Request, all CI jobs must pass before merge.\r\n\r\n---\r\n\r\n## 🧱 Built With\r\n- Python 3.10 / 3.11\r\n- Conda environment management\r\n- pytest + coverage\r\n- black / isort / flake8 / pre-commit\r\n- GitHub Actions for CI/CD automation\r\n\r\n---\r\n\r\n## 📝 License\r\n\r\n\r\n### Mastermind Game: Team Information\r\nDeveloped by **TM26 -Hochschule Campus Wien**\r\n\u003cbr\u003e\r\nMIT License © 2025  \r\n\u003cbr\u003e\r\nA student software engineering project at Hochschule Campus Wien  \r\n\u003cbr\u003e\r\nSprint-based development following **SCRUM**\r\n\r\n\u003cbr\u003e\r\n\r\n| Role | Name | Contact |\r\n|------|------|---------|\r\n| Product Owner | **Laurenz** | laurenz.stelzl@stud.hcw.ac.at |\r\n| Scrum Master | **Markus** | markus.maximus@stud.hcw.ac.at |\r\n| Senior Developer \u0026 Tester | **Ali** | mohammadali.vaezi@stud.hcw.ac.at |\r\n| Python Developer | **Adnan** | adnan.eminovic@stud.hcw.ac.at |\r\n| Python Developer | **Hossein** | seyed.meymandi.nezhad@stud.hcw.ac.at |\r\n\r\n\r\n\u003cbr\u003e\r\n\r\n\r\n---\r\n\r\n## 📘 Project Documentation\r\n\r\nThis project includes full Agile documentation, test specifications, retrospectives, architecture diagrams, and development guidelines.\r\n\r\n[![Open Wiki](https://img.shields.io/badge/Project%20Wiki-Open-blue?logo=github\u0026style=for-the-badge)](https://github.com/alivaezii/mastermindgame/wiki)\r\n\r\n---\r\n\r\n\r\n### 💡 Related Documentation\r\n\r\n- [Quality Assurance \u0026 CI/CD Policy](./docs/Quality_Testing_CICD_Policy.md)\r\n- [Code Quality KPI](./reports)\r\n- [Python ↔ Java Toolchain Comparison](./docs/Python_vs_Java_Tooling.md)\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falivaezii%2Fmastermindgame","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falivaezii%2Fmastermindgame","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falivaezii%2Fmastermindgame/lists"}