## 2. Bedienung des Programms

Dieses Kapitel beschreibt, wie man RealTimeBattle bedient. Wenn es Dir langweilig erscheint, die ganze Anleitung durchzulesen, kannst du auch nach dem `Try-and-Error`-Prinzip vorgehen, und nur nachschauen wenn du irgendwo nicht weiterkommst. Es ist aber eine gute Idee den kurzen Abschnitt über Kommandozeilen-Parameter zu lesen. Beachte auch, dass es keine eingebaute Hilfe im Programm selber gibt - um Hilfe zu erhalten musst du dieses Dokument lesen.

## 2.1 Kommandozeilenparameter

An der Kommandozeile gibt es die Möglichkeit, zwei Optionen zu setzen, die das allgemeine Verhalten von RealTimeBattle kontrollieren. Hier kannst du die Options-Datei wählen, die die Standardwerte der Optionen festlegt. Man kann auch auswählen, in welchem Spielmodus das Programm laufen wird: `Debug-`, `Normal-` oder `Competition-`Modus.

     Programmaufruf: RealTimeBattle [Optionen]

     Optionen:
        --debug_mode,                -d   Debug-Modus
        --debug_level [0-5],         -D   Setzt den anfänglichen Debug-Level. Impliziert -d
        --normal_mode,               -n   Normal-Modus (standard)
        --competition_mode,          -c   Competition-Modus

        --no_graphics,               -g   es werden keine Grafiken angezeigt
        --option_file [file],        -o   wählt die Options-Datei (standard: $HOME/.rtbrc)

        --log_file [file],           -l   erzeuge eine Log-Datei;
                                          wenn als Datei '-' angegeben wird,
                                          wird nach stdout geloggt.

        --tournament_file [file],    -t   Angabe einer Turnier-Datei um
                                          automatisch ein Turnier zu starten.

        --statistics_file [file],    -s   Datei in die Statistiken
                                          geschrieben werden, wenn
                                          automatisch gestartet wird.

        --message_file [file],       -m   Nachrichten in die Datei
                                          "file" umleiten. '-' entspricht
                                          stdout. Wenn die Logs und die
                                          Nachrichten nach STDOUT umgeleitet
                                          werden, wird '-m' ignoriert.
        --replay [file]              -r   Ein Logfile das abgespielt
                                          werden soll. Wenn '-' als Datei
                                          angegeben wird, wird von STDIN
                                          gelesen.

        --help,                      -h   zeigt diese Informationen
        --version,                   -v   gibt die Versionsnummer aus
        --port_number                -p   legt den Port fest, an denen externe Clients sich
                                          verbinden können (Standard: 32134)

Die port_number Option ist nur dann verfügbar, wenn RealTimeBattle mit der --enable-network Option compiliert wurde (siehe Datei `INSTALL`). Die Unterschiede zwischen den drei Comepetition-Modi sind in folgender Tabelle zusammengefasst.

Modus | Debug | Normal | Competition
Debug Kommando verfügbar | Ja | Nein | Nein
Pause während des Spiels | Ja | Ja | Nein
Programm schrittweise ausführbar | Ja | Nein | Nein
CPU-Zeit der Roboter ist unbeschränkt | Ja | Ja | Nein

## 2.2 Kontroll-Fenster

New tournament:

  Ein neues Turnier wird gestartet. Die Sektion Neues Turnier-Fenster öffnen gibt mehr Informationen darüber.

Replay tournament:

  Ein Spiel ablaufen lassen. Du wirst das Logfile des Spiels auswählen müssen das du studieren willst.

Pause:

  Hält das Spiel an. Im Competition-Modus wird erst am Ende des aktuellen Spiels angehalten.

End:

  Beendet das aktuelle Turnier.

Options:

  Öffnet das Options-Fenster.

Statistics:

  Zeigt das Statistik-Fenster an.

Show arena window:

  Diese Box kann dazu benutzt werden die drei Fenster, die während eines laufenden Spieles zu sehen sind, zu verstecken oder anzuzeigen, nämlich: das Arena-Fenster, das Score-Fenster und das Nachrichten-Fenster.

Quit:

  Beendet das Programm.

Im Debug-Modus stehen weitere Möglichkeiten zur Verfügung. Sie dienen dazu, beim debuggen von Robotern zu helfen. Es ist möglich, laufende Prozesse (und somit Roboter) zu debuggen. Wenn man `gdb` benutzt, muss man folgendermaßen starten: `gdb Robotername Prozessnummer`.

