8 — The Observer 🔗

Due Thursday, 09 November 2023, 11:59:59pm

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

Programming Task Implement an observer component with which dev ops can watch and inspect a game from a referee’s perspective.

The observer has two different but related purposes:
  1. it saves the states it receives as PNG files in a directory called Tmp/, using the names "0.png", "1.png", and so on.

    The Tmp/ directory should be created at the place where the program is run, in this case, the test script (xgames-with-observer).

  2. it displays the states it receives as images in a graphical user interface (GUI). This GUI must support at least three interaction capabilities:
    1. A next functionality shows the next state of the game, if it is available.

    2. A previous functionality shows the previous state of the game, if it is available.

    3. A save functionality saves the current state as an instance of JState in a file of the user’s choice.

Protocol The observer must support at least two pieces of functionality: (1) a receive-a-state functionality, which consumes a state; and (2) a game-over functionality, which alerts the observer that no more states will become available. The referee will use the first method to inform the observer of a change in state before a turn is completed and at the very end of the game (why?). The second piece of functionality is used as the referee shuts down.—An observer is wired into the referee on demand only.

Design Task The time has come to prepare for turning your monolithic software system into a distributed one. Imagine your referee managing a game with all the players from your peers in class or your player participating in a game that one of your peers organizes.

Read up on the remote-proxy design pattern.

Then design a protocol for gathering players, launch a game, and reporting the result. Use Logical Interactions as a starting point. Your document should combine English, schematic JSON data definitions (if needed), and sequence diagrams (if needed) to specify a remote-proxy protocol that you and your peers can implement.

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

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

The inputs of xgames-with-observer consist of a JState followed by an array of JActorSpecA. Functionally, xgames-with-observer performs the same computation and produces the same kind of output as the test harness of 7 — The Clean Up.

If the harness is run with the command-line flag "–show", the game observer is attached to the referee; otherwise the referee runs in the usual black-box mode.

Hint Recall that on the College’s headless Linux machines, you will (probably) have to run your program in a simulated graphics context

$ xvfb-run ./xgame-with-observer ...

regardless of whether the "–show" flag is added or not (unless your program links in the observer and the graphics library dynamically).

Your referee should inform all winners first before informing losers. Both inform-steps must proceed in turn order.

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 definition of JActorSpecA is revised as follows:

    A JActorSpecA is one of:

      - a JSON array of two elements: [JName, JStrategy]

      - a JSON array of three elements: [JName, JStrategy, JExn]

      - a JSON array of four elements: [JName, JStrategy, "a cheat", JCheat]


    A JCheat is one of:

      - "non-adjacent-coordinate"

    INTERPRETATION Denotes a player that in response to being granted a turn,

    requests the placement of a tile that is not adjacent to a placed tile.

      - "tile-not-owned"

    INTERPRETATION Denotes a player that in response to being granted a turn,

    requests the placement of a tile that it does not own.

      - "not-a-line"

    INTERPRETATION Denotes a player that in response to being granted a turn,

    requests placements that are not in one line (row, column).

      - "bad-ask-for-tiles"

    INTERPRETATION Denotes a player that in response to being granted a turn,

    requests a tile replacement but it owns more tiles than the referee has left.

      - "no-fit"

    INTERPRETATION Denotes a player that in response to being granted a turn,

    requests the placement of a tile that does not match its adjacent tiles.

For this milestone the Q bonus is 8 and the finish bonus is 4.