"Wings" is a text-based adventure, with retro vibes, written and executed using Python and run within Code Institutes mock terminal using the Heroku platform.

It is an interactive game, that the user interacts with by selecting from two options, each option has a consequence of some sort, some are 'win' outcomes, some result in 'loose' outcomes, and some keep the adventure going. It is, in essence, a 'choose your own' adventure.

The game is based on "Choose your own adventure" books from the 80's and 90's, you can read more about the books here: Wikipedia

• Upon entering the game space you are asked if you want to proceed.
• Promted to enter your name, there are several validation stages to ensure a valid name entry, each will repromt if error triggered.
• Enter the game space.
• Promted to start making your choices.
• The last step repeats until you end the adventure through either success or failure.
• A different conclussion shows depending on success or failure.
• You are promted to choocse between restart or stop.
• If you restarted the game loops back to the beginning.

• You are greeted with an ascii-art image, and a 'typewriter' style printed message welcoming you and inviting you to play the game.
• A goal statement is also printed.

• After selecting 'yes' the game begins.
• You are promted with a username entry, here there are multiple validation steps to ensure valid entry.
• If you selected 'no' there is a querry if this was accurate.

• After a valid name entry you are greeted and introduced to the outline of the game.
• There is a little background text here explaining where you are.
• Then you find yourself making the decisions, the input required is based on binary, option 1 or 2, your choice will lead on to success or failure.

• As you progress through the story you will reach 'end points', some of these are win conditions, some are loose conditions.
• Both have unique statements on completion.
• After you have seen a completion screen you are presented with an option to play again, or quit.

• Add colour to make the game look better.
• Use an API link google sheets to rework and extend the story line.
• Impliment scoreboard tracking individual players.
• Make game so multiple people are capable to play and track their scores, comparing to other players.

Before I started thinking about the code I used a flowchart to design the story arc, from the entry point to the end points. This allowed me visualise the paths I needed to create to ensure a good flow, it also allowed me to back-track when bug testing and discover where I had made mistakes.

Once I had created the flowchart, I started writing the code:

• Class

I created a single class that interacts with the story dictionary I have created. Using a class allows me to encapsulate the both the functionality and the story.

• Dictionary

I used a dictionary to store the story text and allow me to structure it so that it can flow. It also allowed me to separate the games 'logic' from it's 'data'.

The dictionary contains the game's story line, choices, and outcomes structured as follows:

• Values: Dictionaries containing:

  • "step_text": Text describing the current step.
  • "options" (Dictionary): Available choices and their corresponding steps.
  • "outcome": Outcome of the current step ("success" or "failure").

• Keys: Strings representing different steps in the game.

• Logic

  • Functions: To keep code readable and reusable, functions(play_game, display_intro, start_game, get_username) are used to display the game's introduction and loop through the game's story, displaying text, options, and handle user choices, leading to different outcomes.
  • Input Validation: Each user input is validated and handled raising appropriate error depending on game stage and option to re-enter user input is provided if it is invalid.

• Structure

  • Separation of Concerns: Separated the game logic from the data(story line) and the presentation (text-based input and output) to follow a good design practice and keep code well-maintained.
  • The game defines various locations and sub locations, and the player can navigate through these areas based on their choices. The game uses text-based print statements to provide descriptions, dialogues, and narrations to convey the story and set more engaging atmosphere.

• I have considered running this program through lighthouse to check the accessability rating and performance output, but decided not to because this app is not designed to be responsive, it runs in a third party terminal created by Code Institute.

• I have personally tested the input for name entry in as many ways as I could think of:

  • At the username input stage:
    • I have inserted empty space into a string.
    • I have left the entry blank.
    • I used less letters than minimum.
    • I have used special characters.
  • At the options input stage:
    • I have tried using non-numeric characters.
    • I have left the entry blank.
    • I have tried special characters.
  • At the replay input stage:
    • I have tried using non-numeric characters.
    • I have left the entry blank.
    • I have tried special characters.

  In all cases I expected to be reprompted to enter, and I was.

• Code :

  • Python code is tested using Code Institute PYTHON LINTER, with no errors. Code passed through and confirmed no problems.

User testing:

• I want to understand the purpose of the site/game.
  • The ascii code art and welcome screen shows the user what the site/game is about.
• I want the navigation to be intuitive and easy to understand.
  • The user is provided with easy to understand options and easily navigable interface.
• I want to be able to decide to start the game, and not worry about captalisation or typing yes/no.
  • The user can opt in or out of the game, although they will be re-promted in case of an error, username can be entered lowercase or captilised, or uppercase for the really bold statement. Yes/No options can be typed in full or as a simple y/n.
• I want to be able to enter my name and have it acknowledged.
  • The user can enter their name, it will be checked for a validitiy, then they will be welcomed and inserted into the story line.
