Käsekästchen
Käsekästchen (German for: dots and boxes) is a web app that allows users to play the game of Käsekästchen online. The game is played on a grid of dots, where two players take turns drawing lines between the dots. The goal is to complete a square by drawing the fourth line around it. The player who completes the most squares wins the game.
Note: The Validation badges do not always load correctly. If the badge reads "inaccessible", please click on the badge to view the validation results.
UX
User Persona
The target audience for this web app is anyone who wants to play a fun and easy to learn game online. It's possible to play the game for 5 Minutes but if someone wants to play for longer, they can adjust the size of the grid to make the game more complex. The game is single player, so no second player is required. The game is also playable on mobile devices, so it can be played on the go (although a grid larger than 4x4 is not recommended on mobile devices).
Colour Scheme
This web app is displayed in a dark theme. The colour scheme adheres to the Material Design 2 Dark Theme guidelines. This provides a familiar experience for users who are used to the dark theme on their devices. The dark theme also reduces eye strain which enables users to play the game for longer periods of time. The colours used are:
#121212used for dark background#1E1E1Eused for card background#03DAC6used for primary highlights#FFFFFFused for primary text#A5A5A5used for secondary text#BAFC86used for player colour#BB86FCused for AI colour
The player colour is a green colour, while the AI colour is a purple colour. These colours are used throughout the website to differentiate between the two players.
I've used CSS :root variables to easily update the global colour scheme by changing only one value, instead of everywhere in the CSS file:
:root {
/* p = Primary / s = Secondary */
--dark-backgorund: #121212;
--card-background: #1E1E1E;
--p-highlight: #03DAC5;
--p-highlight-transparent: rgba(3, 218, 197, 0.8);
--p-text: #FFFFFF;
--s-text: #A5A5A5;
--player-color: #BAfC86;
--ai-color: #BB86FC;
}The --p-highlight-transparent variable is used for the hover effect on buttons.
I used the coolors.co tool to visualize the colour scheme:
Layout
The layout of the website also adheres losely to the Material Design 2 Dark Theme guidelines. The Layout is based on cards. The cards are used to group related content together.
Information Architecture
The cards are also used to create a visual hierarchy.
- The topmost card is the welcome message, which is the first thing the user sees when they visit the website.
- The biggest card is the gameboard, making it the main focus of the website.
- The card on the top left is the score card, which is the second most important card.
- The options card is the third most important card and always appears below or after the score card.
- The instructions card is only visible upon scrolling down or clicking on the "How to Play" button in the header or in the welcome message.
Typography
- Nunito was used for all text on the website. This font was chosen because of its playful roundness, which fits the theme and style of the game.
- Font Awesome icons were used for the icons in the footer.
User Stories
| As a | I would like to | so that I can |
|---|---|---|
| User | play a fun game | spend some time |
| User | play the game on different devices | play on my preferred device |
| User | select the size of the grid | customize the game to my liking |
| User | see the scores of both players | know who is winning |
| User | change my player name | personalize my game experience |
| User | choose who goes first in the game | strategize my game play |
| User | select the AI difficulty level | adjust the game to my skill level |
| User | adjust the size of the grid | control the complexity of the game |
| User | restart the game | play again |
| User | read the game instructions | understand how to play the game |
Note: User stories that aren't in the scope of this version can be found under Future Features.
Wireframes / Mockups
The wireframes were created using draw.io. The mockups were created using Figma. The mockups were created after the wireframes to visualize the design of the website. The mockups were used as a reference during development.
Some of the design was finalized while implementing it in code. The final design differs slightly from the mockups. The final design can be found in the Features section.
| Device | Wireframe | Figma Mockup |
|---|---|---|
| Mobile |  |
 |
| Tablet |  |
 |
| Desktop |  |
 |