Step:

  In einem angehaltenen Spiel wird dieser Button das Spiel um eine Zeiteinheit voranschreiten lassen. Dies ist sehr nützlich, wenn man einen Roboter im Debugger am Laufen hat, da der Roboter sonst mit Nachrichten überflutet werden würde.

End game:

  Das aktuelle Spiel wird beendet. Das hat den selben Effekt wie ihn ein Timeout haben würde.

Kill marked robot:

  Im Debug-Modus kann man einen Roboter im Score-Fenster markieren. Dieser Roboter wird sterben, wenn man diesen Button drückt.

Debug level:

  Den Debug-Level zu ändern ist eine Möglichkeit, den Robotern mitzuteilen, welche Nachrichten sie senden sollen. Dieser Wert liegt zwischen 0 und 5, wobei 0 bedeutet, dass überhaupt nicht debuggt wird, und 5 ist der höchste Debug-Level, d.h. alle Debug-Nachrichten sollen gesendet werden.

Beim Abspielen einer Logdatei (nicht von STDOUT) gibt es eine Menge Möglichkeiten die Wiedergabe zu steuern. Siehe dazu auch das Kapitel über Replaying.

## 2.3 Neues Turnier-Fenster öffnen

Um Roboter und Arenas für ein neues Turnier auszusuchen, musst du die Dateien auf der rechten Seite markieren und den `add`-Knopf drücken. Die ausgesuchten Dateien werden links angezeigt. Sie können entsprechend auch wieder entfernt werden.

Ein Turnier besteht aus einer bestimmten Zahl von Sequenzen von Spielen. In jeder Sequenz spielen die gleichen Roboter in allen Spielen. Hier wählt man die Anzahl der Spiele und Sequenzen, und auch die Anzahl der Roboter in jeder Sequenz. Wenn du vorhast, jedes Spiel mit allen Robotern zu spielen, ist es ratsam, nur eine Sequenz zu wählen und stattdessen die Anzahl der Spiele zu erhöhen. Der Grund dafür ist, es zu vermeiden alle Roboter-Prozesse neu zu starten, da dies eine Weile dauern kann, besonders wenn viele Roboter gegeneinander antreten.

Es ist auch möglich eine Turnier-Datei zu laden oder das aktuelle Turnier zu speichern. Das letzte gespielte Turnier ist in /tmp/rtb/tmp.tour gespeichert und wird immer angezeigt wenn dieses Fenster geöffnet wird.

Wenn die Datei nicht existiert wird ein leeres Turnier angezeigt. Du musst mindestens zwei Roboter und eine Arena auswählen um starten zu können.

## 2.4 Roboter- und Arena-Verzeichnisse

Damit das Programm die Roboter und die Arenas findet, muss man zwei Optionen setzen: den Roboter-Suchpfad und den Arena-Suchpfad. Die Unterverzeichnisse `Robots` und `Arenas` im Installationsverzeichnis (Standard-Wert: `/usr/local/games/RealTimeBattle`), das vor dem Kompilieren im Haupt-Makefile festgelegt wird, werden auf jeden Fall durchsucht. Wenn man ein neues Verzeichnis erzeugt, oder wenn man RealTimeBattle in ein anderes Verzeichnis installiert hat, muss man diese Optionen setzen.

## 2.5 Arena-Fenster

Hier findet das Gemetzel statt. Wenn du das Spiel detaillierter betrachten willst, kannst du die Zoom-Knöpfe benutzen oder +, - oder 0 drücken. Die Roboter werden als farbige Kreise mit einer Spitze in dem Kreis, die die Radar-Richtung anzeigt, die dicke Linie ist die Kanone und die dünne Linie zeigt in Bewegungs-Richtung.

## 2.6 Score-Fenster

In diesem Fenster werden alle Roboter aufgelistet, die in der aktuellen Sequenz "mitspielen".

## 2.7 Nachrichten-Fenster

Hier werden Nachrichten angezeigt, die die Roboter mittels Print und Debug senden. Die neuesten Nachrichten erscheinen ganz oben. Du kannst das Fenster leeren und auswählen nur die neuen Nachrichten von einem bestimmten Roboter zu sehen.

## 2.8 Options-Fenster

Hier kannst du eine ganze Reihe von Optionen ändern. Im Optionen-Kapitel kannst du detaillierte Informationen zu jeder Option erhalten. Die Änderungen werden erst wirksam, wenn entweder der `apply`- oder der `OK`-Knopf gedrückt werden.

