## 2. Uso del programa

Este capitulo describe como usar el programa en sí mismo. Si te aburre leerlo de seguido, usa el método de prueba-error de toda la vida, y vuelve aquí si te atascas con algo de la interfaz. Aunque es buena idea leer la mini sección opciones de la linea de comandos (command line options) mostrada abajo. Ten en cuenta que no hay ayuda en el programa; es aquí donde debes buscar ayuda.

## 2.1 Opciones de la linea de comandos (Command line options)

En la linea de comandos hay varias opciones que controlan el comportamiento global de RealTimeBattle. Aqui puedes elegir el "archivo de opciones" que determina los valores por defecto de las 'opciones' (options). También puedes seleccionar en que modo de juego se ejecutará el programa: `debug`, `normal` o `competición`.

     Uso: RealTimeBattle [opciones]

     Opciones:
        --debug_mode,                -d   debug mode.
        --debug_level [0-5],         -D   determina el nivel inicial de debug. Implica -d.
        --normal_mode,               -n   modo normal (por defecto).
        --competition_mode,          -c   modo competición.

        --no_graphics,               -g   sin gráficos.
        --option_file [file],        -o   selecciona el archivo de opciones (por defectot: $HOME/.rtbrc)

        --log_file [file],           -l   genera un fichero de registro (log file). Si 'file' es '-' el log se en                                      viará a la salida estandar (STDOUT)

        --tournament_file [file],    -t   especifica un fichero de torneo para comenzar un torneo.

        --statistics_file [file],    -s   fichero en el que se guardarán las estadisticas.

        --message_file [file],       -m   redirecciona los mensajes a un fichero 'file'. Si ponemos '-' en lugar                                       de un nombre de fichero, se redireccionarán a STDOUT. Si tanto el log c                                      omo los mensajes son enviados a STDOUT, '-m' sera ignorado.

        --replay [file]              -r   repite un fichero de registro. Si se pone '-' como nombre de fichero la                                      entrada será tomada de la entrada estandar (STDIN).

        --help,                      -h   muestra este mensaje.
        --version,                   -v   muestra el numero de versión.

Las diferencias entre los tres modos de competición son mostradas a continuación:

## 2.2 Ventana de control (Control window)

Nuevo torneo (New tournament):

  Para comenzar un torneo nuevo. La sección Comenzar un torneo nuevo (Start new tournament window) te dará mas información.

Repetir torneo (Replay tournament):

  Replay a game. Te permite seleccionar un fichero de registro (log file) del juego para poder estudiarlo.

Pausa:

  Detiene el juego, en el modo competición (competition-mode) la pausa del juego sera postpuesta hasta la finalizacion del juego actual.

Finalizar (End):

  Finaliza el torneo actual.

Opciones (Options):

  Muestra la ventana de opciones (options window).

Estadisticas (Statistics):

  Muestra la ventana de estadisticas (statistics window).

Mostrar Arena (Show arena window):

  Esta opción puede ser usada para mostrar y ocultar las tres ventanas durante el juego: the Ventana de Arena (arena window), the Ventana de puntuación (score window) and the Ventana de mensajes (message window).

Quit:

  Finaliza el programa.

En el modo debug (debug-mode) hay otro grupo de botones disponibles, los cuales estan pensados para ayudar en la depuración de Robots. Ten en cuenta que puedes depurar un proceso ejecutandose; si usas `gdb` el comando es `gdb robot-name process-number`.

Paso a paso (Step):

  En un juego modo debug (debug-mode)<@@ref>pauseden pausa (pausa) ejecutará un 'paso' hacia delante. Es muy útil cuando se depura un Robot, ya que de otra manera el robot es 'floodeado' con mensajes (N. del T. el robot recibe demasiados mensajes como para poder analizarlos).

Finalizar juego (End game):

  Finaliza el juego actual. Tiene el mismo efecto que un timeout .

Matar el Robot señalado (Kill marked robot):

  En el modo debug, se puede marcar un Robot en la ventana de puntuación (score window). Dicho Robot morirá al pulsar este botón.

Grado de depuración (Debug level):

  Cambiar el nivel de depuración es una manera de señalar a los robots que mensajes y cuales no deben enviar. El rango posible es ente 0 y 5, donde 0 significa que no hay ningun tipo de debug y 5 es el maximo nivel de debug, esto es, todos los mensajes de debug seran enviados.

Cuando estas repitiendo un log-file que no sea desde la STDOUT, hay varios botones para controlar la repetición. Para mas información mira en la sección repetición (replaying).

## 2.3 Comenzar un nuevo torneo (Start new tournament window)

Para seleccionar robots y arenas para el torneo, marca los archivos de la derecha y pulsa en el botón `añadir (add)`. Los ficheros seleccionados son mostrados a la izquierda y pueden ser borrados igualmente, pulsando el botón `eliminar (remove)`.

Un torneo consiste en un numero de secuencias de juegos. En cada secuencia el mismo robot compite en todos los juegos. Aqui se puede seleccionar el numero de juegos y de secuencias asi como el numero de robots de cada secuencia. Si pretendes jugar con todos los robots en todos los juegos mejor escoger una secuencia en lugar de incrementar el numero de juegos. La razon es evitar el reseteo de los procesos de los robots que llevan un periodo de tiempo, especialmente si hay muchos.

Tambien es posible cargar un torneo desde un archivo o salvar el torneo actual. El último torneo jugado será almacenado en /tmp/rtb/tmp.tour y será siempre mostrado cuando se abre la ventana. Si no está disponible se muestra un torneo vacío.

Debes seleccionar al menos dos robots y una arena para poder empezar.

## 2.4 Directorios de Robots y Arenas

Hay dos maneras de encontrar robots o arenas: Ruta de búsqueda de Robots (Robot search path) y Ruta de búsqueda de Arenas (Arena search path). Por defecto siempre se busca en los subdirectorios `Robots` and `Arenas` de la instalación de Real Time Battle (por defecto: `/usr/local/games/RealTimeBattle`), especificados en el Makefile principal, aun cuando en las opciones ponga otra cosa, pero si creas un directorio nuevo, o si tienes instalado Real Time Battle en otro directorio tendras que especificar estas opciones.

## 2.5 Arena (Arena window)

Aqui es donde tienen lugar las batallas. Si quieres una vista mas detallada, usa los botones de zoom o las teclas +, -, o 0. Los Robots son unos circulos coloreados con una pequeña marca en forma escuadra que muestra la dirección del radar. La linea gruesa es el cañón y la linea delgada apunta en la direccion frontal.

## 2.6 Ventana de puntuación (Score window)

En esta ventana se muestran los robots que compiten en la secuencia actual.

## 2.7 Ventana de mensajes (Message window)

Se muestran los mensajes enviados por los Robots usando Print y Debug. Los mensajes mas recientes son mostrados en la parte superior. Puedes limpiar la ventana y ver solo los mensajes nuevos de un robot en particular.

## 2.8 Ventana de Opciones (Options window)

Aqui tienes la posibilidad de cambiar un gran numero de opciones.En el Capitulo de opciones (Options chapter) puedes encontrar informacion mas detallada. Los cambios no serán aplicados hasta que pulses el botón `apply` o el botón `OK`.

Puedes guardar las opciones en un archivo: `Salvar Opciones (Save options)` salvará las opciones a un fichero que tu elijas y `Salvar por defecto (Save as default)` guardará las opciones en el fichero `.rtbrc` de tu directorio home.

El botón `Default` pondrá todas las opciones con sus valores por defecto.

## 2.9 Ventana de estadisticas (Statistics window)

Hay varias maneras de ver las estadisticas del tornoe. Puedes elegir entre:

- esdisticas de un Robot Individual (Robot),
- el resultado de un juego (game),
- toda la secuencia (sequence total) o
- todo el torneo (total).

Pulsando las flechas puedes moverte al primer elemento, retroceder uno, avanzar uno o ir al último. La barra del centro muestra que es lo que se esta mostrando y pulsandola se actualizaran los datos de las estadisticas del juego actual. Si usas gtk+ 1.1.x, tambien puedes ordenar los datos por columnas presionando en los correspondientes titulos de columnas.

## 2.10 Sin Gráficos (Running without graphics)

Es posible ejecutar RealTimeBattle sin ningun tipo de gráficos. Esto puede ser muy útil cuando se dan casos de series de tests o cuando se ejecuta una competición. Para usar esta opcion tienes dos opciones: pasar el parametro `-g` cuando se ejecute el programa, o bien deshabilitar los gráficos cuando se compila el programa (mira en el fichero `INSTALL` para mas información). La segunda opcion es mejor ya que el ejecutable será menor e irá mas rápido en máquinas lentas. Ello tambien te permite ejecutar RealTimeBattle en ordenadores que no tengan `gtk+` instalado.

Cuando se ejecuta sin gráficos tienes que indicarle un fichero de torneo, o de lo contrario no sucederá nada. También es buena idea crear un fichero de registro o un fichero de estadisticas si quieres saber el resultado.

## 2.11 Ficheros de Torneo (Tournament files)

El fichero de torneo se especifica en las opciones de la linea de comandos (command line option). Cuando se especifica un torneo, él comienza y finaliza automaticamente. Para mas información sobre como guardar las estadisticas mira en la seccion estadisticas (statistics file).

