Aggiungi documentazione: requisiti, implementazione, lezioni apprese

2026-09-24 14:55:53 +02:00
1 parent d1fd88b5ff
commit de45b6c3b0
@@ -0,0 +1,62 @@
+# Report Implementazione — Stato Attuale
+
+**Data:** 2026-09-24  
+**Stato:** NON FUNZIONANTE
+
+## Cosa è stato fatto
+
+### Struttura file
+```
+giochino/
+├── index.html          # Gioco principale (Canvas JS) — NON FUNZIONA
+├── server.js           # Server HTTP Node.js
+├── server2.js          # Server HTTP Node.js (backup)
+├── server3.js          # Server HTTP Node.js (backup)
+├── pong.py             # Versione Python pygame — NON TESTATA
+├── kitbitz-mcp-call.sh # Test MCP Kitbitz
+├── validate.py         # Script validazione JS
+├── Schermata.png       # Screenshot dell'utente
+├── README.md           # Documentazione base
+└── docs/               # Questa cartella
+```
+
+### Server HTTP
+- Creati 3 diversi server Node.js (`server.js`, `server2.js`, `server3.js`)
+- Il server resta attivo su porta 8095 (via nohup)
+- Servizio file HTML funziona (HTTP 200)
+
+### Gioco JavaScript — Problemi riscontrati
+
+#### Tentativo 1
+- **Problema:** Menu disegnato su Canvas non apparebbava (sfondo nero con solo testo HTML visibile)
+- **Causa probabile:** Funzione `drawMenu()` non chiamata correttamente o errori JS silenziosi
+
+#### Tentativo 2
+- **Problema:** Menu con elementi HTML apparevano ma i tasti non rispondevano
+- **Causa probabile:** Event listener non registrava correttamente i tasti frecce
+- **Errore specifico:** La tastiera dell'utente genera codici non standard (`convert`, `nonconvert`, `NumPadEnter`) invece di `ArrowUp`/`ArrowDown`
+
+#### Tentativo 3
+- **Problema:** Pagina si blocca completamente dopo selezione "VS CPU"
+- **Causa probabile:** Loop di gioco con errore runtime non gestito
+
+#### Tentativo 4
+- **Problema:** Nessun menu, gioco parte direttamente ma disco non si muove con F
+- **Causa probabile:** Logica di stato mal implementata, conflitti nel loop principale
+
+### Analisi dei fallimenti
+
+1. **Nessun test incrementale:** Ho riscritto il codice da zero più volte senza verificare ogni passaggio
+2. **Debug insufficiente:** Assenza di try-catch e logging effettivo
+3. **Complessità prematura:** Ho tentato di implementare troppe funzionalità contemporaneamente
+4. **Mancanza di validazione:** Il validator JS (`validate.py`) rilevava solo errori sintattici, non runtime
+5. **Assunza errata sulle API:** Non ho verificato il comportamento reale degli eventi Canvas/tastiera nel browser
+
+### Cosa manca
+- [ ] Menu funzionante con navigazione tastiera
+- [ ] Selezione difficoltà
+- [ ] Gioco vero e proprio con fisica disco
+- [ ] IA CPU
+- [ ] Sistema punteggio con set
+- [ ] Impostazioni tasti funzionanti
+- [ ] Integrazione con asset Kitbitz (mai iniziata)
@@ -0,0 +1,62 @@
+# Lezioni Apprese e Prossimi Passi
+
+## Errori commessi
+
+1. **Sovrainingegneria:** Ho creato troppe varianti di server e codice senza consolidare
+2. **Mancanza di test incrementali:** Ogni riscrittura completa impediva di isolare i bug
+3. **Assunzioni non verificate:** Ho assunto che frecce standard funzionassero, che Canvas rispondesse, che il loop JS non lanciasse eccezioni
+4. **Debug "alla cieca":** Senza console del browser accessibile, non potevo vedere gli errori reali
+5. **Nessuna architettura chiara:** Mescolare logica di rendering, input e stato in un unico file monolitico ha creato accoppiamento
+
+## Cosa farebbe funzionare
+
+### Approccio consigliato per il prossimo tentativo
+
+1. **Iniziare con un prototipo HTML puro**
+   - Menu come elementi HTML (non Canvas)
+   - Nessun JavaScript per il menu
+   - Solo click su pulsanti
+
+2. **Separare rendering e logica**
+   - Canvas SOLO per il gioco
+   - HTML per menu e UI
+
+3. **Testare ogni meccanica isolatamente**
+   - Prima: solo movimento giocatore
+   - Poi: solo disco che si muove
+   - Poi: interazione disco-giocatore
+   - Infine: IA e punteggio
+
+4. **Aggiungere try-catch con visibilizzazione errori**
+   ```javascript
+   try { /* codice */ } catch(e) {
+     X.fillStyle='red'; X.fillText('ERR:'+e.message,10,20);
+   }
+   ```
+
+5. **Gestire tastiera in modo difensivo**
+   ```javascript
+   var up = ['ArrowUp','KeyW','KeyI'];
+   var dn = ['ArrowDown','KeyS','KeyK'];
+   // Testare effettivamente quali codici arrivano
+   ```
+
+## Suggerimento alternativo
+
+Considerare l'uso di **pygame** (Python) invece di JavaScript/Canvas:
+- Più semplice da debuggare
+- Game loop più robusto
+- Input gestito via eventi pygame
+- Sarebbe necessario un server che serva un canvas via WebSocket o un'applicazione desktop
+
+## Riferimenti utili
+
+- [Windjammers Wiki](https://windjammers.fandom.com/wiki/Windjammers)
+- [Fandom Wiki (regole dettagliate)](https://snk.fandom.com/wiki/Windjammers)
+- [Gitea MCP](https://gitea.com/gitea/gitea-mcp) — server MCP per integrazione Gitea
+- [opencode-review-gitea](https://github.com/ccsert/opencode-review-gitea) — skill per review PR su Gitea
+- [Kitbitz MCP](https://kitbitz.art/docs/mcp) — endpoint MCP per asset grafici CC0
+
+## Stato del repository Gitea
+
+La repository `truetype/giteo` è stata creata su http://192.168.0.183:8085 ma contiene il codice non funzionante.
@@ -0,0 +1,46 @@
+# Specifica dei Requisiti — Windjammers Arcade
+
+**Data:** 2026-09-24  
+**Autore:** utente  
+**Stato:** incompleto — implementazione parziale con problemi
+
+## Obiettivo
+
+Creare un gioco web ispirato a **Windjammers** (noto in Giappone come **Flying Power Disc**), sviluppato da Data East e pubblicato da SNK nel 1994 per Neo Geo.
+
+## Requisiti concordati
+
+### Modalità di gioco
+- **VS CPU** con tre livelli di difficoltà: Facile, Normale, Difficile
+- **2 Giocatori** locale
+- **Impostazioni** per riconfigurare i tasti di entrambi i giocatori
+
+### Meccaniche di gioco (ispirate a Windjammers)
+- Campo diviso in due metà da una rete
+- Gol suddiviso in zone da 3 e 5 punti
+- Tre tipi di tiro: normale, lob (alto), supersonic (veloc)
+- Slide (scivolata) per recuperare il disco
+- 3 set per vincere la partita
+
+### Controlli
+| Azione | P1 (default) | P2 (default) |
+|--------|-------------|-------------|
+| Movimento | WASD | Frecce |
+| Tiro | F | K |
+| Lob | G | L |
+| Slide | H | ; |
+
+### Interfaccia
+- Menu principale con selezione modalità
+- Schermata difficoltà (solo VS CPU)
+- Impostazioni tasti con riconfigurazione live
+- HUD con punteggi e timer
+
+### Grafica
+- Sprite procedurali (Canvas API)
+- Stile hand-drawn (ispirato a Kitbitz, CC0)
+- Sfondo campo, reti, porte colorate
+
+---
+
+**Nota:** I requisiti sono stati discussi verbalmente e non sono stati formalizzati in un documento scritto prima dell'implementazione.