Operator game

This interactive game lets users practice the mathematical order of operations for learning or fun.

Users are shown an equation with the operators missing, and they have to guess the correct operators to make the equation true.

The game has a fully responsive and accessible design, and a kinder scoring mechanism, making it suitable for users of a variety of ages and abilities.

Extra features include the user being able to select the difficulty level and celebratory "popups" at certain milestones.

Developer: Dr. Sylvia Blaho

View the deployed game on Github Pages

User Experience

This game lets users guess the correct operators in an equation with randomly generated integers, and see if their guess is correct. There are no limits on the number of guesses or the length of game play.

Furthermore, since a new, random equation is generated each time, the game can be played a large number of times without the puzzles repeating (unlike a fixed-question trivia game where the users are more likely to memorize all questions).

User stories for all users

[UX1] I want to relax and feel good while improving my skills.
[UX2] I want to use the game on a variety of screen sizes.
[UX3] I want to easily navigate between the different stages of the game.
[UX4] I want to know the next logical step in the game play just by looking at the game elements.
[UX5] I want to solve a randomly generated puzzle.
[UX6] I want to know if my guess is correct or not.
[UX7] I want to keep playing as long as I like.
[UX8] I want to have the option to keep trying to guess the solution until I get it right or move on to the next equation.

First-time visitor goals

[FI1] I want to know how the gameplay works.
[FI2] I want to know how the scoring works.
[FI3] I want to open the rule description again at any point during gameplay.
[FI4] I want to decrease the difficulty level of the game.

Returning/frequent visitor goals

Since the game is relatively simple, no distinction is made between returning and frequent visitor goals

[RE1] I want to quickly start the game without reading the rules again.
[RE2] I want to increase the difficulty level of the game.

Design

Visual design

The intention was to create a visual impression that is retro-inspired but still modern and minimalistic. The design uses rounded rectangles that hark back to the 70ies, bold colors and chunky fonts.

Color scheme

The color scheme started out very minimalistic, with only a red and orange border marking the Game Area and Question Area, respectively. The design remained this minimalistic until the JavaScript functions and logic were mostly finished.

The image selected for the Milestone "popups" inspired the development of the color scheme to its current form. An image color picker was used to pick salient colors from the image, which were then used for text elements and backgrounds.

After this, color contrasts were checked and adjusted (see the Color contrast testing section), resulting in the following color palette:

Typography

The project uses 3 Google Fonts:

Madimi One is used for headings and buttons. It is a rounded and interesting font fitting the retro-inspired theme, but it is still easy to read.
Bungee Spice is used for displaying operators. Since operators are the main focus of the game, this bold, colorful font highlights them perfectly, and also fits the color scheme.
Poppins is used for most text. This font is relatively simple and easy to read, and its proportions harmonize with Madimi One.

Imagery

The Milestone image is the only image used in the game. I chose it because it is cheerful but not overly busy: it mainly has shades of 4 colors: teal, red, orange and pink, which tones down the large number of balloons and pom poms on it.

The favicon used for the project depicts the four operators with rounded square backgrounds. This was selected because it is explicitly referencing the main purpose of the game and also fits the design theme. The favicon's color was changed to fit the color palette.

Wireframes

Given that the visual part of this game is relatively simple while the JavaScript part is more complex, only one wireframe was made of the Game Area and the New Game button.

The Welcome screen and the Milestone "popups" were created without prior wireframing.

Flow

Description of the rules

On loading the page, the Welcome screen appears, containing a description of how to play the game and how the scoring works.

Basic gameplay

The game generates a random set of operands: positive integers between 1 and 10 (inclusive). These are displayed on the screen, with an operator drop-down toggle between each operand.
The game generates a random set of operators from the set [ + , - , * , / ]. These are never shown to the user.
The game also calculates the correct result of the equation based on the randomly generated operators and operands, and displays this on the screen.
The user has to select the correct operators to make the equation true.

Evaluation

The user can check their guess, that is, whether the operators they selected give the correct result, by clicking the Submit button.

If the guess is correct, a congratulatory message appears, and a new puzzle can be generated with the New Game button.

If the guess is incorrect, the user can change the operators and try again as many times as they like. There are no limits on gameplay in terms of time or the number of tries.

Difficulty level

The difficulty level of the game is capped in several ways:

only 4 operators are used: [ + , - , * , / ]
the right side of the equation has no more than 2 decimal places
only positive integers are used for operands

The user can adjust the level of difficulty by selecting how many operands the equation should consist of.

Scoring rules

