►Software Development
▼—Project Milestones
•5 — The Rules
8.15.0.2
    contents    up   

5 — The Rules🔗

Due Thursday, 17 October 2024, 11:59:59pm

Purpose This milestone has two distinct learning goals:

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

  • for the Programming Task, place rule-book.PP into Common;

  • for the Design Task, place referee.md into Planning/

  • for the Testing task, place xstrategy & Tests/ into a top-level repo directory named 5

All previous comments on code files apply.

Programming Task Every boardgame comes with a rule book. Both players and referees use the rule book, applying individual rules to take turns and deciding the legality and value of actions. Hence, a developer needs a representation of this information in a game-implementation project.

Starting from The Bazaar Game, the rule book clearly needs to supply pieces of functionality for checking the legality of a player’s request for action, namely

  • the legality of the result of the first call from the referee to the player, and

  • the legality of the result of the second call from the referee to the player.

For the specification of these two calls, see Logical Interactions for the chosen player interface that the referee uses to interact with a player.

Both of these pieces of functionality must consume the turn-state that the referee shares with the player, the player’s response, and the equations (which are global constants); otherwise the player would play “blind.” How these pieces of functionality consume their arguments is up to the developer relative to the chosen programming language.

Also consider which other functionality the rule book should contain or which existing functionality should be moved into the rule book. (Yes, ordinarily a manager would specify these pieces of functionality via some instructions or a “ticket.” Here we appeal to your sense of software design.)

Why is the result of this programming task placed into Common?

Why is it imperative that this component (or any other component in Common/) does not refer to any pieces of the referee component(s)?

Design Task The referee component must communicate with the game-state to run complete games. The referee is a mechanism that manipulates the state turn by turn until the game is over. If someone were to suspend the game for a while, the referee could resume the game from some given and saved state.

Based on your current implementation of the game-state component and your understanding of the referee-player protocol, design a full interface for the game-state component and develop an interaction protocol between the referee and game-state. The document, named referee.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.

Two pages should suffice. Less is more.

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

Testing Task Create a test harness named xstrategy. The harness consumes its JSON input from STDIN and produces its results to STDOUT. Create three tests ([0-2]-{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 input of xstrategy consists of the following JSON values:

  1. the (maximally useful of the running game) *Equations;

  2. the Turn given to the active player; and

  3. its maximization Policy.

The input is guaranteed to allow the player the use of some equations.

The expected output consists of the following JSON values:

  1. a bunch of one *Rules value, which represents the exchanges a the active player wishes conduct to optimize according to the given policy;

    For this milestone and all future milestones, assume that the order of the JSON array is the order in which the player intends to use them.

  2. a bunch of one *Cards value, which represents the cards a player wishes to purchase to optimize according to the given policy;

  3. a natural number, which represents the points the player expects to receive; and

  4. a bunch of one *Pebbles value, which represents the pebbles in the player’s possession after the exchanges are performed and the cards are bought.

The test harness will compare expected results based on the notions of equality for exchanges and purchases spelled out in 4 — The Strategies.

    A Policy is one of:

      -- "purchase-points"

         INTERPRETATION the player tries to maximize the number of points

           when given a turn state.

    

      -- "purchase-size"

         INTERPRETATION the player tries to maximize the number of cards

           it buys when given a turn.

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.

    contents    up