# Creating initial boards with a random board generator

Updated 2025-03-20 for ver 8.000

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.

Customized predefined initial boards can be used in the ML/AI experiments using the Captive Game Server as well. To do that, you must run the CGS with a trial list file that refers to these predefined boards. For details, see Captive Game Server | Use a trial list file.

## The command-line random board generator

The random board generator used by the Game Server is also accessible as a command-line tool, on our main server 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 our server host 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] [options]

Here,

- 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 (n1:n2, with 1≤n1 ≤n2, 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.
- `options` : these include `condTrain=...` or `condTest=...`, which can be used for position constraints in the same way as in the Captive Game Server. You can also have `crowded=true` to allow the random board generator to put multiple pieces in the same cell.

Alternatively, you can run this script with a trial list file name as an argument:

    /home/vmenkov/w2020/game/scripts/random-boards.sh out-dir number-of-boards trial-list-file.csv row-number

With the above format you tell the script to follow the settings in one of the parameter sets in the specified trial list file in CSV format. The last paramters refers to the row number (one-based) in the trial list file. This is particularly suitable when you want to create random boards with image-and-properties-based objects. Examples (which, for simplicity, assume that `/home/vmenkov/w2020/game/scripts` is in your path, and that you want 100 board files to be written to the subdirectory `tmp` of your current directory):

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

In the above example, every initial board will have 5 pieces, with exactly 2 distinct shapes and 3 distinct colors

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

In the above example, every initial board will have 5 pieces, with 1, 2, or 3 distinct shapes (with equal probability) and 3 or 4 distinct colors.

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`.

#### With a trial list file.

In this example, we have the random board generator controlled by the first parameter set in a trial list file:

    random-boards.sh tmp 3 /opt/w2020/game-data/trial-lists/RU/JF/tht/exp4/exp4.csv 1

Any trial list file can be used in this manner, including one that uses image-and-properties-based objects.

## 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 `name`s of a certain kind (those matching `*.json`), and on each of those files it `exec`utes 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.