Features
Existing Features
Logo and Heading
Featured at the top of the page, the Käsekästchen typography logo is easy to see for the user. Upon viewing the page, the user will be able to see the name of the game. The how to play button is displayed on the right side of the display. This button will scroll the user down to the instructions section.
Welcome Message
This section will allow the user to see a welcome message. The welcome message will give the user a brief introduction to the game and the website. The welcome message will also give the user a brief overview of the game instructions. This section was added after a user test revealed that the game instructions were not immediately visible to the user.
Gameboard
This section will allow the user to play the Käsekästchen game. The user will be able to easily see the grid of dots and draw lines between them by clicking on a disabled line. When a box is completed, the box will be automatically filled with the active players colour. Once all boxes are completed, the game will end and a message will be displayed to the user. A new game can then be started by clicking on the "Restart Game" button in the options area.
AI Opponent
The AI opponent is implemented in the game logic and will play against the user. The AI opponent will play a random move on the "Easy" difficulty level. The "Medium" difficulty follows an algorithm. Check it out in the code comments in the script.js file to find out more about the inner workings of the AI. The "Hard" difficulty is currently disabled and in development.
/**
* Determines which border to draw based on the number of drawn borders around adjacent cells.
* If a cell has 3 drawn borders, draws the 4th border.
* If a cell has 2 drawn borders, removes that border from the available borders Array.
* Draws a random border if no cell has 3 or 2 drawn borders around them.
* If there are only borders with 2 drawn borders around them, draws one of them (randomly).
*
* @param {Array} availableBorders - The available borders to choose from.
* @param {Array} grid - The gameboard grid of div elements.
*/
function mediumComputerTurn(availableBorders, grid) { ... }View the full function in the script.js file
Turn indicator slider
At the bottom of the gameboard, a slider indicates whose turn it is. The slider is coloured after the active player's colour. The slider will move to the left when it's the player's turn and to the right when it's the AI's turn.
Score Card
This section will allow the user to see exactly how many squares they have completed and how many squares their opponent has completed, indicating who is winning. The Score Card will also display the name of the player and the difficulty level of the AI. Lastly it indicates whose turn it is by colouring the background of the active player's name and score.
Options Area
This section allows the user to customize their game experience. The options available are:
- Player Name: The user can input their desired name.
- Turn Choice: The user can choose who goes first - the player or the AI.
- AI Difficulty: The user can select the difficulty level of the AI. The options are "Easy", "Medium", and "Hard". Note that the "Hard" option is currently disabled and in development.
- Grid Size: The user can adjust the size of the grid using a range input. The minimum size is 2x2 and the maximum size is 8x8. The default size is 3x3.
- Restart Game: The user can start a new game by clicking on the "Restart Game" button.
Name Input and restart confirmation
If the user starts a game a modal will appear asking if the user is sure they want to start a new game. Also, If the name the user has added is longer than 15 characters, a modal will appear, notifying the user that the name is too long. The user then has to click on the "OK" button to close the modal. The user can then change the name and start a new game.
Instructions
This section will allow the user to read the instructions on how to play the game. The user can click on the "How to Play" button in the header to scroll down to this section.
Footer
This section will allow the user to see copyright information. The footer also contains links to the developer's GitHub and LinkedIn profiles.
Background Blur Design elements
The background blur design elements are used to create a more interesting and playful design. The background blur elements are used behind the header and the footer. When the game is played, more backgorund blur elements are generated behind the gameboard. These elements are coloured to indicate who completed a box. The slider indicator also has a corresponding background blur element.
Responsiveness
The website is fully responsive on all devices. This is acheived using media queries and CSS Grid and Flexbox for most of the layout.
The gameboard is responsive using JavaScript. Each DOM element of the gameboard is individually created and resized depending on the size of the viewport. The gameboard is also responsive to the size of the grid. The grid size can be adjusted by the user in the options area. The gameboard will then be resized accordingly. Note that on mobile devices, a grid size larger than 4x4 is not recommended.
Future Features
Proposed Future User stories
| As a | I would like to | so that I can |
|---|---|---|
| User | select the number of players | play against my friends |
| User | see the leaderboard | see who is the best player |
| User | play against a harder AI | challenge myself |
| User | display the game in a light theme | play in a light theme |
Proposed Future Features
Multiplayer: Allow users to play against each other online.
Leaderboard: Implement a leaderboard that shows the top players.
Harder AI: Implement a harder AI that can play against the user.
Light Theme: Implement a light theme for users who prefer a light theme.
Tools & Technologies Used
- JavaScript used for the game logic and some of the responsive design
- HTML used for the main site content
- CSS used for the main site design and layout
- CSS Flexbox used for an enhanced responsive layout
- CSS Grid used for an enhanced responsive layout
- Git used for version control (
git add,git commit,git push) - GitHub used for secure online code storage
- GitHub Pages used for hosting the deployed front-end site
- Github Issues used for issue tracking
- GitHub Projects used for project management in conjunction with GitHub Issues
- Gitpod used as a cloud-based IDE for development
- Visual Studio Code used a local IDE for development
- Google Chrome used as a browser for development
- Google Chrome Developer Tools used for testing and debugging
- codepen.io used for the initial development of the game logic and proof of concept. See the pen that startet it all
- draw.io used for wireframe creation
- Figma used for design creation
- Windows Snipping Tool used to take screenshots and screencasts on Windows
- grid.layoutit.com used to create the gameboard grid
- Adobe free mp4 to gif converter used to convert screencasts to gif
- shields.io used to create the badges in the README.md file
- autoprefixer used to add vendor prefixes to css for browser compatibility
Special mention: Github Projects
Github Projects was an invaluable tool for project management. A screenshot of the project board can be found below:
Testing
Code Validation and Testing can be found in a separate file called TESTING.md
Deployment
The site was deployed to GitHub Pages. The steps to deploy are as follows:
- In the GitHub repository, navigate to the Settings tab
- From the source section drop-down menu, select the Main Branch, then click "Save".
- The page will be automatically refreshed with a detailed ribbon display to indicate the successful deployment.
The live link can be found here
Local Deployment
This project can be cloned or forked in order to make a local copy on your own system.
Cloning
You can clone the repository by following these steps:
- Go to the GitHub repository
- Locate the Code button above the list of files and click it
- Select if you prefer to clone using HTTPS, SSH, or GitHub CLI and click the copy button to copy the URL to your clipboard
- Open Git Bash or Terminal
- Change the current working directory to the one where you want the cloned directory
- In your IDE Terminal, type the following command to clone my repository:
git clone https://github.com/benschaf/kaesekaestchen.git
- Press Enter to create your local clone.
Alternatively, if using Gitpod, you can click below to create your own workspace using this repository.
Please note that in order to directly open the project in Gitpod, you need to have the browser extension installed. A tutorial on how to do that can be found here.
Forking
By forking the GitHub Repository, we make a copy of the original repository on our GitHub account to view and/or make changes without affecting the original owner's repository. You can fork this repository by using the following steps:
- Log in to GitHub and locate the GitHub Repository
- At the top of the Repository (not top of page) just above the "Settings" Button on the menu, locate the "Fork" Button.
- Once clicked, you should now have a copy of the original repository in your own GitHub account!
Credits
Content
To go to the source of the content, click on the link in the "Source" column. To go to the relevant code inside this project, click on the link in the "Location" column.
| Source | Location | Notes |
|---|---|---|
| Wikipedia | instructions card | used for game instructions |
| Wikipedia | computeLastTurn function | used for game logic |
| Favicon W3C | Favicon link | used for favicon syntax |
| CSS Blurred Background W3C | filter: blur(100px) and function createBackgroundBlurElement() | used for background blur syntax |
| CSS :root Selector W3C | ':root' selector | used for CSS root syntax |
| CSS Variables W3C | variables in ':root' selector | used for CSS variables syntax |
| developer.mozilla.org | box-sizing: border-box; | used for CSS box-sizing syntax |
| mozilladevelopers.github.io | game-area media query | used for CSS grid syntax |
| Medium Article by Martin Kearn | script.js | used for JSDoc syntax |
| Flexiple | Difficulty indicator | used for capitalizing the first letter of the difficulty string |
| W3Schools | all arrow functions | used for arrow function syntax |
| MDN Web Docs | JSDoc comments | used for understanding HTMLDivElement parameter and for using it in JSdoc comments in |
| W3Schools | setTimeout(); | used for setTimeout function to delay AI turns |
| Stack Overflow | @ return {two arguments} | used for understanding JSDoc return syntax when different types can be returned and for using it in JSDoc comments |
| Stack Overflow | let leftOverBorders = availableBorders.slice(); | used for understanding how to create an independent copy of an array |
| W3Schools | div.className = 'border'; | used for understanding how to set and address the class names of the divs in the gameboard grid |
| Medium Article by Steve Amaza | git version control | used for understanding how to write git commit messages with a body using the vim interface |
| W3Schools - CSS Animation | animations in script.js and style.css | understanding CSS animations |
| Stack Overflow | CSS Variables | used for understanding and removing the jigsaw warning "CSS variables are not statically checked" |
| [Stack Overflow](https://stackoverflow.com/questions/10261986/how-to-detect-string-which-contains-only-spaces#:~:text=trim().,string%20that%20contains%20only%20spaces.&text=You%20can%20read%20more%20about%20trim%20here.) | player name validation | used for understanding how to detect a string that contains only spaces |
| Tim Nelson | dynamic copyright notice | asked, to understand how to create a dynamic copyright notice |
| WebDevSimplified | dialog and modal boxes | used for understanding how to create a modal box |
| YouTube in dark mode | background blur elements | used for inspiration for the background blur elements |
Media
| Source | Location | filename | Notes |
|---|---|---|---|
| Fontawesome | Footer | various icons | icons used: fa-github, fa-linkedin |
| Material Design 2 | Colour Scheme and Design | N/A | used for design guidelines |
Acknowledgements
- I would like to thank my Code Institute mentor, Tim Nelson for his support throughout the development of this project.
- I would like to thank the Code Institute tutor team for their assistance with troubleshooting and debugging some project issues.
- I would like to thank the Code Institute Slack community for the moral support; it kept me going during periods of self doubt and imposter syndrome.
- Special thanks to Dajana Isbaner_5P_lead, who helped with user testing and provided valuable feedback.
- I would like to thank Hannes, who was the best test player and provided valuable feedback.
- I would like to thank my wife Maria, for believing in me, and allowing me to make this transition into software development.