• I want to be able to keep story flowing and recieve a message at the conclusion of the storyline.
  • The user drives the story, their input at the options section is how the story line is generated, whether positive or negative there is an end screen for the game.
• I want to play again.
  • Whether you win or loose the user will be promted with the option to replay, depending on the choice the game will either replay or terminate.
• I want replay-ability.
  • The user drives the story line, there are multiple conclusions to play through.

I had to run the code through the Code Institutes pep8 checker multiple times:

• First run, it came back with dozens of errors, mostly blank space on story.py.
  • Fixed the blank space errors with patience and carefully checking each line - these errors occured because I copied text from the google sheets doc I used.
• Second run, it returned a couple of undefined variables on story.py.
  • Fixed these by checking I had copied the variable names and replacing them where needed.
• Third run, switching to run.py, I had very similar issues to those I experienced with story.py.
  • Fixed these by again checking line by line for white space, no syntax errors this time though.

Once everything passed the Code Institute pep8 checker I deployed, and the next round of checks began:

This time I had to fix a couple of syntax errors, I had forgotten to change the variable names from the story.py...

There seems to be one error that is inherant in text based apps, the user can interfere with the display by hitting letters on the keyboard while the text is being generated. I am sure there is a solution but I haven't found one so for now it remains.

This is a list of technologies used during the construction and testing of the site:

• Gitpod IDE to develop the website.
• Github To host the source code and GitHub Pages to deploy and host the live site.
• Git to provide version control (to commit and push code to the repository).
• Code Institute's Gitpod Template to generate the workspace for the project.
• Ascii art Used to create the ASCII airplane.
• Ascii art archive Used to create the ASCII words.
• ViewPDF Converts PDF to JPG.
• Bytesresponsive Used to create responsive image.
• TinyJPG To compress images for README.
• ChatGPT Used for spelling, grammer, and readability checks.
• Code Institutes pep8 checker Used to check the python code.
• Mural USed to create the flow chart.

• sys: used for handling standard input and output streams during typewriter effect.
• time: used for controlling the timing of text output game for typewriter effect.
• Wings Repo

• On Github navigate to the repository "https://github.com/Swewi/Wings-text-based-game/tree/main"

• Click "Code" drop down menu - a green button shown right above the file list.

• Copy the URL of the repository using "HTTPS", "SSH" or "Github CLI".

• Open Git Bash.

• Change the current working directory to the location where you want the cloned directory.

• Type "git clone", and then paste the URL copied earlier.

• Press enter to create local clone. A clone of the repository will now be created.

• For more details on how to clone the repository in order to create a copy for own use refer to the site: Cloning a Repository

• On Github navigate to the repository "https://github.com/Swewi/Wings-text-based-game/tree/main"
• Click "Fork" located towards top right corner on GitHub page.
• Select "owner" for the forked repository from the dropdown menu under "owner".
• It will create forked repo under the same name as original by default. But you can type a name in "Repository name" or add a description in "Description" box.
• Click on "Create fork". A forked repo is created.

• Forking allows you to make any changes without affecting original project. You can send the the suggestions by submitting a pull request. Then the Project Owner can review the pull request before accepting the suggestions and merging them.
• When you have fork to a repository, you don't have access to files locally on your device, for getting access you will need to clone the forked repository.
• For more details on how to fork the repo, in order to for example suggest any changes to the project you can: Forking a Repository

• The app is deployed from Heroku using the following steps:
  • Use: pip freeze > requirements.txt to add external libraries to deployed app.
  • Create Heroku account.
  • In the top right, click 'New'.
  • Click 'Create new app'.
  • Give your app a name and select your region from drop down.
  • Click 'Create new app'.
  • Go to 'settings' tab, it's important you do it before deployment.
  • Scroll down to 'config vars' section and key: PORT and value: 8000.
  • Scroll down to 'Buildpacks' section.
  • Click 'Add buildpack'.
  • Add Python as first dependency and select 'Save changes'.
  • Add node.js as a second dependency and save again (This is settings section done).
  • Select 'Deploy' tab at the top.
  • Select 'Github' from 'Deployment method'.
  • Type the name given to your project in Github and click 'search'.
  • Scroll down and select Manual deployment method.
  • You can also use Auto deployment method to allow the project to update every time you push the code.
  • You can now click to view the app ready and running.

• The web application is displayed and deployed using template provided by Code Institute to test the code.
• For this project I used Manual deployment method to deploy the current state of the branch, every time I pushed the code from Gitpod.

• The code for typewriter effect is referred from https://github.com/Pauldwyer/Choose-your-adventure/blob/main/stories.py
• The implementation of this 'Choose your own Adventure' idea, and general encouragement when I felt lost, my mentor, Ronan McClelland.
• Stack Overflow.
• Code Institute mock terminal template to run the app.
• Code Institute's 'Love Sandwiches' project.
• My partner for understanding why I am working at the weekend.