Updated 2023-01-26 for Game Server ver. 6.008
This document helps the experiment manager to set up the "launch pages" for the APP and MLC users.
This is how you can get a particular rule set to appear in one of the two tables in the APP launch page.
Note: when following the instructions below and putting various files into the control file directory tree (/opt/tomcat/game-data on sapir), please make sure not to copy files to that directory directly (and not to edit files in that directory). You need to have the files auto-deployed via the GitHub repository, as per the Standard Operating Procedures. Otherwise, all your work will be lost on the next auto-deployment (i.e. when somebody else commits his changes to GitHub)!
The Part A table consists of experiment plans which you have chosen to appear there. There are two ways to get an experiment plan to appear in that table:
Either way, every experiment plan you include in the Part A table should contain exactly 1 trial list (because we want player assignment to be deterministic here). The trial list file must may contain one or several data lines (after the usual header line); most likely you will want to have just one data line (unless you want the player to go through two or more rule sets). As in any trial list, each line will specify the name of the rule set you want to expose, along with other necessary control parameters.
As in any trial list, the rule set name (in the rule_id column of the trial list file) is the path name of the rule file relative to the main rules directory (rules). The rule set file may, but does not have to, be located in rules/APP.
You may want to use the Part A table if your rule set needs to be used with some "non-standard" parameters, such as an unusual number of game pieces, a set of custom colors or custom shapes, a set of custom initial boards, etc. Another reason to use the Part A table (specifically, the "launch file" listing is when you, for some reason, want to have a trial list with several lines (this, several rule sets) in it, and you want to write a description for the entire experiment plan (in addition to any descriptions found in the comment lines of individual rule set files).
The columns of the Part A table correspond to "short modifier files" from modifers/APP-short; each of those files only contains columns corresponding to the feedback modalities and the giving-up option. For each table cell, the game server will combine the trial list of the relevant experiment plan with the columns of the relevant modifier file, the later overriding the former. (This is referred to as a "P:" type dynamic experiment plan). For example, if you have a static plan APP/foo, the dynamic plans will have names such as P:APP/foo:APP-short/APP-short-no-feedback
The Part B table is generated directly based on the rule sets you have provided. There are 2 ways to specify which rule sets are displayed:
If any of the rule sets listed in the Part B launch file (or found in the rules/APP directory tree) is already used in part A (because it's referenced in an experiment plan that appears in this part), it will be ignored by the server in part B, in order to avoid repetition (and also to avoid presenting such a rule set without its proper custom-designed trial list file, and thus possibly failing to supply some parameters necessary for that rule set).
The columns of the table correspond to "long modifier files" from modifers/APP; each of those files contains all columns that one would normally find in a "simple" trial list file (one that only uses legacy shapes and legacy colors), with the exception of the ruleSet column. For each table cell, the game server will dynamically create a trial list based on the relevant rule set and the relevant modifier file. (This is referred to as an "R:" type dynamic experiment plan). For example, if you have a rule set named APP/foo, the dynamic plans will have names such as R:APP/foo:APP/APP-no-feedback
For the MLC launch page, the setup rules are very similar to those for the APP launch page. Just replace APP with MLC and app with mlc in all directory and file names. (Except for the files and directories for the modifier files; for the moment, we use the APP modifiers for MLC too).
There is also a smaller similar launch page set up for the people interested in the Captive Game Server (CGS). We call it the CGS launch page, although of course the page itself has nothing whatsoever to do with the CGS. The setup is similar to that of the APP launch page, except that the CGS launch page only has Part B, and no Part A.
The Android app will display the same rule sets (technically, dynamic experiment plans based on rule sets) that show in the CGS launch page. (The Android app requests the list of these rule sets from the server by the /findPlans API call).
The preferred way to set up this list is by editing the Part B launch file in the directory launch/launch-cgs-b.csv under the main game data directory. (Use the usual SOP for editing experiment control files). This is a 2-column CSV file. The first column should have the rule set name (e.g. CGS/foo, which will refer to the rule set file CGS/foo.txt under the main rule directory); the second column may be left blank, or it can have a rule description in it. If the desription is given, it will be displayed in the Android app; so you can use a short or somewhat cryptic phrase or nickname here.
If the description field is blank for a particular rule set, the server will send to the Android app the description that you provide in the line
#Display: some textin the rule set file itself.
If the Part B launch file does not exist, the server will use all rule sets described by rule set files placed by you into rules/CGS (or anywhere in the directory tree under that directory). This approach is not recommended though, as it will make it impossible for you to cleanly remove existing rule set files. (If you remove a rule set file, you will make it impossible subsequent data processing of experimental results for players who played that rule set).