#####  ######  ####### ######  ####### #######  #####   #####   #####
    #     # #     # #     # #     # #     #    #    #     # #     # #     #
    #       #     # #     # #     # #     #    #    #             #       #
    #       ######  #     # ######  #     #    #     #####   #####   #####
    #       #   #   #     # #     # #     #    #          #       # #
    #     # #    #  #     # #     # #     #    #    #     # #     # #
     #####  #     # ####### ######  #######    #     #####   #####  #######


    (C) Copyright 1998 - 2001, All rights reserved.

    CROBOTS is copyrighted by:
                  
         Mikhail Verkhovski
         miscellone@yahoo.com 

    1.  License agreement:

    You may make copies of this program, manual, and other files and
    give it to your friends or include it in the library of a non-profit
    computer club.

    I expressly forbid any for-profit venture from selling this
    software and manual, either separately or as part of a software
    "library".

    DISCLAIMER OF WARRANTY

    THIS SOFTWARE AND MANUAL ARE PROVIDED "AS IS" WITHOUT WARRANTY OF
    AND KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED
    TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS OF
    PURPOSE.  THE USER OF THIS SOFTWARE AND MANUAL ASSUME ALL RISKS.
        
    2. Introduzione

    Si suppone che il lettore conosca il manuale originale 'crobots.doc'
    di Tom Poindexter. Questo manuale insieme con programma 'crobots.exe'
    puo' essere scaricato, per esempio, dal: 

         http://www.pluricom.it/mcm/intellig/files/crobots/crobots.zip

    2-1. Descrizione

    Crobots32 e' il programma di controllo dei crobots per Windows95/NT,
    che sopporta la maggior parte dei crobots gia' esistenti. La ragione
    principale che ha spinto l'autore di mettersi al lavoro e di creare
    'crobots32' e' stato il forte desiderio di evitare la morte dei tornei
    dei crobots. L'autore spera che il nuovo programma che quasi non ha
    i limiti per le caratteristiche dei crobots permettera' di sviluppare
    la nuova generazione dei programmi piu' flessibili e potenti.

    2-2. Problemi di compilazione

    Il programma originale 'crobots.exe' e' anche un compilatore da 
    un dialetto del linguaggio 'C'. Per non mischiare le due cose insieme
    l'autore ha deciso di usare un compilatore vero 
    (Microsoft (R) 32-bit Optimizing compiler Version 11) per compilare i
    crobots. Purtroppo il dialetto usato in 'crobots.exe' non e' un 
    sottoinsieme del 'C'. Cioe' non tutti i crobots esistenti possono essere
    compilati immediatamente. Per esempio:

    - il programma rabbit.r di Tom Poindexter contiene la non definita
      variabile locale 'd'

    - il programma abyss.r di Daniele Nuzzo, partecipante al
      ultimo torneo dei crobots, contiene l'espressione

         (q+=180)%=360

      che non e' stata riconosciuta dal compilatore
        
    Per fortuna questi errori sono pochi e facilmente riparabili. La maggior
    parte dei crobots esistenti viene compilata e eseguita senza problemi.

    2-3. Novita'

    Davanti alla vastissima gamma delle nuove possibilita' che potevano essere
    date alla nuova generazione dei crobots l'autore alla fine ha aggiunto
    al set delle funzioni originali solo due nuove: 'trace' e 'message'.
    La prima serve solo per produrre il log del comportamento interno di un
    crobot. La seconda invece e' molto piu' importante. Infatti i nuovi
    crobots possono comunicare e cooperare fra di loro! Si puo' pensare
    quindi ai tornei misti fra (per esempio) le coppie dei crobots che,
    cooperando, migliorano le loro prestazioni.

    2-4. Hardware and software richiesti

    Per eseguire 'crobots32' serve un personal computer con Windows95
    o WindowsNT installati.
    I crobots vengono compilati con un compilatore 'C' a 32-bit.
    L'autore usa il Microsoft (R) 32-bit Optimizing compiler Version 11
    distribuito insieme con Microsoft (R) Visual C++ 5.0.

    2-5. Interfaccia utente

    Come 'crobots' il programma 'crobots32' non usa menu e finestre e viene
    lanciato dalla command line in una finestra DOS. In differenza il 
    'crobots32' puo' essere eseguita in modo speciale (supervised mode)
    in cui il suo output puo' essere semplicemente usato per disegnare la
    situazione attuale nel campo. Nella distribuzione e' incluso il programma
    'crobcons32' che serve come esempio dell'uso di tale modo. Si
    lasciano le opportunita' di creazione dell'interfaccia grafica agli altri
    programmatori.

    2-6. Distribuzione

    Il file di distribuzione 'crobots32.zip' contiene i seguenti componenti:

      crobots32.exe          - programma di controllo dei crobots
      crobint32.obj          - linked-in modulo d'interfaccia
      crob32.bat             - batch di compilazione dei crobots
      crobcons32.c           - esempio dell'applicazione grafica
      crobcons32.exe         - esempio compilato
      crobdummy32.c          - dummy file per compilazione controllata
      crobdummy32.obj        - dummy file gia' compilato
      coop.r                 - esempio del crobot di cooperazione
      coop.exe               - esempio compilato
      crobots32.txt          - questo manuale

    3. Compilazione del crobot

    Un crobot viene compilato con commando DOS:

         crob32 robot.r

    Il processo di compilazione si divide in due passi.

    1) Il batch compila il file di crobot come un programma 'C' e
       cerca di eseguire un link con il modulo 'crobdummy32.obj' (che
       contiene tute le funzioni "ammesse") usando l'opzione 'nodefaultlib'.
       Questo passo serve per controllo delle chiamate alle funzioni
       di 'C' run-time library e alle funzioni di Windows che non sono
       permesse in crobots.

    2) Se il primo passo di compilazione e' andato senza errori
       Il batch recompila il file di crobot ed esegue il link con
       interfaccia 'crobint32.obj' che serve per connessione con 'crobots32'.

    Il risultato di compilazione e' il file 'robot.exe' che poi' viene
    lanciato in background dal 'crobots32'.

    4. Esecuzione del 'crobots32'

    4-1. Opzioni della command line

    'crobots32' viene lanciato in una finestra DOS con commando:

         crobots32 [flags] <crobot_1> [... <crobot_n>] [>file]

    L'esecuzione troppo lunga puo' essere interrotta con <Ctrl><Break>.
        
    I flag validi sono:

    -d<file>   - Specifica il nome di file per logging.
                 Ci viene stampata tutta l'informazione interna del
                 'crobots32' includendo le posizioni e caratteristiche
                 dei crobots e missili, le richieste dei crobots etc.

    -g<number> - Ripete il gioco con specifico numero.
                 Il numero di gioco normalmente si sceglie casualmente
                 nel intervallo 0 <= N <= 32767 e viene visualizzato
                 nel output del programma (vedi l'esempio del output di
                 'crobots32'). Il flag '-g' da possibilita' di ripetere
                 un specifico gioco (con debug acceso, per esempio)
                 per analizzare i particolari.

    -l<number> - Definisce il numero massimo dei cicli per una battaglia.
                 Se il flag '-l' non e' stato specificato (o il valore e'
                 negativo) il numero massimo e' infinito.

    -m<number> - Specifica il numero delle battaglie in un gioco. Valore
                 di default e' 1.

    -s         - Specifica 'supervised mode' di esecuzione. In questo modo
                 tutte le informazioni interne vengono stampate in standard
                 output e possono essere usate per disegnare il campo della
                 battaglia (vedi 'crobcons32.c').
                 In supervised mode ogni riga di output contiene come il
                 primo carattere un carattere di controllo, seguito da uno
                 spazio.

                 I caratteri di controllo possono essere i seguenti:

                 C - collisione
                 E - errore
                 M - posizione del missile
                 O - stringa di output (viene solamente stampata)
                 P - posizione di un crobot
                 R - richiesta di un crobot
                 X - esplosione

    -t<number> - Specifica il tempo (in millesecondi) di rallentamento per
                 ogni ciclo di esecuzione. Valore di default e' 0. Utile per
                 visualizzare il gioco in modo comprensibile.

    -w<number> - Specifica il numero dei vincitori in ogni battaglia. La
                 battaglia finisce se il numero dei crobots viventi e' 
                 diventato minore o uguale al numero specificato.
                 Valore di default e' 1.

    Il numero massimo dei crobots in campo e' uguale a 8.

    4-2. Esempi

       1) Compilare e far combattere tre crobots:
                 crob32 robot1.r
                 crob32 robot2.r
                 crob32 robot3.r
                 crobots32 robot1 robot2 robot3 

       2) Repetere il gioco numero 25637 con debug:
                 crobots32 -g25637 -dcrobots32.log robot1 robot2 robot3 

       3) Eseguire un gioco di 50 battaglie, limitando numero di cicli a
          200,000 e salvare i risultati:
                 crobots32 -m50 -l200000 robot1 robot2 > save
       
    4-3. Priorita'

    I crobots eseguiti con 'crobots32' non hanno i limiti prestabiliti delle
    dimensioni (che dipendono solamente dalle capacita' fisiche del
    computer utilizzato). Per questo motivo e' stato introdotto il
    meccanismo di penalizzazione dei crobots lunghi. Al inizio del gioco
    'crobots32' assegna ad ogni crobot un numero intero >= 10 - la sua
    priorita'. Al crobot piu' corto (come dimensioni del file .exe) si
    assegna la priorita' 10. La priorita' di ogni altro crobot viene
    aumentata ad 1 per ogni 512 byte della sua lunghezza. Piu' precisamente
    si usa la formula:

                   priority = (size - min_size)/512 + 10;

    Durante il gioco la frequenza con cui il 'crobots32' esegue le richieste
    dei crobots e' uguale alla loro priorita'. Cioe' le richeste dei crobots
    piu' lunghi vengono eseguite piu' raramente! Si spera che il meccanismo 
    sopraindicato permettera' di impedire l'apparizione dei "giganti"
    nel mondo dei crobots.

    4-4. Esempio del output di 'crobots32'

    L'output del commando:
 
         crobots32 -m10 counter rook

    e' stato seguente:

    1    Crobots 32-bit Control Utility, Version 1.11 for Windows95/NT
    2    Copyright (C) 1998 by Mikhail Verkhovski. All rights reserved.
    3    GameNumber=14136
    4    Crobots:
    5    1: counter (size=55808, priority=11)
    6    2: rook (size=55296, priority=10)
    7
    8    Match         1        2 
    9    -------------------------
    10       1:   4075---  4075:17
    11       2:   7874---  7874:04
    12       3:   6218:00  6218---
    13       4:   3274---  3274:02
    14       5:  10970:50 10970---
    15       6:   3314:00  3314---
    16       7:   9597:83  9597---
    17       8:   3754---  3754:02
    18       9:   3182:00  3182---
    19      10:   6009:10  6009---
    20   -------------------------
    21   Total:        6        4 

    Le prime due righe sono identificative. Il numero della versione 
    del 'crobots32' (1.11 in questo caso) e' essenziale. Si prega di 
    indicare questo numero in tutte le comunicazioni con autore.
  
    La riga 3 specifica il numero di gioco, che puo' essere ripetuto
    usando il flag '-g'.

    Le righe 5 e 6 specificano i partecipanti, la loro lunghezza (in bytes)
    e priorita'.

    Le righe 10-19 specificano le 10 battaglie fra i due crobots.
    Ogni riga contiene:
         numero della battaglia
         numero dei cicli per ogni crobot
         danneggiamento finale (--- significa che il crobot e' stato ucciso)
    Per esempio il numero 10970:50 nella riga 14 significa che il crobot
    'counter' e' uscito dalla battaglia 5 con danneggiamento 50 dopo 10970
    cicli.

    La riga 21 specifica il numero totale delle battaglie in cui e' rimasto
    vivo ognuno dei partecipanti. In nostro caso 'counter' e' rimasto vivo
    sei volte mentre il 'rook' solo quattro.

    5. Specifiche dei crobots

    5-1. Estensioni 

    In differenza al 'crobots' nei crobots eseguiti con 'crobots32' sono
    permessi tutte le espressioni del linguaggio 'C', tutti i tipi delle
    variabili, strutture, vettori, #define etc.
    La funzione 'main' riceve un parametro, un numero intero compreso
    fra 1 e 8 (inclusi), che e' un identificativo del crobot (vedi coop.r
    per esempio). Per diversi crobots in campo i numeri identificativi
    sono diversi.

    5-2. Limitazioni
 
    Ogni crobot e' un programma 'C' che viene compilato con compilatore
    'C'. La regola principale del 'crobots' rimane pero' invariata:
    ogni crobot e' solo un file, tutto quello che gli serve ci deve essere
    definito. Sono vietate le #include e le chiamate a qualsiasi funzione
    tranne quelle elencate.

    6. Funzioni

    6-1. Elenco delle funzioni ammesse

    Segue l'elenco dei prototipi di tutte le funzioni ammesse in crobots.

    1)   int cannon (int angle, int range);
         int damage ();
         int drive (int angle, int speed);
         int loc_x ();
         int loc_y ();
         int message (int key, int mess);
         int scan (int angle, int range);
         int speed ();

    2)   int atan (int arg);
         int cos (int arg);
         int rand (int arg);
         int sin (int arg);
         int sqrt (int arg);
         int tan (int arg);
         int trace (char *format, ...);

    Tutte le funzioni tranne 'trace' e 'message' sono descritte nel manuale
    originale 'crobots.doc'. E' importante che le funzioni del primo gruppo
    producono le richieste al modulo centrale 'crobots32' e, quindi, 
    rallentano l' esecuzione. Le funzioni del secondo gruppo vengono 
    eseguite localmente (nel 'crobint32.obj').

    6-2. trace

    Funzione 'trace' serve per stampare il valore delle variabili interne di
    un crobot. Alla prima chiamata la 'trace' apre in modo 'append' il file
    di log con nome 'nome_identificativo'. Se questo file e' aperto ci
    vengono stampate i valori delle variabili specificate usando il formalismo
    della funzione 'printf'. Ci vengono stampate pure le informazioni
    di tutte le chiamate alle funzioni elencate. Il file di log viene chiuso
    specificando (void *)0 come primo e unico parametro di 'trace'.

    Per esempio:
                                       /* aprire il file di log e    */
                                       /* stampare i valori di x e y */
         trace ("x=%d y=%d\n", x, y);
         . . . . . .
         trace ((void *)0);            /* chiudere il file di log    */

    'trace' ritorna 0 se si e' verificato un errore durante l'apertura
    il file di log e 1 in tutti altri casi. 

    6-3. message

    Funzione 'message' serve per organizzare la coordinazione e cooperazione
    fra i crobots. Dopo la chiamata, il modulo centrale 'crobots32'
    memorizza il valore del parametro 'mess' insieme con la chiave 'key'.
    Se un altro crobot (o lo stesso) in un secondo momento chiamera' 'message'
    con lo stesso chiave, valore di 'mess' sara' sostituito con un nuovo
    mentre il valore vecchio ritornato al chiamante.
    I valore validi della chiave 'key' sono compresi fra 0 e 32767 (inclusi).
    'mess' e' un qualsiasi numero intero.
    Inizialmente i valori memorizzati per tutte le chiavi sono uguali a 0.

    Per esempio:

         ret = message (1000, 1);      /* ret = 0, memorizzato 1     */
         ......................
         ret = message (1000, 2);      /* ret = 1, memorizzato 2     */

    7. Contorno

    7-1. crobcons32

    'crobcons32' e' un esempio dell'utilizzo dell'esecuzione in 
    'supervised mode'. 'crobcons32' aggiunge il parametro '-s' alla 
    command line e lancia 'crobots32' usando la funzione 'popen'.
    Il standart output di questo ultimo viene analizzato per disegnare
    la battaglia.

    Per osservare il combattimento fra robot1 e robot2, per esempio,
    si puo' utilizzare il commando:

         crobcons32 -t1 robot1.r robot2.r

    7-2. coop.r

    'coop.r' e' un esempio di cooperazione fra i crobots.
    Lanciato in piu' esemplari, lui stabilizza la gerarchia e passa dal
    generale fino all'ultimo soldato l'ordine, che contiene
    la posizione da raggiungere. Dopo di che, usando sempre l'ordine
    del generale, tutti i crobots sparano simultaneamente, formando
    una specie di parata militare.

    Per osservare la parata si puo' utilizzare il commando:

         crobcons32 -t1 -l10000 coop coop coop coop coop