3 — The State

Due Thursday, 13 October 2022, 11:59:59pm

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

Programming Task Design & implement a data representation for the referee’s game states. This game state comprises three essential pieces of knowledge: the current state of the board; the spare tile; and the players’ assigned avatars, homes, goal tiles, and current positions. What else must the referee's knowledge come with?

The data representations should implement the following pieces of functionality:
  • rotate the spare tile by some number of degrees;

  • shift a row/column by inserting the spare tile plus moving the player from the newly created spare tile to the just inserted one if needed;

  • determine whether the currently active player can reach a given tile;

  • check whether the active player’s move has placed it on its goal tile;

  • kick out the currently active player.

If you think other pieces of functionality will be needed, you may implement them.

Think A player’s knowledge about the game state differs from that of the referee. How? How would you change the representation to reflect this difference?

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.

Each player component consists of two pieces: the mechanics of executing requested game actions and a strategy for pursuing a goal. This task is concerned with mechanics.

Describe the data that a player must know to act, that is, develop a data representation. Then design a player interface in the form of a wish list. For each piece of functionality, describe what it consumes, what it computes, and what the knowledge it must be able to retrieve from the context (if any).

The interface description may mix English with snippets of your chosen programming language. For the functionality, 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.

The memo should not exceed two pages, one page per aspect.

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

Testing Task Create a test harness named xboard. The harness consumes its JSON input from STDIN and produces 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 20Kb.

Its inputs consists of two JSON values: a Board object followed by a Coordinate. The latter designates a starting point.

The expected outputs is an array of Coordinates, sorted in row-column order, listing all Coordinates reachable from the starting point according to the given Board. 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.

Here are the relevant JSON specifications:

    Board is an object with two fields:

      { "connectors" : Matrix[Connector],

        "treasures"  : Matrix[Treasure] }


    INTERPRETATION Contains one Matrix for the connections

      that each tile relaizes (an essential aspect for navigation) and

      one equally-sized matrix for the treasurees each tile displayes.


    CONSTRAINT The Matrix in the "connectors" field is of the same

      size as the Matrix in the "treasures" field. All

      Treasures are mutually distinct.


    Matrix[Cell] is an array of Row[Cell].


    INTERPRETATION Describes a grid of Cell values.

    CONSTRAINT The array contains 7 rows. Each row is of length 7.


    Row[Cell] is an array of Cells.


    Treasures is an array of two Gems.


    Coordinate is an object with two fields:

      { "row#"    : Index,

        "column#" : Index }

    INTERPRETATION Specifies a tile location. The row count starts at the top,

      the column count at the left.


    Index is one of: 0, 1, 2, 3, 4, 5, 6.

Hint This textual interchange representation enforces game-centric constraints on the board, but it 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.

For example,

    [ ["│", "─", "┐", "└", "┌", "┘", "┬"],

      ["│", "─", "┐", "└", "┌", "┘", "┬"],

      ["│", "─", "┐", "└", "┌", "┘", "┬"] ]

is a well-formed JSON value but not a valid Matrix[Connectors]. By contrast, the following Matrix Note the struck out, accidental 8th row.

    [ ["│", "─", "┐", "└", "┌", "┘", "┬"],

      ["│", "─", "┐", "└", "┌", "┘", "┬"],

     ["│", "─", "┐", "└", "┌", "┘", "┬"],

      ["│", "─", "┐", "└", "┌", "┘", "┬"],

      ["│", "─", "┐", "└", "┌", "┘", "┬"],

      ["│", "─", "┐", "└", "┌", "┘", "┬"],

      ["│", "─", "┐", "└", "┌", "┘", "┬"],

      ["│", "─", "┐", "└", "┌", "┘", "┬"] ]

is both a well-formed and valid Matrix[Connectors].

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