██████ █████ ████████ ████████ ██ ███████ ███████ ██ ██ ██ ██████ ███████ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██████ ███████ ██ ██ ██ █████ ███████ ███████ ██ ██████ ███████ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██████ ██ ██ ██ ██ ███████ ███████ ███████ ██ ██ ██ ██ ███████
Battleships Game – Python Terminal Edition
A Python terminal battleship experience built for tactical play, clean UI, and arcade-style feedback.
⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀ ⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⡀⡰⡀⡀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀ ⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠒⠒⠒⢚⠒⠒⠒⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀ ⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠠⢸⠠⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀ ⠀⠀⠀⠀⠀⠀⠀⠀⠀⡂⠀⠀⠀⠀⠀⠠⡑⡹⠠⡀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀ ⠀⠀⠀⠀⠀⠀⠀⠀⠀⡇⠀⠀⢰⣴⣴⠷⡹⣈⡪⣈⣂⣀⡀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀ ⠀⠀⠀⠀⠀⠀⠀⠠⢤⣷⡄⢤⢸⣵⢌⢆⡂⡢⡡⠥⠣⣑⡄⣀⣀⡄⡀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀ ⠀⠀⠀⠀⠀⠀⢀⣰⣽⣿⣥⣥⣽⣿⣥⣕⢐⢰⠫⡨⠨⡒⡳⡙⠵⠉⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀ ⡀⠀⠀ ⠀⠐⠐⡐⠠⠠⠨⢟⡿⢿⡰⡑⣽⢫⢛⡣⡲⠿⠇⠍⠅⣷⢑⠪⢨⠲⡕⡰⣤⣠⣤⣄⣀⡠⠀⠀⠀⠀⠀⠀⠀⠀⡂⠀⠀ ⠀⠀⠀⠀⠁⠌⡈⢆⢌⢂⠪⠩⡙⡓⠶⠶⣬⣌⣮⣨⣨⣷⡠⡑⠄⡇⡫⠩⡘⡍⠈⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀ ⡂⠀⠀ ⠀⠀⠀⠀⠀⠀⠀⠢⡑⡢⣥⡑⡐⢌⠘⠔⠆⡆⡍⢍⢓⠲⠲⠮⣬⣆⣍⢙⡛⡛⣛⣫⡡⢥⣄⣀⠀⠀⠀⠀⠀ ⢐⠀⠀⠀ ⠀⠀⠀⠀⠀⠀⠀⠀⢂⢂⢢⡙⡺⣤⡡⠡⡑⡐⠌⠜⠄⠇⢅⡕⢌⡒⠌⠍⢝⢛⠻⠷⠿⣏⣿⣿⣿⣿⣶⣦⣤⣸⡀⠀⠀ ⠀⠀⠀⠀⠀⠀⠀⠀⠂⠂⠨⠹⡬⣆⣛⠳⣦⡨⠨⠨⠨⡈⠢⡈⠢⠡⠡⡑⡐⠄⠅⢅⢑⢐⠐⠄⢥⣩⠩⠩⠩⢩⠑⠀⠀ ⠀⠀⠀⠀⠀⠀⠀⠀⠔⠌⢌⢂⠒⠟⢷⣵⣔⡙⠻⢮⣦⣈⠢⠨⠨⡈⡂⠢⠨⠨⡈⡂⡂⠢⠡⡑⠽⠣⠡⠡⠡⠁⠀⠀⠀ ⠀⠀⠀⠀⠀⠀⠀⠀⠀⠈⠂⠂⠡⡑⡐⠪⣻⣷⢓⠓⠌⢝⠻⢾⣴⣐⠌⠌⢌⢂⢂⠢⠨⡈⠢⠨⠨⠨⠨⠨⠈⠀⠀⠀⠀ ⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠁⠀⠨⡈⡂⠂⡂⠡⠑⠄⢅⠑⠌⢝⠻⢷⣶⣔⣄⢅⠑⠌⠌⠌⠌⠌⠌⠌⠀⠀⠀⠀⠀ ⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠈⠐⠐⠠⠑⠨⡐⡐⠌⠢⠡⡑⣄⢓⣰⣔⣭⣛⡻⢷⣧⣥⣥⣥⣥⣥⠁⠀⠀⠀⠀⠀ ⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠂⠂⠢⠡⠡⡑⡊⡂⢂⢂⢛⠿⡛⡻⠿⡗⢏⢛⠻⠿⡟⠄⠀⠀⠀⠀⠀ ⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠁⠐⠀⠀⠀⠀⠂⠁⠀⠀⠁⠈⠀⠀⠈⠀⠈⠀⠀⠀⠀⠀⠀ ⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
- Project Overview
- UX Design
- Game Flow
- Features
- Technologies Used
- Project Structure
- How to Play
- Testing
- Deployment
- Credits
Battleships is a terminal-based Python strategy game inspired by the classic naval combat format, where the player must locate and destroy all enemy ships before the enemy destroys the player's fleet.
This project was designed as a complete command-line game experience rather than a basic text-only prototype. The aim was not only to make the game functional, but also to create a more polished and engaging terminal interface with a clear game flow, strong visual structure, responsive feedback, and an arcade-style presentation that remains suitable for the Code Institute deployment terminal.
The project takes the familiar Battleships concept and presents it through a structured multi-screen player journey:
- A welcome screen that introduces the game
- A mission setup screen where the user selects the battlefield size and fleet size
- A mission briefing screen that explains the rules and symbols
- A live gameplay screen with two tactical boards shown side by side
- A status section that continuously reports turn information, ships remaining, and shot counts
- Turn-by-turn feedback after each player and enemy action
- Dedicated end-game result screens for mission success and mission failure
The game was intentionally built around readability and usability. Because terminal-based applications can easily become confusing or visually cluttered, special care was taken to structure each screen in a way that feels organised, easy to scan, and beginner-friendly. Important information is grouped into framed sections, feedback is shown clearly after every action, and controls are explained in plain language.
A major design goal of the project was to ensure that the gameplay experience still feels dynamic even within the limitations of a terminal interface. For this reason, the game includes:
- Stylised title presentation
- Framed tactical boards
- Colour-coded feedback messages
- A clearly separated status panel
- Sequential turn pacing
- Dedicated mission result screens
To maintain a controlled scope, the game focuses on a polished core battle loop rather than attempting to simulate the full traditional Battleships ruleset with complex multi-cell ship placement and advanced AI. This makes the experience easier to understand while still offering strategy, suspense, and replayability.
In practical terms, the player chooses a grid size between 8x8 and 10x10, chooses a fleet size between 1 and 5 ships, and then begins the battle. The player attacks by entering coordinates such as A1, B7, or H8. After each player move, the enemy automatically responds with a valid random strike that never repeats a previous attempt. The match continues until one fleet is completely destroyed.
For deployment stability, the live Heroku version uses a browser-safe ASCII board symbol set and a more compact layout. This keeps the gameplay boards aligned correctly inside the browser terminal, while the local version can still use richer emoji board symbols where terminal support is more reliable. Some short feedback messages still use decorative emoji, but the tactical board itself switches to ASCII in deployment to preserve layout stability.
This project also includes hidden developer testing tools which were used during development to speed up screenshot capture and special-state testing. These tools are intentionally disabled in normal gameplay so that the deployed version remains fair, clean, and assessment-safe.
Overall, this project was built to demonstrate:
- Python programming fundamentals
- Terminal UI design
- Input validation
- Game state management
- User-focused feedback design
- Structured testing and deployment readiness
The primary goal of this project was to create a terminal game that feels complete, readable, and enjoyable from start to finish. Rather than showing only the core logic, the project was designed to guide the user through a clear sequence of screens and interactions that make the experience feel more like a real game product.
The project goals were:
The project needed to be more than a code demonstration. The user should be able to:
- start the game easily
- understand what to do
- interact with the system without confusion
- play until a clear win or loss outcome occurs
Because the final game is displayed through the Code Institute Python Essentials template, the layout had to be carefully designed so that:
- important content remains visible
- the player does not need to scroll through normal gameplay
- framed UI sections remain readable
- boards and prompts stay aligned within a narrow terminal space
Terminal games can feel intimidating for users who are unfamiliar with CLI interfaces. To reduce this barrier, the project includes:
- a welcome screen
- clear setup instructions
- a mission briefing before gameplay
- visible board labels
- input examples
- explanatory feedback after every action
The traditional idea of Battleships is strong, but terminal versions can often feel too plain. This project aimed to improve the experience by including:
- stylised title art
- colour-coded interface elements
- framed battle panels
- tactical status reporting
- mission-style wording
- dramatic success and failure screens
The player should never feel lost after entering a move. The game therefore reports:
- whether the shot was a hit or miss
- the coordinate targeted
- enemy response messages
- changing fleet counts
- total shot counts
- end result summaries
The project also needed to support:
- screenshot capture for the README
- manual testing of special states
- predictable structure for explanation and validation
- assessment-friendly presentation
This project is aimed at several types of users.
Users who enjoy classic turn-based games can play a simplified naval combat experience in the browser through the terminal deployment environment.
Some users may not have much experience with command-line games. The game was designed so that even a first-time player can understand what to do with minimal confusion.
The project also needs to communicate clearly to an assessor. For that reason, the layout, feedback, structure, and documentation are all important. The game should show not only working logic, but also careful attention to usability and presentation.
Users who play more than once should be able to quickly:
- change grid size
- change the number of ships
- start a new match
- enjoy a slightly different battle due to random ship placement and enemy targeting
- As a first-time user, I want a clear opening screen so that the game feels welcoming and intentional.
- As a first-time user, I want setup instructions so that I know how to choose my options.
- As a first-time user, I want to understand the game rules before the battle starts.
- As a first-time user, I want visible coordinate labels on the boards so that I can target correctly.
- As a first-time user, I want input examples so that I know what format to type.
- As a first-time user, I want the game to tell me whether my move was a hit or miss.
- As a first-time user, I want clear messages when I type invalid input.
- As a first-time user, I want a final result screen so that I clearly know whether I won or lost.
- As a returning player, I want to start a new game quickly.
- As a returning player, I want to change the grid size and fleet size for variety.
- As a returning player, I want the battle layout to remain readable every time I play.
- As a returning player, I want feedback to appear quickly and clearly after each action.
- As a returning player, I want the game to feel polished enough that replaying it is enjoyable.
- As the developer, I want the layout to remain stable in the deployment terminal.
- As the developer, I want clear screen sections so the interface does not feel messy.
- As the developer, I want controlled developer cheat tools for fast testing.
- As the developer, I want the README screenshots to match the real deployed interface.
- As the developer, I want the game structure to be easy to explain and assess.
The project uses a naval command / tactical mission theme rather than a plain utility-style terminal layout. This theme was chosen because it helps the user feel that they are controlling a fleet rather than simply running a script.
Terms such as:
- Mission Setup
- Mission Briefing
- Enemy Fleet
- Your Fleet
- Mission Accomplished
- Mission Failed
help create a more immersive and memorable experience.
The layout is divided into clearly separated interface blocks:
- title area
- setup / briefing panel
- gameplay boards
- status panel
- input area
- result screen
This makes the interface easier to scan and reduces cognitive overload. Instead of mixing all information into continuous text, the user is guided through neatly separated phases.
Colour is used purposefully rather than randomly.
- Cyan is used for headings and player-side emphasis.
- Yellow is used for panel borders, dividers, and important UI framing.
- Green is used for positive actions and mission success.
- Red / Magenta is used for warnings, danger, enemy alerts, and defeat-related emphasis.
- White is used for standard readable content.
This colour system improves clarity while also giving the game a stronger visual identity.
Framed panels were chosen to:
- separate sections visually
- make the interface feel organised
- improve readability in the terminal
- create a premium arcade-console feel
Without these panels, the game would still function, but it would feel more like raw output than a designed product.
The battle screen uses two boards:
- Enemy Fleet on the left
- Your Fleet on the right
This is the most intuitive layout because it lets the player compare both battle zones at a glance. It also matches the logic of the game:
- the left board is where the player attacks
- the right board shows the player's own fleet state
The visual symbol system was designed to make the boards quick to read at a glance.
In local terminal play, the game uses emoji-based board symbols for a more expressive visual style:
🌊represents water💦represents a missed strike💥represents a successful hit🚢represents a visible player ship
In the deployed Heroku version, the game uses browser-safe ASCII board symbols instead:
~represents waterorepresents a missXrepresents a successful hitSrepresents a visible player ship
This dual-symbol approach was chosen so the local version can remain visually rich while the deployed browser terminal stays aligned, stable, and easy to read.
The input area was written in a more instructional style rather than a minimal prompt. Instead of only saying something vague, the game explicitly tells the user:
- what format to enter
- gives an example such as
A1 - explains that
Qquits the game
This reduces user mistakes and improves confidence.
The most important UX priorities in this project were:
- clarity
- readability
- stable layout
- understandable rules
- visible feedback
- smooth deployment fit
The game was designed as a structured player journey rather than a single continuous screen. Each phase has a clear purpose and prepares the player for the next one.
- The player launches the game.
- The welcome screen appears.
- The player selects grid size and number of ships.
- The mission briefing explains rules and symbols.
- The battle screen appears with enemy and player boards.
- The player enters a target coordinate.
- The game validates the input.
- The shot is resolved as hit or miss.
- The enemy takes a turn.
- The status panel updates continuously.
- The cycle repeats until one fleet is destroyed.
- A final result screen announces success or failure.
flowchart TD
A[Start Game] --> B[Welcome Screen]
B --> C[Mission Setup]
C --> D[Mission Briefing]
D --> E[Gameplay Screen]
E --> F[Player Enters Coordinate]
F --> G{Valid Input?}
G -- No --> H[Show Validation Message]
H --> E
G -- Yes --> I[Resolve Player Shot]
I --> J{Enemy Fleet Destroyed?}
J -- Yes --> K[Mission Accomplished Screen]
J -- No --> L[Enemy Turn]
L --> M{Player Fleet Destroyed?}
M -- Yes --> N[Mission Failed Screen]
M -- No --> E
The game begins with title art and a clean command-center presentation. This immediately establishes the theme and gives the project a stronger identity than a plain terminal script.
Before the battle begins, the user selects:
- grid size
- number of ships
This setup stage gives the player control over the battle scale and helps make the game more replayable.
The mission briefing acts like a preparation screen. It explains:
- the size of the grid
- the number of deployed ships
- the valid control format
- the meaning of symbols
- the mission objective
This step is especially important for new users.
Once the battle starts, the player enters target coordinates to attack the enemy fleet. The game then:
- checks the input
- checks whether the target was already used
- resolves the strike
- updates the board
- shows feedback
- triggers the enemy turn
- updates status values
When one fleet is fully destroyed, the game exits the loop and displays a dedicated result screen summarising the outcome.
The project currently includes the following gameplay and interface features:
- stylised welcome screen
- mission setup panel
- mission briefing panel
- grid size selection from 8 to 10
- ship count selection from 1 to 5
- side-by-side gameplay boards
- row and column coordinate system
- visible player fleet
- hidden enemy fleet until hit
- turn-based battle loop
- hit and miss detection
- random enemy targeting
- repeated-target prevention
- live status panel
- battle feedback messages
- mission accomplished screen
- mission failed screen
- hidden developer testing tools
The welcome screen is the player's first contact with the game. Its purpose is not only decorative, but functional. It introduces the theme, establishes the tone, and makes the project feel like a complete product.
The welcome screen includes:
- Title art or a fallback compact title, depending on the runtime environment
- A command-center subtitle
- A smooth transition into the setup phase
The welcome screen presentation adapts to the environment in which the game is running. In local play, the game can use a larger stylised title, while the Heroku deployment uses a more compact terminal-safe title layout to preserve alignment and avoid pushing the interface off-screen.
This screen improves first impressions and gives the project a stronger identity. Without it, the player would enter directly into setup and lose part of the polished experience.
No dedicated welcome screen screenshot was captured separately, as the opening presentation transitions directly into the mission setup flow in the deployed terminal experience.
The mission setup screen allows the player to configure the battle before it begins.
The player can choose a battlefield size from:
- 8
- 9
- 10
This affects both boards and changes the battle space.
The player can choose the total number of ships from:
- 1
- 2
- 3
- 4
- 5
This changes battle length and difficulty.
The player can use:
- Up Arrow to move up
- Down Arrow to move down
- Left Arrow to reduce a value
- Right Arrow to increase a value
- Number keys to type values directly
- Backspace to remove typed input
- Enter to confirm and continue
This screen gives the user control, improves replay value, and makes the game feel interactive before combat even begins.
The mission briefing screen acts as a short pre-battle tutorial.
It explains:
- Current grid size
- Number of deployed ships
- Control format
- Board symbols
- Objective of the mission
- Grid range such as
A-HorA-J - Number range such as
1-8or1-10 - Valid target examples like
A1 - The meaning of
Q - The symbols used in the current environment
This is important because it lowers the learning curve. It helps new users understand the battle before the first move and reduces the chance of confusion.
The gameplay screen is the core interface of the project.
It contains:
- the game title
- the enemy fleet board
- the player fleet board
- a status panel
- a feedback message line
- a dedicated target input area
- permanent divider lines for clarity
The enemy board shows what the player knows about the enemy position:
- water for untouched cells
- miss markers where shots failed
- hit markers where enemy ships were found
Enemy ships are hidden unless hit.
The player board shows:
- water
- the player's visible ships
- enemy misses
- enemy hits
This lets the player monitor both attack progress and defence status.
Both boards use:
- row letters (
A,B,C, etc.) - column numbers (
1,2,3, etc.)
This makes targeting intuitive and easy to understand.
The gameplay screen was designed to keep all essential battle information visible at once. The player should not need to guess:
- where to attack
- whose turn it is
- how many ships remain
- what the last action did
The status panel is placed directly below the boards and groups the most important live battle information into three sections.
This shows whether it is currently:
- PLAYER TURN
- ENEMY TURN
This shows how many ships remain for:
- the enemy fleet
- the player fleet
This shows the total number of shots taken by:
- the player
- the enemy
The status panel also includes a visual legend for:
- hit
- miss
- water
- fleet ship
The status panel prevents the user from needing to remember battle numbers mentally. It keeps the interface tactical and readable.
After each move, the game displays a dedicated battle feedback message.
Examples include:
- player hit message
- player miss message
- enemy attack result
- warning before enemy turn
Turn feedback keeps the game from feeling silent or mechanical. It adds pacing and helps the user understand what changed after an action.
Once either fleet is fully destroyed, the game shows a dedicated result screen instead of abruptly ending.
Shown when all enemy ships are destroyed.
It confirms:
- mission success
- that the battlefield is secured
- final shot statistics
Shown when all player ships are destroyed.
It confirms:
- mission failure
- that the enemy has taken control
- final shot statistics
The result screen gives proper closure to the battle and makes the ending feel deliberate and complete.
Strong validation is one of the key gameplay quality features in this project.
The game checks for:
- empty or incomplete input
- coordinates in the wrong format
- non-numeric columns
- coordinates outside the active grid
- repeated target attempts
A11Z9AA- already-used coordinates
Without validation, the game could:
- accept broken input
- confuse the player
- damage the game state
- feel unreliable
Instead, the game provides clear messages and keeps the user on track.
The enemy uses random targeting, but with important safeguards.
- selects a random coordinate
- checks whether that coordinate has already been used
- retries until a fresh target is found
- records the shot result
- updates the player board accordingly
This keeps enemy turns valid and prevents duplicate attacks on the same square.
The logic is intentionally simple, which suits the scope of the project and keeps the gameplay fair and understandable.
Hidden Developer Testing Tools
During development, hidden testing tools were included to speed up screenshot capture and special-state testing.
These tools are intentionally disabled in normal gameplay.
They are kept off in the final version because:
- Normal players should not accidentally activate cheats
- The deployed game should reflect real gameplay
- Testing shortcuts should not affect fairness
- The assessment version should remain clean and reliable
Open run.py.
Inside the BattleshipGame.__init__() method, find this line:
self.dev_mode = FalseReplace it with:
self.dev_mode = TrueCheat codes must be typed in the normal gameplay target input area.
This is the same input prompt where the player would normally enter a coordinate such as:
A1
B7
H8
J10
When the gameplay screen is visible and the game asks for a target, type the cheat code there instead of a coordinate, then press Enter.
Forces an instant player victory.
Where to use it:
Type /WIN in the gameplay target input prompt and press Enter.
What it does:
- Clears all remaining enemy ships
- Ends the battle immediately
- Shows the Mission Accomplished result screen
Best use case:
- Capture the victory screenshot
- Test the final success screen
- Confirm win-state flow
Forces an instant player defeat.
Where to use it:
Type /LOSE in the gameplay target input prompt and press Enter.
What it does:
- Clears all player ships
- Ends the battle immediately
- Shows the Mission Failed result screen
Best use case:
- Capture the defeat screenshot
- Test the final failure screen
- Confirm loss-state flow
Forces a successful player hit on one remaining enemy ship.
Where to use it:
Type /PHIT in the gameplay target input prompt and press Enter.
What it does:
- Removes one enemy ship
- Updates the enemy board with a hit marker
- Increases the player shot count
- Shows hit feedback
Best use case:
- Test hit feedback messages
- Capture gameplay screenshots with visible enemy hits
- Create near-win scenarios
Forces a successful enemy hit on one remaining player ship.
Where to use it:
Type /EHIT in the gameplay target input prompt and press Enter.
What it does:
- Removes one player ship
- Updates the player board with a hit marker
- Shows enemy-hit feedback
Best use case:
- Test enemy impact on the player board
- Capture near-loss gameplay states
- Verify player fleet update behaviour
After testing is complete, developer mode should be turned off again.
Restore this line in run.py:
self.dev_mode = FalseThis ensures that the final deployed version remains fair and assessment-safe.
While the current version meets the core project scope, a future version could expand the experience with features such as:
- smarter enemy AI
- multiple ship sizes
- manual ship placement
- difficulty settings
- score tracking
- multiple rounds
- leaderboard support
- sound effects
- replay mode
- improved animations
- optional colour themes
- full classic Battleships ruleset with horizontal and vertical ship placement
This project was built using a combination of Python, terminal UI libraries, deployment support files, and documentation assets. Each technology was chosen to support either the gameplay itself, the terminal presentation, or the final deployment and assessment requirements.
A key technical consideration in this project was the difference between local terminal rendering and browser-based terminal rendering on Heroku. Because browser terminals can render emoji width inconsistently, the deployed version uses safer ASCII battle symbols and a tighter layout to preserve alignment and readability.
Python is the main programming language used for the entire game. It powers:
- game setup logic
- board generation
- ship placement
- turn handling
- input validation
- enemy attack logic
- win and loss conditions
- terminal rendering support
Python was chosen because it is well suited for building structured logic, managing game state, and developing terminal-based applications in a clear and maintainable way.
colorama is used to add coloured terminal output.
It is responsible for the coloured presentation of:
- title styling
- panel borders
- status highlights
- warnings
- mission success messages
- mission failure messages
- general gameplay emphasis
This improves readability and helps separate interface sections visually.
wcwidth is used to calculate the visible width of characters in the terminal.
This is especially important because the project uses:
- Unicode box-drawing characters
- local terminal emoji board symbols such as
🌊,💦,💥, and🚢 - deployment-safe ASCII board symbols in the live Heroku version
- coloured ANSI text
Normal string length calculations are not reliable for this type of content. wcwidth helps keep alignment stable across the interface.
The project also uses several Python standard library modules:
os– terminal clear handling and system behaviourre– ANSI escape code stripping for alignment calculationssys– terminal output control and input behaviourrandom– random ship placement and enemy targetingtime– message pacing and feedback timingshutil– terminal size detection
These built-in modules support both gameplay functionality and terminal layout control.
Used on Windows systems for single-key input reading.
Used on Unix-based systems for low-level keypress handling.
These are required so the setup screen can respond to:
- arrow keys
- Enter
- Backspace
- direct key presses
without waiting for a full input line.
This project follows the Code Institute Python Essentials template structure and includes the support files needed for browser-terminal deployment.
Used to tell the deployment platform how to run the application.
Lists the Python dependencies required to run the project successfully.
Part of the Code Institute Python Essentials template structure used to connect the deployed browser terminal environment to the Python program.
Supports the Code Institute Python Essentials template's Node-based terminal wrapper.
Git was used throughout development for version control, change tracking, and safe iteration.
GitHub was used to store the remote repository, maintain commit history, and prepare the project for assessment submission.
The README.md file is written in Markdown. Markdown was used because it is the standard format for GitHub documentation and supports:
- structured headings
- code blocks
- tables
- images
- lists
- Mermaid diagrams
Screenshots were created and stored to visually document the project's interface and features.
The image assets used for the README are stored in:
docs/images/
Although this is a terminal-based game, the project still followed a UX-focused design mindset. This included:
- planning screen flow
- organising information into framed sections
- improving readability for first-time users
- making the terminal experience feel polished rather than raw
The project was organised so that gameplay code, deployment support files, and documentation assets remain clearly separated.
boney-battleship-cli-pp3/
|
|-- .gitignore
|-- .python-version
|-- index.js
|-- package.json
|-- Procfile
|-- README.md
|-- requirements.txt
|-- run.py
|
|-- controllers/
| `-- default.js
|
|-- docs/
| `-- images/
| |-- gameplay-screen.png
| |-- mission-accomplished-screen.png
| |-- mission-briefing-screen.png
| |-- mission-failed-screen.png
| |-- mission-setup-screen.png
| `-- turn-feedback-screen.png
|
|-- views/
| |-- index.html
| `-- layout.html
|
`-- __pycache__/
This is the main Python application file and contains:
- terminal UI rendering
- welcome screen logic
- mission setup logic
- mission briefing logic
- gameplay logic
- board drawing functions
- status panel rendering
- input handling
- enemy turn logic
- end-game results
This file is the core of the project.
The main documentation file for the project. It explains:
- the project concept
- UX decisions
- features
- testing
- deployment
- credits
This file contains the external Python packages needed to run the game.
Used during deployment so the hosting environment knows how to start the project correctly.
These files belong to the Code Institute Python Essentials template and make it possible to run the Python game inside a deployed browser-based terminal environment.
This folder stores README images only.
It contains screenshots used to visually support sections such as:
- setup screen
- mission briefing
- gameplay
- turn feedback
- mission success
- mission failure
These image files are safe to keep in the repository and do not interfere with deployment.
Even though the project is kept inside a single main Python file, the code was still structured into logical sections to improve readability and maintenance.
The project is organised in this order:
- imports and setup
- keypress helper logic
- welcome screen class
- shared terminal helper functions
- board rendering functions
- main battleship game class
- program entry point
This approach keeps related behaviour grouped together and makes the flow easier to follow.
This structure supports the project well because:
- the gameplay logic is easy to locate
- README assets are separated from runtime files
- deployment support files remain untouched
- documentation and screenshots stay organised
- the project stays aligned with Code Institute deployment expectations
Battleships is a turn-based strategy game. Your objective is to destroy every enemy ship before the enemy destroys yours.
The game is designed to guide the player through a clear flow, so even first-time users can understand what to do.
Start the deployed terminal or run the program locally.
The welcome screen will appear first, followed by the mission setup screen.
In the Mission Setup screen, choose:
- Grid Size between
8and10 - Number of Ships between
1and5
You can move through the setup using the keyboard controls shown on screen.
Press Enter to continue once your settings are ready.
The mission briefing explains:
- the active grid size
- the number of ships in play
- valid coordinate format
- what the symbols mean
- the main battle objective
Press Enter again to begin the battle.
Once gameplay begins, you will see:
- the Enemy Fleet board
- the Your Fleet board
- a Status panel
- an input section for entering your target
Type a coordinate such as:
A1B7H8J10
Then press Enter.
Your coordinate must always follow the format:
- one row letter
- one column number
After your move, the game shows feedback telling you whether you:
- hit an enemy ship
- missed the target
- entered invalid input
- repeated a previously used coordinate
If the enemy fleet is not fully destroyed, the enemy automatically takes a turn.
The game will display:
- a warning message
- the enemy's attack result
- updated board information
The battle continues in a loop until one side has no ships left.
At the end of the match, the game shows one of two result screens:
- Mission Accomplished if you win
- Mission Failed if you lose
- Up Arrow – move selection upward
- Down Arrow – move selection downward
- Left Arrow – decrease selected value
- Right Arrow – increase selected value
- Number Keys – type a value directly
- Backspace – remove typed value
- Enter – confirm selection / continue
- Type a coordinate such as
A1 - Press Enter to fire
- Type
Qand press Enter to quit the game
The game uses two visual modes depending on where it is running.
When played in a local terminal with emoji support, the game uses:
🌊= water / untouched space💦= miss💥= successful hit🚢= your visible ship
In the Heroku browser terminal, the game uses deployment-safe ASCII board symbols to prevent board misalignment:
~= water / untouched spaceo= missX= successful hitS= your visible ship
This fallback was intentionally added because browser-based terminal rendering can calculate emoji widths inconsistently, which may break alignment in framed game boards.
The gameplay board changes symbols depending on the environment, but some short feedback messages may still use decorative emoji. This means the deployed Heroku version uses ASCII for board stability while local play can still display richer emoji symbols when terminal support is available.
This board shows the enemy side.
You can see:
- water in untargeted positions
- miss markers where you failed to hit
- hit markers where you successfully struck an enemy ship
Enemy ships stay hidden until you hit them.
This board shows your side.
You can see:
- the positions of your ships
- enemy misses
- enemy hits
This helps you track the battle from both sides at once.
- Use the coordinate labels carefully before firing.
- Do not repeat previously targeted positions.
- Keep watching the status panel to track remaining ships.
- Larger grids give more space but may take longer to finish.
- More ships make the battle longer and slightly more demanding.
Testing was an important part of this project because terminal games depend heavily on reliable input handling, stable screen layout, and correct game-state updates.
The project was tested through repeated manual gameplay runs, edge-case checking, and UI review inside the deployment-sized terminal environment.
Manual testing was used to confirm that the gameplay loop, screen structure, and input handling all behaved as expected.
The following checks were carried out:
- the title displays correctly
- the setup screen appears without layout overflow
- arrow key navigation works
- number key entry works
- Backspace behaves correctly
- Enter moves correctly between fields
- invalid setup values are rejected
- setup values remain inside the allowed ranges
The following were checked:
- the mission briefing reflects the chosen grid size
- the mission briefing reflects the chosen ship count
- symbols are displayed correctly
- the briefing remains readable in the deployment layout
- the next step is clear to the user
The following areas were tested repeatedly:
- two boards render correctly
- row and column labels stay aligned
- player ships display correctly
- enemy ships remain hidden until hit
- hit and miss markers update properly
- the status panel updates after each turn
- the input area remains readable
- the turn feedback message appears in the correct place
- the input divider lines remain visible
- no gameplay scrolling is required in the standard deployment view
The following input cases were tested:
- empty input
- single-character input
- row only input such as
A - non-numeric column input such as
AB - out-of-range row input such as
Z9 - out-of-range column input such as
A99 - repeated coordinate input
- lowercase input
- quit command using
Q
The following were checked:
- enemy attacks update the player board correctly
- enemy hits remove player ships correctly
- enemy misses display correctly
- enemy does not intentionally repeat already used coordinates
- shot totals increase correctly
Both final states were tested:
- mission accomplished screen
- mission failed screen
The final shot totals and victory/defeat text were checked for correctness.
The Python code should be tested using the Code Institute Python Linter before final submission.
Checks to confirm:
- no syntax errors
- no indentation errors
- no obvious structural issues
The `run.py` file was tested using the Code Institute CI Python Linter and passed with no errors found.
The game was also reviewed against the Code Institute Python Essentials template deployment size to ensure that:
- the welcome screen fits
- the setup screen fits
- the mission briefing fits
- the gameplay screen fits
- the result screens fit
- normal play does not require scrolling
During development, several issues were identified and corrected.
Issue:
Earlier versions caused noticeable full-screen blinking when warning messages were shown.
Fix:
The warning message handling was adjusted so that it appears more steadily and no longer causes unnecessary repeated flashing.
Issue:
Battle feedback and input elements were not always positioned consistently, which made the interface feel jumpy.
Fix:
The input area was redesigned with a fixed-height structure so that the message area, prompt row, and divider lines remain stable.
Issue:
The status panel content sometimes appeared pushed left or unevenly distributed.
Fix:
The panel layout was reorganised into cleaner sections for:
- turn status
- fleet status
- shots fired
- legend
Issue:
Some board layouts looked too compressed or visually unbalanced.
Fix:
Board rendering was refined so that spacing, headers, and overall alignment remain clearer within the available deployment width.
Issue:
The target prompt did not clearly explain what Q does.
Fix:
The prompt was rewritten to explicitly state that Q quits the game.
Issue:
Capturing victory and defeat states manually through full gameplay took too long.
Fix:
Hidden developer test tools were used during development to quickly trigger special states for screenshot capture and interface testing.
At the time of writing, there are no known major gameplay-breaking bugs in the main battle loop.
Minor terminal rendering differences may still occur depending on:
- local terminal font
- Unicode and emoji support in local terminals
- platform-specific terminal behaviour
However, the deployment-target layout was designed specifically to remain stable within the Code Institute Python Essentials template environment.
This project is deployed to Heroku using the Code Institute Python Essentials template, which provides the browser-based terminal wrapper needed to run a Python command-line application in the browser.
The live application is hosted on Heroku and uses the browser-based terminal structure provided by the Code Institute Python Essentials template.
This project follows the Code Institute Python Essentials template approach. The deployment structure includes the template support files that connect the Python game to the browser terminal wrapper, including:
Procfile- tells Heroku how to run the applicationrequirements.txt- lists the Python dependencies needed for the gameindex.js- starts the Node-based terminal bridge used by the templatepackage.json- defines the Node dependencies and scripts for the browser terminal wrappercontrollers/default.js- handles the websocket connection between the browser terminal and the running appviews/index.html- provides the browser page that displays the terminalviews/layout.html- supplies the shared HTML layout used by the terminal page
Node.js is required because the Code Institute Python Essentials template uses a browser-based terminal wrapper rather than a direct Python-only web deployment.
This repository was generated from the Code Institute Python Essentials template.
Official template: Code Institute Python Essentials Template
- Push the project to GitHub.
- Log in to Heroku.
- Create a new Heroku app.
- Open the app and go to the Settings tab.
- In Config Vars, add:
PORT=8000
- In Buildpacks, add these in this exact order:
heroku/pythonheroku/nodejs
- Go to the Deploy tab.
- Connect the GitHub repository:
boneyphilip/boney-battleship-cli-pp3
- Choose the
mainbranch. - Click Deploy Branch.
- After deployment, open the app and test:
- welcome screen
- mission setup
- mission briefing
- gameplay board alignment
- result screens
The screenshot folder inside docs/images/ is for documentation only and does not interfere with deployment.
The deployed Heroku version uses a browser-safe ASCII board symbol set instead of emoji-based board symbols. This was implemented intentionally because browser terminal rendering can calculate emoji widths inconsistently, which may distort board alignment when emoji are used inside the tactical grid.
For that reason:
- The live deployment prioritises board alignment and layout stability
- The local version can still use richer emoji board symbols
- Some short gameplay feedback messages may still include decorative emoji
- The Heroku version prioritises clean alignment and reliable gameplay presentation
To run the game locally:
- Clone the repository.
- Open the project in your code editor.
- Create and activate a virtual environment if needed.
- Install dependencies from
requirements.txt. - Run the game file.
Example command:
python run.pyForking allows you to create your own copy of the repository.
- Log in to GitHub.
- Open the repository page.
- Click the Fork button in the top-right corner.
- GitHub will create a copy in your own account.
Cloning allows you to download the project to your local machine.
- Open the repository on GitHub.
- Click the Code button.
- Copy the repository URL.
- Open your terminal.
- Run the following command:
git clone https://github.com/boneyphilip/boney-battleship-cli-pp3.git- Move into the project directory:
cd boney-battleship-cli-pp3The core game idea is inspired by the classic Battleships naval strategy game.
The wording and project presentation were adapted into a mission-style terminal experience to make the interface feel more immersive and polished.
The project was influenced by:
- classic Battleships gameplay conventions
- terminal UI design patterns
- Python command-line project structure
- Code Institute Python Essentials template structure
General inspiration also came from building terminal applications that feel more structured and visually engaging than simple text output.
The README screenshots were created from the project itself during development and testing.
Stored screenshots include:
- mission setup screen
- mission briefing screen
- gameplay screen
- turn feedback screen
- mission accomplished screen
- mission failed screen
The screenshots were updated to reflect the current deployment-safe interface, including the ASCII-based Heroku presentation where relevant.
Thanks are due to:
- Code Institute for the project brief, deployment structure, and assessment framework
- the Python community for libraries such as
coloramaandwcwidth - everyone whose documentation and examples helped improve terminal rendering, alignment, and deployment understanding during development
This project was built not only to produce a working game, but also to create a terminal experience that feels readable, structured, and enjoyable for the user. Special attention was given to gameplay flow, UI stability, documentation quality, and deployment suitability.