-
- UX
- Research
- Development Planes
- Strategy
- Scope
- Structure
- Skeleton & Design
- Colour Scheme
- Typography
- Imagery
-
- Visual Features
- Gameplay + Code Features
- Features to Implement in Future
-
- Resolved Bugs
-
- Languages Used
- Python Modules Used
- Frameworks
- Libraries
- Programs
Contained as a seperate document here
-
- Step-by-step guide on how to deploy
████████████████████████████████████████████████████████████████████████████████
___________ _____ _____ _______ ____ _________ ______________
/ // // // _ \ / \\ _ \\ \
/ // // // // / / /\ \\ \\ \\ \
/ _____// // // ' / / / \ \\ \\ \\ \\ \\ \
/ // ' // _ | / / / / \ \\ \\ \\ \\ \
/______ // // // // /___/ / \ ` \\ \\ \\ \
/ //__________//_________//_________/ \________\\___\\ \\ \
/ /█ M A R I N E ████ I N A T I O N █\ \\ \
/__________/███ T A C T I C A L █ M A R I N E █ E S P I O N A G E ████\___\\___\
████████████████████████████████████████████████████████████████████████████████
S U B M A R I N E ██ D O M I N A T I O N, is an iteration on a classic game of "Battleships", in a terminal using Python on the command line.
████████████████████████████████████████████████████████████████████████████████
█ █ █ █
█ WELCOME TO █ +| A B C D E F G H || A B C D E F G H |+ █ THIS IS █
█ SUBMARINE █ -|-----------------||-----------------|- █ AN EXAMPLE OF █
█ DOMINATION █ 1| ~ @ ~ ~ @ ~ ~ ~ || ~ ~ X ~ ~ ~ ~ ~ |1 █ THE SIMULATED █
█ SIMULATION █ 2| ~ ~ ~ ~ ~ ~ @ ~ || ~ ~ ~ ~ ~ ~ ~ ~ |2 █ ARENA █
█ COMMANDER █ 3| ~ ~ ~ ~ ~ ~ ~ ~ || ~ ~ ~ ~ . ~ ~ ~ |3 █ █
█ █ 4| ~ ~ ~ X ~ ~ ~ ~ || ~ ~ ~ ~ ~ ~ ~ ~ |4 █ ENEMY SUBS █
█ [LEFT] IS YOUR █ 5| ~ . ~ ~ ~ ~ @ ~ || ~ ~ ~ ~ ~ ~ ~ ~ |5 █ARE HIDDEN[RIGHT]█
█ ZONE █ -|-----------------||-----------------|- █ . = MISSED SHOT █
█ @ = YOUR SHIPS █ +| A B C D E F G H || A B C D E F G H |+ █ X = SUNK SUB █
█ █ █ █
████████████████████████████████████████████████████████████████████████████████
The idea to shift the characteristics of the game to be submarines instead of battleships due to the nature that the player can see board boards simoultaneously.
When the program begins to run, players are asked to position 5 Submarines on the board:
AT THE START OF THE GAME, YOU WILL BE ASKED TO POSITION 5 SUBS
LIKE THIS:
pick a lettered column between A - H:
THEN LIKE THIS:
pick a numbered row between 1 - 5:
Once all 5 submarines are positioned, the game employs the same function to guess the coordinates of the computer's hidden submarines (it also has 5 submarines).
once a player's /computer's submarines have all been targeted, the game is over and a win/loss message is generated, supplemented with the otpion to start a new game.
This project is the third of the five projects to be created for the Diploma in Full Stack Software Development (Common Curriculum)
Based on the Learning outcomes of the section of the Diploma, this project aims to:
- Create an interactive game through a "given algorithm as a computer program" that projects
- Run a game of
S U B M A R I N E ██ D O M I N A T I O Nby "Adapting and combining algorithms" to solve the processes and problem solving operations generated by the game's programming - Utilise "standard programming constructs: repetition, selection, functions, composition, modules, aggregated data (arrays, lists, etc.)" to effictively run the game
- "Explain what the given program does" in it's code through effective commenting and docstrings
- Using the project creation process to "Identify and repair coding errors in a program"
- Create a Project that uses "library software for building a graphical user interface, or command-line interface, or web application, or mathematical software"
- create a project that "implements a data model, application features and business logic" and utilises these to generate easily recognisable responses and outcomes for users/players.
- Create a Project that is developed through a documented process "through a version control system such as GitHub©"
- Be Deployed on Heroku©
This project was designed to be a Minimally Viable Project (MVP). Therefore it aligns as-close-as-possible to the design brief. Of course, as the code developed, personal flair was intertwined with core conepts. But the primary focus of the project (to meet the design brief) was constantly at the forefront of design during development.
the following sources were viewed for the conept of UI visual layout ONLY:
| Code Institute Project brief video |
|---|
 |
