- Description : This Portfolio Project 3, PYTHON program called Fallout Mini - Hangman is an online game (hangman quiz) that allows the user to test their vocabulary, progress through a story line that is based on Fallout 2 RPG game and make an entry to leader board.
- Key project goal : To entertain users of this program and test their vocabulary knowledge attempting the Fallout Mini - Hangman game.
- Audience : There's no age or any other limit to audience of this application. Target audience are any users searching for simple vocabulary games.
Live version : Live version of Fallout Mini - Hangman game can be viewed here .
- 1. Key project information
- 2. Table of content
- 3. Description of functionality and rules
- 4. Functions
- 5. Overall logical flow
- 6. Imports
- 7. Google sheet
- 8. Testing
- 9. Deployment
- 10. Technologies
- 11. Credits
- After starting the program, user is prompted with
Main menuwith 3 options (Start the game, High Scores, Exit) (appendix 1). - If users selects "S" - Start Game, user is prompted with input of their name (appendix 2).
- In next step, user is prompted with perk selection (appendix 3):
- Intelligent - shortens the hidden word by 1 letter
- Lucky - adds extra 5 guesses each round of guessing
- Charismatic - reveals 1 letter from each hidden word
- After selecting the perk, game starts inform the user of the story line and quests (appendix 4).
- As the user completes the word guessing each time, story line moves on and length of hidden word increses. The output of each guess could be :
- Correct guess - user is notified, number of guesses is decreased by 1,list of already guessed letters is updated, correctly guessed letter is revealed in the hidden word, if this was last hidden letter, user goes to next level (appendix 5).
- Incorrect guess - user is notified, number of guesses is decreased by 1,list of already guessed letters is updated, if this was last guess left game ends (appendix 6).
- Letter already guessed - user is notified (appendix 7).
- If user fails to guess any of the hidden words, game finishes and program returns to
Main menu - If users guess all the hidden words correctly, game time based on starting and finishing the game is recorded and program returns to
Main menu - If users selects "H" - High Scores, list of 10 best players is displayed to user, user can return to
Main menuafter (appendix 8). - If users selects "E" - Exit, the program ends.
Appendix 1 - Main menu
Appendix 2 - Name input
Appendix 3 - Perk selection
Appendix 4 - Story line
Appendix 5 - Correct guess
Appendix 6 - Inorrect guess
Appendix 7 - Letter already guessed
Appendix 8 - High Scores
- Name :
display_text(row, column, delay=0.012) - Parameters :
rowcolumn - Goal : Function is designed to display large amount of text with a type-writer effect.
- Function : Function calls
clear_screen()first and then connects to Google worksheet - sheet 'text (appendix 9) and targets cell stated as parameters. Function reads this cell and replaces stringPLAYERwith variableplayer_nameand stringBREAKwith\nto wrap lines in Heroku terminal in suitable positions. - Flow Chart : Appendix 10
Appendix 9 - Connected Google sheet - worksheet text*
Appendix 10 - display_text()
- Name :
clear_screen() - Parameters : None
- Goal : Function is designed to clear the terminal screen before next text is displayed. This scrren was made for compatibility between Windows and Unix systems, instead of changing multiple lines of code if enviroment is changed, the code needs to be only changed inside of this function.
- Function : Function only performs one line of code.
- Flow Chart : Appendix 11
Appendix 11 - clear_screen()
- Name :
update_highscore() - Parameters : None
- Goal : Function is designed to update high score sheet in connected Google sheet
highscore(appendix 12). - Function : Function reads current time and saves it, based on that function then claculates play time (Play Time = Finish Time - Start Time). Function then connects to Google sheet and appends row with player's name and play time in seconds (variables
player_nameandplay_time) - Flow Chart : Appendix 13
Appendix 12 - Connected Google sheet - worksheet highscores
Appendix 13 - update_highscore()
- Name :
update_history() - Parameters : None
- Goal : Function is designed to update history sheet in connected Google sheet (appendix 14) for analytics purposes every time someone plays the game.
- Function : Function reads current date and time, opens Google sheet (worksheet
history) and appends new row to the worksheet with player's name, date, time, perk (variablesplayer_name,date_now,start_time,perk_inteligence,perk_luck,perk_charisma). - Flow Chart : Appendix 15
Appendix 14 - Connected Google sheet - worksheet history
Appendix 15 - update_history()
- Name :
wait_until_keypressed() - Parameters : None
- Goal : Function is designed to make a pause in program run and wait until user presses any key.
- Function : Function reads character pressed into variable
pause_var. This variable is then "displayed" in black color so it is not visible in terminal with balck backdround. Priniting the variablepause_varis not neccessary, but it does avoid error message in code. - Flow Chart : Appendix 16
Appendix 16 - wait_until_keypressed()
- Name :
display_highscores() - Parameters : None
- Goal : Function is designed to read high score sheet in connected Google sheet
highscore(appendix 11) and display accordingly. - Function : Function reads all values in `highscore' Google sheet, if any, displays first 10 in ascending order, if none message "No entries yet" is displayed.
- Flow Chart : Appendix 17
Appendix 17 - display_highscores()
- Name :
end_of_game() - Parameters : None
- Goal : Function is designed to display winning/loosing message and call
update_highscore()if user wins. - Function : Function contains if/else statement determining if variable
game_winneris True. Ifgame_winneris True, high scores are update and congratulations message is displayed. Ifgame_winneris False, then only loosing message is displayed. - Flow Chart : Appendix 18
Appendix 18 - end_of_game()
- Name :
random_word_number() - Parameters : None
- Goal : Function is designed to randomly generate number between 1 and variable
max_word_number. - Function : Function runs in loop. Each cycle function generates number between 1 and value of variable
max_word_number. This variable is currently set to 50 as the database of words contains 50 entries for each word length. Variablemax_word_numberneeds to be adjusted if the database of words is made broader. This function also contains if/else statement to ensure the randomly generated number was not generated already. The cycle is exited only if newly generated number isn't included innumbers_pickedlist. - Flow Chart : Appendix 19
Appendix 19 - random_word_number()
- Name :
word_guess(difficulty, guesses) - Parameters :
difficulty= length of guessed word,guesses= the amount of guesses per word - Goal : Function prepares a hidden word and user needs to guess all the letters correctly or guess the whole word.
- Function : This function resets all the necessary variables first.
message_color = 3,message = '',word_guessed_correctly = False,letters_guessed = []. After they are all reset, function recalculates variablesdifficultyandguessesbased on perks lucks or intelligence were used, also if perk charisma was used, variableperk_charisma_usedis set to 1. Function random_word_number is called and number returned. Function then opens Google worksheet ('words') and based ondifficultyand returned random number targets a specific cell with a word in it. Then this function runs in cycle until either the word is guessed correctly or user runs out of guesses. All letters of hidden word are initially replaced with'-', unless perk charisma was used, then one letter is left unhidden. User is prompted to guess a letter or type the whole word. Depends on the letter being in hidden word or not, the next cycle is determined with message and all displayed information. - Flow Chart : Appendix 20
Appendix 20 - word_guess(difficulty, guesses)
- Name :
print_intro() - Parameters : None
- Goal : Function is designed to display Main Menu (appendix 1) and validate user choice between
S - Start Game,H - High ScoresorE - Exit. - Function : Function prints Main menu and waits for a key to be pressed (
readcharfunction). If users selection is between the letters S, H or E, program calls next function depending on selection, otherwise error message is displayed. - Flow Chart : Appendix 21
Appendix 21 - print_intro()
- Name :
create_character() - Parameters : None
- Goal : Function is designed to get user's name and perk selection, also to validate that
player_nameare only alphabetical characters and the perk selection is between the charactersI - Intelligence,L - LuckorC - Charisma. - Function : Likewise the previous function
print-intro(), this function prints Perks menu and waits for a key to be pressed (readcharfunction). If users selection is between the letters I, L or C, program calls next function depending on selection, otherwise error message is displayed. - Flow Chart : Appendix 22
Appendix 22 - create_character()
- Name :
start_game() - Parameters : None
- Goal : Function runs in loops (4 loops for full game). This function calls the
word_guesswith parameters increasing every loop to make the game harder each loop. After each game, this function determines if user can go to next stage or should the game ends in case of user didn't guess the word correctly. - Function : Function iterates through list
levels. This list has currently 4 positions. Based on the next number in thelevelslist, parameters forword_guessfunction are determined. After each call forword_guessfunction, this function goes through if/else statementgame_winner= True or False,end_of_gamefunction is called then. - Flow Chart : Appendix 23
Appendix 23 - start_game()
Appendix 24 - Overall flow chart
To ensure functionality of this program, variable modules had to be imported.
- Name of module:
readchar - Function : This module reads one character as user input, returning it as string with length 1. Waits until character is available.
- Version used : 4.0.5
- Link to documentation: readchar
- Name of module:
colorama - Function : The Python colorama module is a cross-platform library that simplifies the process of adding color to terminal text. It provides a simple and convenient way to add ANSI escape codes to text, making it possible to color text output on Windows as well as other platforms.
- Version used : 0.4.6
- Link to documentation: colorama
- Name of module:
googleauth - Function : This module, google-auth is the Google authentication library for Python. This library provides the ability to authenticate to Google APIs using various methods. It also provides integration with several HTTP libraries.
- Version used : 2.22.0
- Link to documentation: google-auth
- Name of module:
gspread - Function : This module, gspread is a Python API for Google Sheets. Opens a spreadsheet by title, key or url.
- Version used : 5.10.0
- Link to documentation: gspread
- Name of module:
json - Function : This module enables Python programs to effortlessly communicate with web services, exchange data, and store structured information.
- Version used : built-in
- Link to documentation: json
- Name of module:
os - Function : This module provides functions for interacting with the operating system. OS comes under Python's standard utility modules. This module provides a portable way of using operating system-dependent functionality.
- Version used : built-in
- Link to documentation: os
- Name of module:
random - Function : This module is an in-built module of Python that is used to generate random numbers in Python. These are pseudo-random numbers means they are not truly random.
- Version used : built-in
- Link to documentation: random
- Name of module:
sys - Function : This module provides functions and variables which are used to manipulate different parts of the Python Runtime Environment. It lets us access system-specific parameters and functions.
- Version used : built-in
- Link to documentation: sys
- Name of module:
time - Function : This module provides many ways of representing time in code, such as objects, numbers, and strings. It also provides functionality other than representing time, like waiting during code execution.
- Version used : built-in
- Link to documentation: time
- Name of module:
datetime - Function : This module supplies classes for manipulating dates and times. While date and time arithmetic is supported, the focus of the implementation is on efficient attribute extraction for output formatting and manipulation
- Version used : built-in
- Link to documentation: datetime
In order for the program to work in Heroku terminal, file requirements.txt needs to be created with all third party imported modules. This is done with command pip freeze > requirements. txt. This command ensures that up-to-date requirements.txt (appendix 25) file is generated.
Appendix 25 - requirements.txt
This project uses Google sheets.
Reasons :
- Save large amounts of text - sheet
(text) - Database of hidden words - sheet
(words) - Database of High Scores - sheet
(highscores) - Record of history of accesses - sheet
(history)
It is necessary to implement the following code to access the file with given credentials (appenedix 26).
Google sheet credentials documentation
Appendix 26 - Google sheets credentials
Also, very importantly, the same credentials need to be passed onto Heroku aplication (appendix 27), including the PORT = 8000 as config vars.
Appendix 27 - Heroku settings
Steps :
- Main Menu (appendix 28)
- Name Input (appendix 29)
- Perk Input (appendix 30)
- Guess Word (appendix 31)
Appendix 28 - Main Menu test
Appendix 29 - Name Input test
Appendix 30 - Perk Input test
Appendix 31 - Guess Word test
| User | Nessa Bourke |
|---|---|
| Feedback given | I really enjoyed using the program, instructions were clear and easy to follow and I especially loved the high score feature! It would be good to return to the main menu at any stage. |
| Applied changes | Added "0" as an option to all inputs to return to main menu. Commit 91c8830 |
| User | Julie Carroll |
|---|---|
| Feedback given | All functionality is good, please do spelling check. |
| Applied changes | Spelling check performed. Commit fb2802d. |
- Method : Project (
run.py) was tested by PEP8 validator. - Result : No errors were found when tested (appendix 32).
Appendix 32 - PEP8 validator
Throughout testing, various bugs were discovered, especially with 79 characters long line. They were all fixed, committed and documented via GitHub.
- Bug with inability to return to main menu from the game.
- Fix : Add if/else statement to all user input. If
input = "0"run functionprint_intro. - Error with line length of more than 79 characters.
- Fix : Wrap lines using
end=''code. - In higher levels, the amount of guesses exceeded amount of letters in alphabet.
- Fix : Introduce
round_result = word_guess(level + 3, (level * 2) + 10)multiplication of 2 instead of 3. - When user plays game multiple times, perks are adding and user can avail of multiple perks.
- Fix : Introduce
reset of all perk variablesinmain()function.
There are no know unfixed bugs as of 9.8.2023.
- Task : To ensure regular commitments are done to avoid any data/progress loss.
- Method :
- commands
git add [filename]was used to add specific file to staging area, alternatively commandgit add .was used to add all changed files to staging area - command
git commit -m "[commit description]"was used to add commitments into queue - command
git pushwas used to push all commitments to remote repository on GitHub
- commands
- Finding : CodeAnywhere IDE only holds up to 3 commitments in queue, regular
git pushneeded to be used.
- Task : To use repository on local machine.
- Method :
- Navigate to GitHub and follow
Code -> HTTPS -> Copy button. After those steps open your local coding environment and typegit clone [copied link].
- Navigate to GitHub and follow
- Finding : Git Windows application needs to be installed.
- Task : Enable users to access the program via Heroku terminal.
- Method :
- Once the Heroku account and URL is linked with GitHub repository, the live program does update automatically.
- Heroku has to have all vars set properly (appendix 27)
- Heroku has to have all relevant buildpacks enabled in correct order (appendix 33)
- Finding : Heroku terminal freezes after 1 minute inactivity.
Appendix 33 - Heroku buildpacks
- Python - coding language Python
- Google Cloud - Cloud for developers including Google drive Google cloud
- CodeAnywhere - to write and save the code CodeAnywhere
- GitBash - to make commitments of progress and push the results back to GitHub git - scm
- ConText - code off-line in "doodle-zone" mode ConTEXT editor
- GitHub - to record all commitments and deployment the live project GitHub
- Code Institute - for all fun I had with this project Code Institute
- W3Schools - useful information and cheat sheets W3Schools
- EZGif - render GIF from video files EZGif
- Daisy McGirr - excellent mentoring Daisy McGirr
- Alan Bushell - excellent class cohort Alan Bushell
- My lovely wife Aneta and kids Jan, Izabela and Tobias - great patience and mental support