Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Updated the README.md file #3

Merged
merged 3 commits into from
Apr 19, 2024
Merged

Updated the README.md file #3

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
26c801a
Updated the README.md file
koshambiB Apr 16, 2024
71a1620
Updated README.md
koshambiB Apr 18, 2024
757ac2c
updated the readme.md file
koshambiB Apr 19, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
80 changes: 48 additions & 32 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,11 +10,14 @@

## Description

This is a Chess AI currently in development. **It is written completely on Python, so it will be slower** than other AIs, but algorithms have been optimized wherever necessary and possible. It uses the [`Pygame`](pygame.org) library to provide the GUI and the media controls. FEN notations are supported upto castling, and future support is in development.
This Chess AI is under development and built entirely with Python for a focus on readability and code clarity. Despite the limitations of the language in performance speed when compared to compiled languages, the core algorithms have been optimized for maximum speed within Python's capabilities.

The user interface and media controls are powered by the Pygame library, offering a customizable experience. The AI currently understands and utilizes FEN (Forsyth-Edwards Notation) for game state import and export, including castling using FEN support. Further support features are actively being developed.

## How to install

[Clone the repository](https://github.com/git-guides/git-clone) in a favorable location of your choice on your local machine. The following command does the magic for you:
To get started [Clone the repository](https://github.com/git-guides/git-clone) to a convenient location on your local machine. <br/>
You can use the following command in your terminal:

```shell
git clone https://github.com/a2ys/chess-ai.git
Expand All @@ -25,31 +28,39 @@ Even though the program uses a single library, `Pygame`, going by the [Python co
```shell
python -m pip install -r requirements.txt
```
This command will install the required libraries for you.
This command will install the requisite libraries for you.

Now you just have to run the `main.py` file, and enjoy the program. The following command does the magic for you:
All set! Now let's bring this program to life. Run the `main.py` file using this command in your terminal:

```shell
python main.py
```

## How to use and configure?

As of now, no settings screen has been developed, so to use the program as you intend, you need to change the code. Most of the settings and their values are stored in the [`Constants.py`](defs/Constants.py) file. So to make a change, you first need to go to the file in the location `defs\Constants.py` and change the values of the constants as required. Some instructions are provided below.
While a dedicated settings screen is still under development, you can customize the program's behavior by editing the [`Constants.py`](defs/Constants.py) file. Here's how to make changes:<br/>

1. **Locate the file**: Navigate to the `defs` folder within your project directory and open `Constants.py`. <br/>
2. **Adjust settings**: The file contains comments explaining each setting and its current value. You can modify these values directly in the code.

### Game modes
## Game modes

The Game Mode, by default, is set to AI vs AI. In case you want to change it to another mode, you must do it in the following way:
The Game Mode, by default, is set to AI vs AI. If you want to play against an opponenet be it AI or a friend, follow these steps to modify the game mode

- First of all, go the `Constants.py` file, and search for the variable, `GAME_MODE`. It will look like the block shown below:
- Locate the `Constants.py` file in the directory containing the game codes and look for the variable `GAME_MODE`. <br/>
It will look like the block shown below:

```python
GAME_MODE = GameModes.AI_VS_AI
```
- The `GAME_MODE` variable is responsible for different modes of playing the game, the values it can take are `GameModes.PLAYER_VS_PLAYER`, `GameModes.PLAYER_VS_AI` (you play as white, and the computer plays as black), `GameModes.AI_VS_PLAYER` (you play as black, and the computer plays as white) and `GameModes.AI_VS_AI` (default).
- You can change the value of the `GAME_MODE` variable to any value out of the above four.
- The `GAME_MODE` variable determines the different modes of playing the game.It can take the following value: <br/>
1. `GameModes.PLAYER_VS_PLAYER` <br/>
2. `GameModes.PLAYER_VS_AI` (you play as white, and the computer plays as black) <br/>
3. `GameModes.AI_VS_PLAYER` (you play as black, and the computer plays as white) <br/>
4. `GameModes.AI_VS_AI` (default). <br/>


### Initial board arrangement
## Initial board arrangement

The initial board in the game, by default, is set to the standard initial board. To be able to understand and edit the initial board arrangement, you should be familiar with the [FEN notation](https://www.chess.com/terms/fen-chess) in chess. In case you are familiar, and want to change the inital arrangement, you must do it in the following way:

Expand All @@ -74,66 +85,71 @@ The depth to which the AI can think, by default, is set to $2$, which is suffici

### Colors

The Colors, by default, are set according to a visually pleasing and less noisy palette, so unless you crave for certain colors, you should leave them unchanged. In case you want to change the colors, you must do it in the following way:
The Colors, by default, are set to a visually pleasing and less noisy palette but if you wish to customize it, here's how to do it using FEN notataion.

- First of all, go the `Constants.py` file, and search for the following block of code somewhere in the middle:
- Locate the `Constants.py` file and look for the following block of code:

```python
# Colors format - [LIGHT, DARK]
colors = [(238, 216, 192), (171, 122, 101)]
highlight_colors = [(207, 172, 106), (197, 173, 96)]
legal_move_colors = [(221, 89, 89), (197, 68, 79)]
```
- All the colors are in `RGB` format, in the order `(R, G, B)`. The first `tuple` in every `list` of colors denotes the color applied to the white squares, and the next one denotes the color applied to the black squares.
- The instructions below provide the steps to alter the colors correctly:
- All the colors are formatted as `RGB` in the order `(R, G, B)`. The first `tuple` in every `list` applies color settings to the white squares while the second `tuple` does the same for the black squares.

- The instructions below provide the steps to configure these settings:
- To change the color of the squares when the board is in `idle` state, change the values in the `colors` variable;
- To change the color of the square of a piece which is clicked upon by the user, change the values in the `highlight_colors` variable;
- To change the colors with which the `legal_move` squares are filled, change the values in the `legal_move_colors`.

### Dimensions and FPS
## Configuration Options <br/>
#### (Use with Caution)

The `WIDTH`, `HEIGHT` and `FPS` variables are not recommended to be changed, so as to provide a seamless experience, but in case you want to change them, you must do it in the following way:
The default settings for the `WIDTH`, `HEIGHT` and `FPS` variables are carefully chosen for a seamless experience, but you can customize them if absolutely necessary.

- First of all, go the `Constants.py` file, and find these lines:
- Locate the `Constants.py` file, and look for these lines:

```python
WIDTH = HEIGHT = 720
FPS = 60
```
- Change the values of `WIDTH` and `HEIGHT` variables, keeping both equal to each other, and a multiple of $8$, to avoid any visual inconsistency.
- Change the `FPS` to any value supported by your display.
- Change the values of `WIDTH` and `HEIGHT` variables, keeping both equal to each other, and a multiple of $8$, to avoid any visual inconsistencies.
- The FPS variable controls the game's update rate (frames per second) and is highly dependent on your display's capabilities. You can change the `FPS` to any value supported by your display.

### Final notes on usage and configuration
## Final notes on usage and configuration

All the other variables/functions in the `Constants.py` file, or any other files not mentioned above are not supposed to be edited, and are important in providing necessary functionality to the program. If you want to experiment with the program, or make changes for contributions, you are free to do so with a threshold amount of knowledge in Python and about the project. Comments have been added wherever necessary to help understand the program better.

If you need further assistance with configuration, or any other topic related to this project, you can [create an issue](https://github.com/a2ys/chess-ai/issues/new/choose), or mail me at [oreus@duck.com](mailto:oreus@duck.com). Happy experimenting. :)
All the other variables/functions in the `Constants.py` file, or any other files not mentioned above are not supposed to be edited, and are important in providing necessary functionality to the program.Comments have been added wherever necessary to help understand the program better.

## Libraries in use

The program currently uses only one library, `Pygame`.

`Pygame` provides the necessary working GUI for the program, and connects it to the logic of the program. It also facilitates easy rendering of the images, as well as timely production of appropriate sounds.

## Minimum system requirements
## System prerequisites

- OS: Any operating system with Python 3.x and the required libraries installed.
- Processor: Any dual-core processor
- **OS:** Any operating system with Python 3.x and the required libraries installed.
- **Processor:** Any dual-core processor

> The program makes an extensive use of your machine's processing power, so it is recommended to use a **quad-core** processor, for a seamless experience, even though the minimum requirement is **dual-core**.
- RAM: At least 2GB or above, DDR3 or above
- **RAM:** At least 2GB or above, DDR3 or above

> The program extensively uses hashing and rapid storage and access of information from the machine's primary memory, so it is recommended to have a **DDR4** memory to have a hassle-free experience.
- Permanent storage: Any storage type (SSD recommended)
- **Permanent storage:** Any storage type (SSD recommended)

## Contributing:

## Willing to contribute?
If you'd like to make changes or contribute to the project, consider the following options:

If you are willing to add functionality to the program, you should [fork the repository](https://github.com/a2ys/chess-ai/fork) and make the desired changes. Then you should [create a pull request](https://github.com/a2ys/chess-ai/compare) to allow to merge your changes in the main branch.
- **Fork the Repository:** [Fork the repository](https://github.com/a2ys/chess-ai/fork) to create a copy of it on your local machine which you can later modify. <br/>
-**Make Modifications:** Make your desired changes while following coding conventions and best practices. <br/>

Alternatively, if you find a bug/issue in the program, you can [create an issue](https://github.com/a2ys/chess-ai/issues/new/choose), and wait for it to be fixed.
-**Create a Pull Request:** [Create a pull request](https://github.com/a2ys/chess-ai/compare) to propose your changes for review and potential inclusion in the main project. <br/>

Your contributions are wholeheartedly welcome.

If you need further assistance with configuration, or any other topic related to this project, you can [create an issue](https://github.com/a2ys/chess-ai/issues/new/choose), or mail me at [oreus@duck.com](mailto:oreus@duck.com). Happy experimenting. :)

## License

The project abides by the GNU GPL Version 3, which can be found [here](LICENSE.md).
Expand Down
Loading