# Notes on Rule Game Server parameter sets

Updated for Ver 2.000, 2020-12-22

This document provides additional comments to the summary of the Rule Game Server paramters found in a Google spreadsheet, _0.GameParameters

## Introduction

As discussed in the Rule Game Server Data Guide (the section on Trial list files), each Rule Game player is automatically assigned to one of the trial lists provided in the trial list directory for the experiment plan associated with this player. A trial list consists of a header line (listing the column names), and one or several data lines. Each data line contains a parameter set, which describes the specifics of one of the series of episodes that the player will have to play.

The columns may appear in the file in any order; the header line specifies the order that must be followed in the subsequent data lines.

While most of the parameters are described sufficiently completely in the Google spreadshet created by Paul (see the link at the top of this document), this document provides additional, more detailed notes on some groups of parameters.

## Random board generation

In most experiments, you will likely want the Game Server to randomly generate a new initial board for each episode. In Game Server 1.*, the distribution is controlled by six parameters, discussed under Six-parameter distribution.

In Game Server 2.*, additional parameter, `colors` has been introduced. Its value is a color set to use in the random board generator, i.e. a list of color names (each of them should be defined in the color map file), separated by semicolons. Similarly, the `shapes` parameter specifies the list of shapes to use, separated by semicolons as well.

For example, if your parameter set contains the following parameters:

min_colors | max_colors | colors
--- | --- | ---
2 | 4 | RED; ORANGE; YELLOW; GREEN
min_shapes | max_shapes | shapes
2 | 3 | kangaroo;koala;quokka;echidna

then every randomly created board will contain from 2 to 4 different colors from the specified color list, and 2 or 3 shapes from the specified shape list.

For the `shapes` parameter, the shorthand using `*` is supported. It is used to refer to all shapes whose SVG files are found in a particular directory under the main shapes directory (`/opt/tomcat/game-data/shapes`) on your server. For example, the value `arrows/*` means "every shape for which an SVG file exists in the directory `/opt/tomcat/game-data/shapes/arrows`. If you use this shorthand syntax, make sure to use the lower case for the shape names and shape subdirectory names.

If parameters `min_colors` and `max_colors` have the same value, and this value is equal to the number of colors in your color set (the number of color names in parameters `colors`), then every initial board will use all of these colors, with at least one piece of each color. The same applies to the shapes.

### Absent `colors` or `shape` parameter

If a particular parameter set does not have the color set explicitly specified (either because the trial list file lacks a `colors` column altogether, or because the respective cell in this specific row is empty), then Game Server generates random boards as if the color set was specified to consist of the 4 legacy colors (BLACK, RED, BLUE, YELLOW).

Similarly, if the `shapes` parameter is not supplied, the random boards for this series of episodes will have their shapes drawn from the set of the 4 legacy shapes (CIRCLE, SQUARE, STAR, TRIANGLE).

This ensures backward compatibility, i.e. the ability of Game Server 2.* to interpret older trial list files (which don't have the `colors` and `shapes` parameters) in the same way as they were interpreted by Game Server 1.*.

## Using prefedined initial boards

Most commonly, a series of episodes is played on randomly generated initial boards; the appropriate parameter set needs to contain the parameters of this random distribution, such as the min and max number of objects, shapes, and colors.

However, it is also possible for the experiment manager to create a set of JSON files specifying initial boards, and a parameter set using those initial boards instead of random boards. (And, of course, you can also use the random board generator with a post-processing script to create those initial boards).

The relevant parameters are as follows:

- `initial_boards` : if this column is absent, or if the corresponding cell in a given row is empty, it is disregarded. Otherwise, it should contain a non-empty string which will be interpreted as a directory name under `/opt/tomcast/game-data/boards`. This is the directory from which initial board files will be taken. If this column contains a non-empty string, then the 6 columns specifying the random distribution of board parameters (`min_objects`, `max_objects`, `min_shapes` etc) must be either absent or be empty in this row.
- `initial_boards_order`: this column may contain a non-empty string only if `initial_boards` does. The allowed values are:
  - `random` -- means that the boards from the specified directory will be picked in a random order (without replacement). If the number of episodes played by a given player in this series exceeds the number of files in this directory, a new random sequence is started, again covering all listed boards.
  - `alpha` -- means the the boards will be offered in the order corresponding to the lexicographic ordering of their file names. (This means, incidentally, that if you have more than 9 boards, you'd want to number them x_01, x_02, ..., x_09, x_10, etc, rather than x_1, ..., x_9, x_10 etc). If the player plays more episodes than there are files, the boards will be repeated in the same order.
  - a file name, with a `.csv` extension and no directory name. The server will look for that file in the directory given by the `initial_boards_order` parameters. The file must contain a list of board names (i.e. board file names without the extension), one per line. The server will use those boards in the order specified, looping if the player plays more episodes than there are lines in this file.

For all values of `initial_boards_order`, if the the number of episodes played by a given player in this series exceeds the number of boards provided by this ordering (i.e. the number of JSON files in the directory in the `random` or `alpha` options, or the number of lines in the CSV file in the file name option), then the server repeats the process, i.e. either creating a new random sequence, or literally repeating the deterministic sequence, as the case may be.

This means that if the initial board directory mentioned in a given parameter set contains only one JSON file, this file will be used in every episode of the series. This can be used for testing, when you want a number of episodes played on the same board.

#### Example

For an example of an experiment plan that uses predefined initial boards, see plan `vm20201015`. The one trial list in that plan looks as follows:

    rule_id,max_boards,min_points,max_points,activate_bonus_at,b,clear_how_many,bonus_extra_pts,clearing_threshold,feedback_switches,stack_memory_depth,stack_memory_show_order,grid_memory_show_order,initial_boards,initial_boards_order
    TD-01,5,2,10,2,1.5,2,3,1.3,fixed,6,TRUE,TRUE,vertical-bars,alpha
    TD-02,5,2,10,2,1.5,2,3,1.3,fixed,6,TRUE,TRUE,vertical-bars,reverse.csv
    TD-03,5,2,10,2,1.5,2,3,1.3,fixed,6,TRUE,TRUE,vertical-bars,random

As you can see, in the first series, the board files are used in the alphabetic order of their names; in the second series, in the order contained in reverse.csv (which happens to be the reverse alphabetic order); in the third series, a random permutation of these boards is used.