Specifications
Specifications
Specifications
version 1.25
Table of Contents
1. Some Basics
2. Terminology
3. UML Structure
4. Specification
5. Rule Clarifications
1. Some Basics
In this coursework we'll be asking you to implement a card game, Kim-Joy's Magic Bakery. This
coursework implements almost all the rules of the basic game and we've provided the original rules
document. This coursework does not require you to implement the Scenarios (i.e., you can ignore pages
8-22 of the rules PDF -- but pay attention to the important note about Playing without Scenarios on
page 23). You are also not required to implement the double-value associated with scoring the
Showstopper Cake (the card is still present in the game, but it counts only as one Customer order if
completed). You are also not required to implement the variant of the take ingredient action in which
players take the unseen top card of the Pantry deck instead of drawing an upturned card in the pantry.
This document sets out the class and method structure that is required in your implementation. We'll
also try and clear up some potential ambiguities in the rules.
This document is pretty long, but you don't need to understand everything straight away. We suggest
reading it through once and then re-reading the relevant parts in more depth as you come to implement
the different parts of the game.
Reminder -- If you're struggling to know where to start, try working through the Getting
Started document.
2. Terminology
Collections -- We'll often use this term when referring to one or more classes that extend the
java.util.Collection interface.
Customer / customer order -- These terms are used interchangeably to refer to the cards
represented by the CustomerOrder class. These are the "25 Customer Cards" shown with blue
borders on page 1 of the Rules PDF.
Rules PDF -- The original 24-page game rules document, published by Skybound Tabletop.
Time passes PDF -- A separate one-page document providing a comprehensive set of worked
examples that show how customers are added to and move through the activeCustomers
structure within the Customers class.
3. UML Structure
The structure of the following UML class diagram informs the design of the application. Your
implementation must meet the structure provided in the UML diagram.
✔ You can choose to add classes, attributes, and methods not depicted in the UML (although substantial
extras should not be necessary).
✘ In contrast to Coursework 1, the git repository for Coursework 2 contains only the (empty) driver and
one additional Java source file ( StringUtils.java ). The expectation is that you will write the entire
source for all of the remaining classes described in the above UML.
✘ You should not change variable names, class/member modifiers, method parameters or return types.
✘ Note that the driver (and optional GUI application) should be placed outside of the package structure
(we've provided an empty driver in your repository).
✘ We've indicated some of the dependencies with standard Java library classes, but not all. The ones
that have been omitted should be obvious enough (e.g. List refers to the class with the same name
in the java.util package).
4. Specification
Most classes and methods are self-explanatory but the following description should resolve any
ambiguity.
The MagicBakery class is the primary container for the game state and represents a play through
the game. Get methods provide access to key attributes: the pantry and a Collection of players .
Note that the methods getLayers and getBakeableLayers should not return multiple
instantiations of the same layer.
1. Create a new MagicBakery instance. The three-parameter constructor should be used --- the
first parameter is used to initialise the Random object that is stored in the random attribute and
used when Collections of cards are shuffled. The next two parameters specify paths to files
describing the ingredient and layer cards respectively. (You can find these files in the io
directory of your repository.) These paths can be used in combination with the CardUtils class
to instantiate the pantryDeck and layers . The attributes pantry , pantryDiscard ,
and players should be instantiated with empty values. pantryDeck and
pantryDiscard should have LIFO semantics.
2. Use the startGame method to set up the gameplay based on the number of players, in
accordance with pages 2-3 of the rules PDF. This method takes in a List of playerNames ;
the players attribute should be instantiated with Player objects whose names match those
given in this parameter. A second parameter customerDeckFile specifies the path to a file
describing the customer order cards (you can find this file in the io directory of your repository).
This path should be used to create a new Customers object (see below for more information
about the Customers object. Following the creation of that object, the pantryDeck
should be shuffled once using the Random object stored in this.random and the pantry
should then be populated. One or two CustomerOrders should be drawn (depending on the
number of players). Each player then adds to their hand three cards from the pantryDeck (they
do this in turn, i.e. player A takes all three cards before player B takes any).
3. Each turn, the current player can take a number of actions (this is determined based on the number
of players and can be accessed using the ` getActionsPermitted method). While the
currentPlayer has actions left to take (as indicated by getActionsRemaining ), the
bakeLayer , drawFromPantry , passCard , fulfillOrder and refreshPantry
methods should be used to support the completion of those actions (described in pages 4-5 of the
rules PDF). Note that any cards drawn as a result of garnishing an order during fulfilment should be
added to the player's hand AND also returned by fulfillOrder .
A layer should only be baked if it is "bakeable", i.e., the current player has the required ingredients
(or has enough Helpful Ducks to substitute for any missing ingredients). Likewise, orders can only
be fulfilled or garnished if the cards in a player's hand mean that they are "fulfillable" or
"garnishable" respectively. Get methods for bakeable layers, fulfillable customers and garnishable
customers are included in the MagicBakery UML specification.
When baking a layer, a Layer card will move from this.layers to the current player's hand
-- the corresponding Ingredients will move into the pantryDiscard . When fulfilling an
order, the corresponding ingredients (which may be Ingredients or Layers ) are removed
from the player's hand -- ingredients move into the pantryDiscard , whilst Layers return to
this.layers . When baking a layer or fulfilling an order, a Helpful Duck should only be
removed from the player's hand if necessary to complete the operation (and only if the ingredient
they are substituting for is not an instance of Layer ).
For example, if the bakeLayer method is called and the parameter specifies that it is Pastry
that is to be baked then:
If the current player has a hand containing Butter, Flour and a Helpful Duck, then following the
call to bakeLayer the current player's hand should still contain the Helpful Duck.
If the current player has a hand containing Butter, Butter, Fruit and a Helpful Duck, then
following the call to bakeLayer the current player's hand should contain one Butter plus
the unused Fruit.
When drawing a card from the pantry ( drawFromPantry ), the named card moves into the
current player's hand. The rules state that:
If there’s nothing in the Pantry you want to draw, you may use this action to take the top card
of the Pantry deck.
However, for this implementation, you are not required to implement this option.
The space in the pantry that arises from a player drawing from the pantry is filled with the return
value from a call to drawFromPantryDeck . Note that despite the similarity in their names,
these are different operations that act over different attributes within the MagicBakery instance.
If, during any action, the pantryDeck runs out of cards, then any cards in pantryDiscard
should be removed and added to pantryDeck ; if this results in any cards being added to
pantryDeck , then this deck should then be shuffled once using the Random object stored in
this.random .
4. Once the player has run out of actions, the endTurn method should be used to move between
players (and between rounds if all players have taken a turn in this round). The endTurn method
returns a boolean indicating if there are more turns to follow this one (value is true ) or if the
game has ended (value is false ).
5. At any point, loadState and saveState methods in MagicBakery allow MagicBakery objects
to be serialised out to a file, saving and resuming in-progress games.
The printGameState method prints the information needed for a player to make decisions during
their turn. This includes all layers available for baking, the current contents of the pantry and
player's hand, and the collection of CustomerOrders that represent the customers currently waiting
in the bakery. Again, the format of this is up to you, mine looks like this:
The StringUtils class provides methods designed to make producing the above output easier --
we strongly advise that you use these rather than spend valuable time developing your own custom
layout methods.
printGameState and printCustomerServiceRecord can be called at any time but are most
likely to be useful at the start of a turn (and in the case of printCustomerServiceRecord , at the
end of the game).
The Customers class holds state about the CustomerOrder instances that are:
deckFile is the path to a file describing the customer order cards (see Operation #2 of
MagicBakery above);
random is the exact same Random object initialised in the MagicBakery (see Operation #1
of MagicBakery above) and should be retained in this class's random attribute;
layers is a collection of Layer objects that represent the layers that can be used as part of
CustomerOrder recipes;
and numPlayers is the number of players that were added in the call to
MagicBakery.startGame .
As part of the execution of this constructor, the inactiveCustomers attribute should be initialised
as an empty collection -- the ordering semantics of this collection are unimportant. The
activeCustomers attribute should be initialised with the semantics described in the separate Time
passes PDF. The customerDeck attribute is populated by the initialiseCustomerDeck
method (which takes three of the four parameters passed to the constructor). In this method, the
following things happen in order:
There are getter methods for activeCustomers and the customerDeck . Two non-standard get
methods are provided:
The core of the Customers class is activeCustomers , that is the customers currently in the
shop waiting to be served. As such, Customers provides several standard methods seen in other
data structures that tell us about these CustomerOrders . The isEmpty method returns true if
there are currently no customers in activeCustomers , the size method returns the number of
customers in activeCustomers , and the remove method removes the specified customer from
activeCustomers . The peek method returns the customer occupying the "rightmost" of the
three spaces in the shop (if there are three customers in the shop, then this will be the one who least
recently entered activeCustomers ), or null if there is currently noone in the rightmost of
the three spaces. Movement of customers through activeCustomers is handled by the methods
addCustomerOrder , customerWillLeaveSoon and timePasses , which are described in
the separate Time passes PDF.
The drawCustomer method does not operate over activeCustomers , but instead removes a
card from the customerDeck .
The CustomerOrder class is a representation of a Customer card. It includes its name , details of
the Ingredient s that make up the recipe and garnish , the difficulty level of the
Customer (a value from 1-3) and its present fulfilment status (see the section on The
CustomerOrderStatus Class below). The toString method allows access to the name attribute,
with additional getters provided for recipe , garnish , level and status (a setter is also
provided for status ). Two additional getters, getGarnishDescription and
getRecipeDescription allow recipe and garnish information to be returned in a
String format where each Ingredient (name) is comma-separated.
the parameter ingredients includes all required Ingredient s to fulfil and garnish the
order (or substitutes them with the appropriate number of Helpful Ducks), and
the garnish parameter is set to true
The fulfill method returns the subset of the ingredients that were used to fulfil (and
optionally garnish) the specified order. E.g. if ingredients contains flour and butter
and sugar , and the order requires only butter and sugar , then the return value of
fulfill will be a List containing the butter and sugar objects from the original
ingredients parameter.
The canFulfill and canGarnish methods provide an indication of whether the parameter
ingredients includes all required Ingredient s to fulfil or garnish the order respectively. Note
that in the latter case, the return value is only whether the order can be garnished -- it may still be
the case that the specified ingredients are not sufficient to fulfil the order. That is, a call to
canGarnish with a particular collection of ingredients may return true without a call to
fulfill with that same collection of ingredients successfully setting the status FULFILLED or
GARNISHED .
The ActionType enum represents the possible actions that can be taken in a turn:
DRAW_INGREDIENT (from the pantry), PASS_INGREDIENT (to another player), BAKE_LAYER
(using cards in hand), FULFIL_ORDER (using cards in hand) and REFRESH_PANTRY (from the
pantry deck).
The Ingredient and Layer classes represent the Ingredient and Layer cards of the game
respectively.
An Ingredient has a name , which can be accessed through the toString method.
A Layer has a name and recipe (the collection of Ingredients that are required to bake
the layer). The getRecipe and getRecipeDescription methods behave identically to their
counterparts in the CustomerOrder class. The canBake method provides an indication of
whether the parameter ingredients includes all required Ingredient s (or Helpful Duck
substitutes) to bake the layer.
Ingredient s and Layer s can be sorted and compared. Two objects are considered equal if they
share the same name , and sort behaviour should be to sort the ingredients based on the ASCII values
of their names . That is:
Ingredient s and Layers provide a hashCode method that ensures they can be used in, e.g.,
the HashSet data structure. We suggest that you derive the hashcode from an Ingredient 's
name and Layer 's name and recipe . The following things from the Java documentation of
Object.hashcode are worth repeating here:
Whenever it is invoked on the same object more than once during an execution of a Java
application, the hashCode method must consistently return the same integer, provided no
information used in equals comparisons on the object is modified. This integer need not
remain consistent from one execution of an application to another execution of the same
application.
If two objects are equal according to the equals method, then calling the hashCode method
on each of the two objects must produce the same integer result.
It is not required that if two objects are unequal according to the equals method, then calling
the hashCode method on each of the two objects must produce distinct integer results.
However, the programmer should be aware that producing distinct integer results for unequal
objects may improve the performance of hash tables.
As far as is reasonably practical, the hashCode method defined by class Object returns
distinct integers for distinct objects.
The Ingredient class provides a constant HELPFUL_DUCK which should have a value equal to
the name of the Helpful Duck card.
The Player class represents a player of the game. As indicated in the rules, The Magic Bakery can
be played by 2-5 players.
Each Player is instantiated with a name and empty hand of Ingredient s. The
toString method returns the Player 's name .
The hasIngredient method indicates whether or not a Player currently holds a specified
Ingredient in their hand.
The util package contains three classes: CardUtils and ConsoleUtils are specified in the
UML and (as with the bakery package) you are expected to implement them. StringUtils is
also specified in the UML but we have also provided you with a complete implementation of that class.
CardUtils
The CardUtils class provides methods for reading different types of card ( CustomerOrder ,
Ingredient , Layer ) from file. Note that the methods are all static, and so the expectation is that
you will prevent calls to instantiate the CardUtils class.
Console Utils
ConsoleUtils provides methods relating to Console input. Unlike the other util classes, it
is intended to be instantiated -- it's constructor initialises the console attribute.
The two readLine methods in ConsoleUtils are a direct mirroring of those provided by its
console object.
The remaining methods are intended as convenience methods for common input operations and should
not return until a valid input has been received. All of these methods include a String prompt among
their parameters. This prompt is the text that is used to tell the players what text they are expected to
input. For example, a call to promptForYesNo with a prompt paramter of
"Do you like mushrooms?" would be expected to print the following:
Do you like mushrooms? [Y]es/[N]o
The promptForFilePath method prompts for a file path and returns a new File object
representing that path -- it does not need to check the validity of that path.
The promptForNewPlayers method prompts for 2-5 player names, and returns them as a List
of String objects. It should not be possible to have two players with identical names, even if the
cases used in those names are different.
StringUtils
The StringUtils class provides methods for manipulating Strings and formatting different bakery
object types as Strings. We have provided a complete implementation of all the specified methods
in this class. Note that the methods are all static, and so the constructor in StringUtils never
needs to be called (we have therefore made it private). Key methods in this class are:
customerOrdersToStrings , ingredientsToStrings , and layersToStrings each
return a List of String s; when printed, these Strings will provide a full representation of the
CustomerOrder , Ingredient or Layer objects that were passed as a paramter. That is,
iteratively printing the returned Strings will result in layers, ingredients and orders being printed as in the
screenshot that appears in the MagicBakery portion of this specification document. These methods
all make calls to formatTextAsCardsString to assemble the text into a String representing
multiple cards layed out side-by-side and separated by the CARD_VERTICAL_LEFT and
CARD_VERTICAL_RIGHT separators.
The centreString method is used to pad a given String so that it appears centred in a string of the
specified width. The padString method behaves similarly, but in this case the specified String will
be left-aligned within the return value.
The splitString method splits a String into mutiple substring chunks where the longest chunk is
not more than width characters in length. This is used by the customerOrdersToStrings ,
ingredientsToStrings , and layersToStrings methods to divide their content over multiple
lines.
The replaceLast method replaces the last occurance of the specifed target substring within a
String. If the target isn't present within the specified string, then the original string is returned. The
toTitleCase method converts the given comma-separated string to one in which each comma-
separated element begins with an uppercase letter and the rest is lower case. E.g. BLUE, moon
becomes Blue, Moon .
The above methods amount to a significant amount of code, and we do not suggest that you try
to understand it all. Instead, we expect that your code will need to make calls to:
customerOrdersToStrings
ingredientsToStrings
layersToStrings
Thus, you should understand how to call these three methods and their return values. You should
be able to achieve this with a bit of experimentation, there's no need to understand their implementation.
Error Handling
The loadState method of MagicBakery will need to throw appropriate exceptions if there are
problems reading the specified file or if that file does not contain a valid MagicBakery instance.
Trying to garnish an order without all of the required ingredients (or the appropriate number of Helpful
Ducks) could result in a WrongIngredientsException but this is not required. If this exception
isn't thrown, then a sensible fallback behaviour should be used (e.g. fulfilling but not garnishing the
order).
The EmptyPantryException is an unchecked exception that should occur only when the
MagicBakery 's pantryDeck is completely empty, even after merging the pantryDeck and
pantryDiscard . If this happens, players will need to bake with the Ingredient cards that they
hold in their hands.
In addition to the above functionality, this coursework will require you to:
Organise your code into packages (see Chapter 19 of the course textbook). Package util
contains the helper classes for String and file operations. Package bakery contains game-
specific classes (ingredients, customers, players, errors, and the game engine).
Use Javadoc to document your code (see Chapter 11 of the course textbook). You should Javadoc
all public and protected classes, and all public and protected members. There are some examples
of Javadoc in the provided StringUtils class.
5. Rule clarifications
Taking actions
The number of actions a player may take per turn is described on page 4 of the rules PDF. For the
purposes of this coursework, players must take exactly this number of actions.