Un fichero de torneo esta conformado por cinco 'palabras'. Todas esas 'palabras' pueden ser escritar muchas veces, pero ten en cuenta que solo la ultima de esas 'palabras', que tiene un numero como argumento, es realmente importatnte. Todas las 'palabras' estarán seguidas de una comilla simple.

Games/Sequence o g/s:

  Toma un numero `*` como argumento. El numero indica cuantos juegos deben ser jugados por torneo. El asterisco significa que el programa ejecutará un juego por cada arena que haya. El valor por defecto es 1.

Robots/Sequence o r/s:

  Toma un número `*` como argumento. El número significa cuantos robots competirán en cada secuencia. El asterisco significa que el programa utilizará el máximo número de robots disponibles. El valor por defecto es 2.

Sequences o seq:

  toma un número `*` como argumento. Este número indica cuantas secuencias serán jugadas en este torneo. El asterisco implica que el programa tomará el numero de robots y el numero de secuencias para todos los robots, y realizará un calculo binomial de forma que cada robot compita contra cada uno de los otros robots exactamente una vez. El valor por defecto es 1.

Robots or r:

  Toma uno o mas ficheros de robot como argumento.

Arenas or a:

  Toma uno o mas ficheros de arena como argumento.

Los argumentos de fichero pueden ser algunos de los siguientes:

Just the file:

  Busca la ruta del fichero:

  Por ejemplo: `Robot: empty.robot`

Full path to the file:

  toma el fichero dado

  Por Ejemplo: `Arena: /usr/local/games/RealTimeBattle/Arenas/Circle.arena`

All files in path:

  Busca en todas las rutas del path y selecciona todos los ficheros que encuentre.

  Por Ejemplo: `Arena: *`

One specific directory:

  Busca en el directorio dado y toma todos los ficheros que encuentre.

  Por Ejemplo: `Robot: /usr/local/games/RealTimeBattle/Robots/*`

Es posible también escribir numerosas veces el mismo fichero. Esto es, si quieres 3 robots rotate_and_fire.robot, simplemente escribe rotate_and_fire.robot tres veces. Esto se verifica tambien con `*`.

Ejemplo de fichero de torneo:

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

## 2.12 Ficheros de Registro (Log files)

A veces puede ser útil repetir (replay) un juego y analizarlo detalladamente o simplemente guardarlo para una futura referencia. Añade `-l` al iniciar RealTimeBattle, junto con el nombre de fichero para activar esta opcion, y utiliza `'-'` para que el registro sea mostrado en la salida estándar.

El formato del fichero de registro es de la siguiente manera: cada linea consiste en una letra, que determina el tipo de informacion, seguido de una lista de argumentos separados por espacios. Se muestra la siguiente informacion:

Header:

  H [games/sequence] [robots/sequence] [sequences] [robots]

Arena info:

  A [line from the arena file]

Game start:

  G [sequence number] [game number]

Option:

  O [option:value]

List of robot properties:

  L [robot id] [robot colour] [robot name]

Robot position info:

  R [robot id] [x] [y] [cannon angle] [radar angle] [energy]

Time:

  T [time elapsed]

Print message:

  P [robot id] [message to print]

Cookie:

  C [cookie id] [x] [y]

Mine:

  M [mine id] [x] [y]

Shot:

  S [shot id] [x] [y] [dx/dt] [dy/dt]

Die:

  D [type of object killed] [object id] (if robot: [points received] [position])

## 2.13 Repetición (Replaying)

Puedes repetir un juego a partir de su fichero de registro (log file) pasando al programa desde la linea de comandos (command line option) el parámetro `"-r"` o bien desde la ventana de control (control window). Ten en cuenta que si el registro proviene de la entrada estándar (comando `"-r -"`), no podrás hacer demasiado, pero por otro lado podrás influir en el desarrollo del juego:

- La barra de dsplazamiento superior muestra el progreso del juego. Puedes saltar a cualquier momento del juego desplazandote en la barra.
- El rebobinado y el avance rápido sirven para avanzar o retroceder en la repetición. Puedes variar la velocidad cambiando la opción factor de avance rápido (fast forward factor).
- Puedes estudiar el juego detenidamente avanzando o retrocediendo paso a paso en la repetición. Para ello el juego debera estar en factor de avance rápido (fast forward factor)<@@ref>pausedpausa (paused).
- Con los cuatro botones puedes saltar entre los juegos y las secuencias.

## 2.14 Fichero de estadisticas (Statistics files)

El fichero de estadisticas se usa solo cuando es especificado un fichero de torneo (tournament file). Las estadisticas serán guardadas en dicho fichero cuando el torneo finalize. De todoas modos, puedes salvarlas a mano usando el botón `save` de la ventana de estadisticas (statistics window).