Skip to main content Link Menu Expand (external link) Document Search Copy Copied

Homework 6 - Word Guessing

Due: Monday, November 13, 2023 at 11:59pm (Extended from Friday, November 10)


  • Gain experience writing in JavaScript
  • Handle form data and manipulate the DOM in JavaScript
  • Maintain persistent storage with localStorage


For this homework, you may work alone or with another student in this course. You will implement a Wordle-like game that picks a random target word from a list of possible words, then allows the user to guess the word and provides feedback on correct letters. Unlike Homework 4, in this version, the entire game will be played client-side using JavaScript.

Word Guessing Requirements

Move over Wordle, Quordle, Kilordle, Heardle, Worldle, and so, so many more… we’re writing our own word guessing game! Specifically, in our version, words can be any length and we’re giving more cryptic clues. We’ll pick a word (the “target word”) from our list of possibilities at random, which the user must try to guess. If they get it right, they win! If they don’t, we’ll give them some hints (described below) so that they can guess again. They can keep guessing until they can correctly guess the word.

Our “evil word guessing” game will consist of only one page, index.html, and will display a game page as well as the user’s game stats. For the game, the user will be presented with a text box to enter their guess. Once the user enters a guess, if they are incorrect, the display will be updated, adding their previous guesses and how close they were. That is, we’ll tell the user (1) how many characters in their guess were in the correct position, (2) how many characters in their guess were in the target word, and (3) whether their word was longer, shorter, or the same length as the target word. Users may continue guessing until they guess the word, with their guesses and stats appearing on the game page. The number of games they have played, their current win streak, and number of overall guesses will be maintained in Local Storage on their browser and displayed to the user as well.

For this assignment, you must implement the following components. (You may implement more functionality if you wish, for example by telling users which letters they have in the right spot, but remember that we’ll be grading on effort in implementing these components below.)

  1. Your index.html should have at least the following three sections (i.e., portions of the page) for the user. You may choose to include more.
    1. Game. This section will display information about the current in-progress game. It will include a form with the following input and functionality. Note that the action of the form should not be a PHP page, you should have an event handler instead to update the page when the user submits the form.
      • Instructions asking the user to enter a word.
      • A form and text box for the user to enter the word, with a button to submit their guess.
      • A list of all the user’s prior guesses. Please be creative! You are encouraged to determine how best to organize the display, but for each prior guess, the application must display:
        • how many characters were in the word,
        • how many characters were in the correct location, and
        • if the guessed word is too long or too short.
        • For example, if the target word was “science” and the user guessed “computer”, then the page must state that there were: 2 characters in the word, 1 in the correct place, and the word was too long.
      • An option (link, button, etc) for the user to start a new game (which will end the current game, if applicable).
    2. User Game Statistics. This section will display the user’s game statistics:
      • The number of games played
      • The number of games won
      • The length of the current win streak (how many games they have won in a row)
      • Average number of guesses per game
    3. Clear History. In a separate section, provide the users a button to clear out their data from the application.
  2. You must implement the following event handlers in JavaScript:
    1. New game functionality. The user must be able to start a new game.
      • When the user clicks the new game button/link, the event handler should load a new random word using the provided getRandomWord() function (see below).
      • If a game was currently in progress when this event handler is called:
        • Update the game statistics to clear the win streak and the average number of guesses per game. Hint: you may want to keep track of the overall number of guesses.
        • Clear the text box in case the user has started entering a word
        • Remove any display of the prior guesses for the in-progress game
      • If a game was not in progress:
        • Enable the text box so that the user can begin to guess the word.
      • Update the game statistics to increase the number of games played
    2. Guess word functionality. The user must be able to enter a guess.
      • When the user enters their guess in the form, it must be compared with the target word in a case insensitive manner (that is, if the target is “computer” and the user enters “COmPUteR”, then they have guessed the target word). In particular, this event handler should calculate and display:
        • how many characters were in the word,
        • how many characters were in the correct location, and
        • if the guessed word is too long or too short.
      • Clear the text box so that the user can enter their next guess.
      • Provide validation and feedback if the user enters an invalid word, such as a word containing numbers or a symbol.
      • If the user correctly guesses the word, update the game statistics and disable the text box until the user starts a new game.
    3. Page load and unload. The user’s data must be stored between views of the page.
      • When the page unloads, store the current game and game statistics in localStorage.
      • When the page loads, if there is a game or game statistics stored in localStorage, then repopulate the display with the stored version.
    4. Clear history. The user must be able to clear the game statistics (and any current game) from the browser.
      • When the user clicks the clear history button, your application should remove any game and game statistics information stored in localStorage, clear the stats from the DOM, and start a new game.
  3. You should use an object or array object to store the game and game statistics. By creating an object to store them, you will be able to store the current state more easily in localStorage by converting the object to a JSON string. See JSON.stringify() and JSON.parse().
  4. Download and include the following wordlewords.js JavaScript into your index.html file. This JavaScript library contains a function, getRandomWord(), that queries our word list and returns a random word. You should use this function to get a new word when starting a new game.
    • wordlewords.js
    • You must write a separate function that handles the setup of the new game. This function must take one parameter: the new target word.
    • In the event handler for when the user chooses to start a new game, call getRandomWord() and pass in this separate function as the only parameter. getRandomWord() will then call your function with the new word.

