Updated for Ver 2.000, 2020-12-22
The original Game Server 1.*, and Kevin GUI client that worked with it, restricted the experiment designer to the 4 built-in shapes and 4 built-in colors. These restrictions have been removed in Game Server 2.*. This document is intended to familiarize the experiment manager with the procedures he or she needs to use to create an experiment plan that uses pieces of arbitrary custom shapes and colors.
You can use arbitrary colors in Game Server 2.*. Once you have decided what colors will be used for game pieces (objects) in your new experiment (e.g. SIENNA, TERRA_COTTA, and UMBER), add the definitions of your chosen colors to the color map file on the server. After this is done, you can refer to these colors in the game rule files (just like you used the 4 legacy colors in Game Server 1.*), in the (definitions of predefined initial boards and in the list of colors for random board generation (see below).
If your experiment plan makes use of predefined initial boards, you can use any colors (defined in the color map) in your initial boards, just like you used the 4 "legacy colors" in Game Server 1.*.
If your experiment plan makes use of randomly generated initial boards, you should use the colors parameter in your parameter set to specify the set from which colors are to be drawn. Please see the discussion of parameters for board generation for the syntax details.
You can refer to your custom colors in the rule set files the same way the rule set files in Game Server 1.* referred to the four legacy colors.
Note that it is not illegal for a rule to refer to a color that's not present on any board during the experiment (because that color does not appear in any initial board). This simply mean that the rule (or the part of the rule that refers to that color) won't ever apply to any piece.
For every shape you want to use in your experiment plan, an SVG file with a matching name should be placed in the shape file directory, /opt/tomcat/game-data/shapes. Please see Shape files for details.
Custom shapes are used in a way analogous to that used for the colors, i.e. you use them rule set files and board definition files in the same way you used the 4 legacy colors in Game Server 1.*.
In the trial list files, you need to use the colors parameter in each parameter set which does not simply rely on the 4 legacy colors. See parameters for board generation for the syntax details.
As with colors, it is not illegal for a rule set to refer to a shape that's not present on any board in the experiment; it simply means that this rule (or the relevant part of the rule) won't apply to any piece.
Once you have created an experiment plan, especially one that uses custom shapes or colors, you may want to check it with our validation tool. While the tool can't guarantee that everythig in the plan is correct, it will check for some easier-to-detect errors, such as a reference to a non-existent file, or an attempt to generate a board using an undefined color or a shape without a shape file.
Eventually, the GUI client app will be updated to make use of Game Server 2.*. At present (2020-12-23) the GUI client is not available yet; but you can create player accounts and play games using the "HTML play" interface in your web browser. This is how:
The experiment plan vmColorTest illustrates most concepts discussed in this document.