Prepared for s4412090. Do not distribute.
The University of Queensland
School of Information Technology and Electrical Engineering
Semester Two, 2018
CSSE2310 / CSSE7231 - Assignment 3
Due: 11:10pm 28th September, 2018
Marks: 50
Weighting: 25% of your overall assignment mark (CSSE2310)
Revision 1.1
Introduction
In this assignment, you will write two types of C99 programs to run and play a game (described later). The
first type of program (players) will listen on their stdin for information about the game and give their actions
to stdout. These types of program will send information about the state of the game to stderr. The second
program (austerity — also known as the hub) will start a number of player processes and communicate with
them via pipes. The hub will be responsible for running the game (sending information to players; processing
their moves and determining the winner(s)). The hub will also ensure that information sent to stderr by the
players, is discarded.
You will produce a number of player programs (with different names) which implement different playing
strategies. However all players will probably share a large amount of common code (with the other players you
write).
Your programs must not create any files on disk not mentioned in this specification or in command line
arguments. Your assignment submission must comply with the C style guide (version 2.0.4) available on the
course blackboard area. This is an individual assignment. You should feel free to discuss aspects of C programming
and the assignment specification with fellow students. You should not actively help (or seek help
from) other students with the actual coding of your assignment solution. It is cheating to look at another
student’s code and it is cheating to allow your code to be seen or shared in printed or electronic form. You
should note that all submitted code may be subject to automated checks for plagiarism and collusion. If we
detect plagiarism or collusion, formal misconduct proceedings will be initiated against you. A likely penalty
for a first offence would be a mark of 0 for the assignment. Don’t risk it! If you’re having trouble, seek
help from a member of the teaching staff. Don’t be tempted to copy another student’s code. You should
read and understand the statements on student misconduct in the course profile and on the school web-site:
http://www.itee.uq.edu.au/itee-student-misconduct-including-plagiarism
As with Assignment 1, we will use the subversion (svn) system to deal with assignment submissions. Do not
commit any code to your repository unless it is your own work or it was given to you by teaching staff. If you
have questions about this, please ask.
While you are permitted to use sample code supplied by teaching staff this year in this course,
code supplied for other courses or other offerings of this course is off limits — it may be deemed
to be without academic merit and removed from your program before testing.
The game
The game consists of two or more players, a deck of cards and five piles of tokens. The token types are: Purple
(P), Brown (B), Yellow (Y), Red (R) and Wild. There are a limited number of tokens of each colour, while
there are an unlimited number of tokens in the Wild pile.
To begin the game, 8 cards are drawn from the top of the deck and placed face up. If ever a face up card is
bought by a player, a new card will be drawn from the deck (additional cards will not be drawn if the deck is
empty).
1
Prepared for s4412090. Do not distribute.
Cards
Each card has the following features:
? Cost to purchase (number of each colour is always a non-negative integer)
– Eg: 1P + 2B + 0Y + 0R
? Number of points the card is worth (always a non-negative integer)
– Eg: 2
? Colour, used for discounts on all future card purchases
– Eg: R
Players will be granted a single token discount of the card colour for each card they own. For example, a player
with three cards, one R and two B, will now have a discount of 1R and 2B. The discount will apply to all future
card purchases.
? Scenario 1:
Player A has two Brown and three Red cards. This means they have a discount of 2B and 3R. When
purchasing a card worth 3R, no additional tokens are required as the card discount of 3R has supplied
the cost of Red for this card.
? Scenario 2:
Player C has one Purple, three Brown and two Red cards. This means they have a discount of 1P, 3B and
2R. When purchasing a card worth 2P+1B+3Y, they will need 1 Purple and 3 Yellow tokens to make up
the remaining cost after applying their discount.
Player turns
On their turn, each player takes one of the following actions:
1. Purchase a card, by paying the token cost (applying any card discounts). Non-wild tokens to be used in
preference to wilds.
2. Take 3 tokens, each of a different colour. If two or more of the coloured piles are empty, this action will
not be possible.
3. Take a single wild token. (Wild tokens can be used to make up for missing tokens of any colour when
purchasing cards).
End of game
The game continues until a player reaches the specified number of points required for a win. Once a player
reaches this number of points, the round continues until all players have had their turn (this means all players
will have had the same number of turns at the end of the game). It is possible for multiple players to reach
the target number of points by the end of the game. The winners of the game are the players with the highest
number of points.
If the end of the deck is reached before players have reached the points required for a win, the game will
continue while there are still cards available for purchase. No new cards will be turned over, as there are none
to draw from. Remaining face up cards will continue to be available for purchase. Once all face up cards have
been purchased, the game will end. The winner(s) in this scenario are the players with the highest number of
points.
Game parameters
A game will require the following information:
1. A file storing the deck of cards to be used.
2. The number of tokens of each colour (this is a single value).
3. The number of points which triggers game end.
2
Prepared for s4412090. Do not distribute.
Deck file
The hub will use the deck file to load the available deck of cards for a game. Each card will be on a new line
within the file.
The structure for a card is: D:V:PP , PB, PY , PR
? D ∈ {P, B, Y, R} — The colour of discount this card gives.
? V — Number of points this card is worth.
? P? — Price of this card in the colour of tokens (can be zero)
For example:
B:1:1,0,0,0
Y:0:0,3,0,2
Invocation
Invocation — players
The parameters to start a player are (in order):
1. The number of players (in total).
2. The number of th?s particular player (starting at 0).
The maximum number of players permitted in a game will be 26.
The player will read game information from stdin and send its responses to stdout.
Invocation — hub
The parameters to start the hub are (in order):
1. The number of tokens in each of the (non-wild) piles. This is a non-negative integer.
2. The number of points required to trigger the end of the game. This is a non-negative integer.
3. The deck file to use.
4. Player programs to run. There must be at least two players.
For example:
./austerity 7 15 cards ./shenzi ./shenzi ./shenzi
would start a game having 7 tokens in each non-wild pile, requiring 15 points to trigger the end of game, using
the cards deck file, and with 3 players (each running ./shenzi).
Arguments should be parsed in the order specified above. The deck file should be loaded before attempting
to start player proceses.
The hub will be responsible for starting up the player processes and communicting with them via pipes to
stdin and stdout.
3
Prepared for s4412090. Do not distribute.
Message Representations
When the players and hub communicate, they must do so using messages encoded in the following way.
Messages from the hub to players
Encoded form Parameters Purpose
eog Inform player of end of game.
dowhat Ask the player for their choice of
action.
tokensT T — Number of tokens in each
non-wild pile.
Informs the player how many tokens
are in the non-wild piles.
Only sent at the start of the
game, before first round starts.
newcardD:V:TP , TB, TY , TR D ∈ {P, B, Y, R} — The colour
of discount this card gives
V — Number of points this card
is worth
T? — Number of each colour of
token this card costs (can be
zero)
Inform players that a card has
been drawn from the deck and
added to the board.
purchasedP:C:TP ,TB,TY ,TR,TW P — Player who submits the action
C — Card number (0 to 7)
T? — Number of each colour of
token involved in the purchase
Inform players that a card was
purchased.
tookP:TP , TB, TY , TR P — Player who submits the action
T? — Number of each colour of
token taken
Inform players that a player took
tokens.
wildP P — Player who submits the action
Inform players that someone
took a wild token.
Whenever player’s identity is communicated in messages, player 0 is indicated by ‘A’, 1 by ‘B’ and so on.
Cards are treated as being in a sorted list, oldest to newest (oldest is the first card to be available face up).
The card number references the position of the card in this list, with the oldest being 0 and the newest being 7.
Messages from players to the hub
Encoded form Parameters Purpose
purchaseC:TP , TB, TY , TR, TW C — Card number (0 to 7)
T? — Number of each colour of
token used
Purchase a card
takeTP , TB, TY , TR T? — Number of each colour of
token taken
Take tokens
wild Take a wild token
4
Prepared for s4412090. Do not distribute.
Output
The hub and players will print information explaining what is happening within the game while it is in progress.
Output — hub
The hub will print the following messages to standard out.
Event Output to stdout Parameters
Card added to market New card = Bonus D, worth V,
costs TP , TB, TY , TR
D ∈ {P, B, Y, R} — The colour of discount
this card gives
V — Number of points this card is
worth
T? — Number of each colour of token
this card costs (can be zero)
Player bought a card Player P purchased C using
TP , TB, TY , TR, TW
P — Player letter
C — Card number (0 to 7)
T? — Number of each colour of token
used
Player took tokens Player P drew TP , TB, TY , TR P — Player letter
T? — Number of each colour of token
used
Player took a wild Player P took a wild P — Player letter
Game ends early Game ended due to disconnect
Game over Winner(s) L L — comma separated list of winners
(sorted by player letter, smallest to
largest)
Eg. A,B,C
Output — players
After receiving each message, the players will send the following to standard error.
Message Output to stderr Parameters
eog Game over. Winners are L L — comma separated list of winners
(sorted by player letter, smallest to
largest)
Eg. A,B,C
dowhat Received dowhat
For each other valid message received (except those in the table above), display the following:
1. Display each card in the market (in order oldest to newest, each on a new line):
Card C:Bonus/Score/TP , TB, TY , TR
2. For each player (in position order, each on a new line):
Player letter:TotalPoints:Discounts=DP , DB, DY , DR:Tokens=TP , TB, TY , TR, TW
For example:
Card 0:B/3/0,0,2,1
Card 1:Y/1/1,0,0,0
Card 2:Y/2/0,2,0,1
Card 3:B/0/0,0,0,1
Card 4:R/4/3,2,0,0
Card 5:P/2/0,2,1,1
Card 6:R/1/1,0,0,1
Card 7:B/1/0,1,0,1
Player A:5:Discounts=1,2,0,1:Tokens=2,2,0,0,1,1
Player B:2:Discounts=0,4,3,0:Tokens=0,0,3,4,0,0
5
Prepared for s4412090. Do not distribute.
Hub
Game play
To commence the game, the hub will send all players the cards that have been turned face up using the newcard
message. After this, it will coordinate a number of rounds of the game, until the end condition is met. The
basic order of play in each round is:
1. Ask a player to choose an action
2. Inform other players of the chosen action
3. Move to next player and start process again.
When asking a player for an action, if the player sends an invalid response, the hub shall prompt the player
again for an action. If the player again responds with an invalid message (ie. the hub has received two invalid
responses in a row), the hub will then end the game with a protocol error.
Shutting down the hub
Upon completion of the game by any means, or in response to SIGINT, the hub must shutdown and exit.
Whether the hub shuts down in response to a SIGINT or of its own volition, it should follow the same procedure.
First, all child processes should be instructed that the end of game has been reached. The hub should then
ensure that all child processes have terminated. If they have not all terminated within 2 seconds of the hub
sending the end of game message, then the hub should terminate them with SIGKILL.
During shutdown, additional information may be printed out by the hub. These messages will only be
printed if certain conditions are met at the time of shutdown. If the conditions are not met, no information will
be printed out during shutdown. The conditions that need to be met:
1. all children started successfully.
2. the hub is shutting down normally (not as a result of SIGINT).
When these conditions are met, for each player (in order), the hub will do one of the following:
1. If the process terminated normally with exit status 0, then don’t print anything.
2. If the process terminated normally with a non-zero exit status, then print (to stderr):
Player ? ended with status ?
3. If the process terminated due to a signal, then print (to stderr):
Player ? shutdown after receiving signal ?
The ? placeholders should be filled in with the appropriate values.
Players
The following describes players which you will create. This does not mean that every player your hub is run
with will be one of these three.
Type A - shenzi
The executable for this player will be called: shenzi
Makes decisions as follows:
1. If you have enough tokens to buy a card, buy one. Choose the card worth the most points. If there are
multiple cards which you can afford, prioritise cards as follows. Stop when one of these gives a single
choice: