21 The Card Game
Project Summary
This website aims to demonstrate my skills of Javascript, HTML & CSS as learned from the Code Institute Full Stack Software Development course. In order to do so I will create my version of the card game Twenty-One. The project will be created using a mobile first design strategy. The project will further the developers knowledge of Javascript and it's implementation.
Contents
- 21 The Card Game
- Project Summary
- Contents
- The origin of the card game Twenty-One
- User Experience (UX)
- Strategy
- Scope
- Structure
- Skeleton
- Surface
- Features
- Technologies Used
- Testing
- Implementation
- Deployment
- Credits
The origin of the card game Twenty-One
Twenty-One, formerly known as Vingt-Un in Britain, France and America, is the name given to a family of popular card games, the progenitor of which is recorded in Spain in the early 17th century. The game is first mentioned by name as early as 1611 in a Spanish dictionary where, under the entry for "card" (carta), it mentions the game of Ventiuno ("twenty-one")
Twenty-One rose to prominence in France in the 18th century and spread from there to Germany and Britain from whence it crossed to America. Known initially as Vingt-Un in all those countries, it developed into Pontoon in Britain after the First World War and Blackjack in Canada and the United States in the late 19th century, where the legalisation of gambling increased its popularity.
Information gathered from Wikipedia. Read More here
User Experience (UX)
Strategy
Developer Objectives
To grow my skills as a developer and create a simple easy to use and enjoyable interactive game. Develop the project from its initial concept to the final finished product. To utilise and expand my skills in Javascript, HTML & CSS.
Target Audience:
- General public.
- People looking for a fun distraction while taking a break from their day.
- Commuters who like to play games to pass the time on their journey.
User Stories
- As a user I want to be able to easily understand the rules of the game so I can get started quickly.
- As a user I want the game play to be intuitive so I don’t have to spend much time learning how to play.
- As a user I want a fun and interesting game so that I can enjoy playing it when I have some free time.
- As a user I want to know if I win, lose or draw a game so that I can keep playing and improve.
- As a user I want to know how many games I win/lose/draw so that I can track how well I’m doing.
- As a user I want to be able to reset a game so that I can start again.
- As a user I want to have a visually appealing interface so that I will enjoy playing the game for longer.
- As a user I want a game I can play on my mobile so that I can play while on the go.
Site Owner Stories
- As a site owner I want to present my work in a professional, creative and visually appealing way.
- As a site owner I want to provide a good user experience for my users, so that they want to come back.
- As a site owner I want to present a game users can start playing quickly and intuitively so that they don’t have to make a big time commitment in learning how to play.
- As a site owner I want to provide feedback to my users on how they are doing.
- As a site owner I want to give users options so they can style the game to their liking.
Scope
This will be a Minimal Viable Product containing the most important core content required.
Functional Specifications:
- Rules
- Game statistics
- Reset
- Start game
- Settings
- Win/Lose/Draw game outcomes
- Background music and sound effects
Content Requirements:
- Logo.
- Brief description of how to play.
- Option to change theme.
- Reset button.
- Game stats for tracking win/lose/draw.
- Dealer heading
- Display dealer hand.
- Display card total for dealer.
- Player heading.
- Display player hand.
- Display card total for player.
- Display game outcomes – win/lose/draw.
- Game play buttons.
Strategy/Scope Trade Off
Providing background music and sound effects for the game was not deemed to be of high importance at this time. There is a thin line between irritating the user and enhancing the user experience using music and so will not be included in the initial release of the website.
Structure
Interaction Design:
User interactions will be intuitive and allow for easy game play.
The game play centres around 3 clearly labelled buttons at the bottom of the screen for easy access when playing. One button to start the game, one button to request another card i.e. hit and one button when the player is happy with their hand and wants to hold. These buttons have been given a box-shadow effect and a bold font has also been applied to elevate them in the visual hierarchy.
Information Design:
Will allow for the prioritisation of the information to be displayed in a clear and concise manner to make it as easy as possible for the user to read and to quickly find the information that is most relevant to their needs.
The 4 game options buttons are displayed above the game play area. These allow the user to change the theme, read the rules, check their game stats using modals The fourth button allows users to reset a game.
Modal pop ups used to deliver information about the game outcome and inform the player if they win, lose or draw.
Skeleton
Wireframes:
Difference between final design and original wireframes:
Logo:
In the original wireframes the logo/heading was 21 Card Game this was changed to be 21 The Card Game for better readability.
Player Heading & Score:
The player heading and score has moved to above the player hand as it gives better structure to the game play area and maintains the same hierarchy as the dealer heading/hand layout.
Win/Lose/Draw Modals:
The win, lose and draw modals have been expanded to now include more options to give the player more feedback as to how they won or lost the game. Rather than the 3 modals outlined in the wireframes we now have a modal for each of the following game outcomes:
- Player wins by getting 21
- Dealer gets 21, player loses
- Player wins
- Dealer wins, player loses
- Player went bust, dealer wins
- Dealer went bust, player wins
- A draw
Deal Button:
The deal button in the original wireframes has been renamed to start, this gives the user a clearer understanding of the intent of the button.
Game Board Area Border:
A border was added to the game board area to define the space where the game play takes place.
Game Stats:
No of wins by getting 21 was added to the game stats window as a way of tracking how many times a user gets the coveted 21 score from their hand.
Surface
Typography:
Montserrat Subrayada font is used for the main logo as it’s unique underlined style lends well to being used as a heading/logo which provides immediate impact.
Lora is an well-balanced contemporary serif with roots in calligraphy which offers a great contrast to the graphic heading of Montserrat Subrayada and allows for easy reading of the text content of the Website.
Colour scheme:
Classic Theme:
The classic green colour scheme is a nod to the green felt used in casino tables where the game would often be played. The colours #c9de9 & #398235 are used to create a light to dark gradient from top to bottom to soften the scheme and provide visual interest rather than using one solid colour.
The font colour used is #120202 which was checked for contrast against the background colours using the Webaim contrast checker. This same colour is also used for the border around the game board area.
Beach Theme:
The beach theme uses a beach image as the background. The change of colours from the sea to the sand in the image also echoes the gradient effect of the classic theme. The beach image is given a slight blur effect to ensure the game contents, cards, score etc are still the main focus while providing a tranquil background. All other colours are the same as for the classic theme.
Night Theme:
The night theme uses an image of the night sky as its background. This particular image was chosen as it also echoes the gradient effect first created in the classic theme, with the changing colour of the night sky from top to bottom. This may be a more suitable background for those that prefer a dark background or like to play at night.
The font colour was changed to #D6D6D6 and was chosen to give sufficient contrast with the backdrop without being too bright. The border colour of the game board area is also set to this colour.
Accent Colours & Modal Windows
The accent colour #E27D60 is used for all the buttons and the headings in the modal pop ups. This colour was chosen as it works well in contrast to the backgrounds of the three different themes.
Modals were created with a dark background of rgba(06, 09, 06, 0.761) which includes a slight transparency to still feel connected to the game/background behind.
The font colour used in the modals with text content is #FAFAD2, this is also the colour of the play again button in the game outcome modals.
Cards
Card background: #FEF3EC The white of the cards was chosen as the best contrast to the backgrounds used while also not being too contrasting.
Red cards: #CE070E
Black cards: #120202
Card border: #3D0D0D
Features
-
Responsive.
-
Game Statistics button for user to check how many games they’ve won/lost.
-
Reset button so the user can reset a game at any stage, this opens an alert pop up to ask the user if they are sure they want to quit the current game and start again.
-
Rules button to display the rules of the game.
-
Settings button for the user to be able to choose between 3 different backgrounds for the game – Classic, Beach, Night.
-
Game board area where the game play happens.
-
Dealer heading for the dealer area.
-
Dealer card value total display.
-
Dealer area where the dealers cards are displayed.
-
Player heading for the player area.
-
Player card total to display the total of the players cards.
-
Player area where the players cards are displayed.
-
Start button to start the game.
-
Hit button for the user to draw another card.
-
Hold button for the user when they are satisfied with their current hand.
-
Game outcome modals. Modal windows are opened for each of the different game outcomes to tell the user how they did in the game.
-
Collapse cards down when 4 cards or more in a hand.
-
Game play buttons at the bottom of the screen have been given a shadow effect to make them stand out as they are the buttons most used while playing the game.
-
Highlight buttons on hover.
Future Features
- Difficulty level added where the second dealer card is not revealed until after the player decides to hold.
- Implement a betting system.
- Add background music and sound effects.
Technologies Used
Html - Hyper Text Markup Language, used for creating the website.
Css - Cascading Style Sheet, used for styling the website.
Javascript – Used for providing functionality to the game play and it’s interactive features
Bootstrap - Bootstrap grid system.
Google Fonts - The 2 fonts used throughout the website are from Google fonts.
Balsamiq – Used for creating the wireframes.
Git - Used for version control.
GitHub - Used to store the project repository.
Gitpod IDE - Development environment where the site was built.
GitHub Pages - Where the live site is deployed/hosted.
Gimp 2.1 - Used for editing, scaling images and creating a favicon.
Tiny png - Used for compressing images.
Webaim contrast checker - Used to check the contrast between the text font and background colours.
Chrome Dev Tools - Used throughout the development of the website to quickly see changes, find problems and debug. Also used to view website in different device views.
Lighthouse in Chrome Dev Tools.
AutoPrefixer - Used to add vendor prefixes onto the CSS code to ensure compatibility with various browsers.
W3C HTML validator - Used to validate code.
W3C CSS validator - Used to validate code.
JSHint – Used to validate Javascript code
Coolors - Used for selecting complimentary colour palettes.
Unsplash – Used for finding background images.
GitHub Wiki TOC generator - Used for creating a table of contents in README.md
Testing
Code Validators & Auto Prefixer:
CSS code was passed through Auto Prefixer to add vendor prefixes:
- Prefixed by https://autoprefixer.github.io
- PostCSS: v7.0.29,
- Autoprefixer: v9.7.6
- Browsers: last 4 version
CSS code was passed through the W3C CSS Validator:
No errors found and 17 warnings, 16 relating to vendor prefixes and the other 1 warning was: Imported style sheets are not checked in direct input and file upload modes once investigated on Stack Overflow and Slack decided it is ok to leave these.
HTML code was passed through the W3C Markup Validator.
No errors found.
Javascript code was passed through jshint.
Found 11 unused variables, however these are all triggered from index.html using the onclick attribute.
Lighthouse from Chrome Dev Tools Testing:
Desktop report:
Mobile Report:
Buttons Testing:
Each button was tested and passed under the criteria set out below.
Game Options Buttons:
Settings button
- Highlights on hover.
- Opens settings modal window when clicked.
- Shows theme selection menu when opened.
- Theme selection – backdrop changes when click each radio button.
Checked all changes:
- from classic to night
- from classic to beach
- from beach to classic
- from beach to night
- from night to classic
- from night to beach
- X to close modal closes the modal window when clicked.
- Clicking outside the modal window closes the modal window.
Rules button
- Highlights on hover.
- Opens rules modal window when clicked.
- Window opens with vertical scroll bar if the content is taller than the screen size available.
- Shows how to play when opened.
- X to close modal closes the modal window when clicked.
- Clicking outside the modal window closes the modal window.
Stats button
- Highlights on hover.
- Opens stats modal window when clicked.
- Shows game stats when opened.
- X to close modal closes the modal window when clicked.
- Clicking outside the modal window closes the modal window.
Reset button
- Highlights on hover.
- Opens reset alert pop up when clicked.
Reset Alert
- Opens when reset button clicked.
- No button :
- Highlights on hover.
- Closes the alert window and returns to the game.
- Yes button:
- Highlights on hover.
- Clears the game board and resets the game.
- Closes the alert window.
Game Play Buttons:
- Hit & Hold buttons are disabled on page load
Start button
- Highlights on hover.
- Creates and shuffles a new deck each time.
- Deals 2 cards to each player.
- Enables hit and hold buttons.
- Disables itself when clicked.
- Adds card hand total for each player.
- Checks if either hand is over 21 and if so ends the game and declares a winner.
- Checks if either hand is 21 and ends game.
Hit button
- Disabled on page load.
- Highlights on hover.
- Adds another card to the player hand.
- Updates card hand total for the player hand.
- Checks score - If card hand is 21 ends game declaring the player as the winner.
- Checks score - If card hand over 21 ends game declaring the dealer as the winner.
- If player hand has 4 cards it collapses the cards down.
Hold button
- Highlights on hover.
- Disables hit button so player cannot draw another card once they have decided to hold.
- Disables hold button so no further action can be taken.
- If dealer score is 16 or less it adds another card to the dealer hand.
- Updates card hand total for the dealer hand.
- Checks score - If card hand over 21 ends game declaring the player as the winner.
- Checks score - If card hand is 21 ends game declaring the dealer as the winner.
- If dealer score still 16 or less it will continue to add another card and check score until the dealer hand is over 16 and will declare a winner:
- If dealer card total is over 21, the game ends and the player is declared the winner.
- If dealer card total is 21, the game ends and the dealer is declared the winner.
- If dealer card total is over 16 and less than 21 and greater than the player card total the game ends and the dealer is declared the winner.
- If dealer card total is over 16 and less than 21 and less than the player card total the game ends and the player is declared the winner.
- If dealer hand has 4 cards it collapses the cards down.
Play Again Button (found in the game outcome modal window)
- Resets the game.
- Closes the game outcome window.
- Clicking outside the modal window closes the modal window and resets the game.
Game Outcome Testing:
Each time a game ends a game outcome is communicated to the user via a modal window. These game outcomes were tested numerous times to ensure the correct game outcome is displayed each time. There are a total of 7 possible game out comes:
- Player gets 21 and wins.
- Dealer gets 21 and wins.
- Player goes over 21 (bust) and loses.
- Dealer goes bust and player wins.
- Player beats dealer score without going over 21 and wins.
- Dealer beats player score without going over 21 and player loses.
- Player score and dealer score are equal – it’s a draw.
Responsiveness Testing:
The responsiveness of the website was tested using Chrome Dev Tools and setting it to display on various mobile/tablet devices that are included. Responsiveness is optimised for screen sizes from 320px and in portrait orientation for smaller devices.
Device testing:
All aspects of the website mentioned above were manually tested on the following devices: iPad 2, iPhone 8, MacBook Pro.
Browser Testing:
All aspects of the website mentioned above were manually tested on the following browsers: Chrome, Safari, Mozilla Firefox
Friends & Family User Testing:
The general feedback was that the site looks well and is easy to navigate. Gameplay is fun and intuitive without much of a learning curve.
The only slight negative feedback was that the pop up window at the end of the game covered the last cards being dealt. To rectify this I delayed the gameOutcome pop up using a setTimeout so now you can see the final card hands before the pop up opens telling you the result.
Devices used: iPad Pro, iPhone 8 Plus, Laptop (windows running the Chrome browser).
Testing User Stories
-
As a user I want to be able to easily understand the rules of the game so I can get started quickly.
-
Rules are easily found by clicking on the rules button near the top of the screen.
-
For anyone who already knows the rules the game play is designed to be intuitive.
-
The game play buttons provided are clearly labelled and should be easily recognisable for anyone who is already familiar with the game.
-
Start button is provided and clearly labelled, so the user can get started quickly.
-
Hit & Hold buttons are disabled on page load so that the user cannot start playing without first clicking on the start button.
-
-
As a user I want the game play to be intuitive so I don’t have to spend much time learning how to play.
-
The game layout is designed to be easy to read and understand without being cluttered.
-
Three clearly labelled game play buttons are provided.
-
When page loads the start button is the only one of the game play buttons that is enabled giving the user a clear indication as to how to start playing.
-
Once the start button is clicked it is disabled while the hit and hold buttons are then enabled, this helps guide the user to understand how the game should be played.
-
-
As a user I want a fun and interesting game so that I can enjoy playing it when I have some free time.
-
The game gives the user a fun and simple way to pass the time.
-
The game lets the user start the game play and is interactive to keep the user interested.
-
The user gets to decide what moves to make in the game eg. Whether to draw another card or hold with the hand they have in order to beat the dealer.
-
The game keeps the user guessing as it’s hard to predict the outcome and so makes for a more entertaining gaming experience.
-
-
As a user I want to know if I win, lose or draw a game so that I can keep playing and improve.
-
The total of each of the players card hands is clearly displayed so that the user can make an informed decision about their next move.
-
A variety of different game outcomes are possible.
-
Game outcomes are clearly communicated to the user through a pop up that appears at the end of each game telling the user how they did. The pop ups inform the user:
- If they won by getting a score of 21.
- If they won by beating the dealer score.
- If they went bust ie scored over 21 therefore losing the game.
- If the dealer went bust and therefore they win.
- If the dealer gets 21 and therefore they lose.
- If the dealer wins by beating their score.
- If the game is a draw.
-
Each pop up also gives the user the option to play again so that they can continue playing.
-
-
As a user I want to know how many games I win/lose/draw so that I can see how well I’m doing.
-
Each time a game ends the result is logged in the game statistics. These stats can be checked by the user by clicking the Stats button above the gaming area, this will open the stats window.
-
The stats window shows the user the number of games they have:
- Won by getting 21
- Won
- Lost
- Drawn
-
-
As a user I want to be able to reset a game so that I can start again.
-
A reset button is provided above the game play area.
-
The reset button opens an alert to ensure that the user wants to quit the current game and start again:
- By clicking yes in the alert window the user starts a new game.
- By clicking no in the alert window the user returns to the current game.
-
-
As a user I want to have a visually appealing interface so that I will enjoy playing the game for longer.
-
The design of the site is kept simple to avoid unnecessary clutter from confusing the user.
-
It consists of a title, a row of 4 game options buttons, the game board area and a row of 3 game play buttons, clearly laid out with space around each of the elements.
-
The user can choose between 3 different backgrounds via the settings button. Each of which provide a different aesthetic to cater to different user needs.
-
The default classic theme provides a clean green background with a gradient fading between a lighter and darker green, providing a more visually appealing background than if it was a single solid colour.
-
The Beach theme provides a relaxing atmosphere with an image of the sea and sand which may appeal more to some users.
-
The night theme also provides an interesting and relaxing image of the sky at night, which may suit those who prefer to play in the evenings.
-
-
As a user I want a game I can use on my mobile so that I can play while on the go.
-
A mobile first design approach was used in order to ensure an excellent user experience for mobile users.
-
Game play buttons are ideally located near the bottom of the screen for mobile users.
-
Testing Site Owner Stories
-
As a site owner I want to present my work in a professional, creative and visually appealing way.
-
Professional look and a friendly feel to the website.
-
Visually appealing throughout.
-
Intuitive and easy to navigate around the site and game play.
-
-
As a site owner I want to provide a good user experience for my users, so that they want to come back.
-
Provide simple but fun interactive game play.
-
Future releases to add more features to keep users interested and offer something new to returning users.
-
-
As a site owner I want to present a game users can start playing quickly and intuitively so that they don’t have to make a big time commitment in learning how to play.
-
Simple and easy to use layout that is easy to learn on first visit to the site.
-
Rules are easily accessed by the rules button near the top of the screen. The rules are written in a concise manor to convey the basic game play to the user without being verbose.
-
The game play is intuitive.
-
Three clearly labelled game play buttons are provided.
-
When the page loads the start button is the only one of the game play buttons that is enabled giving the user a clear indication as to how to start playing.
-
Once the start button is clicked it is disabled while the hit and hold buttons are then enabled, this helps guide the user to understand how the game should be played.
-
-
As a site owner I want to provide feedback to my users on how they are doing.
-
The total of the dealers & players card hand is clearly displayed so that the user can make an informed decision about their next move.
-
Game outcomes are clearly communicated to the user through a pop up that appears at the end of each game telling the user how they did.
-
Each time a game ends the result is logged in the game statistics. These stats can be checked by the user by clicking the Stats button above the gaming area, this will open the stats window.
-
The stats window shows the user the number of games they have:
- Won by getting 21
- Won
- Lost
- Drawn
-
-
As a site owner I want to give users options so they can style the game to their liking.
-
The user can choose between 3 different backgrounds via the settings button. Each of which provide a different aesthetic to cater to different user needs.
-
The default classic theme provides a clean green background with a gradient fading between a lighter and darker green, providing a more visually appealing background than if it was a single solid colour.
-
The Beach theme provides a relaxing atmosphere with an image of the sea and sand which may appeal more to some users.
-
The night theme also provides an interesting and relaxing image of the sky at night, which may suit those who prefer to play in the evenings.
-
Implementation
Once the initial concept for the project was decided upon I first developed the wireframes. From these wireframes I then developed the basic game logic required to run the game. This is documented in the Game Logic Map
Initially I set up a basic html layout, from which I could start coding the JavaScript required to get the basic game play working before adding any styling. I set up a message-status element on the html page to display the game outcomes so I could see how they were working before creating the game outcome modal windows to ensure the correct game outcomes were being displayed.
Throughout the project I used Chrome Dev Tools to monitor what was happening in the code. I used console.log() to check what functions and variables were doing. I also used the watch window so that I could monitor what was happening as I tested the game play. I used the debugger to set breakpoints to investigate and resolve any issues I was having.
Once I was happy that the game was working in its most basic form I began adding some style and rendering the cards in the html. I could then add additional functionality to the game e.g. .game stats and update the styling as needed.
Issues/Solutions
While trying to implement the counter variables to track the number of games won/lost/drawn I discovered that certain game outcomes were being counted twice. In order to investigate this further I set up some debuggers in the script and started stepping through the code in Chrome Dev Tools, while having the counter variables in the watch window I was able to figure out under what circumstances game outcomes were being counted twice and narrowed it down to the checkScore and gameOutcome functions being executed twice in the hold function due to the setTimeout which was running the whole function again if the dealer hand total was 16 or less. In order to resolve this I added the setTimeout into its own if statement nested into the original if statement of the function.
Known Bugs
Bugs found and not fixed:
-
When first switching themes to either beach-theme or night-theme, the whole page reloads and can see the background colour while the image loads. A suitable background colour has been used for this reason and as a failsafe in case the image doesn’t load.
-
Difference between Chrome Dev Tools device display and actual display for iPhone 8. Also happens for some desktop views after posting the project on peer code review a couple of people came back to say the bottom buttons were cut off on their laptops - when checked their screen resolutions on Chrome dev tools it looked fine, I have set overflow-y to scroll in media queries from medium screen sizes to avoid losing content completely. This should be investigated further.
Deployment
This website was created in the Gitpod development environment. After installing the Gitpod extension for Chrome web browser and creating a new repository in GitHub using the Code Institute template, the green Gitpod button was used to initialise the repository in Gitpod. Throughout the process the git commands git add
and git commit
were used to store the work in the local Gitpod environment, git push
would then be used to push the commits to the GitHub repository. From here the website could then deployed to Git Pages:
Git Hub Pages:
From the Git Hub repository:
- Go to settings
- Scroll down to Git Hub Pages section
- Select branch to be deployed, in this case the master branch
- Click Save
Creating A Local Clone:
You can clone the repository to create a local copy on your computer.
From the Git Hub repository:
- Click
Code
at the top of the file list - Click the clipboard icon to copy the url provided
Open terminal:
- Change the current working directory to where you want the cloned directory to be
- Type
git clone
and paste the copied url after it - Press enter and the clone will be created
Credits
Code
Code Snippet 1: Devdojo - Creating a card object. Used with modifications.
Code Snippet 2: Devdojo - Creating a deck object. Used with modifications.
Code Snippet 3: Yanze Dai - The optimal solution to shuffle an Array in Javascript - Implementation of Fisher Yates Shuffle.
Code Snippet 4: echohatch1 - BlackJack Project - code originally based on ecohatch1's getCardsValue() but then modified to suit this project.
Code Snippet 5: echohatch1 - BlackJack Project - code originally based on ecohatch1's endGame() but then modified to suit this project.
Resources
Code Institute course material and mini projects form the main resource for this project.
Bootstrap Documentation - General resource.
W3Schools - General resource.
MDN web docs - General resource.
CSS Tricks - General resource.
Debugging JavaScript - General Resource
That Software Dude - How To Code Blackjack Using JavaScript - Inspiration for building the card game.
echohatch1 - BlackJack Project - Further inspiration for building the card game.
Mike Bostock - Fisher Yates shuffle
Inside code - Good explanation video and visualisation of the Fisher Yates Shuffle Algorithm
Anna Greaves How to Approach Writing Your README File webinar.
Content
All text content of the website is written by myself.
The origin of the card game Twenty-One section of README.md is extracted from Wikipedia
Media
Beach Image credit: Photo by Fezbot2000 on Unsplash
Night Sky Image credit: Photo by Wil Stewart on Unsplash
Acknowledgements
My mentor @spence_mentor for great support and positivity throughout.
All at Code Institute and Tutor support.
The Slack Community for their ever present knowledge.
Disclaimer
This project is for educational purposes only.