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.
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.
{"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.
{"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 }
{"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).
{"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).
{"errmsg":"Gave up series 0","error":false}
{"error":false,"byteCnt":91,"path":"/opt/tomcat/saved/guesses/qt-01.csv"}