Assignment 3. Chorus lapilli

Quick Links

• React – A JavaScript library for building user interfaces
• Tutorial: Intro to React
• React source code
• Starter code

Overview

This assignment is designed to let you build an app of your own, so that you can see all its pieces. This is in contrast with your main class project, where your project team will build a client-server application and most likely you will become expert in your part of the app with only nodding familiarity with the rest.

This assignment is supposed to be quite simple, because you should be spending most of your time working on the project. To help keep it simple, you’ll do a tutorial on basic React, the JavaScript runtime that is the basis for most of the student projects.

Setup

You worked on the past two assignments on SEASnet, an environment managed by a third party. For this assignment, you will complete it on your own local environment.

If you're on Microsoft Windows, try to follow the WSL installation instructions.

Make sure you have the following installed on your system. It's more than possible that some are already installed. (If you're on WSL make sure to install the Linux version of these, except for Chrome.)

• Google Chrome
• Git
• Node.js (at least 22; earlier versions may work, but it's not guaranteed)
• Python (at least 3.11; earlier versions may work, but it's not guaranteed)

Start by cloning the starter code cited above. You may do this by running the following command:

  git clone https://github.com/UCLA-CS-35L/assign3
    

Finish your environment setup by running ./helper init inside the created assign3 directory. If you're on WSL, run sudo ./helper wsl first. If this command fails, don't run it again; instead, follow the Docker installation instructions.

A simple interactive game app

The goal of this assignment is to build a simple application using React.

A secondary goal of this assignment is for you to record what you did. This is so that someone else can build your app, and so that you can see later what you did, to fix your app or to build a similar app.

Build the simple tic-tac-toe game of the tutorial cited above. You need not follow the setup instructions listed in the tutorial; you've already set up your environment. All changes should be made in src/App.jsx. Use ./helper dev to view your changes in the browser.

As you go, keep a log in the file tic-tac-toe.txt of what you have done so that you can reproduce the results later. This should not merely be a transcript of what you typed: it should be more like a true lab notebook, in which you briefly note down what you did and what happened. Write down every significant action that you take, including installing and configuring components as well as any code that you write.

Next, take a breather and reread the source code of your app. Although you needn’t understand every little detail of what it does, it may well give you pointers about useful things to know about React, JavaScript, JSon, Node.js, Vite, HTML, CSS, DOM, JSX and JavaScript in JSX, and Chrome DevTools, React list rendering, React state preservation, etc.

Now, use your experience to modify your tic-tac-toe solution that lets you play a variant of terni lapilli (“three grains”), a popular board game in ancient Rome. We’ll call this variant chorus lapilli (“dancing grains”).

Chorus lapilli is like tic-tac-toe in that players take turn placing pieces on a 3×3 board and the goal is to get three pieces in a row. However, it differs from tic-tac-toe in two ways:

• After your first three moves, instead of adding further pieces you must instead move one of your existing pieces to an adjacent empty square. Therefore, after your third move you always occupy three squares. The move can be up, down, left, right, or diagonal.
• If it is your turn to move and you have three pieces on the board and one of your pieces is in the center square, your move must either win or vacate the center square.

Before submitting to Gradescope, it's recommended that you write tests to verify your solution. Write your tests in the provided tests.py file. Use ./helper test to run these tests. (If you're on WSL, use ./helper test headless instead. If you needed to run the Docker installation instructions, run ./helper test-docker instead.) It includes two example tests: one checks for an empty board state on refresh, and the other checks clicking the top left tile places an X on an empty board. While we won't be checking for this, add at least three more tests. One of your tests should check that your app prevents additional moves once a player wins.

Keep a log of how you built your chorus lapilli app in a file chorus-lapilli.txt. Like your other log file, it should be a complete set of steps to build your toy application, that you could give to someone else to write + reproduce your game.

Common Problems

• I started on the previous version of this assignment, what should I do?
  • That's okay. Make sure to follow the setup instructions and move all content in src/App.js to src/App.jsx.
• sudo ./helper wsl is not working on WSL.
  • Install dos2unix with sudo apt install dos2unix and run dos2unix helper.
• The test commands are not working on WSL.
  • Run ./helper clean.

Autograder Test Cases

• The time travel functionality is not required or graded.
• Starting from the fourth move, one move is done by two clicks: the first click selects the piece to move and the second click selects the destination. Your app should correctly detect invalid moves and revert to the start of the move after two clicks. Drap and drop is not supported by the autograder.
• The autograder does not support pop-up or alert windows.
• The Chorus Lapilli tests interact with your application, clicking tiles and measuring whether the content in tiles are expected. The tile indices are listed below:

  
  tileIndices = [
      [0, 1, 2],
      [3, 4, 5],
      [6, 7, 8]
  ]
  

Submission Requirements

Submit the following files to Gradescope within a ZIP file named assign.zip by the posted deadline.

• Your solution's source code in src/* and index.html.
• Files required to build your solution: package.json and vite.config.js.
• Your lab notebook files tic-tac-toe.txt and chorus-lapilli.txt.

Please use the command ./helper zip to generate this ZIP file. It will run some basic checks (lab notebook files are not empty) before zipping your submission.

Feel free to run this command before completing the whole assignment; a partial ZIP file will be created. You may run this through the Gradescope autograder to see what score you’d get up to this point.

You have unlimited submissions; we’ll choose your best scoring one. Make sure that you choose the best scoring one as your active submission. As per the syllabus, remember that all code is subject to manual inspection.