DidaWiki

Questa pagina è in sola lettura. Puoi visualizzare il sorgente, ma non puoi modificarlo. Contatta l'amministratore se pensi che ci sia un errore.
====== Progetto 2 ======

Questa pagina descrive il **II Progetto di LPR 2009/10**.

===== Descrizione del gioco =====

Un certo numero di robot assassini sono intrappolati all'interno di una struttura, composta da varie stanze variamente collegate, e interamente circondata da un muro. Ciascun robot può spostarsi  all'interno di questo "labirinto", guardarsi intorno, e fare fuoco con un raggio laser incorporato. Ogni robot è poi dotato di una batteria che lo alimenta, e che viene (lentamente) ricaricata tramite pannelli fotovoltaici dalla luce ambientale.
Ogni giocatore controlla un numero variabile di robot, che possono agire individualmente o come squadra; lo scopo del gioco è distruggere il maggior numero possibile di robot avversari... prima che questi ultimi distruggano voi!

Il campo di gioco è costituito da una superficie di 32x32 caselle, suddivisa in ambienti da una serie di muri; su questi muri si aprono tipicamente varie porte che li mettono in collegamento. Ogni robot è controllato da un client, che interagisce col server tramite protocollo TCP; i diversi client di una squadra **devono** interagire tra di loro, con modalità a scelta dello studente, per realizzare strategie di cooperazione che consentano di ottenere una maggior efficienza.

Per ogni robot avversario distrutto, viene assegnato al robot assassino un punteggio pari a 1 più la metà del punteggio dell'avversario distrutto (approssimato in basso); i robot più efficaci sono quindi anche le prede più ambite.
===== File eseguibili =====
Il progetto consiste nella scrittura di un client (giocatore) per un server dato (che gestisce il gioco). Il codice del server è disponibile per essere scaricato; è possibile che vengano rilasciate versioni successive (con modifiche minori, quali fine-tuning di alcuni parametri) in seguito.
==== File scaricabili ====

