From c4ac5567597c1cfcc390d649886b04eb640492d2 Mon Sep 17 00:00:00 2001 From: aleandro Date: Sun, 14 Jun 2026 21:27:36 +0200 Subject: [PATCH] Add: README.md --- README.md | 202 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 200 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 65aec0d..9c0bf73 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,201 @@ -# Ing-sw-2026-pirrera-radice-pagani-pellegrino -Progetto Ingegneria del Software 2026 +# Mesos — Ingegneria del Software 2026 +**Gruppo GC14** — Pirrera · Radice · Pagani · Pellegrino + +--- + +## Funzionalità implementate + +| Funzionalità | Stato | +|---|:---:| +| Regole complete del gioco | ✅ | +| Interfaccia TUI (Text User Interface) | ✅ | +| Interfaccia GUI (JavaFX) | ✅ | +| Rete — RMI | ✅ | +| Rete — Socket/TCP | ✅ | +| FA1 — Persistenza | ✅ | +| FA2 — Resilienza alla disconnessione | ✅ | + +### Note sulle funzionalità avanzate + +**FA1 — Persistenza** +Il server salva automaticamente lo stato della partita su disco (`GameSaves/save.dat`) dopo ogni evento di gioco. Se il server viene riavviato, la partita salvata viene ripristinata automaticamente e i client possono riconnettersi. Il salvataggio viene scartato solo se al momento del crash erano disconnessi tutti i giocatori tranne al massimo uno. + +**FA2 — Resilienza alla disconnessione** +Un client che perde la connessione viene marcato come disconnesso ma non rimuove la partita. La partita continua con gli altri giocatori. Il giocatore disconnesso può riconnettersi in qualsiasi momento con lo stesso username e ritrovare la partita nello stato corrente. + +--- + +## Requisiti di sistema + +- **Java 25** o superiore +- I JAR sono fat-jar (tutte le dipendenze incluse), non è necessario installare librerie esterne +- La GUI richiede un display grafico (non funziona in ambienti headless puri) + +--- + +## Compilazione + +Per generare i JAR dalla sorgente: + +```bash +./mvnw package -DskipTests +``` + +I tre JAR vengono prodotti nella cartella `target/`: + +| File | Descrizione | +|---|---| +| `target/Server.jar` | Server di gioco | +| `target/ClientTUI.jar` | Client testuale (TUI) | +| `target/ClientGUI.jar` | Client grafico (GUI) | + +--- + +## Avvio — Server + +```bash +java -jar Server.jar +``` + +All'avvio il server elenca le interfacce di rete IPv4 attive e chiede all'operatore di sceglierne una (necessario per il corretto funzionamento di RMI in rete locale). Se è presente una sola interfaccia, viene selezionata automaticamente. + +**Esempio di output:** + +``` +[0] eth0 -> 192.168.1.10 +Choose interface: 0 +192.168.1.10 +Server RMI: 192.168.1.10 +``` + +**Porte utilizzate dal server** (non devono essere bloccate dal firewall): + +| Protocollo | Porta | +|---|---| +| RMI registry | 1099 | +| TCP gioco | 8080 | +| TCP heartbeat | 8081 | + +--- + +## Avvio — Client TUI + +```bash +java -jar ClientTUI.jar +``` + +All'avvio il client chiede interattivamente: + +| Campo | Valori accettati | +|---|---| +| `Username` | stringa libera, max 32 caratteri | +| `Number of players [2-5]` | intero tra 2 e 5 | +| `Network [rmi/tcp]` | `rmi` oppure `tcp` | +| `Server IP [localhost]` | indirizzo IP del server; invio vuoto usa `localhost` | + +### Comandi disponibili in-game (TUI) + +| Comando | Descrizione | +|---|---| +| `slot ` | Sposta il totem nello slot in posizione `` | +| `draw upper tribe ` | Pesca la carta tribù in posizione `` dalla riga superiore | +| `draw upper building ` | Pesca la carta edificio in posizione `` dalla riga superiore | +| `draw lower tribe ` | Pesca la carta tribù in posizione `` dalla riga inferiore | +| `draw lower building ` | Pesca la carta edificio in posizione `` dalla riga inferiore | +| `totem ` | Sceglie il totem in posizione `` (fase di selezione totem) | +| `skip` | Passa il turno | +| `clear` | Ridisegna la board a schermo | +| `details buildings` | Mostra la descrizione di tutti gli edifici | +| `details events` | Mostra la descrizione di tutti gli eventi | +| `details characters` | Mostra la descrizione di tutti i personaggi | +| `help` | Lista dei comandi disponibili | +| `rematch` | Torna alla schermata di login (solo a fine partita) | +| `quit` | Disconnette e chiude il client | + +La TUI supporta il completamento automatico con **Tab** per tutti i comandi. + +--- + +## Avvio — Client GUI + +```bash +java -jar ClientGUI.jar +``` + +Si apre direttamente la finestra grafica. Compilare i campi nella schermata di login: + +- **Username** — nome del giocatore +- **N. players** — numero di giocatori (2–5) +- **Protocollo** — toggle RMI / TCP (click per cambiare) +- **Server IP** — indirizzo IP del server + +Premere **Accedi** per connettersi. La GUI si avvia in modalità fullscreen; premere **ESC** per uscire dal fullscreen e **F11** per rientrarci. + +--- + +## Test in locale (tutti su localhost) + +1. Aprire un terminale e avviare il server: + ```bash + java -jar Server.jar + # quando chiede l'interfaccia, premere invio o scegliere 127.0.0.1 + ``` + +2. Aprire N terminali (uno per client) e avviare i client: + ```bash + # TUI + java -jar ClientTUI.jar + # Username: giocatore1 Players: 2 Network: tcp IP: [invio] + + # oppure GUI + java -jar ClientGUI.jar + ``` + +3. Non appena il numero di giocatori configurato si è connesso, la partita parte automaticamente. + +--- + +## Test in rete locale + +1. Il server gira sulla macchina con IP es. `192.168.1.10`. +2. Avviare il server e scegliere l'interfaccia `192.168.1.10`. +3. I client su altre macchine usano quel IP come `Server IP`. +4. Assicurarsi che le porte **1099**, **8080**, **8081** siano raggiungibili dalla rete. + +> **Nota RMI**: RMI richiede che il client possa raggiungere il server all'IP dichiarato durante l'avvio. Se server e client sono sulla stessa macchina usare `localhost`; se sono su macchine diverse usare l'IP della rete locale (non `localhost`). + +--- + +## Struttura del progetto + +``` +src/main/java/it/polimi/ingsw/gc14/ +├── Controller/ # GameController (server) e ClientController (client) +├── Model/ # Entità di gioco: Player, Game, Board, Card, Slot, ... +│ ├── Cards/ # BuildingCard, TribeCard, EventCard, Character* +│ ├── GamePackage/ # Board, CurrentState, GameStages +│ └── Orders/ # Logica di ordinamento turni +├── Network/ # Protocolli di rete +│ ├── RMI/ # Client e server RMI +│ ├── TCP/ # Client e server TCP +│ └── NetworkEvents/ # Tutti gli eventi di rete serializzabili +├── View/ +│ ├── GUI/ # Schermate JavaFX (Login, Totem, Main, Leaderboard) +│ └── TUI/ # Renderer testuale con JLine +├── ServerLauncher.java +├── ClientLauncherGUI.java +└── ClientLauncherTUI.java +``` + +--- + +## Persistenza — dettagli tecnici + +Il file di salvataggio viene creato nella directory da cui si lancia il JAR del server: + +``` +./GameSaves/save.dat +``` + +Per forzare una partita nuova (ignorando il salvataggio) è sufficiente eliminare questo file prima di avviare il server.