# Modular Framework for the Rock-Paper-Scissors Game.
*A solo game of "Rock, Paper, Scissors" against the computer, implemented in
modern Python.*
## Purpose
This project provides a modular and extensible framework for creating and
experimenting with the Rock-Paper-Scissors game and its variants.
While the default game implements the classic three-choice version
(Rock, Paper, Scissors) with a simple Terminal interface, the architecture
supports:
- Adding more choices with cyclic rules
(e.g., Rock-Paper-Scissors-Lizard-Batman).
- Adding a more complex or graphical interface.
- Customising input handling and game logic.
- Adding more players.
- Adding more advanced strategies for the computer player.
- Defining new rules and behaviors.
## Overview
A dynamic implementation of "Rock, Paper, Scissors" against the computer,
with support for additional choices. The game uses cyclic rules to determine
the winner, ensuring every option beats some choices and is beaten by an equal
number of other choices, thus there must be an odd number of choices.
## Features
- Play the classic version of "Rock, Paper, Scissors."
- Extend the game with custom rules, more choices, or alternative
user interface.
- Unit tests (pytest) are provided to validate game logic.
## How It Works
Rather than hard coded "Scissor beats Paper" rules, the game generates rules
dynamically from a list of choices, following the rules:
1. Each item beats `(n-1)//2` predecessors and is beaten by `(n-1)//2`
successors, where `n` is the total number of choices.
2. The total number of choices (`DEFAULT_CHOICE_NAMES`) must always be odd.
3. Choices cannot start with the letter 'Q' (reserved for "Quit").
4. All choices must start with a unique letter.
### Example Custom Configuration
An example configuration with five options:
```python
DEFAULT_CHOICE_NAMES = ('Rock', 'Batman', 'Paper', 'Lizard', 'Scissors')
```
The corresponding rules would be:
- **Rock blunts Scissors:** Rock wins.
- **Rock crushes Lizard:** Rock wins.
- **Batman vaporizes Rock:** Batman wins.
- **Batman smashes Scissors:** Batman wins.
- **Paper disproves Batman:** Paper wins.
- **Paper wraps Rock:** Paper wins.
- **Lizard eats Paper:** Lizard wins.
- **Lizard poisons Batman:** Lizard wins.
- **Scissors decapitate Lizard:** Scissors win.
- **Scissors cut Paper:** Scissors win.
- **Draw:** Both choose the same option.
If you make changes to DEFAULT_CHOICE_NAMES, ensure that you run
[test_default_choices.py](rock_scissors_paper_framework/tests/test_default_choices.py).
## Getting Started
### Prerequisites
- Python 3.10.11 or later.
- Pytest (for running unit tests)
See the [pyproject.toml](pyproject.toml) file for full details.
## Running the game
It is not necessary to install this game to run it, though instructions for
installing are provided in the [Installation](#installing-the-game) section.
The quickest way to run the latest version of the game is to simply
download the raw `.py` file from the
[GitHub Repository](https://github.com/JamzTyson/Rock_Scissors_Paper/blob/main/rock_scissors_paper_framework/rsp.py)
and run it from a terminal window:
```bash
python3 /path/to/rsp.py
```
## Cloning this repository:
```bash
git clone https://github.com/JamzTyson/Rock_Scissors_Paper.git
```
**Running the game from the cloned repository:**
Navigate to the project directory:
```bash
cd rock_scissors_paper_framework
```
And then launch the game with:
```bash
python3 rsp.py
```
## Installing the Game
### Installing from PyPi
The recommended way to install the game is to install for the
current user with [pipx](https://pipx.pypa.io/latest/installation/).
```bash
pipx install rock-scissors-paper-framework
```
**Note:** The PyPI package name is rock-scissors-paper-framework, but
the package is imported as rock_scissors_paper_framework in your Python code.
After installation, the main entry point for the game is the
`rsp` command or `rsp.py`.
If you prefer local development or customisation, install the package
within a virtual environment:
```bash
# Create and activate a virtual environment:
python3 -m venv venv
source venv/bin/activate # On Windows, use: venv\Scripts\activate
# Install the package using pip (or pipx):
pip install rock-scissors-paper-framework
# Run the application:
rsp
# Deactivate the virtual environment when finished:
deactivate
```
## How to Play
1. Start the game by running rsp.py
2. When prompted, choose an option by typing its initial letter
(e.g., R for Rock, S for Scissors). The input is case-insensitive.
3. The computer selects its option randomly.
4. The winner is determined based on the [predefined rules](#default-rules).
5. Type `Q` to quit the game.
**Note:** If the game has been [installed](#installing-the-game), the `rsp.py`
file can be run using the command:
```bash
$ rsp
```
**Example Session:**
```bash
Player: 0 | Computer: 0
[R]ock, [P]aper, [S]cissors, or [Q] to quit:
```
Player enters R, S, or P (case-insensitive):
```bash
r
```
```bash
You = Rock : Computer = Scissors : YOU WIN
Player: 1 | Computer: 0
```
### Default Rules:
- **Rock blunts Scissors:** Rock wins.
- **Scissors cut Paper:** Scissors win.
- **Paper wraps Rock:** Paper wins.
- **Draw:** Both choose the same option.
## Contributing
Contributions are welcome!
If you encounter any bugs, please open an issue on the GitHub repository.
If you have ideas for new features, extended rules, or bug fixes, feel free
to submit a pull request. Please ensure your changes are well-documented and
are accompanied by pytests (if applicable).
## License
This project is licensed under the MIT License. See the [LICENSE](LICENSE)
file for details.
**Author:** JamzTyson
For inquiries, reach out through GitHub issues or discussions.
Raw data
{
"_id": null,
"home_page": "https://github.com/JamzTyson/Rock_Scissors_Paper",
"name": "rock-scissors-paper-framework",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0.0,>=3.10.11",
"maintainer_email": null,
"keywords": "rock, scissors, paper, python, game",
"author": "JamzTyson",
"author_email": "151654652+JamzTyson@users.noreply.github.com",
"download_url": "https://files.pythonhosted.org/packages/8b/63/23cd5f9ff881fad6b971d0561268c68439d3f69a61a753f0f689f5935f77/rock_scissors_paper_framework-1.0.0.tar.gz",
"platform": null,
"description": "# Modular Framework for the Rock-Paper-Scissors Game.\n\n\n\n\n*A solo game of \"Rock, Paper, Scissors\" against the computer, implemented in\nmodern Python.*\n\n## Purpose\nThis project provides a modular and extensible framework for creating and\nexperimenting with the Rock-Paper-Scissors game and its variants.\n\nWhile the default game implements the classic three-choice version\n(Rock, Paper, Scissors) with a simple Terminal interface, the architecture\nsupports:\n\n- Adding more choices with cyclic rules\n(e.g., Rock-Paper-Scissors-Lizard-Batman).\n- Adding a more complex or graphical interface.\n- Customising input handling and game logic.\n- Adding more players.\n- Adding more advanced strategies for the computer player.\n- Defining new rules and behaviors.\n\n## Overview\n\nA dynamic implementation of \"Rock, Paper, Scissors\" against the computer,\nwith support for additional choices. The game uses cyclic rules to determine\nthe winner, ensuring every option beats some choices and is beaten by an equal\nnumber of other choices, thus there must be an odd number of choices.\n\n## Features\n\n- Play the classic version of \"Rock, Paper, Scissors.\"\n- Extend the game with custom rules, more choices, or alternative\nuser interface.\n- Unit tests (pytest) are provided to validate game logic.\n\n## How It Works\n\nRather than hard coded \"Scissor beats Paper\" rules, the game generates rules\ndynamically from a list of choices, following the rules:\n\n1. Each item beats `(n-1)//2` predecessors and is beaten by `(n-1)//2`\nsuccessors, where `n` is the total number of choices.\n2. The total number of choices (`DEFAULT_CHOICE_NAMES`) must always be odd.\n3. Choices cannot start with the letter 'Q' (reserved for \"Quit\").\n4. All choices must start with a unique letter.\n\n### Example Custom Configuration\n\nAn example configuration with five options:\n\n```python\nDEFAULT_CHOICE_NAMES = ('Rock', 'Batman', 'Paper', 'Lizard', 'Scissors')\n```\n\nThe corresponding rules would be:\n\n- **Rock blunts Scissors:** Rock wins.\n- **Rock crushes Lizard:** Rock wins.\n- **Batman vaporizes Rock:** Batman wins.\n- **Batman smashes Scissors:** Batman wins.\n- **Paper disproves Batman:** Paper wins.\n- **Paper wraps Rock:** Paper wins.\n- **Lizard eats Paper:** Lizard wins.\n- **Lizard poisons Batman:** Lizard wins.\n- **Scissors decapitate Lizard:** Scissors win.\n- **Scissors cut Paper:** Scissors win.\n- **Draw:** Both choose the same option.\n\n\nIf you make changes to DEFAULT_CHOICE_NAMES, ensure that you run\n[test_default_choices.py](rock_scissors_paper_framework/tests/test_default_choices.py).\n\n## Getting Started\n\n### Prerequisites\n\n- Python 3.10.11 or later.\n- Pytest (for running unit tests)\n\nSee the [pyproject.toml](pyproject.toml) file for full details.\n\n## Running the game\n\nIt is not necessary to install this game to run it, though instructions for\ninstalling are provided in the [Installation](#installing-the-game) section.\n\nThe quickest way to run the latest version of the game is to simply\ndownload the raw `.py` file from the\n[GitHub Repository](https://github.com/JamzTyson/Rock_Scissors_Paper/blob/main/rock_scissors_paper_framework/rsp.py)\nand run it from a terminal window:\n\n```bash\npython3 /path/to/rsp.py\n```\n\n## Cloning this repository:\n\n```bash\ngit clone https://github.com/JamzTyson/Rock_Scissors_Paper.git\n```\n\n**Running the game from the cloned repository:**\n\nNavigate to the project directory:\n\n```bash\ncd rock_scissors_paper_framework\n```\n\nAnd then launch the game with:\n\n```bash\npython3 rsp.py\n```\n\n\n## Installing the Game\n\n### Installing from PyPi\n\nThe recommended way to install the game is to install for the\ncurrent user with [pipx](https://pipx.pypa.io/latest/installation/).\n\n```bash\npipx install rock-scissors-paper-framework\n```\n\n**Note:** The PyPI package name is rock-scissors-paper-framework, but\nthe package is imported as rock_scissors_paper_framework in your Python code.\nAfter installation, the main entry point for the game is the\n`rsp` command or `rsp.py`.\n\nIf you prefer local development or customisation, install the package\nwithin a virtual environment:\n\n```bash\n# Create and activate a virtual environment:\npython3 -m venv venv\nsource venv/bin/activate # On Windows, use: venv\\Scripts\\activate\n\n# Install the package using pip (or pipx):\npip install rock-scissors-paper-framework\n\n # Run the application:\nrsp\n\n # Deactivate the virtual environment when finished:\ndeactivate\n```\n\n## How to Play\n\n1. Start the game by running rsp.py\n2. When prompted, choose an option by typing its initial letter\n(e.g., R for Rock, S for Scissors). The input is case-insensitive.\n3. The computer selects its option randomly.\n4. The winner is determined based on the [predefined rules](#default-rules).\n5. Type `Q` to quit the game.\n\n**Note:** If the game has been [installed](#installing-the-game), the `rsp.py`\nfile can be run using the command:\n\n```bash\n$ rsp\n```\n\n\n**Example Session:**\n\n```bash\nPlayer: 0 | Computer: 0\n\n[R]ock, [P]aper, [S]cissors, or [Q] to quit:\n```\n\nPlayer enters R, S, or P (case-insensitive):\n\n```bash\nr\n```\n\n```bash\nYou = Rock : Computer = Scissors : YOU WIN\nPlayer: 1 | Computer: 0\n```\n\n### Default Rules:\n\n- **Rock blunts Scissors:** Rock wins.\n- **Scissors cut Paper:** Scissors win.\n- **Paper wraps Rock:** Paper wins.\n- **Draw:** Both choose the same option.\n\n## Contributing\n\nContributions are welcome!\n\nIf you encounter any bugs, please open an issue on the GitHub repository.\n\nIf you have ideas for new features, extended rules, or bug fixes, feel free\nto submit a pull request. Please ensure your changes are well-documented and\nare accompanied by pytests (if applicable).\n\n## License\n\nThis project is licensed under the MIT License. See the [LICENSE](LICENSE)\nfile for details.\n\n**Author:** JamzTyson\n\nFor inquiries, reach out through GitHub issues or discussions.\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A modular framework for Rock-Paper-Scissors game.",
"version": "1.0.0",
"project_urls": {
"Homepage": "https://github.com/JamzTyson/Rock_Scissors_Paper",
"Repository": "https://github.com/JamzTyson/Rock_Scissors_Paper"
},
"split_keywords": [
"rock",
" scissors",
" paper",
" python",
" game"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "3ccdf8434dfcba84037fec00e8601a06f74655898411f82e1ddca8fede289fae",
"md5": "8afefa9ecaad34ceae8f773f4efbd29b",
"sha256": "c53e3557f72a7e8fae6f55d628286d502eaecacf89da4240645e259698bf52fd"
},
"downloads": -1,
"filename": "rock_scissors_paper_framework-1.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "8afefa9ecaad34ceae8f773f4efbd29b",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0.0,>=3.10.11",
"size": 9415,
"upload_time": "2024-12-26T13:57:35",
"upload_time_iso_8601": "2024-12-26T13:57:35.301546Z",
"url": "https://files.pythonhosted.org/packages/3c/cd/f8434dfcba84037fec00e8601a06f74655898411f82e1ddca8fede289fae/rock_scissors_paper_framework-1.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "8b6323cd5f9ff881fad6b971d0561268c68439d3f69a61a753f0f689f5935f77",
"md5": "2c279703815a32ac5782ad8198e2e948",
"sha256": "a10a5f82fc800279f2834d7357f3bc009cd10bc7ed94ad785295f6439a063ccb"
},
"downloads": -1,
"filename": "rock_scissors_paper_framework-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "2c279703815a32ac5782ad8198e2e948",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0.0,>=3.10.11",
"size": 8200,
"upload_time": "2024-12-26T13:57:36",
"upload_time_iso_8601": "2024-12-26T13:57:36.542246Z",
"url": "https://files.pythonhosted.org/packages/8b/63/23cd5f9ff881fad6b971d0561268c68439d3f69a61a753f0f689f5935f77/rock_scissors_paper_framework-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-26 13:57:36",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "JamzTyson",
"github_project": "Rock_Scissors_Paper",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "rock-scissors-paper-framework"
}
JSON
