Developer: Aleksandra Haniok
This is a command-line version of the classic Connect Four game for two players.
The classic game is played on a standing board with seven columns of six rows where two players take turns dropping coloured discs from the top to the bottom into a column of their choice. The piece falls straight down, occupying the next available space within the column.
The objective of the game is to be the first one to achieve a horizontal, vertical or diagonal line of four connected discs.
- Project Goals
- User Experience
- User Stories
- Technical Design
- Technologies Used
- Features
- Validation
- Testing
- Bugs
- Deployment
- Credits
- Acknowledgements
- Play a fun and easy game with other player
- Read the rules of the game
- Be able to log in to an existing account
- Create a game that is easy and clear to user
- Ensure that users understand the purpose of the game
- Create a game that gives feedback to the user whilst playing
There is no specific audience of this game. However, I would recommend that players are at least 6 years old, as per the classic board game.
- A simple, error-free game
- Straightforward navigation
- Game personalisation by entering players' names
- Feedback on game results
Click here to view instructions
On the main menu, users are presented with an ASCII art rendering of the name 'Connect 4'. Below the welcome graphic there are a couple of options for user to select from. Operation: Input a numeric value and press enter key.
- View game rules
- Play game
At any point of the game, if the user inputs a number which do not correspond to the available option then they will be prompt to try again.
With the first option to view game rules, the users are presented with a short game rules and once read they can go back to the main menu. Operation: Click any key and enter.
With the Play Game option, users are asked if they have played the game before or not. Operation: Input a numeric value and press enter key. The extra available option is to press 'y' key for 'yes' and 'n' for 'No'.
- Yes
- No
When selecting option 1, users are asked to input their email addresses they used in the previous game, starting with the Player 1.
The email goes through a validation process. If the user inputs an email that has not been registered they have an option to either try another email or create a new user. Operation: Input a numeric value and press enter key.
- Try another email
- Create a new player
User can try to input their email address until it matches the one already registered. If it does, then the greeting message with their name will be displayed. If they forgot their email address they can create a new players by selecting the second option.
Same option follow for Player2.
This option is available from the play option menu and during the existing users log-in. Here you can sign up to create a new user.
Firstly, the Player1 is asked for their name follow by the email address. Both values go through the validation.
Username has to be between 2-12 characters long and contain only A-Z. It can already exist in the database. Email: has to be a valid email containing exactly one @-sign from an existing domain. It must not exist in the database.
Same option follow for Player2.
If the registration is selected as part of the log-in option (Create a new player), then the relevant player will need to input their name and email address and once validated, type the email again for log in.
Once both users have been logged in, the program will display a greeting message with both names and start the game.
Players take turns to make their moves. The player to start is randomly selected by the program. The current player's name is displayed beneath the blue board showing which piece they play with. Player has to select which column they want to locate their piece in. Operation: Input a numeric value between 1 - 7 and press enter key.
A selection of invalid column will display a warning message and ask user to select a valid column.
The game continues until one of the players connect their four pieces.
When a player wins, a message with their name is shown on the screen.
Players have 4 different options to choose from:
- Play again
- Go to main menu
- See your statistics
- Quit game
Operation: Input a numeric value and press enter key.
By selecting this option a new game starts for the same players.
Brings players to the main menu of the program.
Display number of games won so far by each logged player.
With the guit game option, the user exits the program with a goodbye message.
- I want to have clear options to select in the main menu
- I want to be able to read the rules of the game
- I want to personalise the game and enter my name
- I want to be able to log-in if I return to the game
- I want to receive a real time feedback throughout the game
- I want to get a feedback when I win the game
- I want to be able to play multiple games when I'm logged in
- I want a random selection of the player to start a new game
- I want to see how many games I've won so far
- I want users to have a positive experience whilst playing the game
- I want users to easily select options from the menu
- I want user names and emails to be saved to Google Spreadsheet
- I want the user to get feedback in case of wrong input
- I want data entry to be validated, to guide the user on how to correctly format the input
The following flowchart summarises the structure and logic of the application.
Flowchart
- Python programming language for the logic of the program
- Diagrams.net was used to draw program flowchart
- Font Awesome - icons from Font Awesome were used in the footer below the program terminal
- Git was used for version control within VSCode to push the code to GitHub
- GitHub was used as a remote repository to store project code
- Google Cloud Platform was used to manage access and permissions to the Google Services such as Google auth, sheets etc.
- Google Sheets were used to store players details
- PEP8 was used to check my code against Python conventions
- Render Platform was used to deploy the project into live environment
- Visual Studio Code (VSCode) VSCode was used to write the project code using Code Institute template
- os - used to clear terminal
- random - used to alternate first player to start the game
- sys & sleep - used to create a typing effect within the games rules
- time - used to displayed delayed messages in the terminal
- unittest - used to carry out testing on single units in validation.py file
- colorama - JUSTIFICATION: I used this library to add color to the terminal and enhance user experience. I marked warning/error information with color red and user feedback with blue and green
- email_validator - JUSTIFICATION: I used this library to validate if user email input is of the form [email protected]
- gspread - JUSTIFICATION: I used gspread to add and manipulate data in my Google spreadsheet and to interact with Google APIs
- google.oauth2.service_account - JUSTIFICATION: module used to set up the authentification needed to access the Google API and connect my Service Account with the Credentials function. A creds.json file is created with all details the API needs to access the google account. In deployment to Render this information is stored in the config var section.
- Provides user with graphic welcome message
- Gives user option to view game rules or start game
- User stories covered: 1, 2
Main Menu Screenshot
- Displays clear game rules
- Allows user to return to the main menu once read
- User stories covered: 2
Game rules Screenshot
- Gives players options to either log in or create a new user
- User stories covered: 4
Play options Screenshot
- Asks users for their email addresses
- Informs them if the email they input is incorrect or not registered
- Gives user alternative option to try another email or create a new player
- If correct, saves their details to Google Spreadsheet
- User stories covered: 4, 5, 12, 13, 14
Log-in Screenshot
Alternative options Screenshot
- Asks user for their name and email address
- Validates user input values
- Informs user if the name they input is incorrect
- Informs user if the email is already taken and asks for another one
- User stories covered: 5, 12, 13, 14
Sign-up Screenshot
Sign-up email verification Screenshot
- Displays a greeting message to the user once logged in
- User stories covered: 3, 10
Greeting Screenshot
- Displays the name of currect player
- Players are asked to select the column to insert their piece
- Display warning message of incorrect column selected
- Provide feedback on who's won the game
- Gives options to play again after finished game
- User stories covered: 3, 5, 6, 13, 14
Game Screenshot
Incorrect Move in Game Screenshot
Winner Message Screenshot
Finished Game options Screenshot
- Restarts the game for the same players
- User stories covered: 7
Restart game Screenshot
- Brings players to the main menu of the program
- Display number of games won so far by each logged player
- User stories covered: 9
See your statistics Screenshot
- Exits the program with a goodbye message
Quit game Screenshot
- Displays an error message if user input is not in a form that was expected
- Asks for a new input and provides guidance to user on how to correctly format the input
- User stories covered: 5, 13, 14
Username validation Screenshot
Email validation Screenshot
Validation of input during the game Screenshot
PEP8 Validation Service was used to check the code for PEP8 requirements. All the code passes with no errors and no warnings to show.
PEP3 check for run.py
PEP3 check for validation.py
PEP3 check for colors.py
PEP3 check for test_validation.py
The testing approach is as follows:
- Manual testing of user stories
- Automated unit testing using the Python unittest library
See user stories testing
- I want to have clear options to select in the main menu
| Feature | Action | Expected Result | Actual Result |
|---|---|---|---|
| Main menu | Select option 1 | Users are presented with game rules | Works as expected |
| Main menu | Select option 2 | Users are asked if they played the game before | Works as expected |
Screenshot
- I want to be able to read the rules of the game
| Feature | Action | Expected Result | Actual Result |
|---|---|---|---|
| Main menu | Select option 1 | Users are presented with game rules | Works as expected |
Screenshot
- I want to personalise the game and enter my name
| Feature | Action | Expected Result | Actual Result |
|---|---|---|---|
| Play game options | Select option 1 (log-in) | Users are asked to input their email addresses, and once validated, a greeting message with their name is displayed. Names are displayed during the game | Works as expected |
| Play game options | Select option 2 (sign-up) | Users are asked to input their names, once validated the names are saved and greeting message displayed. Names are displayed during the game | Works as expected |
Screenshot
Screenshot
- I want to be able to log-in if I return to the game
| Feature | Action | Expected Result | Actual Result |
|---|---|---|---|
| Play game options | Select option 1 (log-in) | Returning users are asked to input the email address they registered before and once validated, a greeting message with their name is displayed | Works as expected |
Screenshot
- I want to receive a real time feedback throughout the game
| Feature | Action | Expected Result | Actual Result |
|---|---|---|---|
| User Input Validation & Feedback through game play | Players will be informed if their input is invalid | Error messages displayed | Works as expected |
Screenshots
- I want to get a feedback when I win the game
| Feature | Action | Expected Result | Actual Result |
|---|---|---|---|
| Game screen | Player has connected 4 pieces in a row | Message is displayed with the winning player's name | Works as expected |
Screenshots
- I want to be able to play multiple games when I'm logged in
| Feature | Action | Expected Result | Actual Result |
|---|---|---|---|
| Finished Game options | User selects play again option | The game restarts for the same players | Works as expected |
Screenshot
- I want a random selection of the player to start a new game
| Feature | Action | Expected Result | Actual Result |
|---|---|---|---|
| Game screen | Once players have logged-in or signed-up the game is loaded | Different user names display | Works as expected |
Screenshots
- I want to see how many games I've won so far
| Feature | Action | Expected Result | Actual Result |
|---|---|---|---|
| Finished Game options | Select option 3 | Display number of games won for Player1 & Player2 | Works as expected |
Screenshots
- I want users to have a positive experience whilst playing the game
| Feature | Action | Expected Result | Actual Result |
|---|---|---|---|
| Across all screen | Simple navigation and game play | Colored messages and straightforward instructions | Works as expected |
Screenshots
- I want users to easily select options from the menu
| Feature | Action | Expected Result | Actual Result |
|---|---|---|---|
| Across all screen | User inputs invalid numeric value | Users are asked to try again between available options from the menu | Works as expected |
Screenshots
- I want user names and emails to be saved to Google Spreadsheet
| Feature | Action | Expected Result | Actual Result |
|---|---|---|---|
| Log-in | Both users input their names and email address which has not been previously registered | Username and email addresses are saved to Google Spreadsheet to the next available rows in columns 1 & 2 respectively | Works as expected |
Screenshot
- I want the user to get feedback in case of wrong input
| Feature | Action | Expected Result | Actual Result |
|---|---|---|---|
| Across all screen | User inputs invalid numeric value in the menu or game. User inputs invalid value during log-in or sign-up | Feedback message displayed to the user | Works as expected |
Screenshots
- I want data entry to be validated, to guide the user on how to correctly format the input
| Feature | Action | Expected Result | Actual Result |
|---|---|---|---|
| Across all screen | User inputs invalid data | Feedback message with instructions diplayed to the user | Works as expected |
Screenshots
See unit testing
- I wrote unit tests using Python unittest library
- I tested separate functions to verify correct user input:
- validation of user email and user name input
I needed to amend the function and add 'Try Except' blocks to handle TypeError. Initial error called - 'TypeError: object of type 'int' has no len()'
- validation of data in log_in_players and register_new_players
When running the test initially, there was a TypeError called - 'TypeError: 'int' object is not iterable'. I handled this error by adding 'Try Except' blocks to both functions. This resulted with passed test.
| Bug | Fix |
|---|---|
| When selecting 'go back to main menu' option after the game has finished, the game title was not displayed | Correct the function's indentation |
| When selecting a correct menu option after a few wrong numeric inputs the relevant game option was not called | Move the while loop at the top within the function |
| Underscores within the game title were not displayed after deployment to Render portal | Changed color settings for yellow & red |
| Gradient background color does not take up the full screen size | Add background-attachment property |
| Players names input values are not displayed in the game – instead of name a “‘Player1’’s / ‘Player2’’s move.” is shown | Reassign a value of player1name & player2name to the indexed-0 value (name) input by the user in ‘create_new_players’ function |
| Users input data was recorded in the same row in four columns instead of 2 separate rows | Created a list of players and while loop inside the 'register_new_players' function for Google Spreadsheet update separately for two players |
| There were quite a few errors and warnings related to exceeded number of characters in line, whitespace within a blank line, trailing white spaces or missing white spaces around operators | Split the comments or print functions into two separate rows maintaining correct indentation. Followed a guidance within pep8 online tool and corrected all warnings and errors |
This application has been deployed from GitHub to Render by following the steps:
- Create or log in to your account at render.com
- Make sure you have connected your GitHub account to Render.com - follow the steps to Get Started and Sign up for Render. Click “New +” and select “Web Service”, on the right of the page, select “+ Connect account” for GitHub, ensure All repositories is selected and click “Install”
- Web service creation: Click “New +” and then “Web Service”. Search for relevant repo and click “Connect”.
- Settings: the web service's configuration settings are required to ensure the application is configured correctly. Add a Setting Name, leave Root Directory blank, add Environment 'Python3', Region (The physical location of the server hosting the web service), Branch - main
- Set the Build Command:
pip install -r requirements.txt && npm install - Set the Start Command
node index.js - Set up Environment Variables: Scroll down and click “Advanced” and “Add Environment Variable”. Add a key 'PORT' and value of '8000' and 'PYTHON_VERSION' with value of 3.10.7.
- Click “Add Secret File” and add a Filename 'creds.json' and file content.
- Click “Create Web Service” and wait for the project to build. First, the build is initiated. Then the build and deployment processes are carried out. Finally, the application is deployed and ready for public viewing.
- Go to the GitHub repository
- Click on Fork button in top right corner
- You will then have a copy of the repository in your own GitHub account.
- Go to the GitHub repository
- Locate the Code button above the list of files and click it
- Highlight the "HTTPS" button to clone with HTTPS and copy the link
- Open Git Bash
- Change the current working directory to the one where you want the cloned directory
- Type git clone and paste the URL from the clipboard ($ git clone https://github.com/YOUR-USERNAME/YOUR-REPOSITORY)
- Press Enter to create your local clone
- Flaticon was used for the website favicon
- ASCII Art Generator was used to create game title
- Code Institute - for git template IDE and "Love Sandwiches - Essentials Project" which helped me with connecting the Google Spreadsheet to my project.
- ColorSpace was used to create a gradient button and background effect
- How to install a Python module, eg. email validation
- gspread documentation explained how to obtain a specific value from the google spreadsheet
- Instructions how to print colored text from this and this sources
- Stack overflow helped me create typing effect in games rules
- Stack overflow code used to clear the terminal console
- Youtube video on Unit Test in Python made by Socratica was very helpful to understand the concept of unit tesing
- Youtube tutorial “Python Connect 4 Tutorial” made by Spencer Lepine - I used a part of Spencer's code for display of the game board, moves of alternative players and saving last move's coordinates on the board
- Youtube tutorial “Creating a Connect 4 Game in Python” made by “Painless Programming” - inspired me to create a schemat for winning move logic
See winning move schemat
I would like to thank everyone who supported me in the development of this project:
- My mentor Mo for professional guidance, helpful feedback and words of encouragement whilst creating the project. Also, for encouraging me to learn about the unit test and including it within this project.
- My partner for his support and playing/testing the game with me
- Code Institute community on Slack for resources and support