11 — Designing a Protocol

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 GB

Changed in version 1.2: Mon Mar 28 21:34:32 EDT 2016
JSON input modified

Changed in version 1.1: Mon Mar 28 20:49:39 EDT 2016
responses to Alex and Lydia’s comments

Added 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.

To simplify the game somewhat, the player may choose only the following actions instead of those allowed by the official rules of Evolution:
  • 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 — Selecting testable methods to a folder for this project. Add step4 to this code base.

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.

A BT is one of:

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.

Delivery Place an executable called xstep4 into your main folder. Make sure it can be run from the command line like this:

    ./xstep4 < some-json-input | diff - some-json-output

The xstep4 executable must use the method from task 1. It may assume that all test inputs satisfy the JSON specification above.

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 protocol comprises
  • 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.

In anticipation of the eventual remote-interaction protocol, your (not so)omniscient software architect has decreed that the external player objects may not share any state with the dealer. Similarly, your architect also wishes to keep the number of interactions between the dealer and the players small, because these interactions will turn into network messages.

While a true game server will accommodate 100s and 1,000s of simultaneous games, we will deal with just one game at a time.

One common way to specify such protocols is to draw so-called interaction diagrams. If you choose to use diagrams, draw life lines for just main, the player objects, the dealer objects, and the internal representations of players. Use annotations and texts to explain what kind of {Java, Python, or Rust} data flows across method call or return arrows. Finally, draw at least three different diagrams: for starting up the game, a per-turn diagram, and a diagram for shutting down the game.

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.