rock-scissors-paper-framework 1.0.0

A modular framework for Rock-Paper-Scissors game.

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:

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.

Getting Started

Prerequisites

• Python 3.10.11 or later.
• Pytest (for running unit tests)

See the 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 section.

The quickest way to run the latest version of the game is to simply download the raw .py file from the GitHub Repository and run it from a terminal window:

python3 /path/to/rsp.py

Cloning this repository:

git clone https://github.com/JamzTyson/Rock_Scissors_Paper.git

Running the game from the cloned repository:

Navigate to the project directory:

cd rock_scissors_paper_framework

And then launch the game with:

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.

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:

# 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.
5. Type Q to quit the game.

Note: If the game has been installed, the rsp.py file can be run using the command:

$ rsp

Example Session:

Player: 0 | Computer: 0

[R]ock, [P]aper, [S]cissors, or [Q] to quit:

Player enters R, S, or P (case-insensitive):

r

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 file for details.

Author: JamzTyson

For inquiries, reach out through GitHub issues or discussions.