This document contains the description for the C4 Alpha project assigned to the students in the Spring 2024 CSCI 1302 classes at the University of Georgia. Students who are assigned this project are expected to read the entirety of this project description file before beginning their project.
There are different deadline options for this project. Students who perform their final submission
via the submit command before the date/times listed below automatically receive some
Submission-Based (SB) extra credit. The late penalty does not start applying until after the final
date listed.
- Wednesday, February 7th @ 11:55 PM EST (+10 SB Extra Credit)
- Thursday, February 8th @ 11:55 PM EST (+5 SB Extra Credit)
- Friday, February 9th @ 11:55 PM EST (+0 SB Extra Credit)
Contents
This first CSCI 1302 project for Spring 2024 is designed to help you apply and extend your prerequisite Java programming knowledge with new concepts from CSCI 1302 in a Unix development environment (i.e., Odin).
If you are competent with the learning outcomes for CSCI 1301 (i.e., the prerequisite course), then you already have most of the Java programming knowledge required to complete this project; otherwise, this assignment will help you identify the gaps in your prerequisite programming knowledge so that you can tackle those gaps early in the semester. We also recommend completing the Tic-Tac-Toe Assignment before beginning this project.
This project will also require you to apply some of the new concepts covered in CSCI 1302, including named packages, exception (creating and handling), and Java development in a Unix environment. If you have actively engaged with the CSCI 1302 course content offered so far this semester, then you should be able to comfortably, but not necessarily quickly, complete those aspects of the project by applying what you have practiced and learned from your content engagement.
Finally, this project may require you to do things that you have never been given explicit directions or instructions for — this is just a part of software development. In such cases, you may need need to do some research to help you plan your solution. That being said, we have carefully prepared this project description document so that it hopefully answers the majority of your questions. If not, then please do not hesitate to ask a question on the course Piazza or during office hours.
All students at the University of Georgia explicitly agree to abide by the UGA student honor code when they sign the application for their admission to the University. Additionally, all students enrolled in a CSCI 1302 course section in Spring 2024 are subject to the Academic Honesty policy included in the Spring 2024 CSCI 1302 course syllabus. Furthermore, anyone with access to this project description document is expected to respect the copyright and licensing terms provided or linked to at the bottom of this document.
With academic honesty in mind, we ask all Spring 2024 CSCI 1302 students not to fork this repository on GitHub. Doing so may make your copy of the project publicly visible, and that can violate several of the policies described earlier. Instead of forking the repository, please follow the instructions provided later in this document to acquire a copy of the project description and starter code.
If you work on and complete this project, then you will gain exposure and practice with the following learning outcomes:
| # | Exposure | Description |
|---|---|---|
| LO1.a | ⭐⭐ | Navigate and modify files, directories, and permissions in a multi-user Unix-like environment. |
| LO1.b | ⭐ | Execute, redirect, pipe, and manage programs/processes in a multi-user Unix-like environment. |
| LO1.c | ⭐⭐ | Create and modify text files and source code using a powerful terminal-based text editor such as Emacs or Vi. |
| LO1.d | ⭐⭐ | Use shell commands to compile new and existing software solutions that are organized into multi-level packages and have external dependencies. |
| LO2.b | ⭐⭐ | Define, throw, and propagate exceptions appropriately in a software solution. |
| LO3.a | ⭐⭐ | Create and update source code that adheres to established style guidelines. |
| LO3.b | ⭐ | Create class, interface, method, and inline documentation that satisfies a set of requirements. |
| LO7.c | ⭐ | Use common abstract data types and structures, including lists, queues, arrays, and stacks in solving typical problems. |
If your instructor updates the project's requirements or starter code before the project is due, then this section will be updated to include a summary of those updates and, if needed, instructions that describe how to update your working copy of the project with the latest versions of any changed files.
In this project, you will implement and test a class that represents the popular board game Connect Four. Connect Four is a two-player connection game involving a two-dimensional grid of tokens. Here are the basic rules for Connect Four:
- To prepare a new game of Connect Four, the grid is setup to accommodate an acceptable number of rows and columns; however, it should not yet contain any tokens.
- To get ready to play, both players are assigned a unique token.
- To play the game, both players take turns "dropping" copies of their token into non-full columns in the grid. When a token is dropped, it falls to the lowest position in the column that does not yet contain a token.
- To win the game, a player must strategically drop their tokens so that four of them connect inside the grid — they are allowed to connect horizontally, vertically, and diagonally.
- The game is over once all positions in the grid a filled or when a player wins the game.
The class that you will implement and test will be expected to provide the high-level functionality described above via its constructor and instance methods — the specific details about what is required are included later in this document. What you are about to read may seem counter-intuitive, but you will not be writing any code for this project to let users interactively play a game of Connect Four; instead, you will implement and test a class that, once fully implemented, can be used to make writing such an interactive program easier. This is similar to what you did in the Tic-Tac-Toe assignment earlier this semester.
You will not be starting from scratch. Instead, starter code is provided that you will need to download to get started, then modify and test to meet the project's requirements. To download the starter code, follow these instructions:
Login to Odin.
If you have not done so, we recommend creating a separate directory inside of your home directory to store all of your CSCI 1302 projects instead of having them all directly inside your home directory.
Change to your CSCI 1302 projects directory.
Execute the following command to download the starter code into a sub-directory called
cs1302-c4-alpha:$ git clone --depth 1 https://github.com/cs1302uga/cs1302-c4-alpha.git
Change to the
cs1302-c4-alphadirectory that was just created, then use thetreecommand to verify that you now have a copy of the starter code undersrc:$ tree src src └── cs1302 └── game ├── ConnectFour.java ├── ConnectFourCLI.java └── ConnectFourTester.java
To help you with planning out this project, here are some suggested steps you can take that your instructors believe will help you complete the project more easily. Some of the items in this checklist may not make sense until you have read the entire project description. These steps are suggestions and, therefore, do not constitute an exhaustive list of the steps that you may need to take to complete the project.
| Target: | Finish before Thursday, Jan. 25th. |
|---|
- Read through the entire project description, including any appendices, and write down questions as you go.
- We recommend reading the project description again. A second read-through will help you fill in gaps in your understanding and you may be able to answer some of the questions you wrote down during your first read-through.
| Target: | Finish before Monday, Jan. 29th. |
|---|
- If you have not yet done so, download the starter code on Odin.
- Read all of the comments included in
src/cs1302/game/ConnectFour.java, but do not write any code yet! Instead, try to list out the high-level steps for the constructor and methods using a sequence of distinct steps that you can turn into code later. - Read through the notes you just wrote. If you see that the steps you wrote for one method include a sequence of steps in another method, then consider whether you can have one method can call the other — that's code reuse which will greatly minimize bugs in your code! If you see the exact same steps in several methods, you should consider factoring out the common parts into a single, separate method that you can call from both places — that's code reuse and refactoring!
- Read all of the comments included in
src/cs1302/game/ConnectTester.java.
| Target: | Finish before Sunday, Feb. 4th. |
|---|
- Implement the
ConnectFour(int, int)constructor, ensure it's written with good code style, then test it by writing a few lines of code in thecs1302.game.ConnectFourTesterclass to make sure the constructor only throws an exception when the board size is too large/too small. Also, your code should print out the instance variables of theConnectFourobject to make sure they are consistent with the diagrams in this document.- There are a few example test methods given in
ConnectFourTester.java. However, those methods are not currently called from themainmethod. The provided tests are meant to test the full gameplay which requires all methods to be implemented. We will revisit this in a later step below.
- There are a few example test methods given in
- Implement the
getRows()andgetCols()methods, ensure they are written with good code style, then test them by adding test code to thecs1302.game.ConnectFourTesterclass in a manner that is consistent with your constructor test code. You will want to, at a minimum, print out the return value from valid calls togetRowsandgetColsalong with the instance variables from theConnectFourobject to make sure they are consistent. - Repeat this process to implement, check code style, and test the remaining methods in the
order that they appear in the
ConnectFour.javastarter code. - As mentioned in the comments in
ConnectFourTester.java, the provided tests do not cover all of the input scenarios that need to be tested. You should add methods to test additional scenarios. Please note that you can also test your code using thecs1302.game.ConnectFourCLIclass and by using input redirection as discussed in class.
| Target: | Finish before Wednesday, Feb. 7th. |
|---|
- Do one final pass through the project document to make sure that you didn't miss anything.
- Run your code through your test cases one last time.
- Check your code style.
- Run your code through the
ConnectFourTester.javaprogram and ensure that all of your test cases are passed. - Play your game using the provided
ConnectFourCLI.javaprogram. - Check your code style one last time.
- Submit your code on Odin.
A functional requirement defines a specific behavior between program inputs and outputs, and a collection of functional requirements describes how a program should function. If your submission satisfies a functional requirement listed in this section, then the requirement's point total is added to your submission grade.
The cs1302.game.ConnectFour class is one of the classes that you are responsible for
implementing and testing. When you downloaded the starter code, a partially implemented version of
this class was included under the project's src directory:
| Source: | src/cs1302/game/ConnectFour.java |
|---|---|
| FQN: | cs1302.game.ConnectFour |
| Package Name: | cs1302.game |
| Simple Name: | ConnectFour |
When you implement this class, you will not have much leeway in terms of the class's overall design; however, you are free to add additional instance methods, as needed, to improve readability and code reuse. The specific details regarding what you are explicitly not permitted to do are explained later in the Non-Functional Requirements section.
It should also be noted that the ConnectFour class depends on some classes that we have included
in lib/cs1302-gameutil.jar. You do not have access to the source code for the classes in that Java
ARchive (JAR) file; however, API documentation for those classes is provided here. The
compilation instructions that we include below will ensure that these dependencies are available
on the classpath so that the compiler can find them.
To compile ConnectFour.java, execute the following command while directly inside the
cs1302-c4-alpha directory:
$ javac -cp lib/cs1302-gameutil.jar -d bin src/cs1302/game/ConnectFour.java
Once compiled, you can begin to test the ConnectFour class by modifying and running the
provided tester class.
Your implementation of cs1302.game.ConnectFour is expected to support the multiple phases
defined by the cs1302.gameutil.GamePhase enumeration. When a ConnectFour game object is constructed, it's
said to be in the GamePhase.NEW phase — that just means that GamePhase.NEW is assigned
to the object's phase instance variable. The game object may move into other phases as methods
are called on it. The behavior of some methods depends on the phase the object is in when called.
Here is a high-level overview of all the required phases and the methods that trigger a game
object to change what phase it is in:
The details for each game phase are provided below:
A newly constructed game is in this phase.
When a ConnectFour object is created, the constructor should check for any exceptional cases,
then initialize the object's instance variables to the values described below:
rows: | the supplied value of the rows constructor parameter |
|---|---|
cols: | the supplied value of the cols constructor parameter |
grid: | a two-dimensional Token array with rows-many rows and cols-many columns |
player: | a one-dimensional Token array of length 2 |
numDropped: | the int value 0 |
lastDropRow: | the int value -1 |
lastDropCol: | the int value -1 |
phase: | GamePhase.NEW |
Below is an example of some code that constructs a game object with six rows and seven columns followed by an illustration of what the inside of that object should look like when it's done being constructed:
ConnectFour game = new ConnectFour(6, 7);
A game that is ready to be played is in this phase.
A game object that is in the GamePhase.NEW phase should move into the GamePhase.READY
phase when its setPlayerTokens method is called for the first time.
Below is an example of some code that sets the player tokens of a game object in the
GamePhase.NEW phase followed by an illustration of what the inside of that object
should look like immediately after the code has executed and the object is in the
GamePhase.READY phase:
game.setPlayerTokens(Token.RED, Token.BLUE);
A game that is being played is in this phase.
A game object that is in the GamePhase.READY phase should move into the GamePhase.PLAYABLE
phase when its dropToken method is called for the first time.
Below is an example of some code that drops several tokens into the grid of a game object
in the GamePhase.READY phase. Each line of code is followed by an illustration of what
the inside of that object should look like immediately after the line has been executed.
Please note that the object is in the GamePhase.PLAYABLE phase immediately after
the first line has executed:
game.dropToken(0, 0); // first player, column 0
game.dropToken(1, 1); // second player, column 1
game.dropToken(0, 1); // first player, column 1
game.dropToken(1, 2); // second player, column 2
A game that has ended is in this phase.
A game object that is in the GamePhase.PLAYABLE phase should move into the GamePhase.OVER
phase when its isLastDropConnectFour method is called and one of the following conditions
are met:
- the grid is full; or
- the method is about to return
truebecause the last drop created a connect four.
Consider the following illustration of a game object that is currently in the
GamePhase.PLAYABLE phase:
Below is an example of some code that drops a winning token into the grid of the game object
depicted above, then checks for that win using the object's isLastDropConnectFour method.
The code is followed by an illustration of what the inside of that object should look like
immediately after the code has been executed. Please note that the object moves into the GamePhase.OVER
phase immediately after the last call to isLastDropConnectFour() has executed:
game.dropToken(1, 4); // second player, column 4
if (game.isLastDropConnectFour()) {
System.out.println("second player has won!");
} // if
| Implementation (100 points): | Your After the due date, it will be tested using several test cases that you will not have access to ahead
of time. The test methods that you write in your |
|---|
The cs1302.game.ConnectFourTester class is where you will write code to test your
cs1302.game.ConnectFour class. When you downloaded the starter code, a partially
implemented version of this class was included under the project's src directory:
| Source: | src/cs1302/game/ConnectFourTester.java |
|---|---|
| FQN: | cs1302.game.ConnectFourTester |
| Package Name: | cs1302.game |
| Simple Name: | ConnectFourTester |
You should use this tester class to help you test the constructor and methods of
your ConnectFour class under different scenarios. In many respects, you have a lot
of leeway. The specific details regarding what you are explicitly not permitted to do are explained
later in the Non-Functional Requirements section.
It should also be noted that the ConnectFourTester class depends on some classes that we have included
in lib/cs1302-gameutil.jar. You do not have access to the source code for the classes in that Java
ARchive (JAR) file; however, API documentation for those classes is provided here. The
compilation instructions that we include below will ensure that these dependencies are available
on the classpath so that the compiler can find them.
To compile ConnectFourTester.java, you need to first (re)compile ConnectFour.java, then
run the following command directly inside the cs1302-c4-alpha directory:
$ javac -cp bin:lib/cs1302-gameutil.jar -d bin src/cs1302/game/ConnectFourTester.java
Once compiled, you can run cs1302.game.ConnectFourTester using java:
$ java -cp bin:lib/cs1302-gameutil.jar cs1302.game.ConnectFourTester
There are no functional requirements for cs1302.game.ConnectFourTester. Just keep in mind that
you are expected to use it to help you test your code.
The cs1302.game.ConnectFourCLI class provides a command-line program to let users play your
game. When you downloaded the starter code, an implemented version of this program was
included under the project's src directory:
| Source: | src/cs1302/game/ConnectFourCLI.java |
|---|---|
| FQN: | cs1302.game.ConnectFourCLI |
| Package Name: | cs1302.game |
| Simple Name: | ConnectFourCLI |
This command-line program does not replace the testing that you are asked to do in ConnectFourTester. Instead,
it is provided to give you a way to play your game, assuming it is implemented properly. It may also help you
when you debug your code.
To compile ConnectFourCLI.java, you need to first (re)compile ConnectFour.java, then
run the following command directly inside the cs1302-c4-alpha directory:
$ javac -cp bin:lib/cs1302-gameutil.jar -d bin src/cs1302/game/ConnectFourCLI.java
Once compiled, you can run cs1302.game.ConnectFourCLI using java:
$ java -cp bin:lib/cs1302-gameutil.jar cs1302.game.ConnectFourCLI
There are no functional requirements for cs1302.game.ConnectFourCLI. Just keep in mind that
you are expected to use it to help you test your code.
A non-functional requirement specifies criteria that can be used to judge your submission independently from its function or behavior. If functional requirements describe what your submission should do, then the non-functional requirements describe how your submission is supposed to be. If your submission does not satisfy a non-functional requirement listed in this section, then the requirement's point total is deducted from your submission grade.
This project must compile and run correctly on Odin using the specific version of Java that is enabled by the CSCI 1302 shell profile, and your directory structure and package structure should match the structure of the starter code.
- You should NOT modify the location of any of the provided
.javafiles. - You should NOT modify the package statement in any of the provided
.javafiles. - The location of the default package for source code should be a direct sub-directory of
cs1302-c4-alphacalledsrc. The only.javafiles that you should include are your modified versions of the ones in the starter code — you should NOT add any additional source code files. BothConnectFour.java,ConnectFourTester.java, andConnectFourCLI.javaare expected to compile on Odin using the commands provided in the compilation instructions that are included earlier in this document. - The location of the default package for compiled code should be a sub-directory of
cs1302-c4-alphacalledbin. If you include compiled code with your submission, then it will be ignored. Graders are instructed to recompile your submission on Odin code before testing your submission.
If a problem is encountered for your submission that is explicitly described above, then 100 points will be subtracted from your earned point total; however, if the problem is compilation-related or structure-related and NOT explicitly described above, then it will be handled on an individual basis.
Every .java file that you include as part of your submission for this project must
be in valid style as defined in the
CS1302 Code Style Guide.
All of the individual code style guidelines listed in the style guide document are considered
for this requirement.
If check1302 on Odin reports any style violations for your submission, then
5 points will be subtracted from your earned point total for each
violation, up to a maximum deduction of 20 points.
You will submit your project on Odin. Before you submit, make sure that your project files are
located in a directory called cs1302-c4-alpha. If you followed the instructions provided earlier in this
document to download the project, then that is your directory name. To submit, change into the
parent of your project directory (i.e., one directory above it), then complete the steps below:
Check your code style — we know that you have done this frequently, but it does not hurt to double-check it before you submit:
$ check1302 cs1302-c4-alpha
If there are style violations, then fix them and retest your code!
Once you have no style guide violations and your code compiles and works, you can submit your work using the following command:
$ submit cs1302-c4-alpha csci-1302
Inspect the output of the last command to verify that your project was submitted. Your
cs1302-c4-alphadirectory should now contain arec(receipt) file.
If you have any problems submitting your project then please contact your instructor as soon as possible; however, doing this the day or night the project is due is probably not the best idea.
In Java, .jar files are Java™ Archive (JAR) files that bundle multiple files into a single
compressed file. Typically a JAR file contains the package directories and .class files for
a library. This is just like the bin directory that you are used to, except it is all bundled
into a single file. For example, the lib/cs1302-gameutil.jar file contains the package directories
and .class files for the classes and enumerations defined in cs1302.gameutil package. If you
are in the cs1302-c4-alpha directory, then you can use the following command to take a peek into the
archive:
$ jar -tf lib/cs1302-gameutil.jar
You should notice that the top-level directory in the JAR file is cs1302, which means that
the JAR file itself can serve as the default package for compiled code — this is why we use -cp
in examples given elsewhere in this project description.
Copyright © Michael E. Cotterell, Bradley J. Barnes, and the University of Georgia. See LICENSE.rst for license information. The content and opinions expressed on this Web page do not necessarily reflect the views of nor are they endorsed by the University of Georgia or the University System of Georgia.