The RoboTour command line interface

Quick Start

You can simply start RoboTour with some robot files (.ROB or .RBI files) as command line arguments.

Example: robotour ruhe.rbi dj.rbi test.rob

The result is a tournament of all robots specified against all. At the end of the tournament, a table will be shown containing the results of all robots.

Wildcards (*) are permitted, for example, to select all files of one type.

Example: robotour -s thebestbot.rob bots/*.rob top20/*.rbi

As the -s parameter is used in this example, only the first specified robot, thebestbot.rob, will be simulated against all other robots.

You can get more information about possible options by calling robotour without parameters or by reading the following sections.

Parameter overview

Mostly, RoboTour will be used to simulate tournaments. There are several standard settings that can be changed:

Tournament configuration options
-h Prints a help screen which shows all of the options supported by RoboTour.
-n n You can change how often each fight will be repeated. Normally, it is ten times like in the Classic competition on the Internet. Example: -n 5
-o RCOFile Set the game settings (timings, ...) file to RCOFile. Normally, the enclosed file robocom.rco is used, which loads the settings of the Classic Competition from the Internet. Example: - o hard.rco
-r Disable randomizing. This causes RoboTour to produce the same results every time it is started.
Mode selection options
-c Switch to "charts" mode: Simulate every robot against every other robot. This is the standard mode.
-s Switch to "single" mode: Simulate only the first robot against all others. Useful for testing new robots.
-i Switch to "all-in-one" mode: Load all specified bots into one simulation.
-t n Switch to "top n" mode: Create a charts list where it is possible to add robots. If there are more than n robots in the charts, the worst will be dropped. Example: -t 20
-T n
Switches to the "top n" mode, too, however, old results (partially simulated robots from the last run of RoboTour) are re-used.
-cf Folder Sets the competition folder. That is the folder in which RoboTour looks for robots and results files when using the top mode. Using this switch, you can run top mode competitions from every folder (e.g. the one in which RoboTour is installed.)
Special RoboTour configuration options
-v n Set the verbose level of RoboTour. Normally, this is set to 5, lower values cause less output. Example: -v 2
-p n Print the field every n cycles. The resulting text mode field is not very nice, so the feature is normally deactivated. The visualization mode can do a much better job for this. Example: -p 100
-batch Never pops up any message boxes. This option is useful for batch scripts running RoboTour. (Only the Windows version of RoboTour sometimes pops up message boxes. This setting has no effect under the Unix version.)
-sound
Enables sound output. Using this option, you can listen to the first robot's success even when RoboTour is running in the background. (In single mode, the first robot is the one that plays against all others; in top mode, it is the one which is being added to the competition.) Not all versions of RoboTour support sound; it is only supported if it appears on the help screen (-h ).
-prof Type
Enables the instruction profiler. Three different types of profiles can be generated:
  • count will simply count how often each instruction is executed.
  • time will count all cycles spent executing a certain instruction.
  • fail will calculate the failure ratio for certain instructions, such as CREATE and TRANS.
-vis
Enables the visualization mode. RoboTour will launch a graphical window which displays the tournament.

Examples:

robotour bots/*.rbi
robotour -n 5 -o easy.rco -v 2 others/*.rob
robotour -s mybestbot.rob top20/*.rbi
robotour -r -p 100 -v 0 ruhe.rbi dj.rbi > ruhe_dj.log
robotour -t 20 infector.rob

Modes

RoboTour supports various tournament modes that are useful for different purposes.

The top mode

The top mode works like RobServ: it manages a competition with fixed maximum size. New robots can be added to the competition, and only the best robots will stay in the charts as soon as the maximum size is reached. A result HTML charts file is automatically created whenever robots are added to the competition; detailed simulation results pages can be created using the makehtml program (see below).
RoboTour's top mode is very powerful, for example, the Eternal Competition is run using RoboTour's top mode. 

The detailed procedure to set up a competition is as follows:

makehtml

The helper program makehtml is used to create HTML results files for competitions run using the top mode (see above). Following is a detailed description of its command line arguments: 

-h
Prints a help screen which shows all makehtml command line options.
-name CompName
Sets the competition's name to CompName . The competition name is shown on all HTML pages.
-cf Folder
Sets the competition folder to Folder . That is the folder in which makehtml looks for the result files written by RoboTour. If the parameter -cf is not specified, the current folder is used.
-of Folder
Sets the output folder to Folder. That is the folder in which the generated HTML pages are written. It is usual to use the same folder as for -cf here. Howeber, if -of is not specified, the current folder is used.
-nolinks
Do not create links to the detailed results pages. Normally, makehtml generates links from the charts page to the detailed pages, and between the detailed pages. If you'd like to publish a single page (for example, the charts page only), these links would however lead to nowhere, so here's the option to switch them off.
-nodownload
Do not create links to the robot source files ( .rob / .rbi). Normally, makehtml generates links to the robot source files much like RobServ. However it does not encode .rob files to binary files, so if you do not want to publish the source files, you will not want to have download links.

Any other command line argument (wildcards are permitted) is interpreted as a robot file relative to the competition folder, and for this robot, a detailed results page is created.
However, you can even start makehtml without any command line arguments; in that case, it just creates the charts page.

Customizing the output

The HTML pages written by makehtml can now be customized by editing the charts.css file which is written to the output folder. (Note: makehtml ensures that the file is not overwritten if it exists, so your changes will not be lost when re-running makehtml.)

That charts.css file is a standard cascaded stylesheet file and can be edited with every plain-text editor. The most interesting thing you may want to change are the different colours for current and old robots. These are the styles topcur (robots in the charts, played against the current version) down to badold (robots which are no longer in the charts, and where we've played against an old version only). Along with the style title (the table header fields), you may create an entirely new color-scheme for your competition.

kickbot

The helper program kickbot is used to throw robots out of a top-mode competition. Well, actually, the robots are only thrown out of the charts, they are still left in the competition (results against them still show up in the detailed results pages). It is used, for example, when a robot is considered a simple copy ("clone") of another previously-existing robot, and is no longer allowed to appear in the Eternal Competition. 

Kickbot is run with kickbot -cf compFolder badbot.rob, where compFolder is the competition folder name as it was given to robotour, and badbot.rob is the file name of the robot which should be thrown out of the charts (relative to the competition folder).
As usually, kickbot -h gives all possible command line options.

There's one pitfall with kickbot: it does not recreate the HTML result pages, nor recalculate the charts. Of course, you can run makehtml afterwards to recreate the result pages, and the bad bot will indeed vanish from the charts, but some results may be slightly incorrect. The only solution is to add a new robot to the competition using robotour (or simply re-simulate one), which will recalculate the results.
Normally, this is not a problem as most competitions have lots of new robots all the time.