Colossus options design
$Id: options.txt 3628 2009-02-26 03:01:06Z dripton $

There are two basic kinds of options in Colossus, client and server.
Server options are those for the whole game.  They are set at game
start by the player who starts the game.  Client options are for one 
client, or one player.  (There is one client per player, including
non-GUI AI clients.)

There are three main ways to set an option: on the command line, with
a GUI menu, or from a config file.  They should be as orthogonal as
possible -- it should be possible to set any option in any of these 
ways.  (Though it's not, yet.)

The command line is a convenient place to set some options to allow
automated testing, or quick startup for advanced users.  But most 
endusers will run the game from a GUI or Java Web Start, where 
command line options are difficult or impossible to set, so any 
option available on the command line should also be available on a 
menu.

A config file is a convenient way to reuse earlier option settings.
We use standard Java Properties files, with filenames 
Colossus-{playername}.cfg or Colossus-server.cfg   We automatically
load config files corresponding to the user's name during 
initialization.  We also have save and load option menu items for
the player options.  Server options are automatically saved and 
loaded, with no explicit save or load menu items.

Note that because of multiple ways to start the game (Java Web
Start versus JRE on command line versus running a local executable 
jar file from a GUI) it's not always obvious where to look for these
config files.  We use the Colossus subdirectory under whatever 
directory is pointed to by the Java property user.home.  

It is very easy for users to view and change boolean options using 
checkboxes.  Options with numeric or string values require slightly 
more complex GUIs to view or change.  I added a generic PickIntValue 
dialog that replaces PickScale and PickDelay and should work for 
setting any future int options.

There are two main GUI classes that allow changing options.  One is 
GetPlayers, which is used only by the primary client at the beginning 
of the game.  (Some functionality, like setting all of the player 
names from this dialog, will obviously change for networking.)
The other is MasterBoard, which has menus that stay up for the whole
game.  Some options, like balanced starting towers and variant, only 
work if set before the game starts.  Others can be varied during the 
game.  For simplicity we will require that *all* server options be
set for good at the start of the game.  (Client options can be changed
during the game.)

The net.sf.colossus.util.Options class is used (separately) by the
server and each client.  It actually stores the set of options in
a Properties, which is in turn backed by a Hashtable of string
keys to string values.  So this means that all options are really 
strings, and we need to do some conversion to return them as ints 
or booleans.  Options has methods to assist, but because of the lack
of type checking it's important to ask for the right kind of value
for each option.  Properties includes the interface we use for file 
saving and loading.

The rule when option settings conflict is that command-line options
override options loaded from a config file at game start.  Options
changed on a menu should override anything set earlier on the command 
line or in a config file.

Options are never duplicated between client and server sides.  Client 
options are controlled from the MasterBoard menus and 
Colossus-{playername}.cfg.  Server options are controlled from the 
GetPlayers menus, Colossus-server.cfg, and command-line options.  
No server options can be changed in the middle of a game.  (This is 
unfortunately inconvenient for some options.)  The player cfg files 
never override the server cfg file.

To simplify the GetPlayers dialog, and allow reusing the values from
the previous game, we're now treating player names and types and the
variant as server options.

Note that Game.syncOptions() copies all server options to all clients,
so that client-side clones of server functionality (e.g. Movement)
know the correct settings for optional rules.