# Using custom shapes and colors in Rule Game Server 2.*

Updated for Ver 2.000, 2020-12-22

## Introduction

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.

## Colors

### Defining 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).

### Colors in predefined boards

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

### Colors in board generation

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.

### Colors in rule set files

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.

## Shapes

### SVG files

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.

### Using custom shapes

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.

## Validation

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.

## HTML play

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:

- Go to the HTML play page.
- In the /playerHtml form, enter a player ID you would like to use (e.g. FirstNameLastNameYYYYMMDD_001, or something shorter; it does not matter), and the name of the experiment plan to use (this could be an experiment plan you have just created, or `vmColorTest`, which is a recently created plan for color and shape testing). Click on Submit.
- If the player creation is successful, you'll get to a screen with an appropriate report, and a "Play an episode" button which will take you to the beginning of the first episode.
- During the play, the current board will be shown on the screen, and you can enter your moves by specifying the (x,y) coordinates of the piece to be moved and of the destination bucket (e.g. moving the piece at x=6 y=6 to the corner bucket at x=7 y=7).

## Examples

The experiment plan `vmColorTest` illustrates most concepts discussed in this document.