Man kann seine Optionen auch in eine Datei sichern: `Save options` wird die Optionen in eine Datei deiner Wahl speichern und `Save as default` wird sie in die Datei `.rtbrc` in deinem Homeverzeichnis sichern.

Der `Default`-Button wird alle Optionen auf ihre Standardwerte zurücksetzen.

## 2.9 Statistik-Fenster

Man kann sich die Statistiken des aktuellen Turniers auf verschiedene Arten anzeigen lassen:

- Statistiken über einzelne Roboter,
- die Ergebnisse eines Spieles (game),
- die Gesamtergebnisse der Sequenz (sequence total) oder
- die Gesamtergebnisse(total) des Turniers.

Mit den Pfeiltasten kann man zum ersten Element, eines zurück, eines vorwärts oder zum letzen Element gelangen. Der Balken in der Mitte ist ein Indikator dafür, was gerade angezeigt wird; Wenn man auf den Balken drückt, werden die Statistiken erneuert, vorausgesetzt das Spiel läuft gerade. Wenn du gtk+1.1.x verwendest ist es auch möglich, die einzelnen Spalten zu sortieren, indem man ins entsprechende Titel-Kästchen klickt.

## 2.10 Spiel ohne Grafiken

Wenn man will, kann man RealTimeBattle auch ganz ohne Grafiken laufen lassen. Dies kann besonders nützlich sein, wenn man eine lange Reihe von Tests oder einen Wettbewerb durchführt. Man hat zwei Möglichkeiten diese Option zu benutzen: Entweder man verwendet die Option `-g` beim Programmstart, oder man schaltet die Grafiken schon beim Kompilieren ab (die Datei `INSTALL` gibt dazu nähere Informationen). Die letze Alternative ist besonders nützlich, da die ausführbare Datei kleiner wird und daher auf Rechnern mit weniger Arbeitsspeicher schneller läuft. Das ermöglicht es auch, RealTimeBattle auf Rechnern laufen zu lassen, auf denen kein `gtk+` installiert ist.

Wenn man ohne Grafiken arbeitet, muss man ein Turnier-file angeben, andernfalls wird nichts passieren. Es ist auch zu empfehlen eine Log-Datei und/oder Statistik-Datei zu erzeugen, wenn man die Ergebnisse wissen will :-)

## 2.11 Turnier-Dateien

Die Turnier-Datei wird als Kommandozeilenparameter angegeben. Wenn diese Datei verwendet wird, wird das Turnier automatisch anfangen und beendet werden. Wie man die Statistiken speichert steht im Kapitel Statistik-Datei.

Eine Turnier-Datei besteht aus 5 Schlüsselwörtern. Alle diese Schlüsselwörter können mehrmals benutzt werden, aber man muss sich dessen bewusst sein, dass nur das letzte Schlüsselwort, das eine Zahl als Parameter annimmt, gezählt wird. Alle Schlüsselwörter sollten mit einem Strichpunkt beendet werden.

Games/Sequence oder g/s:

  Als Parameter muss man entweder eine Zahl oder ein `*` angeben. Die Zahl legt fest wieviele Spiele pro Turnier gespielt werden sollen. Das Sternchen bedeutet, dass das Programm die genaue Anzahl von Arenas hernimmt und diese Zahl als Parameter verwendet. Der voreingestellte Wert ist 1.

Robots/Sequence oder r/s:

  Als Parameter muss man entweder eine Zahl oder ein `*` angeben. Die Zahl legt fest wie viele Roboter in jeder Sequenz antreten. Das Sternchen bedeutet, dass das Programm die Anzahl der Roboter als Parameter nimmt. Der Default-Wert ist hier 2.

Sequences oder seq:

  Als Parameter muss man entweder eine Zahl oder ein `*` angeben. Die Zahl legt die Anzahl der Sequenzen die im Turnier gespielt werden sollen fest. Wenn man ein Sternchen angibt, errechnet das Programm aus der Anzahl der Roboter und der Anzahl der Roboter pro Sequenz eine Zahl, sodaß alle Roboter genau einmal gegeneinander antreten. Diese errechnete Zahl wird dann als Parameter verwendet. Der Default-Wert ist 1.

Robots oder r:

  Als Parameter wird eine oder mehrere Roboter-Datei(en) angegeben.

Arenas oder a:

  Eine oder mehrere Arena-Dateien werden als Parameter übergeben.

Datei-Argumente können wie folgt aussehen:

Nur die Datei selber:

  Hier wird der Pfad nach der Datei durchsucht.

  Beispiel: `Robot: empty.robot`

