MindGym

MindGym is a browser-based classic Memory game.

UX

User stories

The game is intended primarily for younger users (children) who enjoy playing Memory. However, the Experienced and Hero difficulty levels may also appeal to older users who like a casual game which also trains their memory.

The following user stories have been identified:

1. As a user, I want the home screen to be visually appealing, making me want to try the game.
2. As a user, I want to be able to start a game easily.
3. As a user, I want to be able to choose a difficulty level.
4. As a user, I want to be provided with instructions on how to play the game.
5. As a user, I want to be provided with in-game feedback on my progress.
6. As a user, I want to be able to restart the game without going back to the home page.
7. As a user, I want to have a scoreboard to track my progress compared to previous attempts.

UI structure

Taking into consideration the above user stories, the following basic UI structure has been established:

• Home page with a large cartoon-style "hero image", a large Play button and a small adjacent Info icon to open Instructions (in modal format);
• Level selection page with on-hover flip cards for difficulty level selection, each card providing information (on its flip side) about the respective level's features;
• Gameplay page, displaying the game tile set and in-game messages, and containing a Restart button.

A top-fixed navigation bar in the header contains the MindGym favicon and navigation links to Home, Level selection and Instructions.

The footer contains copyright information only.

The colour palette has been selected to be cartoon-like and vivid but not overwhelming.

Three wireframes were created (using wireframe.cc) during the initial UI design phase:

Home page
Level selection
Gameplay

Two details are different in the final game design compared to the wireframes:

• the Instructions button was replaced by a small Info ("?") icon to avoid having the word "instructions" repeated twice on the same page;
• the "Time elapsed" feature was not implemented in this version due to eventual time constraints (no pun intended!); as a result, User story #7 will need to be fulfilled in a future version.

Features

Existing Features

Navigation bar

The top-fixed navigation bar provides the user with links to navigate to Home (via favicon or Home link) and Level selection (via Game link) and to view Instructions. The Instructions are always displayed as a modal, thus it is possible to view them from any page, including during a game itself, via the Instructions link in the Navbar.

Note: The Gameplay page cannot be accessed directly from the Navbar but only via the Level selection page. This is a defensive programming feature to make sure that the game is always started with the intended difficulty level.

Home page

The large "Play!" button in the centre of the Home page picture enables the user to go to Level selection to start a game immediately. The small Info icon ("?") beside the Play button opens the Instructions modal.

Level selection page

The level selection "buttons" are implemented as on-hover flip cards. The front side of each card displays an image symbolic of the respective level, while the flip side displays the level's name and settings (a sample tile and number of tile pairs):

• Rookie, with 8 tile pairs containing different alphabet letters (A-H);
• Experienced, with 12 tile pairs containing different colours;
• Hero, with 18 tile pairs containing different (simplified) playing cards.

Clicking on a flipped card will select the chosen difficulty level and start the game with it.

Gameplay page

The central area of the page is occupied by the game tiles.
Below the "play area" is a Restart button which, if clicked during a game, will restart the game with the same difficulty level (but with rearranged tiles).
Once a game is completed (board clear), the Restart button changes to a "Play again?" button which, if clicked, will navigate the user to Level selection.
A message area, displaying in-game messages, is implemented dynamically:

• at screen widths below 1700px, the message area is above the tile area and displays text only;
• at large desktop widths of 1700px or above, the message area is positioned to the left of the tile area and features an "avatar" (the same cartoon character from the Home page image) and the message appearing in a comics-style "message bubble".

Features Left to Implement

