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
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.
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 |
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.
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.*.
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.
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.
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,randomAs 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.
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.
Experiment plan vm/composite-01-super. It has 2 super-series, each consisting of 2 internal series.