Documentation

Playing the game

This program can be used without any program arguments, they simply allow customization of the gameplay.

Program arguments to customize a game

• -seed STR
  • The seed used for the random number generator. The value can be any string. Random default.
• -size N
  • The size of the game board (always a square). Default 14.
• -colors N
  • The amount of colors used for the game. Only values between 2 and 35 (inclusive) are allowed. Recommended values are between 4 and 8. Default 6.
• -startPos STR
  • The starting position at the beginning of the game. Can be ul for upper left corner, ur for upper right corner, ll for lower left corner, lr for lower right corner and m for middle of the board. Default ul.

Example

java -jar terminal-flood.jar -seed "xyzzy" -size 18 -colors 6 -startPos m

The above command will create a game with an 18x18 board, 6 colors, starting position in the middle and the string xyzzy used as the seed value for the RNG.

Program arguments to find solutions for a game

The following arguments will make the program try to find winning moves for a game board using the specified algorithms. Only one of them can be used at the same time, and you will not be able to play the game using these arguments. These options might be useful for you if you struggle with a board and want to know a possible solution. You'll have to have the seed of a game board for that though.

Usage recommendation: If you just want a solution, first try -astar_iaf. If the solution is not satisfactory, try -astar_ias or if working with big boards with lots of colors -astar_ia.

• -astar_a
  • Uses an A* algorithm. Uses an admissible heuristic, which means that it will always find an optimal solution. Can potentially take a lot of time to find a solution, especially at higher board sizes with even a moderate amount of colors.
• -astar_ias
  • Uses an A* algorithm. Uses an inadmissible heuristic, which means it will not always find an optimal solution. Still, the result will often be optimal or very close to optimal. Is substantially faster than -astar_a but still runs into long runtimes at higher board sizes and/or a lot of colors.
• -astar_ia
  • Uses an A* algorithm. Uses an inadmissible heuristic, which means it will not always find an optimal solution. Still, the result will often be close to optimal. Is substantially faster than -astar_ias but can still run into relatively long runtimes at high board sizes with a lot of colors.
• -astar_iaf
  • Uses an A* algorithm. Uses an inadmissible heuristic, which means it will not always find an optimal solution. Will find good solutions, but usually not optimal ones. Is fast and can be used even at high board sizes with a lot of colors. This is the recommended computation option if you just want to quickly find a solution for any given game board.
• -astar_iaff
  • Uses an A* algorithm. Uses an inadmissible heuristic, which means it will not always find an optimal solution. Will find decent solutions, but usually not optimal ones. Is very fast, even at high board sizes and a lot of colors.

Working with datasets

Finding solutions for whole datasets

You can also let the program find solutions for a whole file containing compact strings of game boards using this command:

-solutionsForDataset [threads] [strategy] [startPos] [filepath]

Please note that all arguments are mandatory.

• [threads]
  • The amount of boards being computed at the same time. It's generally advisable to set this number no higher than the amount of logical processors of your machine. Also, keep in mind that more simultaneous computations will need more heap space, so set the -Xmx value of the JVM accordingly. For example, 24x24 boards with the astar_ias strategy and 4 threads may need upwards of 10GB of heap space, depending on the specific dataset.
• [strategy]
  • The strategy used to compute solutions. The possible values are the same as the single solution computation arguments, just without the minus sign in front. See above for the list of options and what each option does.
• [startPos]
  • The starting position of the game boards. The option is exactly the same as the argument used when simply playing the game.
• [filepath]
  • The file path to the text file containing the game boards. Please only use forward slashes, even on Windows systems.

Example

java -jar terminal-flood.jar -solutionsForDataset 4 astar_iaf ul "/path/to/dataset.txt"

The above command would compute solutions for the file located at /path/to/dataset.txt using 4 threads, the astar_iaf strategy and using the upper left corner as the starting position for the game boards. The solutions would be saved to /path/to/solutions.txt.

Creating datasets

Additionally, you can use this program to create dataset files containing compact strings of game boards. Compact strings are defined as holding the whole game board in one single line with no whitespace characters in them. The board size is derived from the length of the string. (boardSize = sqrt(string.length))

The command is as follows:

  -createDataset [boardSize] [numColors] [numBoards] [filepath]

• [boardSize]
  • The size of the game boards (always a square). The option is exactly the same as the argument used when simply playing the game.
• [numColors]
  • The amount of colors used for the game boards. The option is exactly the same as the argument used when simply playing the game.
• [numBoards]
  • The amount of boards created for the dataset. The value must be equal or above 1.
• [filepath]
  • The file path denoting the location plus name of the dataset to be saved. Please only use forward slashes, even on Windows systems. This option is optional and if left out, a file named dataset b[boardSize]c[numColors]n[numBoards].txt will be saved in the current working directory.

Example

java -jar terminal-flood.jar -createDataset 14 6 1000 "/path/to/dataset.txt"

The above command would create a dataset containing 1000 boards of the size 14x14 with 6 colors. The dataset would be saved to /path/to/dataset.txt.

Playing or solving specific boards in a dataset

Given a dataset, you can choose and play or solve a board contained in it given the following commands:

-playFromDataset [lineNumber] [startPos] [filepath]
-solveFromDataset [lineNumber] [strategy] [startPos] [filepath]

• [lineNumber]
  • The line number of the game board you want to play within the dataset file. Note that line numbers are starting from 1.
• [strategy]
  • The strategy used to compute a solution. The possible values are the same as the single solution computation arguments, just without the minus sign in front. See above for the list of options and what each option does.
• [startPos]
  • The starting position of the game board. The option is exactly the same as the argument used when simply playing the game.
• [filepath]
  • The file path to the text file containing the game boards. Please only use forward slashes, even on Windows systems.

Example

java -jar terminal-flood.jar -playFromDataset 815 ul "/path/to/dataset.txt"
java -jar terminal-flood.jar -solveFromDataset 815 astar_iaf ul "/path/to/dataset.txt"

With the above commands you would either play or solve board number 815 from the given dataset with the starting position in the upper left (and use the astar_iaf strategy in case you try to solve the board).

Memory saving modes

When trying to find solutions for game boards, you can turn on special memory saving modes with one of the following parameters:

• -lessMemory
  • This mode will trade some performance in exchange for less memory needed for the computation. This can be a net plus for performance in cases of heavy memory requirements where using this mode would result in less GC pauses or the ability to use more cores of your CPU. The quality of the solutions is not impaired by this mode.
• -lessMemoryQueueCutoff
  • The points given for -lessMemory also apply to this mode, but additionally, this mode will also limit the size of the queue used by A* by discarding elements whenever a certain cutoff limit is reached. The result is a clear upper bound in regards to the maximum memory needed to compute a solution, but it also means that the quality of the solution can be impaired by this mode. Don't use this mode together with astar_a when trying to find guaranteed optimal results.