# Tic Tac Toe
:::danger
<b>Early Handin: Thursday, September 26, 11:59pm EST
Regular Handin: Saturday, September 28, 11:59pm EST
Late Handin: Monday, September 30, 11:59pm EST</b>
:::
Watch the demo [here](https://youtu.be/8KDImLk-eQg?si=IbBlLsuNwkqeBOHK "Demo")!
# Assignment Roadmap
:::info
[Silly Premise](#Silly-Premise)
[Collaboration Policy Reminder](#Collaboration-Policy-Reminder)
[New Concepts Covered](#New-Concepts-Covered)
[Helpful Resources](#Helpful-Resources)
[Installing Stencil Code](#Installing-Stencil-Code)
[Grading](#Grading)
### **[FUNCTIONALITY](#Functionality)**
[Coding Incrementally](#Coding-Incrementally)
> [Compiling and Running Your Code](#Compiling-and-Running-Your-Code)
[Suggested Order for Incremental Coding](#Suggested-Order-for-Incremental-Coding)
[Saving Your Work on GitHub](#Saving-Your-Work-on-GitHub)
>
[Minimum Functionality Requirements](#Minimum-Functionality-Requirements)
[Full Functionality Requirements](#Full-Functionality-Requirements)
### **[IMPLEMENTATION](#Implementation)**
[Support Code Interfaces](#Support-Code-Interfaces)
[Javadocs](#Javadocs)
[Using JavaFX Colors](#Using-JavaFX-Colors)
[A Note on getWinningPlayer](#A-Note-on-getWinningPlayer)
### **[DESIGN](#Design)**
[Design Tips](#Design-Tips)
### **[STYLE](#Style)**
### **[HANDING IN](#Handing-In)**
[README](#README)
[Handin](#Handin)
:::
## Silly Premise
Uncle Iroh just invited you to play a friendly game of Tic Tac Toe over a lovely cup of jasmine tea. The only problem is: Momo stole his artisanal hand-carved Tic Tac Toe set! Rather than simply draw a Tic Tac Toe board in the sand like a peasant, you are going to build an awesome Tic Tac Toe game in Java. Let's get started, the tea is getting cold!
Reference: Avatar the Last Airbender, Nickelodeon
## Collaboration Policy Reminder
If you ever have questions about [the collaboration policy](https://docs.google.com/document/d/10rbbd0Y6s1JUzPe8VmoWcL_Mz26XczX-i7p2LUFa9vc/edit?usp=sharing), refer to the collaboration policy or ask a TA!
## New Concepts Covered
* Association
* Accessor/mutator (“**get**”/”**set**”) methods
* Writing classes from scratch
* Implementing interfaces
## Helpful Resources
* This handout!
* [Writing Classes Code-along](https://github.com/brown-cs15-2024/codeAlong2) and [Code-along Recording](https://www.youtube.com/watch?v=A7OJF4DvYIo)
* [Tic Tac Toe demo](https://youtu.be/8KDImLk-eQg?si=IbBlLsuNwkqeBOHK)
* [Javadocs](#Javadocs)
* The [Javadocs](https://cs.brown.edu/courses/cs015/javadocs/cs15/prj/ticTacToeSupport/package-summary.html) contain information that you cannot find in this handout — you will have much trouble implementing this project if you haven’t thoroughly read the Javadocs. When in doubt, first check the handout, then the Javadocs.
* [Javadocs Diagnostic](https://docs.google.com/forms/d/e/1FAIpQLSfEJ5g8qjluYqyzn-nubFtiS338S1zDYQmWaM59E6oOT2hTOQ/viewform?usp=sf_link) (see [here](#Coding-Incrementally) for more details)
* [Working with Objects II Lecture](https://cs.brown.edu/courses/cs015/lecture/pdf/CS15.Lecture_5_Working_With_Objects_Part_2.9.19.24.pdf)
* [Interfaces and Polymorphism Lecture](https://cs.brown.edu/courses/cs015/lecture/pdf/CS15.Lecture_6_Interfaces_and_Polymorphism.9.24.24.pdf)
* [Class & Inheritance/Interface Diagrams](https://docs.google.com/document/d/1LZV1M75gozJuU7jouTmusjw2B4fjLPOCSh9feQ3sDXM/edit?usp=sharing)
* [Style Guide](https://docs.google.com/document/d/1olSJxbrhuIystA_kVbmKu4V8JfN7HE-eDzM5blkoeFw/edit?usp=sharing)
* [GitHub Guide](https://docs.google.com/document/d/1tSxfUIn-Ro6Pr1X4y21BbYKdsiK-nlWW3pGDfyh7SQ8/edit?usp=sharing)
* [Understanding Support Code Handout](https://docs.google.com/document/d/1mWR-huHi6PqizbFlghQrRXGnyJRZaClu_pkY7PFQYqY/edit?usp=sharing)
* [README Guide](https://docs.google.com/document/d/1QJPit-_8ZC3r4l_f5F3ydMK34-NchBYgwtm0c21iwsU/edit?usp=sharing)
* [TA Hours](https://cs.brown.edu/courses/cs015/#hours) and [Ed](https://edstem.org/us/courses/63887)
## Installing Stencil Code
Click **[here](https://classroom.github.com/a/UC72EgQD)** to get the stencil from GitHub — refer to the [CS15 GitHub Guide](https://docs.google.com/document/d/1tSxfUIn-Ro6Pr1X4y21BbYKdsiK-nlWW3pGDfyh7SQ8/edit?usp=sharing) for help with GitHub and GitHub Classroom. Once you have the URL of your personal GitHub repository, open the IntelliJ terminal. Move into your local **`src/`** folder, then use the command **`git clone <URL>`**
Once you’ve cloned your personal repository from GitHub, you’ll need to rename your local folder from **`tictactoe-<yourGitHubLogin>`** to just **`tictactoe`**. You will have issues running your code until you make the change.
## Grading
The grade for this assignment will be determined by [functionality](#Functionality) (55%), [design](#Design) (30%), and [style](#Style) (15%). See each of those sections for more details of this grading breakdown. An ‘A’ project would meet mostly all [full functionality requirements](#Full-Functionality-Requirements) with good design and style.
---
# Functionality
Watching the [demo](https://www.youtube.com/watch?v=8KDImLk-eQg) will give you a better understanding of your task; we **strongly** recommend you do this as soon as you can.
For this assignment you’ll be implementing your very own game of Tic Tac Toe! Your game will have two **`TicTacToePlayers`** competing against each other by placing their respective symbols (“X”s and “O”s) on a **`TicTacToeBoard`**. You’ll use a **`Controller`** as a “referee” of the game to switch turns, check for a winner, and display updates about the gameplay.
The table below summarizes what update should be displayed on each game condition. The wording doesn’t have to be identical, but the general meaning should be the same:
Game Condition (automatically checked by support code) | Relevant Method (automatically called by support code) | Message to Display | Note
:---- | :---- | :---- | :---- |
When a player selects a square so their turn ends | **`selectSquare`** | “Player X finished their turn!” | The player’s “name” (here “X”) must match that player’s designated symbol. |
When a player selects a square that’s been taken | **`invalidSquareChosen`** | “Square chosen has already been taken! Try again.” | In addition, the selected square should flash some color. |
When a player wins | **`playerWins`** | “Player X wins!” | The player's “name” (here “X”) must match that player’s designated symbol. In addition, the winning squares should be highlighted some color.|
When the game ends in a tie| **`noWinner`**|"It's a tie!"
When the game starts or restarts | **`restartGame`** | “Select a square to start playing!” | In addition on game restart, the board symbols and highlights should be cleared. Be sure to call **`playAgain`** on restart or the game will act buggy!
The support code will automatically check for these game conditions (just like how the support code checks when the user presses the “Up” key or when the ball moves offscreen in Pong), so you should never *call* any of these methods. **Instead, you just need to define what should happen in their method bodies. Read more in the [Javadocs](#Javadocs).**
## Coding Incrementally
After you’ve watched the demo, ++*thoroughly read this handout and the [Javadocs](#Javadocs) in full*++ to make sure you understand the project. Before you start coding, make sure you complete the [TicTacToe JavaDocs Diagnostic](https://docs.google.com/forms/d/e/1FAIpQLSfEJ5g8qjluYqyzn-nubFtiS338S1zDYQmWaM59E6oOT2hTOQ/viewform?usp=sf_link). Once you’re done with that, start coding! It is important to code **incrementally**, meaning completely accomplishing one logical task before moving on to the next one.
### Compiling and Running Your Code
Most importantly, incremental coding means that you **run your code after each step** to ensure it’s working as you want it to! Refer to the [Rattytouille handout](https://hackmd.io/@Fall2024-CS15/Sy5evK8NA) for more detailed instructions on how to compile and run your code. Here is a summary:
<img src="https://hackmd.io/_uploads/Syhm12E2R.gif" style="float: right; padding-top: 10px" width="250px"></img>
1. **`cd tictactoe`**
2. **`javac *.java`**
3. **`cd ..`**
4. **`java tictactoe.App`**
5. Repeat!
### Suggested Order for Incremental Coding
**Step 1.** Run the stencil code and complete the [TicTacToe JavaDocs Diagnostic](https://docs.google.com/forms/d/e/1FAIpQLSfEJ5g8qjluYqyzn-nubFtiS338S1zDYQmWaM59E6oOT2hTOQ/viewform?usp=sf_link).
* The stencil will appear as a mostly-gray background with a Quit and Restart button.
**Step 2.** Write a top-level logic class that implements the **`CS15TicTacToeGame`** interface, and ++make the game show up in the **`App`** frame++. **We highly recommend getting something to show up on the screen before doing anything else.**
* Java will ask you to declare method signatures required by an interface before successfully compiling. For now, these method definitions can be left empty.
* After successful completion of this step, you will see two separate, white portions of the screen for the **`Controller`** and **`CS15TicTacToeBoard`**, with a dark blue portion at the bottom for the buttons.
* Make sure you write all of your new code in the **`App`** class beneath the line that reads **`CS15TicTacToeFrame frame = new CS15TicTacToeFrame(stage);`**
**Step 3.** In your top level logic class, instantiate a **`CS15TicTacToeBoard`** and a **`Controller`** so that the screen appears ready to start a round of tic tac toe. When the game starts, you should make the **`Controller`** display the message “Select a square to start playing!”.
**Step 4.** Create a class to represent the players, implementing the **`CS15TicTacToePlayer`** interface. Think about what each player needs to *know about*, take a look [here](#Design-Tips) for some tips!
**Step 5.** Create two instances of your player class (one using the "X" symbol and one using the "O" symbol) and add them to the game via the **`Controller`**.
:::info
Note: if you do not use X and O, our ✨magic support code✨ won’t run properly, so be sure to use those letters!
:::
**Step 6.** Implement the **`selectSquare`** method so that when the user clicks, the player’s symbol (i.e. “X” or “O”) appears in that square. Be sure to update the **`Controller`**’s message per the table above and ***then*** (after updating the message) tell the controller that this turn is over.
**Step 7.** Implement the four remaining methods in the top-level logic class to deal with various game scenarios described in the table above.
### Saving Your Work on GitHub
Refer to the [CS15 GitHub Guide](https://docs.google.com/document/d/1tSxfUIn-Ro6Pr1X4y21BbYKdsiK-nlWW3pGDfyh7SQ8/edit?usp=sharing) for more detailed instructions on how to save snapshots of your work to GitHub. We recommend doing this around once an hour to make sure you’re maintaining a copy of your code. Here is a summary:
1. Move into the **`tictactoe`** directory
2. **`git add -A`**
3. **`git commit -m “<some descriptive message>”`**
4. **`git push`**
5. Repeat!
## Minimum Functionality Requirements
MF Policy Summary: *In order to pass CS15, you will have to meet minimum functionality requirements for all projects. If you don’t meet them the first time around, you may hand the project in again until you succeed, but you will keep your original grade. MF requirements are **not** the same as the requirements for full credit on the project. You should attempt the full requirements on every project to keep pace with the course material. An ‘A’ project would meet all of the requirements on the handout and have good design and code style.*
To meet MF for Tic Tac Toe:
* Both players’ symbols show up on click (i.e. “X” and “O”)
* Controller text updates appropriately for game winning and ties
* Winning squares are highlighted in a color
## Full Functionality Requirements
Beyond the minimum functionality requirements, the rest of the functionality grade will depend on the following criteria:
* Game properly restarts when the “Restart” button is clicked
* Controller box text updates appropriately for invalid square selection
* Invalid square selection flashes a color
* No minor bugs
<img
style="display: block; margin: auto;" src="https://hackmd.io/_uploads/SkI6x34nR.png" width="500px"></img>
---
# Implementation
## Support Code Interfaces
Rather than providing stencil classes with stencil methods for this project, we’re providing two interfaces for you to implement **in two separate classes you must write from scratch**. In order for the support code to connect to your code for this project, you must make sure that you create:
* one top-level logic class that implements the **`CS15TicTacToeGame`** interface
* one class that models a player and implements the **`CS15TicTacToePlayer`** interface
As discussed in lecture, an interface can be thought of as a “contract” signed by one or more classes. This contract outlines specific methods that must be written by whatever classes implement the interface. Take a look at the “Interfaces and Polymorphism” lecture for a reminder on the syntax for an interface.
As a reminder, by implementing an interface, the class promises to define **all** of the methods declared in the interface. Keep that rule in mind when you’re writing your classes (and don’t forget the **`@Override`** tags!). All of these methods will be called ✨automagically✨ by the support code in the appropriate situations.
To create a new Java class in IntelliJ, right-click on the **`tictactoe`** package folder on the left-hand “Project” tab, then select *New > Java Class*. This will create a new **`.java`** file with the class declaration written for you. Make sure each class has a name that describes its purpose in the context of the project.
Refer to the [Javadocs](https://cs.brown.edu/courses/cs015/javadocs/cs15/prj/ticTacToeSupport/package-summary.html) for descriptions of the **`CS15TicTacToePlayer`** and **`CS15TicTacToeGame`** interface methods that you will need to implement.
:::info
**Important**: Each of those methods is already automatically called by the support code in the relevant scenario (summarized in the table above [Coding Incrementally](#Coding-Incrementally)). For example, when all squares have been selected but there is no 3-in-a-row, the **`noWinner`** method will be called. Or, when a player clicks on a square, the **`selectSquare`** method will be called. Your job is to write the code to determine what should happen in each situation!
:::
<ins>**In short, we’ve written most of the code for a tic tac toe game to operate in the support code. Your job is to connect all the pieces together by implementing the methods defined in the support code interfaces.**</ins>
## Javadocs
The [Javadocs](https://cs.brown.edu/courses/cs015/javadocs/cs15/prj/ticTacToeSupport/package-summary.html) have a list of all the classes in the support code and what they do, including support classes and methods, which you cannot see but must use to implement this project! The Javadocs provide detailed documentation of the support code that you need to use in this project. Reading them should help you understand how to connect all the components in this project to create a game.
**The Javadocs contain information that you cannot find in this handout — you will have much trouble implementing this project if you haven’t thoroughly read the Javadocs. When in doubt, first check the handout, then the Javadocs.**
## Using JavaFX Colors
Java has its own form of built-in support code called “libraries”, which consist of a collection of related packages. The JavaFX library is a set of packages used for creating graphics in Java — you’ll get very familiar with JavaFX starting during the Graphics lectures.
The package **`javafx.scene.paint`** contains one very useful class called **`Color`** and defines a series of constants that represent color values. You can find a full list of colors in the **`javafx.scene.paint.Color`** Javadocs [here](https://docs.oracle.com/javase/8/javafx/api/javafx/scene/paint/Color.html). In order to use any of these colors in a class, you should import the class **`javafx.scene.paint.Color`** at the top of the file and then reference a call like **`Color.ALICEBLUE`** or **`Color.FUCHSIA`**.
You’ll find methods in the support code that require a **`Color`** as an argument. You can choose any of the JavaFX **`Colors`** as long as the color change is clear and the tic tac toe board is still visible!
<img style="display: block; margin: auto" width= "350px" src="https://hackmd.io/_uploads/B105Q3V2R.png"></img>
## A Note on getWinningPlayer
In the **`playerWins`** method, you’ll need to know *which* player has won in order to include the winning player’s symbol in the controller message, so you can use the **`getWinningPlayer`** method, which the Javadocs say returns type **`CS15TicTacToePlayer`**, i.e. any class that implements the **`CS15TicTacToePlayer`** interface. Our support code uses this generic return type because we can’t know what you will name your class, but using the interface as a return type guarantees that in your code, any class that implements this interface will be accepted (polymorphism in action)!
Remember that implementing an interface does not limit the methods that you can have in that class. You are still allowed to explicitly declare and define any methods you need that are not required by the interface. <ins>In other words, your class that implements **`CS15TicTacToePlayer`** can have more methods than just **`selectSquare`**, if you so wish.</ins>
Consider this block of code you might write:
```
CS15TicTacToePlayer player = this.controller.getWinningPlayer();
player.methodThatYouWrote(); // your methods should be named more clearly
```
This code is a great example of a polymorphic <ins>declared type</ins> versus an <ins>actual type</ins>. While the declared type of this **player** variable is **`CS15TicTacToePlayer`**, its actual type would be the class that you wrote to represent the player. But, because **`methodThatYouWrote`** isn’t defined in the interface, this code would cause a compiler error (try it!).
Luckily, because of some support code ✨ magic ✨, you can use your own player class as the <ins>declared type</ins> for the returned player from **`getWinningPlayer`**. For example, if your class is called **`TicTacToePlayer`**, the following code block would work:
```
TicTacToePlayer player = this.controller.getWinningPlayer();
player.methodThatYouWrote();
```
---
# Design
## Design Tips
**Association**: Imagine a tic tac toe game where you open the box and pull out a board to start playing with, but both players also bring boards of their own. You wouldn’t actually be playing the game together! Instead, each player needs to *know about* the same **`Board`** they will be playing on. The same idea goes for the **`Controller`**!
**Player Symbols**: How will each player know what letter to put down on the board? We can think of each symbol as a *property* of that player – when creating (i.e., instantiating) a player, it needs to be told what its symbol is (remember that the symbols would be of type **`String`**). Think about how this can be stored so the player knows its symbol (as long as it exists). What special type of method can you write so that the top-level logic class can also know the player’s symbol while keeping the information **`private`** in the player class?
Check out the [Working with Objects II](https://cs.brown.edu/courses/cs015/lecture/pdf/CS15.Lecture_5_Working_With_Objects_Part_2.9.19.24.pdf) lecture for helpful concepts (especially association)! We also recommend using lab1 as a reference for using concepts like local vs. instance variables and creating class diagrams.
Like Pong, <ins>you’ll need to create a class diagram that represents the design of this program and submit it in your final submission.</ins> This diagram will be factored into the “design” portion of the grade.
The following classes must be present in your class diagram for full points:
- Your top-level logic class that implements **`CS15TicTacToeGame`**
- Your player class that implements **`CS15TicTacToePlayer`**
- **`CS15TicTacToeBoard`**
- **`CS15TicTacToeController`**
- **`CS15TicTacToeSquare`**
You can read more about how to make a class diagram [here](https://docs.google.com/document/d/1LZV1M75gozJuU7jouTmusjw2B4fjLPOCSh9feQ3sDXM/edit#heading=h.n64vzvb7650b). You are not required to make an interface/inheritance diagram for this project. To make your diagram, we recommend using Google Docs/Slides/Drawing or paper and pencil. Be sure to upload your diagram to your GitHub repository. Make sure your diagram is a **.pdf**, **.jpg**/**.jpeg**, or **.png** file. <font color="#f00">If you submit a different file format, it may be unsupported so you will receive no credit for the diagram.</font>
---
# Style
Refer to the [CS0150 Style Guide](https://docs.google.com/document/d/1olSJxbrhuIystA_kVbmKu4V8JfN7HE-eDzM5blkoeFw/edit?usp=sharing) for the specific style guidelines along which your code will be graded for the “style” portion.
# Handing In
## README
In CS15, you’re required to hand in a README file (must be named README) that documents any notable design choices or known bugs in your program. Remember that clear, detailed, and concise READMEs best allow your TAs to understand your thought process, helping them better understand your project as well.
You are expected to create your own README file. Please refer to the [README guide](https://docs.google.com/document/d/1QJPit-_8ZC3r4l_f5F3ydMK34-NchBYgwtm0c21iwsU/edit?usp=sharing) for information on how to create a README, what information your README should contain, and how you must format it.
For this project, you should include the following information (in 1-2 sentences each) under the Design Choices section of the README:
1. Where did you use association? Why was this necessary?
2. Did you write any accessor or mutator methods? Where? Why was this necessary?
At the bottom of your README, add the approximate number of hours you spent on this assignment. This will be used only to average how long the assignments are taking students this semester, and it is completely anonymous.
## Handin
To hand in your assignment, follow these steps:
1. In a terminal, move into the **`tictactoe`** folder as if you were about to compile your code
2. Type the command **`rm *.class`** (Mac) or **`del *.class`** (Windows)
a. This will remove the **`.class`** files that are created when compiling so that your submission only includes **`.java`** code files.
3. Add your diagram to your repository
a. Drag and drop or upload your class diagram to your **`tictactoe`** folder
4. [Add, commit, and push your code to GitHub](#Saving-Your-Work-on-GitHub)
6. Go to CS15 2024 on [Gradescope](https://www.gradescope.com/).
7. In the submission for TicTacToe on Gradescope, click on GitHub.
8. Select your **Tic Tac Toe** repository and the **main** branch
9. Upload! Double check that you have uploaded to Gradescope properly and your diagram appears on the submission.
You can submit as many times as you want prior to the deadline, and only your most recent handin will be graded. If you handin before the deadline and again after the deadline, the submission will be counted as late.
**<font color="#f00">Do not include any identifying information on your handin (name, login, Banner ID) as we grade anonymously.</font> Including identifying information will result in a deduction from your assignment.**
Sign in with Wallet
Connect another wallet