Versione iniziale (10 Maggio 2010): [[http://margot.di.unipi.it/LPR-09/Laprore-Server2.jar|Server]] di gioco, [[http://margot.di.unipi.it/LPR-09/Laprore-Client2.jar|Client]] di esempio

==== Istruzioni ====

I file necessitano di Java Virtual Machine installata sulla macchina. Essi possono essere usati sia da GUI (con un doppio click sull'icona) che da riga di comando.
=== Uso da GUI ===
Aprendo il server si aprirà il pannello che rappresenta il campo di gioco, con tutti i parametri impostati al loro valore di default (vedi la prossima sezione). Il server è ora disponibile ad accettare connessioni dai client; chiudendo la finestra, si termina l'applicazione. Il pannello a destra elenca i robot registrati; per ciascun robot viene riportato il nome (troncato ai primi 8 caratteri e preceduto da "+" se il robot è stato distrutto), la carica della batteria, e il punteggio corrente.
Il client può essere lanciato un numero qualunque di volte; a ogni esecuzione da GUI, verrà registrato un nuovo giocatore sul server (con un nome casuale). Per default, le opzioni del client coincidono con quelle del server. Con la chiusura del server, terminano (con un errore) tutti i client collegati fino a quel momento.

=== Uso da riga di comando ===
Il server può essere lanciato con il comando

''java -jar Laprore-Server2.jar //portaTCP//''

in cui:
  * //portaTCP// è la porta su cui il server si pone in ascolto per le connessioni TCP provenienti dai client (per default: 4000)

Il client può essere lanciato con il comando

''java -jar Laprore-Client2.jar //nome host portaTCP//''

in cui:

  * //nome// è il nome scelto per il robot (per default: generato casualmente)
  * //host// è l'indirizzo della macchina su cui gira il server (per default: localhost)
  * //portaTCP// è la porta, sull'//host//, su cui il server è in ascolto (per default: 4000)

Tutti i parametri (sia del server che del client) sono opzionali, ma se presenti devono essere indicati in ordine. Per esempio, è possibile indicare sul client il nome del robot, omettendo host e porta.


===== Documentazione del protocollo =====

Client e server comunicano tramite un unico canale tramite TCP. Tutte le comunicazioni sono iniziate dal client.

==== Convenzioni generali ====
=== Formato ===
Il protocollo di comunicazione è basato sullo scambio di comandi e risposte di un singolo byte; alcuni comandi considerano il byte suddiviso in campi di bit, a cui sono assegnati specifici significati; in altri casi, i byte vengono interpretati come valori numerici a 8 bit.

=== Temporizzazione ===
Ciascun cliente **deve** inviare almeno un messaggio ogni 5 secondi (altrimenti viene dichiarato //morto di sonno// e chiuso). Per prevenire lo spamming, il server **ignora** ogni messaggio che sia ricevuto dopo meno di 50ms dal messaggio precedente dello stesso client. È comunque possibile inviare poi in seguito altri messaggi, sempre rispettando i vincoli temporali di cui sopra. Si noti che se un messaggio ignorato prevedeva una risposta, la risposta non verrà inviata: è quindi opportuno assicurarsi di non inviare messaggi troppo ravvicinati, oppure prendere le dovute cautele per rilevare, con un timeout, il caso in cui una risposta attesa non arrivi in tempo. In condizioni normali, le risposte ai comandi vengono inviate immediatamente dopo la ricezione ed elaborazione del comando da parte del server.

=== Fairness ===
Tentativi di sabotare il server o il protocollo sono lodevoli, ma considerati illegali ai fini dell'esame. È possibile contattare il docente per verificare la "legalità" di una tecnica non ortodossa che si intende usare. È altresì considerato illegale usare nella propria implementazione classi del server o del client di esempio, estratte dal codice fornito.
==== Messaggi TCP ====
I comandi hanno la seguente struttura:
  * bit 7-6: riservati per future espansioni
  * bit 5-2: opcode di comando
  * bit 1-0: codice di direzione

=== Comandi ===
^ Comando ^^ Descrizione ^ Risposta ^ Consumo energia ^
^ Nome ^ Valore ^ ^ ^ ^
| Comandi con codice di direzione |||||
^ STEP ^ 1 | Si sposta di un passo verso la //direzione//, se possibile. | - | 1 unità |
^ LOOK ^ 2 | Guarda verso la //direzione//, fino a incontrare un ostacolo a distanza //d//. | Un byte contenente il tipo di ostacolo, seguito da un byte contenente //d//. | - |
^ FIRE ^ 3 | Emette un raggio laser lungo la //direzione//, fino a incontrare un ostacolo a distanza //d//. | Un byte con valore NAK se non è stato colpito alcun avversario, o se non si ha energia sufficiente; oppure con valore ACK se è stato colpito un avversario. | //d// unità |
| Comandi senza codice di direzione |||||
^ GPS ^ 5 | Restituisce la propria posizione corrente. | Un byte contenente la posizione //x//, un byte contenente la posizione //y//. | - |
^ BATTERY ^ 6 | Restituisce la carica corrente della batteria. | Un byte contenente la carica corrente; 255=massima, 0=esaurita. | - |
^ SCORE ^ 7 | Restituisce il punteggio corrente. | Un byte contenente il punteggio corrente. | - |
^ TELEPORT ^ 8 | Teletrasporta il robot in un punto casuale della mappa. | - | 10 unità |
^ REGISTER ^ 9 | Registra il client sul server; questo comando deve essere inviato prima di ogni altro comando, e il byte di comando deve essere seguito da una stringa ASCII NUL-terminated contenente il nome del robot, che deve essere unico. Il comando è illegale se inviato successivamente alla prima registrazione. | Un byte ACK se la registrazione è stata accettata, o NAK se è stata rifiutata. | - |

Per il comando GPS, il sistema di coordinate utilizzato è quello consueto (in Informatica), con (0,0) nell'angolo in alto a sinistra, e coordinate crescenti verso destra e verso il basso.

=== Altre costanti ===
^ Costante ^ Valore numerico ^ Descrizione ^
|Direzioni|||
^ N ^ 0 | nord (verso l'alto) |
^ E ^ 1 | est (verso destra) |
^ S ^ 2 | sud (verso il basso) |
^ W ^ 3 | ovest (verso sinistra) |
|Codici di conferma|||
^ ACK ^ 1 | conferma; vero; esito positivo |
^ NAK ^ 0 | diniego; falso; esito negativo |
|Oggetti di mappa|||
^ ROBOT ^ 82 | un robot |
^ WALL ^ 88 | un muro interno |
^ OUTSIDE ^ 0 | fuori mappa (un muro esterno) |

==== Gestione della batteria ====
Se il robot non dispone di energia sufficiente a eseguire un comando, l'azione corrispondente non viene eseguita (ma, se prevista, viene inviata una risposta come di consueto). La batteria viene ricaricata dalle celle fotovoltaiche al ritmo di 2 unità ogni secondo. La carica massima della batteria è di 255 unità, e i robot entrano in gioco con la batteria carica al massimo.

==== Comunicazioni intra-client ====
Il protocollo, i formati, e il tipo di comunicazione (tipicamente: TCP, UDP, Multicast o RMI) fra client sono interamente a discrezione dello studente, che dovrà darne documentazione nella relazione. In ogni caso, i vari clienti devono essere istanze dello stesso eseguibile, eseguite su JVM distinte e potenzialmente su macchine diverse. Non è ammessa la comunicazione fra client che utilizzi tecniche diverse dalla comunicazione via rete.

==== Trattamento degli errori e terminazione ====
Se il server riconosce un errore nel comportamento del client, la comunicazione viene interrotta (il giocatore rimane registrato ma viene "espulso" dal gioco). Il server segnala tali errori emettendo una eccezione (con l'indicazione del giocatore che ha causato l'errore e del tipo di errore).
Il timeout di una comunicazione è considerato un errore, così come l'invio di comando invalidi. Lo "spamming" non è invece considerato un errore, ma i comandi in eccesso vengono scartati. Quando un robot viene distrutto, il client relativo viene sconnesso; questo caso non è considerato un errore (ma essere distrutti non fa piacere a nessuno).
Il gioco non prevede la possibilità di de-registrare un giocatore, né un esplicito "fine partita"; ogni esecuzione del server corrisponde a una partita, che può essere interrotta in qualunque momento interrompendo il server (da tastiera con Ctrl-C o chiudendo la sua finestra).

===== Requisiti generali e modalità di consegna =====

Ogni studente che vuole sostenere l'esame di LPR deve consegnare il 
progetto svolto al docente del corso di appartenenza (Prof. Gervasi per il Corso A, Prof. Corradini per il Corso B).
Il progetto deve essere sottomesso individualmente, ma può essere
svolto da un gruppo di due studenti al massimo: in questo caso nel
progetto va indicato esplicitamente il collega con cui si è collaborato.
L'esame orale del corso, che comprende la discussione del progetto, sarà individuale: ciascuno studente
è responsabile dell'intero progetto consegnato.

Per poter essere valutato, il codice del client sviluppato nel progetto deve essere in grado di 
interagire senza errori con il server pubblicato in questa pagina, in una o più istanze (l'esatto numero verrà comunicato dopo l'iscrizione degli studenti alla gara finale) eseguite su host diversi o anche sullo stesso host. Il progetto deve funzionare correttamente sulle 
macchine del CLI, dove verrà testato. 

Il codice del progetto deve essere ben commentato e deve essere accompagnato da una relazione
di 3-5 pagine che descrive l'organizzazione del codice, le strategie realizzate per il funzionamento
del singolo client e per la collaborazione tra più client, e le politiche di sincronizzazione tra thread
utilizzate. Inoltre occorre produrre un breve manuale d'uso che descrive i comandi necessari per 
avviare le varie istanze del client, sia su uno stesso host che su host diversi. 

Codice, relazione e manuale d'uso devono essere inviati per posta elettronica al docente del 
corso **entro le ore 24 di lunedì 21 Giugno 2010**. Progetti inviati dopo tale scadenza non
verranno ammessi, e lo studente dovrà svolgere un nuovo progetto che verrà pubblicato successivamente.

I progetti sottomessi verranno testati durante un evento pubblico; i dettagli verranno forniti in seguito.
===== Suggerimenti finali =====

L'implementazione del cliente di esempio (che sarebbe già sufficiente ai fini dell'esame, tranne che per la mancanza di coordinamento) consta di circa 100 righe di codice Java (di cui circa 60 significative); si consiglia agli studenti di iniziare con un'implementazione semplice, e poi eventualmente dedicarsi al miglioramento dell'efficienza e delle strategie. Si noti che ai fini della valutazione verranno considerati primariamente:
  * la correttezza dell'uso delle tecniche di multithreading e di comunicazione di rete; 
  * il design e l'implementazione del protocollo inter-client;
  * l'efficienza della soluzione (sia in termini di uso delle risorse che di efficacia della strategia complessiva della squadra);
  * la qualità complessiva di scrittura del codice e della relazione.
Nella parte orale verranno invece verificate le conoscenze teoriche su tutti gli argomenti trattati nel corso.

Si raccomanda di verificare in anticipo il funzionamento dei client sulle macchine del Centro di Calcolo (Laboratori H-Lab e M-Lab), su cui verrà svolto il "torneo" finale dopo la data di consegna. Si raccomanda altresì di contattare i docenti, a ricevimento o per email, **prima** della consegna in caso di dubbi sull'interpretazione del testo.

Per lanciare più istanze del client in maniera rapida, si può usare un comando di shell di questo tipo:

''for i in 1 2 3; do java -jar Laprore-Client2.jar Test-$i & done''

o un suo equivalente su altri sistemi operativi.
===== FAQ =====
**Come è definita una "squadra"?**
\\
Non esiste sul server il concetto di squadra; dal punto di vista del server, si tratta di robot singoli. Ai fini dell'esame, una "squadra" è l'insieme delle istanze di un client lanciate dallo stesso studente (sulla stessa macchina o anche, potenzialmente, su macchine diverse). Sta allo studente implementare una qualche strategia di comunicazione per consentire il loro coordinamento (per esempio, per riconoscersi l'un l'altro ed evitare di distruggersi a vicenda).

**Il server mi restituisce a volte -1 in risposta al comando BATTERY, è un errore del server?**
\\
No, il valore restituito è del tutto corretto. Si raccomanda di verificare la propria interpretazione del valore, perché...
//En este mundo traidor, nada es verdad, ni mentira: todo es según el color del cristal con que se mira//.