3 — The State 🔗

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

Partnership Evals For this milestone, we request an evaluation of your partnership.

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

  • for the Programming Task, place game-state.PP into Q/Common/game-state.PP;

    Some languages demand a specific organization within the file system. In that case, you may place a link to game-state.PP into Q/Common/game-state.PP.

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

  • for the Testing task, place xmap and Tests/ into a top-level repo directory named 3.

    If your testing task requires a Makefile place it in 3, too.

Since some languages' Python's naming systems is are badly designed and its convention interferes with the specified name, Pythonistas users of such languages may substitute _ for - in these file names.

Programming Task Design & implement a data representation for the referee’s game states. This game state comprises two three essential pieces of knowledge: the current state of the map, the state the players’s states, and the order in which the players take turns. The active player is the player whose turn it is.

Also design & implement a data representation for information about all players that a referee may wish to share with the active player.

The data representations should come with the following pieces of functionality:
  • for extracting the data to be sent to a player when it is its turn;

  • for completing a turn action; and

  • for checking whether a proposed placement by the currently active player satisfies the rules of The Q Game.

If you think other pieces of functionality will be useful for future assignments, you may implement them now or wait.

Design Task In contrast to human players, AI players are not in charge; the referee of the game framework is and it plays the role of arbiter, which is often left to the collective of all players (or a subset of knowledgeable ones).

Here the referee engages the players, informing them of the game’s progress as needed, and managing turns. When granted a turn, a player responds with a description of the desired action, but it is the referee that executes them on behalf of the player on the ground-truth state of affairs—if the request is legal.

Design a player interface in the form of a method/function wish list. For each piece of functionality, describe what knowledge it must be able to retrieve from context (if any). Choose the wish list format that you got to know in Fundamentals I and Fundamentals II, depending on which of the languages used in these courses matches your chosen language most closely.

Note, each player component consists of two pieces: the mechanics for executing game actions and a strategy (or several strategies) for pursuing a goal. This task is concerned with mechanics only.

The memo should not exceed a page.

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

Testing Task Create a test harness named xmap. The harness consumes its JSON inputs from STDIN and sends its results to STDOUT. Create three tests 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 xmap consist of two JSON values: a JMap object followed by a JTile.

The expected outputs is an array of JCoordinates, sorted in row-column order, listing all JCoordinates where this tile could be added to the given JMap.

Sorted in row-column order Two coordinates c1 and c2 are in row-column order if either the row index of c1 is strictly less than the row index of c2 or, the two row indices are equal and the column index of c1 is strictly less than the column index of c2.

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

Here are the relevant JSON specifications:

    JMap is a JSON array:

     [JRow ...]

     INTERPRETATION Represents a complete game map of tiles.


    JRow is a JSON array:

     [RowIndex, JCell, ...]

     INTERPRETATION Represents one row of the game map of tiles. RowIndex

     denotes the row coordinate of all JCells in the array. Negative is up,

     positive is down---just as for computer graphics.

     CONSTRAINT The RowIndex integers form a set without gaps and overlap.

     The JCell sequence must be non-empty.


    JCell is a JSON array:

     [ColumnIndex, JTile]

     INTERPRETATION Represents one tile of the game map of tiles. ColumnIndex

     denotes the column coordinate of the JTile. Negative is left, positive is

     downright---just as for computer graphics.

     CONSTRAINT The ColumnIndex integers form a set.


    JTile is an object with two fields:

      { "color" : Color,

        "shape" : Shape }

     INTERPRETATION Describes a tile's shape and color.


    JCoordinate is an object with two fields:

      { "row" : RowIndex,

        "column" : ColumnIndex }


    RowIndex is an Integer.


    ColumnIndex is an Integer.


    Shape is one of: "star", "8star", "square", "circle", "clover", "diamond".


    Color is one of: "red", "green", "blue", "yellow", "orange", "purple".

Hint This JSON data exchange representation is not intended to be identical to your data representation (and it is certainly not the one used for the oracle implementation).

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.

Beyond integeration testing, we should eventually move to stress testing. The course will touch on this idea in November or December.

Pedagogy Besides unit tests, multi-component projects also need integration tests. Such tests compose several components and run tests on the composite that exercise functions across the components. This task is a lightweight illustration of this idea.

When a milestone assignment requests an integration test harnesses, you should not have to modify the core functionality from the previous milestone—other than the addition of code for (de)serialization between your chosen data representation and JSON; see Q.Com, a Plan.

That is, building harnesses for integration tests doesn’t slow you down—it actually accelerates your progress because the goals are always compatible with the current task and lay its foundation. Work thru the integration testing task before tackling the programming task.

Partner Evaluation

Each individual should send an email to the head TA (Michael), using the following format:

    Subject: Sw Dev partnership evaluation


    My name: Foo Bar

    My partner's name: Fumble Mumble

    Our TAHPL: Python 4.312


    Our partnership is ...

The body of the message can be a single sentence (e.g., "... the happiest ever") or several paragraphs with details (e.g., "Our first minute of coding .. Our second minute ..."). What you want to say is completely up you.

Only the head TA and, if necessary, the instructors will read your responses; nobody else will. At their digression, the instructors may interview partners.

The partnership evaluation is worth 10 points.