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.

Single (-s) and charts (-c) mode are similar to the tournament mode of RoboCom Workshop. In single mode, the first specified robot will play against all others, in charts mode, everyone will play against everyone.
The all-in-one (-i) mode is similar to the simulation mode in RoboCom. The big advantage is that you can use bigger fields (by editing the RCO file) because RoboTour is much faster.

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:

Create a new empty folder in which your competition will reside; let's assume it's called x:\tour for this tutorial.
Copy all robots which should be added initially to your competition into the competition folder.
Change to the RoboTour folder in your command shell and run robotour -t 20 -cf x:\tour *.rob *.rbi
-t 20 means that you want to start a competition with chart size 20 (of course you can use any other number)
-cf x:\tour means that your competition (i.e. all the bots and results files) lives in the folder x:\tour. *.rob *.rbimeans that you want to include all robots in the competition folder.
Run makehtml -cf x:\tour -of x:\tour *.rob *.rbi to create HTML files from the competition results. You will need to re-run makehtml every time after entering new robots into the competition. See below for more details on makehtml.
When inserting new robots to the competition later,
- copy them into the competition folder
- run robotour -cf x:\tour -t 20 newbot.rob (where newbot.rob is the file name of the new robot; of course you may specify more than one robot file in the command line).
To update a robot in your competition with a newer version, just copy the newer version of the robot into the competition folder under the same file name (like RobServ!) and run robotour -cf x:\tour -t 20 updated.rob.
If you want to throw a robot out of the competition, run kickbot -cf x:\tour sillybot.rob and insert a new robot. (The charts will only be recalculated after another robot was added.)

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