# Notes on Rule Game Server parameter sets

Updated for Ver 8.000, 2025-03-20

This document provides additional comments to the summary of the Rule Game Server parameters 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.*.

### With image-and-property-based objects

Since GS 3.*, you can design games with image-and-properties-based (IPB) objects. Unlike games with legacy color-and-shape objects, for a game with IPB objects you need to specify the set of objects using the `images` column, rather than the `colors` or `shape` columns of your trial list file. For details, please see supports Image-and-property-based objects |Controlling the initial board generation.

### With constraints

Since GS 7.009, it is possible to use in trial list files the same constraints as available in the Captive Game Server. You can use the optional columns named `condTrain` or `condTest` to require, for example, that all game pieces are located within a particular quadrant of the board, or that every board has at least one piece outside of this quadrant. For an example, see the experiment plan `vm/cond` (trial list file: /opt/w2020/game-data/trial-lists/vm/cond/basic-10-B.csv ). The vaues in these columns are file names relative to the main constraint file directory, /opt/w2020/cond. The extension `.txt` can be omitted.

### "Crowded boards": allowing multiple game pieces in one cell.

Historically, all boards in Rule Game have at most one game piece per cell. However, since GS 8.000, boards with multiple game pieces per cell (so called "crowded boards") are allowed as well. You can allow the random board generator to put multiple pieces into a cell by adding the column named `crowded`, with the value `true` to the parameter set.

## 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 1

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.

#### Example 2

For another example, which uses predefined boards with image-and-properties-based objects, please see experiment plan `vm/exp4`

### Pre- and post-game experiences

The player's pre-game experience includes the IRB consent page and the instruction booklet; the post-game experience includes the demographics survey. Since ver. 6.000, these are controlled by parameter `pregame`. See Pre- and post-game experiences

## Proposal for implementing "super-series" in ver. 5.008 (2022-07-31)

This section describes my plan for implementing the feature proposed by Charles and Gary in July 2022: configuring an experiment in such a way that several series are presented to the player as a single series (a super-series, as I will call it).

To be clear on the terminology, will call the sequence of episodes played with the same rule set an internal series, and a concatenation of several "internal series" presented to the player as one series, a super-series.

Each "internal series" will be controlled by its own parameter set, i.e. its own line in the trial list file, just like all series have been prior to the addition of the "super-series" feature. For the experiment designer to be able to indicate which internal series are "merged" into a super-series, an additional optional column, called `continue`, will be added to the trial list files. If that column is present and contains `true` in a given row, it means that this row's series is "merged" with the one of next row into a super-series. Thus if a super-series consists of N internal series, than N-1 of the corresponding rows (all but the last one) will contain `true` in the `continue` column.

Numbering of series and episodes. The introduction of superseries will result in the appearance of a "split" between internal numbering of series and episodes and the "visible" numbering (displayed in the GUI client). Internally, the series and episodes in them will be numbered as they always were, at the level of internal series; these numbers will be appear, for example, in the SQL database and in any data files saved by the server. Externally (in the GUI display), each super-series will appear as a single entity.

I have sent a technical proposal to Kevin dealing with the changes in the web API to accommodate this "dual numbering".

Number of episodes per internal series. As with normal series, the number of episodes in each internal series will be given by the value in the `max_boards` column.

No Incentive scheme. At this point, the experiment designers are requested to construct experiment plans with super-series without any incentive scheme (either BONUS or DOUBLING). This means that the trial list file should have neither the `activate_bonus_at` column (and its associated columns describing the bonus scheme) nor the `x2_after` column. This will obviate potential problems involved in handling the bonus subseries in this setting.

Initial board generation. Each "internal series" of which a super-series is composed will have its initial board generator defined by the appropriate parameters in the corresponding row. You, as the experiment designer, may, of course, choose to have the same parameters (e.g. those of a 6-parameter random board generator) in each series; but you may also change the generator from on internal series to the next. For example, the first internal series may be run with several simple predefined boards, while the second series may use prefedeined boards from a different set, or a random board generator.

Feedback options. Similarly, each "internal series" may have its own set of feedback options; so, if the experiment designer so desires, he may choose, for example, to go from the "feedback_switches=fixed" to "feedback_switches=free", or whatever.

Giving up. At this point, giving up during any inner series within a super-series is not allowed.

#### Example

Experiment plan `vm/composite-01-super`. It has 2 super-series, each consisting of 2 internal series.