• Add the "Elapsed time" feature (User story #7) and modify the corresponding Game completion message to indicate the time of game completion; possibly add a Pause button;
• Add a "Best times" page, where after a game the user could enter their name and their accomplishment would be displayed in a table sorted by difficulty levels and best times of previous plays;
• Add a flip animation to game tiles (corresponding to the one on Level selection);
• Add sounds (tile flip, matching tiles, non-matching tiles, game completed...).

Technologies Used

The languages, frameworks, libraries, and other tools used during this project:

• HTML5 for page structure and content;

• CSS3 for content styling;

• JavaScript (ES6 to the best of my ability) for game logic/processing and DOM manipulation;

• jQuery was used to facilitate DOM manipulation;

• Bootstrap was used for navigation bar and modal implementation and some additional styling (buttons);

  Note: Bootstrap was not used for responsive design as the nature of the game (individual tiles) required additional customisation. CSS Flexbox and media queries were used instead.

• Fonts were obtained from Google Fonts;

• Icons were obtained from Font Awesome;

• Beginner and Expert tile images were created in Microsoft Word;

• Favicon.io was used for favicon creation;

• W3C Markup Validation Service was used to validate HTML and CSS code;

• JSHint was used to validate JavaScript code;

• Jasmine with jasmine-jquery was used for automated JavaScript testing;

• W3schools.com Color Converter was used to convert colours between default, HEX and RGB for CSS coding purposes;

• Autoprefixer CSS online was used for correct vendor prefixing of CSS styles where required;

• Convertio was used for image conversion from EPS (from Shutterstock) to JPEG;

• Compress JPEG and Compress PNG for image file size reduction;

• Google Chrome Developer Tools were used for console development and testing, debugging and as a styling aid;

• Gitpod was used as the IDE for development and Git version control;

• GitHub was used for source code storage and site deployment (GitHub Pages).

Testing

The test procedure and results are detailed in a separate document.

Testing summary:

1. All HTML, CSS and JavaScript code has been validated successfully.

2. All automated (Jasmine) tests have been passed successfully.

3. All relevant User stories (excluding #7, see clarification under UI structure) have been fulfilled.

4. During structural integrity testing, one issue was raised:
   Issue #1: On Gameplay page, the navbar Home link is wrongly indicated (colour-coded) as active/current.
   Issue #1_ has been identified, analysed, fixed and verified, and is considered closed. No further issues were identified.
   Therefore all structural integrity tests are considered as passed successfully.

5. All Gameplay tests have been passed successfully. No issue has been identified.

6. All Interactive Components tests have been passed successfully. No issue has been identified.

7. All Responsive Design tests have been performed successfully. The following observation has been raised:

   Observation #1:
   On test device LG Wine Smart (LG H410) Android smartphone, with extra small screen (480x320px):
   - on Home page, scrolling is required to reach the Play button; also, the Play button is (too) far from the main picture compared to the footer;
   - on Gameplay page, at Hero level settings, some scrolling is required to reach the last three rows of tiles.
   Considering that screens of this small size are infrequent, the above observation is not treated as an issue at this point.

Testing conclusion:
All relevant tests have been passed successfully and relevant issues fixed. The application is ready for official deployment.

Deployment

The deployment version of the source code is stored on GitHub, in the master branch of bravoalpha79/MindGym.

From the master branch, the site has been published using GitHub Pages using the following procedure:

1. On the bravoalpha79/MindGym repository page, make sure that the "master" branch is selected.
2. Click on the Settings tab.
3. In the GitHub Pages frame, from the Source dropdown menu, choose "master branch".
4. Scroll back down to the GitHub Pages frame, where the address of the newly-published site is now displayed.

The deployed site code is identical to the code stored on the master branch on GitHub.

The live version of the site is located at:
https://bravoalpha79.github.io/MindGym/

Credits

Code

HTML and CSS

• The "perfect background image" CSS code snippet (used for styling of background images on all pages) was obtained from CSS-tricks.
• The "message bubble" CSS code snippet was obtained from Bubbly.
• The tile flip animation HMTL/CSS code snippet (for levelselection.html) was obtained from W3Schools.
• The correct script order for test.html, as well as the suggestion on how to describe the Jasmine test procedure to the reader of the README, was obtained by taking a peek into a project by anna_ci.

JavaScript

• The array generation algorithm was suggested by Eventyret_mentor.
• The Shuffle Array algorithm, as well as the "\xA0" string to address the HTML "&nbsp", was obtained from Stack Overflow.
• The localStorage solution was obtained from W3Schools and Stack Overflow.
• The handlers.clickExpect method is based on a video lesson by Watch and Code and a post on Stack Overflow.

Media

• All pictures were purchased on Shutterstock, except for the tile background wallpaper which was obtained from PublicDomainPictures.net.

Acknowledgements

• A special THANK YOU to anna_ci and Eventyret_mentor for giving me a generous boost and encouragement when I hit the wall mid-project. I would never have been able to complete this project (let alone in time) and learn so much along the way without their help.
• I received inspiration for this project from my little nephew Gabrijel, who enjoys playing Memory.