Battleship game in README.md

4 min read • November 7, 2022

Some time ago, while I was browsing for GitHub profile customization ideas, I stumbled across the profile of @JonathanGin52, who has an interactive Connect 4 Game in GitHub README.md. I liked the idea and wanted to make something similar.

First, check out the short video below to see it in action, or play it on my profile!

Everything works by using a few components

GitHub Actions - to run the code when someone interacts with README.md
Python script - to take care of game logic and updating README with new values
Database (MongoDB) - to store all the data (statistics, coordinates of ships, etc.)
README.md file - game’s “GUI”

Board representation

To represent the board, I created this bitboard to represent each table cell by a different number. When someone makes a move, I can easily find its location. It’s also easy to generate ships with this method. I can choose one random number and then go horizontally or vertically to get the rest of the ship.

+---------------------------------------+
| 0  | 1  | 2  | 3  | 4  | 5  | 6  | 7  |  8
| 9  | 10 | 11 | 12 | 13 | 14 | 15 | 16 |  17
| 18 | 19 | 20 | 21 | 22 | 23 | 24 | 25 |  26
| 27 | 28 | 29 | 30 | 31 | 32 | 33 | 34 |  35
| 36 | 37 | 38 | 39 | 40 | 41 | 42 | 43 |  44
| 45 | 46 | 47 | 48 | 49 | 50 | 51 | 52 |  53
| 54 | 55 | 56 | 57 | 58 | 59 | 60 | 61 |  62
| 63 | 64 | 65 | 66 | 67 | 68 | 69 | 70 |  71
+---------------------------------------+

Info
Note the extra numbers on the right. All of these numbers are treated as invalid. This way Python script knows when the row ends and next one starts to avoid splitting the ship during generation.

GitHub Actions

Whenever an issue with the prefix battleship|action|location is opened, it triggers the GitHub Actions workflow. The title of the issue and the user’s username are passed as environment variables to a Python script, which then splits the issue title every | and decides if it should create a new game or make a move based on action.

Creating a new game

When a new game has to be created, we need to make a blank board with ships placed randomly. To achieve it, we call the create_game() function that calls the place_ships() function, which generates a ship by choosing one random place on board and then generating the rest of it horizontally or vertically (example below).

+-------------------------------+
|   |   |   |   |   | - |   |   |
|   |   |   |   |   | - |   |   |
|   |   |   |   |   | - |   |   |
| - | - | - | - | - | • | - | - |
|   |   |   |   |   | - |   |   |
|   |   |   |   |   | - |   |   |
|   |   |   |   |   | - |   |   |
+-------------------------------+

Database

Now we have to store ships’ location somewhere. I used MongoDB as the NoSQL structure works great for this project.

Modifying the README

Time to change our board visually by updating the README file. We can do it using the same method we would use to modify a text file. First, we read the file line by line and save content to a variable. We can then modify the specific lines we want. To create an empty table cell, I used a blank image with a link by using this format: [![](image link)](link that creates issue).

Committing, pushing, and closing the issue

The last step is to commit and push everything to GitHub. We can do it with GitHub Actions using git commands. Then to keep everything clean, we can close the opened issue using GitHub CLI command: gh issue close.

Playing the game

The process is the same as creating a new game. Instead, we have to check if the location shot has the ship or not by using our database and modifying this location in README with either a white or red mark image.

Statistics

The statistics under the game title were made with shields.io.
A leaderboard is made by storing all users with their statistics and sorting the database and getting top 5 players.