Der volle Pfad zur Datei + der Dateiname:

  Die angegebene Datei wird verwendet.

  Beispiel: `Arena: /usr/local/Games/RealTimeBattle/Arenas/Circle.arena`

Alle Dateien im Pfad:

  Diese Angabe durchsucht den ganzen Pfad und verwendet alle gefundenen Dateien.

  Beispiel: `Arena: *`

Ein bestimmtes Verzeichnis:

  Es wird das angegebene Verzeichnis durchsucht und alle gefundenen Dateien werden verwendet.

  Beispiel: `Robot: /usr/local/Games/RealTimeBattle/Robots/*`

Es ist möglich Dateien mehr als einmal in die Turnier-Datei zu schreiben. Wenn du z.B. drei `rotate_and_fire.robot`s haben willst, trage einfach drei mal `rotate_and_fire.robot` in die Turnier-Datei ein. Dies gilt genauso für `*`.

Beispiel Turnier-Datei:

`R: * Arenas: Circle.arena Square.arena G/S: 2 r/s: 3 Sequences: *`

## 2.12 Log-Dateien

Manchmal ist es ganz nützlich, ein Spiel detailliert zu analysieren ( Replay), oder es einfach nur aufzuheben, weil man es später vielleicht noch brauchen könnte. Hierfür sind Log-Dateien sinnvoll. Gib `-l` als Kommandozeilenparameter an, wenn du RealTimeBattle startest, und dahinter den Dateinamen der Log-Datei, um dieses Feature zu aktivieren. Wenn du als Datei '-' angibst, wird nach stdout geloggt.

Die Log-Datei ist wie folgt aufgebaut: Jede Zeile besteht aus einem Buchstaben, der den Typ der Information angibt, gefolgt von einer Liste von Argumenten die durch 'Whitespaces' getrennt sind. Die folgenden Informationen werden angegeben:

Header:

  H [Spiele/Sequenz] [Roboter/Sequenz] [Sequenzen] [Roboter]

Arena Info:

  A [Zeile aus der Arena Datei]

Spielstart:

  G [Sequenznummer] [Spielnummer]

Option:

  O [Option:Wert]

Liste von Robotereigenschaften:

  L [Roboter-ID] [Roboterfarbe] [Robotername]

Roboter Positions-Info:

  R [Roboter-ID] [x] [y] [Kanonen-Winkel] [Radar-Winkel] [Energie]

Zeit:

  T [verstrichene Zeit]

Nachricht ausgeben:

  P [Roboter-ID] [Nachricht]

Cookie:

  C [Cookie-ID] [x] [y]

Mine:

  M [Minen-ID] [x] [y]

Schuß:

  S [Schuß-ID] [x] [y] [dx/dt] [dy/dt]

Tod:

  D [Typ des gekillten Objekts] [Object-ID] [Wenn's ein Roboter war: erhaltene Punkte] [Position]

## 2.13 Replaying

Du kannst ein aufgenommenes Spiel mit Hilfe seiner Log-Datei abspielen lassen, und zwar entweder aus dem Kontroll-Fenster heraus, oder indem du die Kommandozeilenoption `"-r"` verwendest. Beachte aber, dass du, wenn du Standard-Input als Log-Datei verwendest ( Kommandozeilenoption `"-r -"`), nicht viel mehr machen kannst als das Spiel anzusehen. Normalerweise kann man den Ablauf des Spiels folgendermaßen beinflussen:

- Der Scroll-Balken ganz oben zeigt an, wie weit das aktuelle Spiel schon abgelaufen ist. Man kann an einen beliebigen Zeitpunkt springen, indem man an dem Scrollbalken zieht und ihn richtig positioniert.
- Fast Forward und Rewind funktionieren so, wie man es von CD-Spielern und Video-Geräten gewohnt ist. Die Geschwindigkeit kann mittels Fast Forward Factor geändert werden.
- Step forward und step backward können dazu verwendet werden zu studieren was im Detail passiert. Zuerst sollte man das Spiel allerdings auf Pause setzen.
- Mit den vier Buttons ganz unten kann man zwischen Spielen und Sequenzen hin- und herwechseln.

## 2.14 Statistik-Datei

Die Statistik-Datei wird nur benutzt, wenn eine Turnier-Datei angegeben wurde. Die Statistiken werden in diese Datei gespeichert, wenn das Turnier zu Ende ist. Man kann die Statistiken aber auch mit dem `save`-Knopf im Statistik-Fenster manuell speichern.