4 — The Score 🔗

Due Thursday, 12 October 2023, 11:59:59pm

Delivery Place the product of this week’s milestone into your git repo as follows:

  • for the Programming Task, place the scoring and rendering functionality into Qwirkle Q/Common/game-state.PP;

  • for the Design Task, place player-protocol.md into Planning/

  • for the Testing task, place xlegal and Tests/ into a top-level repo directory named 4

All previous comments on code files apply.

Programming Task Equip your game-state component with the following two pieces:

Design Task The player components must communicate with the referee. This communication involves both function/method calls and orderings of those, i.e., a protocol. Since outsiders will program to this interface, it must be spelled out precisely and in detail. Hint To start your brainstorming—what is a software system? What are the key phases of the game?

A protocol supplements an API to explain the calling sequence. Protocols are rarely checked, violations hard to detect, and the resulting errors tend to be obscure.

Design the interaction protocol between the referee and the player(s). The document, named player-protocol.md, should be a well-organized English write-up. If you are familiar with UML sequence diagrams (or you have time to read up on them), illustrate the prose with one of those.

One page should suffice. Less is more.

Keep in mind our Q.Com, a Plan while you work on a design task.

Testing Task Create a test harness named xlegal. The harness consumes its JSON input from STDIN and produces its results to STDOUT. Create five tests ([0-4]-{in,out}.json) and place them in the specified Tests/ folder.

A test case always consists of given inputs and expected outputs. For this course, a test consists of a pair of files: n-in.json, the input file, and n-out.json, the expected output file, where n is an integer between 0 and the requested number of tests (exclusive).—Constraint No test file may exceed the size limit of 40Kb.

The inputs of xlegal consist of the following sequence of two JSON values:
  1. a JPlacements array and

  2. a JPub object, which describes what the referee knows about the state of the game.

  3. a JPub object, which describes what the referee knows about the state of the game; and

  4. a JPlacements array.

The expected output is either false or the newly constructed JMap if the placement is legal.

[Entirely Optional but Helpful Your instructors found it extremely helpful to have graphical rendering functions for states around to formulate test cases.]

Here are the relevant JSON specifications:

An alternative data representation could represent states between turns or even in the middle of turns. Stop! Think this through.

    JPub is an object with three fields:

      { "map"      : JMap,

        "tile*"    : Tile#,

        "players"  : [JPlayer, Tile#, ..., Tile#] }


     INTERPRETATION Describes the current public knowledge of a player about

      the map and all players between two complete rounds of game play.  The

      first item in "players" denotes the current player. The

      natural numbers report the scores of the remaining players (and

      implicitly the order of play). The "tile*" informs the

      player how many tiles the referee owns.


    JPlayer is an object with two fields:

      { "score" : Tile#,

        "name"  : String,

        "tile*" : [JTile, ..., JTile] }


     INTERPRETATION Describes a player's current score and possibly the

      tiles in its possession.


    JPlacements is an array of the following shape:

      [ 1Placement, ..., 1Placement]


     INTERPRETATION Describes the sequence of placements that the active

      player wishes to perform.


    1Placement is an object with two fields:

      { "coordinate" : JCoordinate,

        "1tile"      : JTile }


     INTERPRETATION Add the given tile at the specified coordinate to the

      current map.

Tile# is a Natural no larger than 10000 1000000 the number of tiles available.

Well-formed and Valid You may assume that all inputs to your test harnesses from STDIN are well-formed and valid. A well-formed piece of JSON satisfies the grammar; such a piece is valid if it also satisfies all the side constraints of a schema specification.