# How to set up APP and MLC launch pages: instructions for the experiment manager

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.

## Setting up the APP launch page

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)!

### Part A: pre-created trial lists

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:

- You can list the experiment plan as one of the entries in the "launch file", `launch/launch-app.csv` under the main control file directory (`/opt/tomcat/game-data`). The launch file is a 2-column CSV file; the first column contains an experiment plan name (e.g. `foo` for an experiment plan whose trial list files are in the directory `trial-lists/foo` under the main control file directory), and the second column contain an arbitrary text which will be displayed by the server as part of the plan's description.
- Alternatively, you can place the experiment plan's directory within the directory `trial-lists/APP` under the main control file directory. (This can be at any depth in the directory tree).

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`

### Part B: "naked" rule sets

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:

- You can create a Part B launch file, `launch/launch-app-b.csv`. This is a 2-column CSV file. The first column should have the rule set name (e.g. `APP/foo`, which will refer to the rule set file `APP/foo.txt` under the main rule directory); the second column may be left blank, or it can have a rule description in it. This description is ignored for the web launch pages though. If this file is present, only rule sets from this list will be displayed. Thus having this launch file is convenient if you want to add and remove rule sets to/from the display list at will.
- 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/APP` (or anywhere in the directory tree under that directory).

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`

## Setting up the MLC launch page

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).

## Setting up the CGS launch page

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.

## Setting up the rule list for the Andorid app

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 text

in 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).