Creating initial boards with a random board generator

When creating an experiment plan, you need to give a thought to where intial boards are coming from.

In many plans, an initial board for each episode is created on-the-fly by the random board generator, which draws boards from a random distribution controlled by 6 parameters (or 8, if you have color and shape lists) in your trial list file. (For detail on how configure the parameters, see Rule Game Server parameter sets / Random board generation).

In some plans, however, you may want to give your players a set of boards that satisfies some more sophisticated design requirements, e.g. making sure that a particular color+shape combination does not occur in any initial board, or that no pieces are put to certain cells of the board. Or you may want to ensure that every player gets the same sequence of initial boards. Both of these objectives can be achieved by creatig a number of JSON files describing initial boards, either manually or using some kind of tool, and then configuring your experiment plan to use these initial boards, as explained in Rule Game Server parameter sets /Using prefedined initial boards.

The command-line random board generator

The random board generator used by the Game Server is also accessible as a command-line tool, on sapir or on any computer on which you have checked out and build the server code. It can be used to create a desired number of initial boards files with specified properties.

The script resides on sapir in /home/vmenkov/w2020/game/scripts/random-boards.sh; you can use it in that location. (Don't copy it into your own directory, as it relies on its location to find JAR files etc). It will be found on at a similar location in your directory tree if you follow the SOP instructions for checking out and building the server code on your own machine. The script is to be used as follows:

/home/vmenkov/w2020/game/scripts/random-boards.sh out-dir number-of-boards objects-range  shapes-range  colors-range [shapes-list colors-list]

• out-dir = the name of an existing, preferable empty, directory into which the new JSON files will be written
• number-of-boards = the number of files to create (≥1)
• objects-range = the number of game pieces to place on the board (a positive integer), or a range (n₁:n₂, with 1≤n₁ ≤n₂, e.g. 2:4)
• shapes-range = the number of different shapes to be used on the board. (A positive integer or a range)
• colors-range = the number of different colors to be used on the board. (A positive integer or a range)
• shapes-list = unless you want to use the 4 legacy shapes and 4 legacy colors, use this parameter to specify the list from which shapes are to be drawn. Wildcards are allowed. (A single-quoted semicolon-separated list, e.g. 'camel;cat;duck', or 'arrows/*;rainbows/*').
• colors-list = unless you want to use the 4 legacy colors, use this parameter to specify the list from which colors are to be drawn. (A single-quoted semicolon-separated list, e.g. 'red;pink;orange;mauve'). As with any colors, the colors mentioned here must exist in the color map on your server.

Specify the number of pieces, the number of shapes, and the number of colors, as single numbers

random-boards.sh tmp 100 5 2 3
	

Same as the above, but with using ranges for any of the three quantities.

Ranges and single numbers can be combined in arbitrary ways; essentially, a single number n is equivalent to the range n:n. E.g.

random-boards.sh tmp 100 5 1:3 3:4
	

When using ranges, make sure that the upper bound of range of the number of shapes the upper bound of the range of the number of colors do not exceed the lower bound of the range of the number of pieces. Otherwise, the random board generator may be occasionally faced with an impossible task of creating a board which has more distinct colors or shapes than it has pieces!

Same as the above, but with custom shapes and/or custom colors.

To specify the sets from which colors and/or shapes will be drawn by the initial board generator, you can add additional parameters to the command line. The values of the parameters are semicolon-separated lists of colors and/or shapes, respectively. Make sure to use single quotes as shown below, since semicolons would be interpreted by the UNIX shell as command separators otherwise.

  random-boards.sh tmp 100  3 2 2 'arrows/arrow-up-left;arrows/arrow-up-right;arrows/arrow-down-right;arrows/arrow-down-left' 'red;pink'
	   

One is allowed to use * to mean "use all shapes for which SVG files exist in the appropriate subdirectory of the main shapes directory". Thus, 'arrows/*;weather/*' is equivalent to listing every shape from /opt/tomcat/game-data/shapes/arrows and /opt/tomcat/game-data/shapes/weather

If you're using custom shapes and/or custom colors, it is necessary that a list of colors and a set of shapes SVG files are found at the appropriate locations under /opt/tomcat/game-data, as explained in the document Using custom shapes and colors in Rule Game Server 2.*. If you're running your board generator on sapir (the server used for the human subjects), and are playing a game that human subjects are already playing, then you're all set, because the human-player experiment team has already set up the necessary files in /opt/tomcat/game-data.

Post-processing: selecting boards matching your additional criteria

Now that you know how to create e.g. a bunch of random boards, each with 4 pieces of 4 different colors and 4 different shapes, how can you carry out additional selection on these boards, to only select those with desired properties?

Copy the file /home/vmenkov/game/sample-scripts/sample-random-boards-01.sh to any of your own directories, examine it, and modify it as needed. (Unlike the files under scripts, those under sample-scripts are meant to be "adopted" by users, i.e. copied to their own directories and modified as needed).

What this file contains is the following:

• Creating a directory for the JSON files to be produced. (set dir=tmp; mkdir $dir).
• Running random-boards.sh with desired parameters, producing 100 files with 4 game pieces each, of different shapes and colors. Modify that as needed.
• Looking at all files in the output directory, and deleting those that are not matching the desired criteria. In this script we use Linux's versatile find command to organize this process. It finds all files with the names of a certain kind (those matching *.json), and on each of those files it executes the Linux grep command. The grep command looks for a certain substring in each JSON file; due to the way the files are formatted, the search substring only appears in JSON files that have a certain combination of color and shape in the same game piece. When the match occurs, the find command performs the -delete the unwanted file.

  find $dir -name '*.json' -exec grep -i '"color":"RED_HIGH","shape":"birdlow"' {} \; -delete 
  	  

• The find command is repeated several times, to purge JSON files containing pieces with other unwanted color+shape combinations.

You should be able to customize the find commands (likely, the pattern insde the grep that's nested in find ) to remove files based on other criteria. If you need advice for a particular case, ask Vladimir.

No support for image-and-properties based objects

As of GS 3.003, the Random board generator only works with the traditional shape+color based objects. It has no support for image-and-properties based objects introduced in GS 3.*.

Viewing your initial boards

You can use the Board display tool to view the boards you have produced. Go to the second form in the tool's main screen Board display tool / Display a single board from a file (or multiple boards from multiple files), and upload all the JSON files you've got (or a representative sample of them), to see a graphics display of them all. Due to the limitations of our display tool, the color of images may not be shown correctly: instead of properly painted icons, you may see black icons with a colored background, or a colored square frame around them.