The RoboTour Stream Interface
-----------------------------

RoboTour can be remote controlled via the stream interface. 
This is a useful communication method for programs written in other programming 
languages (like Java or Delphi).


* Basics *******************************************************************************

The controlling application is responsible itself for acquiring RoboTour's 
standard input and output stream. 
RoboTour must be started with the parameter "-v -999" to invoke the stream
interface. (This is a special verbose value.)

Commands sent to RoboTour are mostly one-line and generally have the form

   command [param1 [param2 [...]]]

with one space between the command and the parameter(s) and between every two
parameters. Every command or parameter may be surrounded by quotation marks (")
and may then contain spaces, an example is 
  insert "hello world.rob" 
which will correctly insert the file "hello world.rob".

The results given back by RoboTour are given one result per line, i.e.
  
   result1
   result2
   ...



* Work-Flow ****************************************************************************

         +-------------------------------+
         | Start Robotour with "-v -999" |
         +-------------------------------+
                          |
                          v
         +-------------------------------+   _exit_
     +-->|   Simulation Setup Mode       | ----------> Quit Robotour
only |   +-------------------------------+
 RT3 |                    |
mode |                    v
     |   +-------------------------------+   _exit_
     +---|   Run Mode                    | ----------> Quit Robotour
         +-------------------------------+

* Commands *****************************************************************************

Note: Commands and parameters are case sensitive!!!

Table format is "command name, number of return lines, description"
Stars denote new commands (i.e. which are only available in RoboTour 3).

- Always available ---------------------------------------------------------------------

     _exit_         0       Exits RoboTour immediately. Do NOT simply close the
                            streams unless RoboTour has completed successfully!


- Sim Setup Mode -----------------------------------------------------------------------

    version         1       Returns RoboTour's version as a floating-point number (e.g. 3.0)
  * langversion     1       Returns the maximum supported language version (e.g. "RC300")
  * commands        1-x     Returns all supported commands in setup mode, then _done_
                            You should not rely on a particular order in the return values.
  * options c       1-x     Returns all supported options for setup command c, then _done_
                            c may be one of the commands with special string options, 
                            in this version "ttype" and "mode". If you give any other command,
                            just _done_ will be returned. 
                            You should not rely on a particular order in the return values.
    num    n        0       Sets the sim repeat count to n (like -n).
    randomize b     0       (b = "true"|"false") Sets randomize option (like -r).
    rco f           0       Sets the option file to f (like -o).
    insert f        1-2     Inserts robot file f.
                            Returns _too_many_bots_ if too many bots were inserted.
                            Otherwise, returns the number of bots present (e.g. 5)
                            and, in the next line, either _unable_to_open_ or the 
                            bot's robot name.
  * assemble f      1-x     Tries to assemble the given file without inserting it into the
                            tournament. Returns any number of errors (one line per error)
                            in the file, or specially "_unable_to_open_" if the file was
                            not found, then "_done_". If the program assembles correctly,
                            only one line "_done_" is returned. 
    listbots        1+2*n   Returns first the number of inserted bots (e.g. 5),
                            then for each bot its global id (from 0)
                            and its robot name.
  * ttype t         0       Sets the tournament type. t must be one of "Single","Charts",
                            or "All_In_One" (corresponding to the command line options
                            -s, -c and -i).
  * mode m          0       Sets the interface mode. m must be one of "Old" or "RT3".
                            If this command is not given, the Old mode (compatibility to
                            RoboTour 1.x) will be used. Only the RT3 mode displays information
                            about multiple tasks and supports more than one tournament.
                                
    start           1-4     Switches to run mode.
                            If the tournament type is Single or Charts, returns "_bots_", then the 
                            two global ids of the players in the new simulation, then "_done_".
                            Else, simply returns "_done_".

- Run Mode -----------------------------------------------------------------------------

  * commands        1-x     Returns all supported commands in run mode, then _done_
                            You should not rely on a particular order in the return values.
  * options c       1-x     Returns all supported options for run-mode command c, then _done_
                            c may be one of the commands with special string options, 
                            in this version "display". If you give any other command,
                            just _done_ will be returned. 
                            You should not rely on a particular order in the return values.
    step s          0       Sets the number of cycles RoboTour will simulate uninterruptedly.
                            After approximately s cycles, RoboTour will prompt for input again.
    cycle           1       Returns the current simulation cycle.
    abort           1-4     Aborts the current simulation, declares it a tie and continues
                            with the next simulation.
                            See start for return lines.
    allbotnums      1+2*n+1 Returns first the number of programs in this simulation (programs
                            with no more bots may or may not be included), then for each of them
                            their local id and their number of robots.
                            Finally returns "_done_".
    allbotnames     1+2*n+1 Returns first the number of programs in this simulation (programs
                            with no more bots may or may not be included), then for each of them
                            their local id and their robot name.
                            Finally returns "_done_".
  * allids          1+2*n+1 Returns first the number of programs in this simulation (programs
                            with no more bots may or may not be included), then for each of them
                            their local id and their global id. 
                            Finally returns "_done_".
    display d       0       Sets the display mode for field. d must be one of "Running_Bank_Owner", 
                            "Generation", "Num_Banks", "Running_Bank" or "NONE".
                            
    field           ???     Returns the current field. See the table below for returns.
    
    next            1-x     Simulates the next (step) cycles. Returns _done_ if the simulation
                            is not finished after them, or _gameover_, the end cycle and the sim 
                            results (see runmode.pdf) if it has ended.
                            

Note that many commands return _done_ at the end of their output. For "field", it is required,
and for all others returning _done_, it is suggested that after parsing the expected result of
the command, you skip any lines until receiving a _done_. That makes it possible to extend commands.


- "field" Return Table -----------------------------------------------------------------

: For Old Mode: ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::

+---------------------------------------+
| "global constant Fields"              |
+---------------------------------------+
| For each row (top -> down)            |
+-+-------------------------------------+
| | For each field (left -> right)      |
| +-+-----------------------------------+
| | | No <- Bot on field? -> Yes        |
| | +------+----------------------------+
| | | "-1" | "bot owner local id"       |
| | |      | "bot heading"              |
| | |      | "bot active value"         |
| | |      +----------------------------+
| | |      | display mode specific vals |
| | +----- +----------------------------+
| | | "_next_"                          |
+-+-+-----------------------------------+
| "_done_"                              |
+---------------------------------------+

where display mode specific vals are:

Display mode        Vals
---------------------------------------------------------
Running_Bank_Owner  "local id of the running bank owner"
Generation          "bot generation"            
Num_Banks           "bot number of banks"        (1..50)
Running_Bank        "number of the running bank" (1..50)
NONE                (no vals)


: For RT3 Mode: ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::

+---------------------------------------+
| "global constant FieldsX"             |
| "global constant FieldsY"             |
+---------------------------------------+
| For each row (top -> down)            |
+-+-------------------------------------+
| | For each field (left -> right)      |
| +-+-----------------------------------+
| | | No <- Bot on field? -> Yes        |
| | +------+----------------------------+
| | | "-1" | "bot owner local id"       |
| | |      | "bot task count"           |
| | |      +----------------------------+
| | |      | For each task              |
| | |      +-+--------------------------+
| | |      | | "task heading"           |
| | |      +-+--------------------------+
| | |      | "bot active value"         |
| | |      +----------------------------+
| | |      | display mode specific vals |
| | +----- +----------------------------+
| | | "_next_"                          |
+-+-+-----------------------------------+
| "_done_"                              |
+---------------------------------------+

where display mode specific vals are:


Display mode        Vals
---------------------------------------------------------
Running_Bank_Owner  for each task:
                      "local id of the running bank owner"
                      
Generation          "bot generation"            

Num_Banks           "bot number of banks"        (1..50)

Running_Bank        for each task:
                      "number of the running bank" (1..50)
                      
NONE                (no vals)



- Notes on how to interprete the return values -----------------------------------------

Headings: 0 = right, 1 = up, 2 = left, 3 = down


IDs: 
  - Global IDs are the indices of a certain program in the tournament result table.
    They are used for returning results of simulations and are returned by "insert" and
    "listbots", also when starting the simulation in Charts or Single Mode.
  - Local IDs are the indices of a certain program in the simulation's program table.
    They are used for identifying robots on the field and are returned by the "allnames" 
    command.
  You can translate between these IDs using the "allids" command.