Word Wheel is JavaScript educational game in which a user guesses words by their definitions. After a player has selected a certain topic of words and starts the game, the app gets a random word on this topic from the local array and searches for a definition in the online dictionary using API. If the definition is successfully found, the app shows it to the user, and the word itself is hidden behind flip cards.
-
- As a first-time player, I want to see the game instructions/rules.
- As a first-time user of the game, I want to easily understand the aims of the game.
- As a first-time user of the game, I want to be able to start the game easily.
- As a first-time player, I want to be able to select a topic of the words
-
- As a returning user of the game, I want to be able to start the game again.
- As a returning user, I want to select other topics of the words
- As a returning user, I want to learn the meanings of new words
-
- As a frequent user, I want to initiate and control game actions.
- As a frequent user, I want to see progress indicators.
- As a player, I want to be able to spell out a word if the definition is hard to understand.
- As a frequent user, I want to discover an intuitive interface that will guide me through all the stages of the game.
- As a frequent user, I want to contact the game developer.
- As a frequent user, I want to get all interaction feedback.
- As a frequent user, I want to be notified of all errors resulting from my actions.
The Word Wheel game was designed based on wireframes produced in Balsamiq. All design features were implemented.
Desktop | Tablet |
---|---|
The game is designed with an interactive and intuitive interface. Consistency evident across all page and covers interactivity as well as design. User actions are confirmed where appropriate, feedback is given at all times. The appearance and UI design are quite user-friendly, simple, and responsive. The game page was designed to fit any mobile screen resolution both vertically and horizontally.
-
The game is based on a single interactive page with significant interactive functionality. The page is designed in a such way as to guide the user through all stages of the game from top to bottom consistently and intuitively, reducing cognitive overload for a better user experience. The main js script is attached to the index.html page as a module. ES6 modules with import and export statements are used to get data. 404.html page for defensive design.
-
The main game font is Open Sans. It's is a clean and modern sans-serif typeface designed by Steve Matteson and commissioned by Google. The font was chosed as it especially designed for web and mobile interfaces and it is incredibly readable in small sizes which plays a big role in the responsive design of the game page.
-
The game design meets accessibility requirements including sufficient contrast between background and foreground colours. The basic color is Light Moss Green. The top and bottom sections of the game page as well as the buttons are implemented in a minimalist modern style using a gradient from two base colors such as Yellow-Green and Crystal. Red tones and brighter Yellow-Green are used to accentuate more important objects of the game. Muted shades of the same color scheme are used for temporarily inactive objects.
The Word Wheel game is designed to strictly adhere to accessibility guidelines across all sections of the page and all interactive elements. Any interaction causes a positive response to the user through the semantic structured information, colors, clear and unambiguous navigation structures.
Topic names and words are stored in the vocabData.js file as a Javascript object. Topic name is a property, array of relevant words is a value. The definition of words is retrieved automatically makes HTTP request to the Free Dictionary API.
-
This script is NOT a part of the GAME! Node.js is required!
This Parser is an additional script that simplifies the work for developer and helps to get words from the external file and add them to the game. Manual for the parser inside the script.
-
The Topic Dropdown list generated from the properties of the Javascript object
topicWords
which is in vocabData.js file and populate the dropdown menu with a list of topics. The dropdown list is updated every time the user clicks on theTopic
button and is displayed to the user. If the array of words is exhausted during the game, the js object with the name of the topic is removed from the vocabData.js file, which is notified to the user. -
New words can be added to the game using the Parser or directly into the array of the relevant topic in the Javascript object
topicWords
found in the vocabData.js file. When the user starts a new game cycle, the app extracts a random word from the array of the Javascript objecttopicWords
for the chosen topic. If the word fails the validation, it is removed from the array and a new random word is extracted. -
When a suitable word is found, the app makes a asynchronous HTTP request using the Fetch API to the Free Dictionary and gets the definition of this word. If no definition is found, the app extracts the new word from the array and makes a new request.
The game menu includes two buttons (Topics
and Rules
) and was implemented in such a way that the user can read the game instructions/rules and select the topic of words which is an integral part of the game.
The nav menu is located on the top right corner of the game page for convenient user access. The menu buttons respond to mouse hover and change the text color to brighter to give user feedback. Also, if the user tries to start the game but the topic has not yet been selected, the Topics
button is temporarily highlighted.
Menu | Highlighted Menu |
---|---|
-
The choice of topics is implemented by clicking on the
Topics
button in the form of a drop-down menu. The list of topics is updated and displayed every time when the user clicks on theTopics
button. If the user tries to start a new game cycle but no topic is selected, the user will be prompted to select one. When the topic is selected by the user from the dropdown menu, the app changes the button name for the name of the selected topic. During the game cycle, the app will refer to the button'sdata-value
attribute which stores the row topic name, to search for the relevant word. The topic name will be removed from the dropdown menu during the game if the topic's word list is exhausted. The user can select a topic of the words at any time in the game, but a new word from the topic will be received only when the cycle of the current game is completed.Dropdown menu Selected Topic -
The rule set can be opened at any time by the user, as he/she may need to clarify some details of the game. The rules section opens on the same page on top of the game window. On the rules pages, in addition to the ruleset itself, the user also has access to a link to the game repository itself which opens on a new page.
Clicking on the Spin the Wheel
button once initiates the launch of the game cycle and the start of the wheel animation, after which the button is deactivated to prevent the creation of a new game cycle instance. The user can also spin the wheel by pressing the Space
key on the keyboard.
At the beginning of the game cycle, the animation of the wheel spinning and the random change of letters that are not associated with the word is started If the data is successfully extracted, the color of the wheel changes to yellow, and a question mark is displayed inside. If the user entered the wrong answer or opened the whole word manually, the color changes to red, and an X mark is displayed inside. If the user gave the correct answer, the color changes to turquoise, and the checkmark is displayed inside.
The word definition is obtained by HTTP request to the Free Dictionary API, parsed, validated and displayed to the user. If the keyword itself was found in the definition, it is replaced with asterisks. Also if the definition is too long, it is truncated before being shown to the user.
Hidden/Revealed word
Initially, the keyword is hidden behind the flipped tiles. The user has the ability to reveal each letter separately by clicking on a tile if it is difficult to guess the whole word. At the end of the game cycle, after the user clicks on the Submit
button the word is revealed completely, regardless of the outcome of the game.
Hidden word | Revealed word |
---|---|
While the game is not active, the input field is disabled and the placeholder text prompts the user to spin the wheel
. When the user has started the game cycle, the input field becomes active and the user is prompted to enter an answer.
Disabled Input field | Active Input field |
---|---|
While the game is not active, the submit
button is disabled. When the user has started the game cycle, the submit
button becomes active. If the button was clicked by the user and the input field is empty, an alert appears prompting the user to enter an answer. The user can also submit the answer by pressing the Enter
key on the keyboard.
Disabled Submit button | Active Submit button |
---|---|
At the start of each game cycle, a credit score is given that adds up to the number of letters in the word. For each open letter, one point is deducted from the credit score. For a guessed word, the balance of credit points, which is equal to the number of hidden letters, is added to the total score. If the word is entered incorrectly, the total score counter is reset to zero. If each letter tile is clicked, revealing the letters, the total score is not reset.
- HTML5 - building, structuring and presenting project
- CSS3 - game styling
- Java Script - game functionality
- Fetch API - request a data from the Free Dictionary API
- Node.js - JavaScript runtime environment. Used for get words from the external file and add them to the game.
- WSL - Ubuntu - terminal environment
- Balsamiq - wireframes
- VScode - code editing
- GIT, GitHub - tracking, storing, hosting project
- Chrome DevTools - inspecting and debugging code
- Adobe Photoshop - favicon, readme support images
- iloveIMG - compressing and resizing readme support images
- NameCheap - Custom Domain name
See TESTING.md for an overview of the game testing and debugging.
The Live link is https://flashdrag.github.io/word-wheel
The app is hosted on GitHub pages and used a custom domain, which is registered via Namecheap Educational Promotion. The game also can be accessed using link: https://www.wordwheel.me (expired, not renewed. Use https://flashdrag.github.io/word-wheel instead)
Here you can find instructions: How to register a domain at nc.me
- In the GitHub repository, navigate to the Settings tab.
- Once in Settings, navigate to the Pages tab on the left hand side.
- In the Build and deployment section under Branch, select the master branch and click Save.
- Once the master branch has been selected, the page will be automatically refreshed and a display indicates the successful deployment and the link to the address.
- Go to the WordWheel Github Repo
- Click on the green Code button and Download ZIP
- Extract the ZIP file on your local machine
- Run the index.html file in a browser
- Go to the Word Wheel Github Repo
- Click the Code button to the right of the screen and copy the HTTPs link there
- Open a GitBash terminal and navigate to the directory where you want to locate the clone
- Type
git clone
and paste the copied HTTPs link, press the Enter key to begin the clone process
The Word Wheel game based on my own implementation of code, applying what I've learned from CodeInstitute Full Stack Developer Course and other tutorials.
- Google Fonts - fonts
- FontAwesome - icons
- Dictionary API - Free Dictionary API for words definitions
- Visual Dictionary - word sets
- Logo - game logo