Tank Soar and Eaters Configuration Files

Soar2D is a general framework that includes both Eaters and TankSoar. This document describes how to modify these environments using the configuration settings files.

• Tank Soar and Eaters Configuration Files
• Configuration Files
• clients
• eaters
• general
• soar
• players
• room
• taxi
• tanksoar
• terminals
• Logging
• Map Files
• Map file
• Objects File

Configuration Files

Soar2D configuration files are stored in the Soar2D folder. When running the soar2d jar, you may specify the configuration file to use on the command line, or run without specifying any and a dialog window will pop-up.

java -jar soar2d.jar configs/tanksoar.cnf
java -jar soar2d.jar configs/eaters.cnf
java -jar soar2d.jar configs/room.cnf
java -jar soar2d.jar

Configuration entries are of the format:

''key'' = ''value''; # Note the trailing semicolon.

Use the pound sign for comments. Start them anywhere on a line.

# Comments go here

Configuration keys are simple identifiers. Stick to alphanumeric characters and underscores.

exampleKey = ''value'';
example_key = ''value'';

Configuration keys have an optional hierarchy separated by dots or braces. These are equivalent:

path.to.key = ''value'';
path.to.another = ''value'';

path
{
   to 
   {
      key = ''value'';
      another = ''value'';
   }
}

path
{
   to 
   {
      key = ''value'';
   }
}
path.to.another = ''value'';

Configuration values are strings or an array of strings using the following notation:

single = data;
single_element_array = [ data ];
trailing_comma_ok = [ data, ];
two_element_array = [ data, banks ];
two_element_array_with_trailer = [ data, banks, ];

Most whitespace is stripped out of the configuration file. These lines are all equivalent:

path.to.key = databanks;        # Value is "databanks"
path.to.key = data banks;       # Value is "databanks"
path . to.key = databanks;      # Value is "databanks"
path.t o.key = d a t a banks;   # Value is "databanks"
pa th. to. k ey = "databanks";  # Value is "databanks"
pa th. to. k ey 
= "databanks";                  # Value is "databanks"

Preserve spaces using quotes:

path.to.key = "data banks";     # Value is "data banks" with a space.
arrays_too = [ "data banks", "another value" ]; # Values are "data banks" and "another value"

Don't split keys or values across lines:

crazy.                 # Syntax error
spacing = "databanks"; # 
crazy.spacing = "data  # Value truncated
banks";                # Syntax error

OK to split other things along lines (or not). These are all legal entires:

key1 = value1;
key2 = 
       value2;
key3 = [ value3.1, value3.2, value3.3 ];
key4
=
[ value4.1, value4.2 ];
key5 = [
     value5.1,
     value5.2,
];
key6 { subkey6.1 = value6.1; subkey6.2 = value6.2; }

Backslash doesn't escape anything (this is a change from the original behavior).

Code exists to easily pull out types boolean, string, int, double, or arrays of these types:

parameter = 5.434; # config.requireDouble("parameter");
switch = false;    # config.requireBoolean("switch");
count = 4;         # config.requireInt("count");
players = [7, 8]   # config.requireInts("players"); // returns int [] length 2

Defaults can be enforced in code:

config.getInt("some.value.not.in.config.file", 4); // returns 4

clients

Clients are encoded in a clients block using their names for their sub block. Additionally, their names must be enumerated in an active_clients array. For example:

clients
{
   active_clients = [ "watchdog", "timer" ];
   watchdog
   {
      command = "run-watchdog.bat";
   }
   timer
   {
      command = "run-timer.bat";
   }
   disabled # not enumerated, so it is ignored.
   {
      command = "run-something-someothertime.bat";
   }
}

Note that there is a default, hidden client named "java-debugger". Don't use this name or put it in the active_clients list.

eaters

general

soar

players

Players are encoded in a players block using arbitrary identifiers for their sub blocks. Active player IDs must be enumerated in an active_players array. For example, the following configuration file defines 3 players but only uses two of them for the run:

players
{
   active_players = [ "obscure", "simple" ];
   obscure
   {
      productions = "agents/tanksoar/obscure-bot.soar";
   }
   simple
   {
      productions = "agents/tanksoar/tutorial/simple-bot.soar";
   }
   mapping
   {
      productions = "agents/tanksoar/tutorial/mapping-bot.soar";
      shutdown_commands = [ "echo shutting down", "print" ];
   }
}

Do not id players with the prefix "gui" or "clone", the players created at runtime use those.

room

There are currently no configuration options for the Room environment.

taxi

tanksoar

terminals

Logging

http://logging.apache.org/log4j/1.2/index.html

Map Files

Maps are now stored in the config/maps/game folder where game is the game type, such as eaters.

Map file

• objects_file (string)
• This file defines objects in the world, see Object File below. The path is relative to the map file.
• objects (string array)
• This is an array of objects ids that are available for use on the map. Often time these ids are one character so the map is easily human-readable.
• cells (block)
• This sub-block defines the cells in the map, or properties about the cells that will be randomly generated.
• cells.size (int)
• Width and height of map.
• cells.random_walls (boolean)
• Randomly generate the walls on this map.
• cells.random_food (boolean)
• Randomly place food on the map.
• cells.rows (block)
• Cell instances
• cells.rows.INTEGER (string array)
• The rows the map, from 0 to size - 1, represented as an array of strings. The strings maps to object ids. Separate multiple objects with dashes. Use a single dash for an empty cell.

Objects File

Objects are under an objects sub-block, and then an id block where the name of the block is their id used in the human-readable map file. Objects need a name property, which is how they are referred to in the code and logs. The rest of the properties are mostly domain specific.

# <ignored> means that the value is ignored, key presence is used for "true"
#objects {
#	+<id> {
#		name = <name>;
#		*<p1> = <value>;								# user property
#		*<p1> = [<value1>, <value2>];					# user property
#		?apply.points = <int>;							# number of points to apply
#		?apply.energy = <int>;							# amount of energy to apply
#		?apply.energy.shields = <boolean>;				# condition for energy apply
#		?apply.health = <int>;							# amount of health to apply
#		?apply.health.shields-down = <boolean>;			# condition for health apply
#		?apply.missiles = <int>;						# number of missiles to apply
#		?apply.remove = <boolean>;						# remove on apply
#		?box-id = <int>;								# this box's id number (set after load)
#		?apply.reward-info = <boolean>;					# contains reward information
#		?apply.reward-info.positive-id = <int>;			# correct box id (set after load)
#		?apply.reward = <boolean>;						# is reward box
#		?apply.reward.correct = <boolean>;				# is the correct box (set randomly after load)
#		?apply.reward.positive = <int>;					# reward if correct
#		?apply.reward.negative = <int>;					# "reward" if incorrect, different from wrong box
#		?apply.reset = <boolean>;						# reset sim on apply
#		?apply.properties {								# these get moved to top level on applyProperties call
#			?<p1> = <value>;							# user apply property
#			?<p1> = [<value1>, <value2>];				# user apply property
#		}
#		?update.decay = <int>;							# decay apply.points by this amount on update
#		?update.fly-missile = <int>;					# increment update.fly-missile phase on update
#		?update.linger = <int>;							# decrement update.linger on update, remove at 0
#	}
#}