11 —
Due Sunday, 3 April, midnight
Your software architect has decided that the remainder of step 4 in an Evolution turn is so complicated that it deserves its own development stage. It is also time to design an interaction protocol with external players, that is, players written in the same language and linked into your program statically.
Changed in version 1.4: Sun Apr 3 17:58:08 EDT 2016
added delivery instructions for task 2 (thanks Alp)Changed in version 1.3: Wed Mar 30 09:38:39 EDT 2016
added constraints for GP and GBChanged in version 1.2: Mon Mar 28 21:34:32 EDT 2016
JSON input modifiedChanged in version 1.1: Mon Mar 28 20:49:39 EDT 2016
responses to Alex and Lydia’s commentsAdded in version 1.0.
Task 1 Design the step4 method for the dealer. The method will be called from a (so far imaginary) runGame method, which deals with step 1 of the turn and collects information about the player’s actions from steps 2 and 3. In preparation of the feeding cycle, the method uses the information about step 3 to bring its representation of the game state up to date (food cards added/subtracted from watering hole food supply, added boards, etc). Then it runs the complete feeding cycle. The "end of turn" action is left to the (imaginary) runGame method.
The player may add a new species board to the end of an existing sequence only. It is impossible to add it at the left end.
The player cannot add traits to a species board, only replace them.
Delivery Move the code in dealer from 8 —
Task 2 Develop a test harness for the step4 method. The harness accepts JSON arrays from STDIN and writes a single JSON array to STDOUT.
The STDIN input consists of an array that contains two arrays: the first is Configuration and the second is a Step4. The former represents the state of the dealer before step4 is called; the latter is a JSON representation of step4’s input.
The STDOUT is also a Configuration array. It represents the state of the dealer after the call to step4, with the player list in the exact same order as the given one.
A Step4 is [Action4, ..., Action4].
Interpretation Each Action4 specifies what the corresponding player object wishes to do with its cards.
Constraints The list of Action4s is exactly as long as the list of players in the input Configuration.
An Action4 is [Natural, [GP, ...], [GB, ...], [BT, ...], [RT, ...]].
Interpretation Every natural number in an Action4 represent an index into a sequence of species boards or cards. The first natural number specifies the card that a player is turning into food.
Constraints The embedded arrays (GP, GB, BT, and RT) may be empty.
The dealer must ensure that the specified species board and card indexes are within the range appropriate for the corresponding player. If an error is discovered, the dealer may abort; the test harness outputs nothing on STDOUT.
A GP is ["population",Natural, Natural].
Interpretation A ["population",i,j] array requests a trade of card j for a growth of the population of species board i by one.
A GB is ["body",Natural, Natural].
Interpretation A ["body",i,j] array requests a trade of card j for a growth of the body of species board i by one.
Interpretation A BT represents a species board addition to the right of the existing sequence of boards for the corresponding player. Specifically, [i, j, ..., k] uses the first of the player’s cards (i) to "pay" for the new board and uses the remaining (up to three) cards (j, ..., k) as traits.
Constraint Once a player has added a species board, it becomes impossible to add a trait.
An RT is [Natural, Natural, Natural].
Interpretation An RT represents a trait replacement for a species board. Specifically, [b, i, j] specifies that board b’s i’s trait card is replaced with the j’s card from the player’s card sequence.
./xstep4 < some-json-input | diff - some-json-output |
If possible, supply a compilation script.
Shell scripts A script must start with #!/bin/sh or #!/bin/bash or #!/usr/bin/python17.3 etc. Don’t assume we supply whatever it takes to get it started.
Task 3 Design an interaction protocol that manages a yet-to-be-designed main program for Evolution, the dealer, and the external players.
the expected API (method names) of an external player
the expected call-back API, if any, for the dealer
the data (in the form of descriptions) that must flow from one object to another for the specified method calls and returns
the order in which the methods of the API(s) are called on a per game and per turn basis.
Sharing state between X and Y means that if X changes, Y "hurts", too.
While a true game server will accommodate 100s and 1,000s of simultaneous games, we will deal with just one game at a time.
Keep in mind that an interaction diagram does not show decisions and loops; its purpose is to explain interfaces (behavioral and temporal) between components. It cannot explain all possible situations. If you are unsure of what interaction diagrams are, please read up on them; you ought to have seen them in Fundamentals II and/or OOD but if not, the "Internet" has plenty of samples and explanations.
Finally, keep in mind that I consider such diagrams "design doodles" not architectural blue prints. So trade off effort and precision and neatness appropriately.
Delivery Create a sub-folder named api. Place a plain text file api.txt into the folder. Add whatever images you need as .png files.
The text file explains the protocol with "pointers" to the image files. If you are good at ASCII art, consider drawing the protocols in ASCII.