The whole game is designed around minimizing stress and only using positive reinforcement. There are no time limits, a decreasing number of "lives" or competition against another player or the computer. These cause unnecessary stress and frustration, and are especially hostile towards people who are neurodivergent or live with mental health issues.

Instead, the game encourages personal growth without measuring ourselves against others, and the agency to set the difficulty of the puzzle to what we can handle at a given time.

Accordingly, incorrect guesses are not counted. The only counter is one of correct answers in a row (the Perfect Streak counter). This is only reset when the user makes an incorrect guess. Crucially, if the user chooses to skip a puzzle by clicking the New Game button or reduces the difficulty of the puzzle with the Operand selector toggle, their streak is maintained.

Features

Tip

To facilitate assessment/testing, uncomment one or more of the lines in script.js following a comment like this:

// ASSESSMENT uncomment the next line for testing/assessment

This will show the randomly selected operators and/or the correct equation in the console.

Tip

Only screenshots of features are included in this section. For videos of how each feature works, see the Full testing of functionalities section.

Responsivity

The game is fully responsive for all device emulators available in Chrome Developer tools, and adjusts to narrow viewports including 280 px in width.

Welcome screen

The Welcome screen is the first element the user sees. It is visually different from the main game screen, and can be hidden completely by pressing the Start Game button at the end of the Welcome Screen, and shown again by pressing the Welcome Screen button at the very bottom of the main game screen.

The Welcome screen contains the following elements:

the section describing of how gameplay works,
the section describing of how scoring works,
the Start Game button with the text "Let's Play!"

The second section is hidden by default, and only the first section and the Start Game button is shown on page load.

The Welcome Screen is responsive on all devices. On small viewports, the text inside the Welcome Screen sections is set to scroll.

Gameplay Rules section

This section explains the purpose of the game and how it is played. It also contains a small button to switch to the Scoring Rules section within the Welcome Screen.

Scoring Rules section

This section explains how the scoring works in the game and why it works the way it does. It also contains a small button to switch to the Gameplay Rules section within the Welcome Screen.

Start Game button

This button hides the welcome screen and reveals the actual game screen. The text on the button has been changed from "Start Game" to a "Let's Play!", as this is deemed more engaging for the user.

Game Area

The game area includes the following elements:

a short instruction line on how to play
the Question Area displaying the puzzle to be solved
the Solution Area where the feedback message is shown when the user clicks the Submit button
the Submit button that displays the appropriate message in the Solution Area

The game area is responsive on all tested devices.

Question Area

The Question Area displays an equation without the appropriate operator(s). Instead of each of the operators, a drop-down selector is shown, where the user can select the correct operator to make the equation true.

The numbers (operands) are selected randomly from the range of integers between 1 and 10 (inclusive). The operators are selected from the array [ + , - , * , / ].

The operator + is shown on each drop-down selector by default. It is reset whenever a new puzzle is generated, but not when the user guess is wrong, so that they can keep track of the guesses they tried more easily.

The difficulty of the puzzle is capped by making sure the result only has a maximum of 2 decimal places. Whenever this is not the case, a new equation is created.

Negative integers are allowed for the solution of the equation, but not for the operands.

By default, the equation has 3 operands and 2 operators. The number of operands and operators in the equation can be changed by the Operand selector toggle.

The question area is also responsive, and adapts to very narrow viewports with a maximum width of 280 px.

Solution Area

The Solution Area is empty by default, and its content is added by JavaScript when the Submit button is clicked. The content varies depending on whether the user got the answer right, and what guess they submitted.

Correct guess

If the user's guess is correct, a congratulatory message appears with some celebratory emojis, and the Submit button is disabled.

The Perfect Streak counter is incremented by 1 on a correct guess.

The user can then play a new game by clicking the New Game button.

Incorrect guess

If the user's guess is incorrect, another message appears, containing the equation using the operators selected by the users and its result. The user is also instructed to change an operator.

The Submit button is also disabled in this case, but it is enabled again when the user changes any of the operators. Changing an operator also clears the Solution Area.

The Perfect Streak counter is reset to 0 on an incorrect guess, including the effect of Milestone "popups" on the Perfect Streak counter.

Submit button

The Submit button appears at the bottom of the Game Area, and bears the text "Check Answer" by default.

When the Submit button is clicked, the app compares the result of the user's guess with the correct results of the equation.

It also populates the Solution Area with content depending on whether the user's guess was correct.

The Submit button is disabled once it has been pressed, and its text content changes to "Check Again".

The Submit button is enabled again in the following cases:

when the user changes an operator
when a new game is run
when the page is reloaded
when the Continue button on a Milestone "popup" is clicked