| trinket.io | copyassignment.com |
|---|---|
 |
 |
The following points were picked up by comparing the visual elements of the following 3 sources:
- UI is very narrow and bunched together
- The constraints of the UI makes User interface very bland and cluttered
- The visual representation for the "computer" playing the game is limited
Taking this into account. When the code for this project is developed. there will be focus drawn to making the command-line messages and interface more game-like.
The following user stories were created based off of the following design brief set out in The Portfolio Project 3 Assessment Guide:
The Battleships game is played on grids on which each player's fleet of battleships are marked. The locations of the fleets are concealed from the other player. Players call shots at the other player's ships, and the objective of the game is to destroy the opposing player's fleet.
The application provides a working battleships game for a single user to play against the computer.
Potential features to include:
The ability for the user to set the grid size
Warn the user if their guess is off-grid
External user’s goal:
The application user wants to play a logic game
The learning outcomes below hae also been taken as a point of reference for the project. sourced directly from The Portfolio Project 3 Assessment Guide:
| Learning outcomes |
|---|
| LO1 Implement a given algorithm as a computer program |
| LO2 Adapt and combine algorithms to solve a given problem |
| LO3 Adequately use standard programming constructs: repetition, selection, functions, composition, modules, aggregated data (arrays, lists, etc.) |
| LO4 Explain what a given program does |
| LO5 Identify and repair coding errors in a program |
| LO6 Use library software for building a graphical user interface, or command-line interface, or web application, or mathematical software |
| LO7 Implement a data model, application features and business logic to manage, query and manipulate data to meet given needs in a particular real-world domain. |
| LO8 Demonstrate and document the development process through a version control system such as GitHub |
| L09 Deploy a command-line application to a cloud-based platform |
After reviewing this information, the following user-stories were created:
- "As a user, i want to play a simple game of battleships"
- "As a user, i want to play some kind of logic game"
- "As a user, i want to be able to position my own ships to allow for own personal strategy"
- "As a user, i want to play against a 'computer' player"
- "As a user, i want to be able to make my own choices when trying to guess the position of enemy ships"
- "As a user, i want to be notified if i accidentally pick the same coordinate twice"
- "As a user, i want to be prompted if enter invalid coordinates"
- "As a user, i want to feel like my choices matter against the 'computer' player, and that i won't win if i just select each coordinate in sequential order"
Based on the criteria outlined above, the following project goals have been divided into User Goals and Developer Goals. These have been listed below:
User Goals:
Based on the user stories, User goals are defined as:
- create a command line game that is easy to follow
- the UI must be readable and friendly within the given limitations
- Employ code that simulates players playing against a chellenging AI opponent
- Allow for elements of personal choice when positioning ships and targeting enemy ships
- have contingencies in place if a mistake is made during an input error
- not punish the user for not enetering EXACT coordinates information
Developer Goals:
Based on Project research and design brief, Developer Goals are defined as:
- Have a command line game deployed and playable on the internet via Heroku©
- Develop a version of the game "Battleships" in the coding language: Python
- implement use of python libraries to enhance the UX of The terminal based game
- Make use of ASCII Art to add more of a visual element to the game
- create a program that only requires game narrative input from the user, no knowledge of working from a command line should be required to play the game.
Based on the results yielded from refining the design brief and research in the previous section, the following features will be developed for the project:
- Horizontal Game board and Center Aligned HUD design
- Given the terminal is wider than it is in height, the print statements for the game will be created to accomodate free lateral real estate in the terminal
- Classic Battleships Coordinates
- To elaborate on the focus of a user friendly feel, the coordinates used will be similar to that of the original "Battleships", where players would target an area on the board by a letter and a number
- Game-like Narrative
- Flipping the concept of taking the terminal as a limitation to style and turning it into a style choice, create a narrative in the language of the interface to make the game mimic the style of gimmicky vintage war game
- Anticipated error handling on user input
- ensure that input field data isn't case sensetive
- If invalid field data is parsed into the terminal, the programme can recognise how the data is invalid, notify the user, then let them retry inputting a value without crashing the programme or punishing the user
- Responsive Terminal
- The terminal will routinely clear and update game-state information, to prevent scrolling and simulate that of an interactive game
- the gameboard in the terminal will update every time a turn or change has been made to the game board
- How to Play Section
- An option will be present at the start menu that will explian the rules of the game to the user
In Terms of web layout, the project is hosted entirely through the project template after being deployed to Heroku©
Link to the template used to create the Repo for this project
The page itself acts as an index, and has no further functionality as this is out-of-scope for this project
Regarding the terminal, the amount of rows was increased from 24 to 30 accomodate some additional descriptions within print statements and remove the need for scrolling.
in terms of game structure, the following flowchart was drafted on LucidChart:
Due to the nature of this project, both of these planes have been merged.
As this project was to run entirely of of a terminal. Notepad on Windows was the optimal choice to create mockups define the structure for each section. Transcript lisfted directly from planning and quoted in codeblock below:
80 columns x 24 rows
https://ascii.co.uk/art/submarine
https://ascii.co.uk/art/explosiv
.
|`-:_
,----....____ | `+.
( ````----....|___ | - (sub art by Shimrod)
\ _ ````----....____
\ _) ```---.._
\ \
)`.\ )`. )`. )`. )`. )`. )`. )`. )`. )`. )`.
-' `-' `-' `-' `-' `-' `-' `-' `-' `-' `-' `
████████████████████████████████████████████████████████████████████████████████
████ / // // // _ \ / \\ _ \\ \ ████
███ / // // // // / / /\ \\ \\ \\ \ ███
██ / _____// // // ' / / / \ \\ \\ \\ \\ \\ \ ██
█ / // ' // _ | / / / / \ \\ \\ \\ \\ \ █
█ /______ // // // // /___/ / \ ` \\ \\ \\ \ █
█ / //__________//_________//_________/ \________\\___\\ \\ \ █
█/ /█ M A R I N E ████ I N A T I O N █\ \\ \█
█__________/ █████████████████████████████████████████████████████████\___\\___█
████████████████████████████████████████████████████████████████████████████████
____
__,-~~/~ `---.
_/_,---( , )
__ / < / ) \___
- ------===;;;'====------------------===;;;===----- - -
\/ ~"~"~"~"~"~\~"~)~"/ Nuclear
(_ ( \ ( > \) Explosion
\_( _ < >_>' Mushroom
~ `-i' ::>|--" - by Bill March
I;|.|.|
<|i::|i|`.
(` ^'"`-' ")
------------------------------------------------------------------
███████████████████ +| A B C D E F G H || A B C D E F G H |+ ███████████████████
███████████████████ -|-----------------||-----------------|- ███████████████████
███████████████████ 1| ~ ~ ~ ~ ~ ~ ~ ~ || ~ ~ ~ ~ ~ ~ ~ ~ |1 ███████████████████
███████████████████ 2| ~ ~ ~ ~ ~ ~ ~ ~ || ~ ~ ~ ~ ~ ~ ~ ~ |2 ███████████████████
███████████████████ 3| ~ ~ ~ ~ ~ ~ ~ ~ || ~ ~ ~ ~ ~ ~ ~ ~ |3 ███████████████████
███████████████████ 4| ~ ~ ~ ~ ~ ~ ~ ~ || ~ ~ ~ ~ ~ ~ ~ ~ |4 ███████████████████
███████████████████ 5| ~ ~ ~ ~ ~ ~ ~ ~ || ~ ~ ~ ~ ~ ~ ~ ~ |5 ███████████████████
███████████████████ -|-----------------||-----------------|- ███████████████████
███████████████████ +| A B C D E F G H || A B C D E F G H |+ ███████████████████
████████████████████████████████████████████████████████████████████████████████
█ █ █ █
█ WELCOME TO █ +| A B C D E F G H || A B C D E F G H |+ █ THIS IS █
█ SUBMARINE █ -|-----------------||-----------------|- █ AN EXAMPLE OF █
█ DOMINATION █ 1| ~ @ ~ ~ @ ~ ~ ~ || ~ ~ X ~ ~ ~ ~ ~ |1 █ THE SIMULATED █
█ SIMULATION █ 2| ~ ~ ~ ~ ~ ~ @ ~ || ~ ~ ~ ~ ~ ~ ~ ~ |2 █ ARENA █
█ COMMANDER █ 3| ~ ~ ~ ~ ~ ~ ~ ~ || ~ ~ ~ ~ . ~ ~ ~ |3 █ █
█ █ 4| ~ ~ ~ X ~ ~ ~ ~ || ~ ~ ~ ~ ~ ~ ~ ~ |4 █ ENEMY SUBS █
█ [LEFT] IS YOUR █ 5| ~ . ~ ~ ~ ~ @ ~ || ~ ~ ~ ~ ~ ~ ~ ~ |5 █ARE HIDDEN[RIGHT]█
█ ZONE █ -|-----------------||-----------------|- █ . = MISSED SHOT █
█ @ = YOUR SHIPS █ +| A B C D E F G H || A B C D E F G H |+ █ X = SUNK SUB █
█ █ █ █
████████████████████████████████████████████████████████████████████████████████
AT THE START OF THE GAME, YOU WILL BE ASKED TO POSITION 5 SUBS
LIKE THIS:
pick a lettered column between A - H:
THEN LIKE THIS:
pick a numbered row between 1 - 5:
████████████████████████████████████████████████████████████████████████████████
YOU WILL THEN USE THIS SAME PROCESS TO PREDICT ENEMY SUB PLACEMENT
THE HIGHLY ADVANCED AI WILL IN-TURN ATTEMPT TO PREDICT YOUR HIDDEN SUBS
SIMULATION STEPS REPEAT UNTIL ALL 5 ENEMY SUBS ARE DOMINATED
OR ENEMY DOMINATES ALL 5 OF YOUR SUBS
+| N: New Game || I: How to Play || X: close simulation |+
pick a lettered option listed above:
---POSITION SUB NUMBER 1, COMMANDER---
DESIGNATE RADAR COLUMN, COMMANDER
pick a lettered column between A - H:
pick a numbered row between 1 - 5:
As the Terminal is black, the HTML template used was appended with a style rule to change thepage background to black, to immerse with the style of the game and improve visual effect
the python library termcolor was used to color text in the terminal to raise importance of certain messages and increase readability
Typography generated and unedited by Terminal
As seen in the Notepad block above. Art was sketched out on the notepad manually. for more complex shapes, ASCII art was sourced from ASCII.co.uk. Original artists are credited above as appropriate
when building the board, an active choice was made to characterise blank spaces on the board with ~, as this effectively represent waves on a body of water.
@ signs were employed as player subs, as it was the closest thing to imagine as a periscope sticking out of the water.
. was used for a miss, as it was to emphasise stillness in the water but be more identifiable than -
X was used to mark a hit on the board for both sides, as an X is synonymous with negative outcomes. Also, sinking a sub is a relatively negative thing (if you are on board).
-
webpage
- houses the terminal to be used. coloured black to stylize itself with the terminal
-
Upon page load (and inevitably, terminal load) users are presented with the Title art along with instructions. Design is minimalistic and driects users to pick one of 2 options immediately:
- New Game
- Entering "N" will start a new game
- How to Play
- Entering "I" will clear the board and display the game rules
- New Game
-
How To Play
- when activated, clears the terminal then displays an example of the board, bookended with terminology to understand the game items
- further explanation of how to enter coordinates and rules of the game are then displayed directly below
-
New Game
- Displays a blank board and gives prompts to begin entering in coordinates for users to position their own subs
- every time a set of coordinates is entered, the terminal clears and an update of the board is printed.
- because of the low amount of data parsed, the terminal clear and repopulation appears instantaneous. simulating a running game and not a terminal.
-
winning conditions
- If a player beats the computer, then the terminal is cleared and ASCII art of a submarine with a congratulatory message appears
- From here, players have the option to start a new game, or return to the title screen
-
losing conditions
- If the programme guesses all the player's sub positions, the terminal is cleared and modified ASCII art appears of a nuclear explosion over water
- a game over message is printed underneath, with the option for players to start a new game or return to the title screen
-
during gameplay
- With each turn, the terminal is cleared and the gameboard is updated to reflect the current state of play
- if there are any errors in coordinates, the terminal also refreshes and displays the current state of the game to display up to date messages without the user having to scroll
- Title function Loads
printstitle art and welcome messageinputfield appears to select option- player picks "new game"
- player picks "how to play"
- Player Picks "How to play"
game_infofunction called- clears terminal
printsexplanation on how to play with examplesinputoption given, options given to return to title or start new game
- Return to title
- calls
titlefunction and repeats step 1
- calls
- Player picks "new game"
- calls
mainfunction mainfunction establishes important variablesprintsnew game board to terminal- sets a
boolean variablethat determines state of the game - calls function that assigns values for Comps subs in the background
- calls position_subs function, parses in state of the game variable to determine messages to print
- Position_subs function, calls pick_coords function to allow user to input coords. returns coords to dict
boolean variablevalue updated to change game messgaes when calling functions- upon function conclusion, dict is unpacked into 2 lists
- calls
- Core Gameplay loop begins
- housed within a
while loop - calls
fire_torpedofunction, which in-turn usespick_coordsfunction to target a coordinate on the board - value from
pick_coordsreturned tofire_torpedoand compared against Comp's sub coordinates - depending on hit or miss, the coordinate is updates on the board with "
X" or "." - back in the
while loop,mainfunction takes the updated value of the coordinate, and depending on the value, reduces the comp_shipcount by1or0 - process is repeated using neighbouring functions for comp's turn
- The
turnvariable is incrementally increased by1, keeping track of the amount of turns played - A message is printed detailing the current score of lives between the player and computer
While looploops back to topifcomp's shipcount is >0and player's shipcount is >0
- housed within a
hit_checkerfunction called during allfire_torpedofunctions- this checks to make sure that coordinates selected have not been picked before, or if a submarine has already sunk at this position
- if either above outcomes is
truea relevant statement isprintedto the terminal. The player is then required to pick a new coordinate
- step 5 repeats
if3,7,11,15or18turns pass, the comp will automatically guess a predesignated player's submarine- This is to prevent plays's from "cheesing" a victory by just entering every coordinate sequentially 1 after the other
- Winning
ifthecomp_shipcountvariable is reduced to0, the loop ends- the
player_winfunction is called - the function generates relevant ASCII art, congratulating player on their victory
- offers then to start a new game
- if they accpet,
mainis called again - if they choose no,
titleis called instead
- Losing
iftheplayer_shipcountvariable is reduced to0, the loopbreaks- the
player_losefunction is called - the function generates relevant ASCII art, letting them know they have lost
- offers then to start a new game
- if they accpet,
mainis called again - if they choose no,
titleis called instead
Upon reading the brief, there was room for further features that were overlooked to prioritise project delivery on deadline. instead they will be features that will be implemented in the future
- allowing player to select bot difficulty
- this would increase/reduce the amount of turns it would take for the programme to guess all of the player's coordinates
- Allowing player to determine board size
- increase or shrink boardsize
- contain different styles of boards to reflect this
- Allow player to enter their own name
- create a scroeboard by linking a google sheet to the programme
- this would allow creation of a global scoreboard that could be displayed at the end of each game, displaying how many turns it took to win, at selected difficulty
After hearing feedback from testers the following features were suggested for the future:
- "if a player has selected all coordinates or a row/column, error should be raised before player is allowed to put in second part of coordinate, reducing amount of unnecessary steps for player"
Resolved Bugs
- Global variable PLAYER_SUBS not logging all positions from player
- The dict that was packing all input data was overiting and value on a key that had already been entered instead of making a new key: value pair. This meant that if players picked the same row for more than one Sub the loop would just overrite the value for that row
- This was refactored out by making the return value of the position_subs() function to a tuple which unpacks to 3 variables (game_start, p_rows, p_columns), which now produces the desired end result
| Omercan Cirit |
|---|
| "Bug!... 5 subs, then at one point i think i lost 3 of them" |
 |