Note: We have explicitly left some requirements of the assignment vague to provide freedom of design. You are encouraged to be creative in your implementations!

Additional JavaScript Notes

  1. You may include your JavaScript code directly in your index.html file or write a separate .js file and include it in index.html.
  2. For this submission, you may NOT use jQuery.
  3. The following hints may help in computing the number of characters in the word or in the correct place:
    • .length returns the length of a string.
    • Strings may be indexed in JavaScript as arrays; that is, var a = "hello"; document.write(a[2]); will write “l”.
    • See Mozilla’s JavaScript String reference for more helpful built-in functions.


The submission will consist of two parts:

  1. Submit your code (HTML, CSS, JavaScript, etc) to Gradescope in the “Homework 6” submission. You may choose to upload the files individually, upload a zip folder, or upload from a GitHub repository.
    • You must include a link to your published version in the comments of your index.html page
  2. Publish your web site to the cs4640 server under a folder titled “hw6”. Therefore, we should be able to access your work at If you work with a partner, each person should publish the work to their web space.

Grading Rubric

This homework is worth 50 points, based on the following rubric:

  • 5 points - Game display
  • 5 points - User Stats display
  • 10 points - New game event handler
  • 10 points - Guess word event handler
  • 10 points - Clear history event handler
  • 5 points - Maintain state in Local Storage across page loads
  • 5 points - Publishing your site to the cs4640 server

Academic Integrity

For this assignment, you are welcome to share/publish your website! You’ll be doing that on our cs4640 server as well. We only ask that you not make any GitHub projects public until after the deadline.

Note: You must cite any sources you use in a comment at the top of your index.html file. For example:

<!DOCTYPE html>
Sources used:, ...
<html lang="en">

Use of Generative AI

For Homework 6, you are not allowed to use generative AI tools to help you solve this problem.

Other Notes

In case you are interested, here is the PHP code of our API endpoint. It reads from a static word list, then prints out a random word.

// Allow Cross-Origin Scripting so that we can develop
// on our local Docker environments
header("Access-Control-Allow-Origin: *");
header("Access-Control-Allow-Headers: X-Requested-With, Content-Type, Origin, Authorization, Accept, Client-Security-Token, Accept-Encoding");
header("Access-Control-Max-Age: 1000");
header("Access-Control-Allow-Methods: GET, OPTIONS");

// Read the word list, removing new lines (\n) from the returned array
$words = file("../homework/wordlist.txt", FILE_IGNORE_NEW_LINES);

// Print out one random word
echo $words[array_rand($words)];