The Submit button also triggers Milestone "popups" when the Perfect Streak counter reaches certain values.

Milestone popups

Certain perfect streak milestones trigger a celebratory "popup". Currently, these are at 3, 5, and 10 correct guesses in a row.

At these points, clicking the Submit button activates the Milestone event. This consists of 2 parts:

a "popup" appears with a background picture of colorful balloons, a congratulatory text showing the perfect streak length, and a Continue button to return to the game.
The Perfect Streak counter gets a colored background.

The background color of the Milestone text and the Continue button is different for each milestone. The background color of the Perfect Streak text is the same as the background color of the last Continue button.

These color effects use inline HTML styles assigned by the Javascript code. Apart from changing the display property of elements, this is the only case of using inline styles in this project.

New Game button

The New Game button is located directly below the Game Area and bears the text "New Puzzle" (since "New Game" was found confusing by some testers regarding how the Perfect Streak counter works).

Clicking the New Game button resets the Game Area to its defaults and generates a new puzzle, but it does not reset the Perfect Streak counter or the Operand selector toggle and its effect (see the Scoring rules section for the reasoning why).

Perfect Streak counter

The Perfect Streak counter records and displays the length of the user's consecutive correct guesses. It is only present when the user submits an incorrect guess or reloads the page, but not when the user generates a new puzzle with the New Game button or changes the difficulty level with the Operand selector toggle without solving the current puzzle (see the Scoring rules section for the reasoning why).

The Perfect Streak counter changes background color in connection with the Milestone "popups": it gets a new background color after every milestone. This color effect is reset when the streak counter is reset.

Operand Selector toggle

The Operand Selector toggle lets the user choose the difficulty level of the game by selecting the number of operands in the equation they have to solve. The number of operator drop-down selectors is adjusted accordingly (it is one less than the number of operands).

The Operand Selector toggle currently offers a range between 2 and 6 (inclusive). It is set to 3 by default.

When the Operand Selector toggle is changed, the equation template is adjusted to consist of the number of operands selected by the user. This also resets the Game Area to its defaults and generates a new puzzle, but it does not reset the Perfect Streak counter (see the Scoring rules section for the reasoning why).

Welcome Screen button

This is the last element of the gameplay screen. Its function is to enable the user to show the Welcome screen again, in case they want to double-check the rules. Its text content is "Show the rules again".

This button is hidden whenever the Welcome screen or a Milestone "popup" is shown.

Future implementations

While this game is relatively minimalistic, there are several additional customisation options that were beyond the scope of the current project:

the number of operands: This can easily be changed by modifying the "number-selector" form in the HTML code to include larger numbers. The only concern here is that the Question area might look overcrowded and take up too much space on smaller screens.
the range of operands: This is also easily changed by modifying "11" in the function showRandomOperands(11) in the Javascript code to an integer of our choice.
- As a further enhancement, a drop-down similar to the Operand Selector toggle could let the user choose the upper bound of the generated operands themselves.
negative operands: By rewriting the function generateRandomNumbers() in the Javascript code so that each operand is multiplied by either 1 or -1 randomly, negative operands can be included in the game. The function eliminateZero() would still make sure 0 is never one of the operands.
the range of operators: Exponentiation is fairly straightforward to add by modifying the function generateRandomOperators() in the Javascript code so that the operators array includes ** for exponentiation.
- Including roots and parentheses in the equation would require some more rewriting of the concatenation and evaluation rules of the game.
color palettes: A different kind of customisation option would be to enable the user to choose their preferred color palette. There are 2 different ways of implementing this:
1. Users can select any color for certain elements in the game. This can be implemented with some color picker form elements. However, additional care has to be taken when selecting which elements the user can change, to ensure that sufficient color contrasts are maintained.
2. Users can select between predefined color palettes, changing several elements at once. Naturally, color contrast testing would also need to be done as part of implementing this feature.
a timer option: This is a very popular option for small games and quizzes, however, it is contrary to the "kinder scoring" approach taken in this game. Therefore, I would only choose to implement a timer as an opt-in, non-default option for this game.

Accessibility

The game avoids visual clutter, such as excessive borders and shadows, elements of very different shapes, color gradients, transparency, background images behind normal text, and auto-moving elements of all kinds.

These elements tend to cause problems for a variety of users (e.g. those with visual impairment, executive functioning impairment, vertigo, etc.), so steering clear of these chimes in perfectly with accessibility goals.

The content of the site is structured with semantic tags, and Aria labels are used for sections without headings.

Alt text is used for embedded visual elements.