- Since debugging, this error has not been replicated. it was suspected that; upon defeat by the computer, the program would not exit the
while loopthat ran the core gameplay loop, resulting in an error throwing when it was trying to run thewhile loopon values which no longer had a value as the game had been restarted:
| Joe Collins |
|---|
| "Just had a little play looks great but did encounter an error that kicked me out. I think the coordinate i hit to get this was C1. I have added a screenshot of the IndexError this caused." |
| screenshot 1 | Screenshot 2 |
|---|---|
 |
 |
| Joe Collins: |
| Cheryl Phillips: |
|---|
| "G1 here... This was the state of play at the time:" |
| Screenshot 1 | Screenshot 2 |
|---|---|
 |
 |
After consultation with The project mentor (Seun Owonikoko), the above explanation was expected. at this stage, the bug has been removed by implementing a break of the loop upon player_shipcount decreasing to 0
Given the nature of this project, other languages were used to build the suitable platform to deploy the project.
- Random - To create random numbers
- OS - to create a function that clears the terminal
- colorterm - to color terminal print statements
- Pylint - to ensure that code follows PEP8 guidance.
- pdb -
import pdb; pdb.set_trace()used to manually debug code mid-run of program at specific intervals
- GitHub - Used to store, deploy and publish site.
- GitPod - Used to write and preview code, commit and push to GitHub.
- Google Chrome - Used to run GitPod in browser, test deployment, and google search etc.
- Mozilla Firefox - Used to test UX
- Microsoft Edge - Used to test UX
- Safari on Mac and iOS - Used to test UX
- Opera - Used to test UX
- Google Chrome on Android - Used to test UX
- LucidChart - Used to create Structure plane flowchart
- Python Tutor - Used to simulate isolated blocks of code during build
- Diffchecker - used to check for differences in code against reference structures
- Cloud Converter - Used to create all GIFs in README
- MS Notepad - Used to initially sketch own ASCII art and ideas
- MS Powerpoint - Used to create features flowchart
- MS Clipchamp - Used to create all GIFs in README
- Zoom Screen recording - Used to create all GIFs in README
Testing is housed in the following appendix: TESTING.md
Upon creation of the project in GitHub/GitPod, the project was launched externally on Heroku
below are the following steps one should take to deploy this project on Heroku:
- Log in/Sign up for an account with Heroku
- Upon logging in, at the dashboard select "create new app".
- if you have previously created projects on Heroku, this option can be accessed from the "new" buttonat the top right corner of the screen
- Give your project a unique name. You cannot name your project with a name that's already in use
- select the region you wish to deploy your project to
- click "create app"
- select the deployment method, in this scenario, we are using GitHub
- upon page refresh, enter the name of the repo you want to link up to Heroku
- If you have not done so, you will need to ollow the steps to link your GitHub account to your Heroku account
- You must seach for the correct repo name of your project in the field given. misplellings will result in Heroku being unable to find your repo
- Set up your prject to automatcally deploy on every push update
- deploy your project
- Allow time for Heroku to deploy the project(the video here is sped up)
- click to iew your deployment!
additional steps specific to this project Before Deploying:
- Once you have created the project, you will also have to install Buildpacks
- this can be done in the settings tab of the project, along the top of the page.
the following 2 buildpacks need to be added for this project to function. they must be added in the following order:
- Python
- NodeJS
- in it's current state, this project does not have any CREDS required to run the project. However, in the futre, should this be needed. the contents of the creds.json file in the repo would need to be copied to the configvars of the project in Heroku, with the creds.json file also being added to .gitignore in the repo.
resources for creating code:
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent