SWEN30006 Software Modelling and Design
Project 2: Lucky Thirteen
- Project Specification -
School of Computing and Information Systems
Semester 1, 2024
1 Background
The JQK Computer Game Company (JQK) observes a steep increase in a popularity of card games. The company foresees abright future of digital card games and aims at exploring this opportunity. While there exist many card games already, the company decides to create yet another card game called Lucky Thirteen.
A software team at JQK has started to develop a framework for this new digital card game. The code does work to some extent. However, it was implemented in a rush and was not properly designed. JQK has recruited you and your team to revise the existing design and codebase as well as extending the framework to also include additional logic and features to make the game even more exciting.
2 Rules for the Lucky Thirteen Games
The Lucky Thirteen (LT) game play is briefly described below. The current program developed by JQK already supports this behaviour.
• The game is played with a standard 52-card deck with four suits, each having thirteen ranks.
• Each rank is associated with a numerable value where
。 For summing during the game: Number cards represent as is (i.e., 2 is two). For picture cards, ‘A’ can represent either zero or one, while ‘J’, ‘Q’, ‘ K’ can be 10, 11, 12, or 13.
。 For scoring after the game: Number cards score according to its numerable value (i.e., 2 is
worth two points). For picture cards, ‘A’, ‘J’, ‘Q’, ‘K’ score 1, 11, 12, 13 points respectively.
(See Table 1 for a summary)
• The goal of a player is to have the sum of the value of the cards to thirteen (see below for more details about the summation).
• The game involves four players who play independently.
• All cards are dealt face down. Note that the software version deals the cards face up to make it easy for developers to see what is going on. However, computer players should not be able to “see” the cards of the other players.
• At the start of the game, all 52 cards areshuffled. Two cards are dealt from the pile and put face up (every player can see these cards). These two cards are referred to as public cards. Then, two cards are distributed to each player (players cannot see each other cards), these cards are called private cards. A total often cards are dealt from the pile at this step.
• The game consists of four rounds. Each round, each player deals one card from the pile and discards one card of their choice. Note that a player can choose to discard any of the three private cards in their hand, and every player can see the discarded card.
• Player 0 always starts first. The game then proceeds clockwise.
• At the end of the fourth round, each player sums the value of the private cards (regardless of the suit) in their hand or combines with the public card(s) dealt at the beginning of the game to achieve the summation of thirteen. The summation can only be one of the following two scoring options (see also Table 2):
。 Option1: Two private cards in their hand.
。 Option2: One private card in their hand and one card from the two public cards. Note that the game automatically checks these two options.
• There are three cases to assign scores to a player. Note that each case considers both scoring options mentioned above.
。 Case1: If there is only one player who achieves the sum of exactly thirteen, that player wins the game and gain a score of 100 points. In other words, only one player receives a score. The other three players’ score remains zero.
。 Case2: If no player has the sum of thirteen, each player receives a score of the sum of the two private cards in their hand according to the following calculation:
. Each suit corresponds to a multiplication factor as follows: spade (♠) x 4, heart (♥) x 3, diamond (♦) x 2, club (♣) x 1.
. A number cardscore as is. Picture cards score as follows: A = 1, J = 11, Q = 12, K = 13.
. Example 1: A player with 8-heart and 5-club would receive a score of 8x3 + 5x1 = 29 points. Note that in this case, all players receive a score.
。 Case3: If more than one player achieves the sum of thirteen, those players receive a score from the cards that add up to thirteen according to the score calculation above. If the public card is used, the multiplication factor is always 2 regardless of the suit. If a player can sum the cards in different ways to thirteen, the calculation should maximize the score (see Example 3a below) .
. Example 2: The score of 7-club (in hand) together with 6-club (from public cards) is 7x1 + 6x2 = 19.
. Example 3a: A player has J-diamond and A-heart. The public cards are 5-spade and 2- diamond.
• [Option1] Two cards in hand:
。 Scoring: J is 11 and A is 1 -> 11x2 + 1x3 = 25
• [Option2] One card in hand and one public card:
。 Summing: J as 11 -> 11 + 2 = 13
。 Scoring: J is 11 -> 11x2 + 2x2 = 26
• The player earns the score of 26 since it is the highest.
Note that in this case only the player(s) whose sum is thirteen may receive scores. The score of the other players remains zero.
• The winner and the score obtained are displayed on the screen.
The LT program currently supports two types of players: human interactive player who selects the card to play through a double-left-mouse-click, and random computer player who selects a card to discard at random. The current configuration is always one human at position 0 and three random players at the other positions.
3 Your Task
You task is to improve the design of LT game, refactor the existing codebase, and implement additional logic/features as follows:
1) Ensure that all player types (see below) follow the rules of LT listed above.
2) Add another option to sum the card to thirteen, namely,
Option3: Two cards in their hand and two cards from the two public cards.
Note that there is now a total of three options to sum the card to thirteen.
Example 4: The score for 2-diamond and 4-heart (in hand) together with 5-spade and 2-club (from public cards) is 2x2 + 4x3 + 5x2 + 2x2 = 30.
3) If more than one player achieves the sum of thirteen (Case3), the score calculation must consider all three options to sum the cards to thirteen and a player will receive the maximum among those three (see also Table 2).
Example 3b: A player has J-diamond and A-heart. The public cards are A-spade and 2-diamond.
. [Option1] Two cards in hand:
• Summing: J as 12 and A as 1 -> 12 + 1 = 13
• Scoring: J is 11 and A is 1 -> 11x2 + 1x3 = 25
. [Option2] One card in hand and one public card:
• Summing: J as 11 -> 11 + 2 = 13
• Scoring: J is 11 -> 11x2 + 2x2 = 26
. [Option3] Two cards in hand and two public cards:
• Summing: J as 11 and both A’s as 0 -> 11 + 0 + 0 + 2 = 13
• Scoring: J is 11 and both A’s is 1 -> 11x2 + 1x3 + 1x2 + 2x2 = 31
. The player earns the score of 31 since it is the highest.
4) Support four player types: human, random, basic, clever
a) Human player’s behaviour should not change from that supported by the current framework.
b) Random computer player’s behaviour should not change from that supported by the current framework.
c) Basic computer player discards a card with the lowest value where A (=0) < 1 < 2 < 3 < ... < 10 < J (=11) < Q (=12) < K (=13) and club (=x1) < diamond (=x2) < heart (=x3) < spade (=x4). This means that if the basic player has 6-spade and 7-diamond, the player will discard 7-diamond since 7x3 = 21 < 6x4 = 24.
d) Clever computer player must keep track of all the cards played and use this information together with the knowledge of the cards in its hand to try to maximize its score. The clever player must produce cleverer play than the basic and random players. (You will have to explain how your design supports the clever play.)
5) Load appropriate game parameters from the property files. You must support configuring the player types in the property file using identification of the form. “players.0=clever” for the full set of player types {human, random, basic, clever} and player positions {players.0, players.1, players.2, players.3}. All properties you add must have default provided in the code (see setProperty() in main()).
4 Provided Package
4.1 Getting started
• The package is provided as an IntelliJ project in a GitHub repository:
https://classroom.github.com/a/CZL3V7l2
To access the base package and set up, you can follow the instructions in Workshop 0. Note that the project requires at least Java 19.
• Build and run the project: You will see the GUI appear and can play the current version of Lucky Thirteen using the mouse actions.
4.2 System design
• The classes in the provided ‘app/src/main/java’ package primarily handle the game behaviour where the GUI operates by using theJGameGrid library. You can refer to the classes and their functions in this framework inJava Doc.
o The required changes for this project relate only to the game behaviour. You should not need to modify any code pertaining to the GUI.
o Implementation hints: The JGameGrid library has provided many useful functions that you can reuse to implement the proposed extensions. The codebase should also provide examples for implementing the extensions.
• The system reads a properties file that specifies the player type for each of the four players, auto- play configuration (for testing purposes) and some of the cards the player will play in auto-play mode. You can edit the properties in these files for your own testing but make sure to preserve the default behaviour.
• The ‘logResult’ string in the LuckyThirteen class is for testing your system. Please see Section 4.3 Testing Your Solution for more details. Image files of characters and items are provided in the ‘sprites’ folder (app/src/main/resources/spites). The file names of these imagefiles must not be changed.
4.3 Testing Your Solution
• We will be testing your application programmatically, so we need to be able to build and run your program with a gradle build script. This is the same structure as the Workshop 0. You need to follow the following guideline for gradle build to work:
o You should use the gradle script. that we have set upvalid for you to run the project.
o The entry point must remain at Driver and the Driver file needs to remain at `src/main/java`.
o Whenever you pushto Github, Github should automatically build and run the test in your code with the testcases already provided by us in the project. You are not required to run the test in your local machine. When you are developing the app, please ensure that your code passes the testing when pushed to Github.
o Initially, your code will pass test case Original and fail test cases Extension. You need to implement the requirement and pass all testcases. Your code needs to pass the automatic tests as well as the manual tests that teaching staff will perform. on your final submission. For manual tests, we will run the app as a human player to play against random, basic and clever players.
o We have provided the sample log that the project needs to generate to pass the test case. Your log needs to follow the format but does not need to match the sample log 100%.
• You must not change anything in the test directory as we will overwrite all your changes with our default values when testing is executed. You must also not change the build.gradle and settings.gradle file as we will. It means that any other keys or values that you add into your properties files in the app directory will not work in testing.
• Four properties files are provided as samples for development (gameX.properties) and five properties files are provided as the key resources for testing (testX.properties).
• The auto mode may control some player for some card selections, and then it may stop after a few turns or a few rounds. When the auto mode stops the cardselection of a specific player, your program will need to take over and selects the cards for the player based on the player type (random, basic or clever).
• You need to ensure that any modification still preserves the original behaviour, i.e., logResult generated by your extended version can pass the testing that we provide.
• For your understanding, below are some key gradle build explanations. Note that you are not expected to change anything outside of your development directory and documentation directory:
o `settings.gradle`: to set up the name of the project and the main development directory
o `app/src`: where the development and testing code is
o `app/src/build.gradle`:set up the dependencies, the language version and the main class
o `app/src/main/java`: where your development code is
o `app/src/main/resources`: where your properties files and images are
o `app/src/test/java`: where the testing code is
o `app/src/test/resources`: where the properties files and images are
o To load a property or text file: you need to use
`CLASS_NAME .class.getClassLoader().getResourceAsStream(propertiesFil e)`. This is already done for you, so you only need to be aware of it if you need to read any other text file.
5 Project Deliverables
5.1 Your version of the LT game
Submit your whole project (with any/all libraries used included, with all the gradle structure and gradle setting files)
• Ensure that your code is well documented and includes your team's name and team members in all changed or new source code files.
5.2 Report
A design analysis report detailing the changes made to the project and the design analysis including identifying design alternatives and justifying your design decisions with respect to design patterns and principles (GoF and GRASP). The report must also include your strategy for Clever computer player.
5.3 Software Models
To facilitate the discussion of your design, the following software models should be provided in the report and used along with the discussion. You can use sub-diagrams or provide additional diagrams where appropriate.
• A domain class diagram for capturing the covering the domain concepts relating to computer players
• A static design model (i.e., a design class diagram) for documenting your design relating to computer players
• Additional static and/or dynamic design models to support your explanation as you judge useful and appropriate.
6 Submission
All project deliverables should be included in the one project zip file with the specified structure (see Figure 2). Do not include the .git folder in your submission. Only one member in the team submits the file. See more details about submission and evaluation on the project submission page.
Note: It is your team’s responsibility to ensure that you have thoroughly tested their software before submission.