The color scheme was designed to ensure sufficient contrast for legibility, and modified where necessary to ensure that color combinations meet WCAG AAA standards (see the Accessibility testing section for more detail).

The fonts used in the game are easy to read, prioritizing legibility over eccentricity.

External links open in a new tab.

Technologies used

Languages used

HTML
CSS
JavaScript
Markdown

Frameworks, libraries & programs used

Am I Responsive? – show the website on a range of devices
Balsamiq – create wireframes
Birme – resize image and convert to webp format
Coolors.co - color palettes
Favicon.io – create the favicon
Flaticon – search for image for favicon
FontAwsome – icons for operators (not used in the final version)
Git – version control
GitHub – store the source files
GitHub Desktop – GitHub UI
GitHub Issues – project management, bug tracking
GitHub TOC generator – automatically generate a Markdown TOC
GitHub web editor - the only way (known to me) to add videos to the README
GitPod – Integrated Development Environment (only used for tutoring)
Google Chrome Developer Tools – troubleshoot, test responsivity and styling
Google Fonts - import fonts used on the website
Image color picker – color picker from image
Lipsum, loremipsum.io – Lorem Ipsum generators (not used in final version)
MacDown – Markdown editor
Preview – cropping and annotating images
PythonTutor – debugging Javascript Code
Redketchup.io - color picker from image
Shields.io – add badges to README
Slack – mentor communication
Visual Studio Code – code editor
WebAIM – color contrast checking
Web Disability Simulator – accessibility testing

Deployment

Local deployment

To view the site on your local machine (laptop or desktop), follow these steps:

click the following link to download the zipped project folder from GitHub.
double click on the downloaded zip file operator-game-main.zip to unzip it.
in the folder operator-game, double click on index.html to open it in your browser.

Important

Do not take index.html out of the folder, or change the folder structure in any way, as this may break the file paths defined in the project.

Fork the repository

You can fork the repository by following these steps:

Log in to GitHub (if you don't have a GitHub account yet, you can create one for free).
Navigate to the project website https://github.com/blahosyl/operator-game.
Click on Fork in the upper right part of the screen.
On the next page you have the possibility to change the repository name. To do this, simply write your desired name in the text field in the center part of the screen. You can also leave the name as it is.
Click Fork in the bottom right part of the screen.

Tip

If you do rename the repository, make sure to keep the GitHub naming conventions in mind.

Deployment on GitHub Pages

The site was deployed on GitHub pages using the steps below. You can follow the same steps to deploy it on your GitHub account after you have forked the repository.

Log in to GitHub (if you don't have a GitHub account yet, you can create one for free).
Navigate to the project website https://github.com/blahosyl/operator-game.
Click on Settings in the top right of the screen.
On the left-hand menu, click Pages.
In the center of the page under Branch, select main from the dropdown menu, then click Save.
After the site refreshes automatically, a message appears in the top center part of the screen, displaying the link to the deployed site: "Your site is live at https://blahosyl.github.io/operator-game/".

Note

The link will look stlightly different for you, containing your GitHub username instead of blahosyl.

Note

If you have renamed the repository when forking it, your chosen repository name will appear instead of operator-game in the deployment link.

Testing

Tip

To facilitate assessment/testing, uncomment one or more of the lines in script.js following a comment like this:

// ASSESSMENT uncomment the next line for testing/assessment

This will show the randomly selected operators and/or the correct equation in the console.

Issues and bugs are tracked in Github Issues.

Automated testing

Code validation

The html, css and js files of the project were periodically validated throughout development.

The issues discovered during validation are tracked in GitHub Issues #37 and #38.

HTML validation with the W3C validator

The html file of the project was regularly tested by the W3C validator.

In the current version of the site, no errors or warnings were found during validation.

CSS validation with Jigsaw

The css file of the project was regularly tested by Jigsaw. The issues discovered during validation are tracked in GitHub Issues.

In the current version of the site, no errors or warnings were found during validation.

JavaScript validation with JSHint

The js file of the project was regularly tested by JSHint. The issues discovered during validation are tracked in GitHub Issues.

In the current version of the site, no errors or warnings were found during validation.

Lighthouse

Lighthouse performance testing

Lighthouse performance tests were carried out throughout development (selected tests can be found in the folders lighthouse-performance) and lighthouse-full). No significant issues were found.

The current performance score is 90 on mobile and 100 on desktop.

Lighthouse accessibility testing

Lighthouse accessibility tests were carried out throughout development (selected tests can be found in the folders lighthouse-accessibility) and lighthouse-full).

One issue was found, which was fixed in this commit.

The current performance score is 100 on both mobile and desktop.