# RESTful API for the use by the Rule Game client - second batch

Ver 1.011, 2020-09-03

This is the "Second Batch" (prefix=`/GameService2`) of the Game Service web API calls. They are intended for use with a client app that works with players enrolled in experiments; each player is identified by a player ID, and the server assigns each player to a "trial list" (a particular track in the experiment plan with which this player ID is associated with).

For calls used by players not enrolled in experiments (e.g. our own team members developing and testing games), see the First Batch.

1. POST `/startTrial:` Start a player's interaction with the system, and obtain a randomly selected trial list for this player Player ID:

   The input parameter is the player ID (a string). In the future, the system will determine, based on the player ID, what experiment the person is enrolled into (e.g MTurkers vs. psych students vs. ourselves testing a particular game); at present, the player ID does not really matter, as everybody is considered to be enrolled in the experiment called "default".

   Sample output:

             {"errmsg":"Debug:...",
             "error":false,
             "newlyRegistered":false,
             "trialListId":"trial_1"}

   In practice, you don't need any of the returned values, other than the error code.
2. POST `/newEpisode`: Create a new episode for a specified user: Player ID:
   Results:

         {"errmsg":"Debug...",  // either used to describe errors, or contains various status info for debugging.
         "error":false,    // true if something bad has happened
         "alreadyFinished":false,   // this will be true if error==true, and the error is caused by the fact that the player has already done all his param sets
        "board":{"longId":0,"id":0,"value":
       [{"buckets":[0],"color":"RED","id":0,"shape":"STAR","x":3,"y":1},
       {"buckets":[0],"color":"RED","id":0,"shape":"STAR","x":3,"y":5}]},
        // description of the initial board
       "bonus":false,     // true if this episode is part of a bonus subseries
       "bonusEpisodeNo":0,  // the number of previous bonus episodes in this series
       "canActivateBonus":false,  // true if you can put an "Activate Bonus" button on the screen in this episode
       "episodeId":"20200828-021427-FJRX9J", // Save this and use it in /move calls later!
       "para":
       {"clearing_threshold":1.3,"max_points":10,"b":1.5,"min_points":2,
       "max_colors":1,"f":4,"feedback_switches":"fixed","min_objects":1,"m":9,"n":1,
       "clear_how_many":2,"bonus_extra_pts":3,"rule_id":"TD-02","max_objects":3,
       "grid_memory_show_order":false,"min_shapes":1,"stack_memory_show_order":false,
       "max_shapes":1,"min_colors":1,"stack_memory_depth":6,"max_boards":2,
       "activate_bonus_at":2}, , // All the parameters from the current param set
         //  (the current row of the trial list file). Some of them may be used by the
       //GUI tool to control some points of the appearance
       "seriesNo":1,  // the 0-based sequential number of this series (= 0-based sequential number of this row of the trial list file).
       // You can increment this number by 1 and display it in a "You are working on Rule No. X" message.
       "episodeNo":0, // the 0-based number of this episode within the series (i.e. among
       // the episodes played under a given rule set).
       // You can increment this number by 1 and display it as Y in a "Rule No. X, Episode No. Y" message.
       "totalRewardEarned":33  // the sum total of rewards earned by this player in all episodes so far
       }

   As of ver. 1.011, in the board description the field `dropped` is shown only in the pieces that have been already removed from the board; the value is the ientifying number (0 thru 3) of the bucket into which the piece has been dropped.

3. GET `/display`: View the current display: Episode ID (returned by an earlier newEpisode call):
   Sample output

         {"board":{"longId":0,"id":0,"value":
         [{"buckets":[0],"color":"RED","dropped":1,"id":0,"shape":"STAR","x":3,"y":1},
         {"buckets":[0],"color":"RED","dropped":3,"id":0,"shape":"STAR","x":3,"y":5}]},
         "bonus":false,   // true if this episode is part of a bonus subseries
         "code":-8,  // It is always -8 on /display calls
         "errmsg":"Display requested",
         "finishCode":1, // Tells if the episode still continues, has stalemated,
       //    has been finished by clearing the board, or has been given up.
       //    For the semantics of the code and  finishCode fields,
       //    see the entry on the MOVE command in the documentation on the Captive Game Server
         "numMovesMade":3,  // the number of move attempts made so far in this episode
         "totalRewardEarned":0  // the sum total of rewards earned by this player in all episodes so far
         }

4. POST `/move`: Make a move: Episode ID (returned by an earlier newEpisode call):
   Piece to move: column=x=, row=y= (both ranging 1 thru 6)
   Destination bucket (identified by bucket_column=bx=, bucket_row=by= (possible values are 0 and 7)
   Attempted move count so far (the number of previous calls to `move` in this episode. This can also be interpreted as 0-based number of this move attempt)
   Sample response

         {"board":{"longId":0,"id":0,"value":
         [{"buckets":[1],"color":"BLUE","id":0,"shape":"TRIANGLE","x":4,"y":2},
         {"buckets":[1],"color":"BLUE","dropped":3,"id":0,"shape":"TRIANGLE","x":2,"y":3}]},  // the board after this move
         "bonus":false,  // true if this episode is part of a bonus subseries
         "code":4,  Outcome of this move.
           For the semantics of the code and  finishCode fields,
           see the entry on the MOVE command in the documentation on the Captive Game Server
         "errmsg":"...", // either used to describe errors, or contains various status info for debugging.
         "finishCode":0,  Overall state of this episode now.
           For the semantics of the code and  finishCode fields,
           see the entry on the MOVE command in the documentation on the Captive Game Server
         "numMovesMade":1,  // the number of move attempts made so far in this episode
         "totalRewardEarned":42 // the sum total of rewards earned by this player in all episodes so far
         }

   The finish code reports the current state: 0=can play (there are pieces on the board, and some can be moved), 1=finish (no pieces left on the board), 2=stalemate (there are pieces on the board, but none of them can be moved anymore).

5. POST `/activateBonus:` Activate the bonus for this player. The current episode (if still active) and all subsequent episode of the same series (i.e. played by the same rule) will constitute the "bonus subseries"
   Sample output

           {"errmsg":"Bonus activated successfully","error":false}

The finish code reports the current state: 0=can play (there are pieces on the board, and some can be moved), 1=finish (no pieces left on the board), 2=stalemate (there are pieces on the board, but none of them can be moved anymore).

6. POST `/giveUp:` "Gives up" the current series (i.e. the series played with the current param set), so that the next episode will be run with the next param set. If this is invoked while an episode is in progress, the episode will be marked as "given up" as well. However, you may choose to only used this call at the end of an episode (that is, give the player an option of switching to the next param set for the next episode, regardless of one's current position in the current series). Player ID: Series No.:
   The seriesNo value must be exactly the same to which the current (or just completed) episode belongs to, as per the "seriesNo" value obtained in the last /newEpisode call. This is required as a safety check, to ensure that the client and server are on the same page. (If it's an annoyance to have it, I can remove this parameter)
   Sample output (on success):

       {"errmsg":"Gave up series 0","error":false}

7. POST `/guess:` Recording a guess Episode ID (returned by an earlier newEpisode call):
   Please type your guess here (an arbitrary test)
   Response (on success):

       {"error":false,"byteCnt":91,"path":"/opt/tomcat/saved/guesses/qt-01.csv"}

8. GET `/debug`: Same info as given by /player, and some more for a specified user: Player ID: