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_colorsmax_colorscolors
2 4 RED; ORANGE; YELLOW; GREEN
min_shapesmax_shapesshapes
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:

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.