README - TWANG ESP32
=====================

Scopo
-----

Repository per il gioco TWANG su ESP32. Ho migrato il controllo LED da FastLED a NeoPixelBus per evitare problemi specifici su ESP32. Questo README spiega come verificare che la build funzioni e come testare la striscia LED e gli input.

Checklist rapida (stato)
------------------------

- Migrazione FastLED -> NeoPixelBus: Done
- Rimozione build flags FastLED: Done
- `LedController` aggiornato per NeoPixelBus: Done
- `GameEngine` aggiornato per usare `RgbColor`: Done
- Correzione `Level::reset` signature: Done
- Build PlatformIO: PASS (firmware generato)

File modificati / aggiunti
-------------------------

- `platformio.ini` — dipendenza aggiornata a `makuna/NeoPixelBus` e rimozione flags FastLED
- `src/hardware/LedController.h` — nuova implementazione con NeoPixelBus
- `src/game/GameEngine.cpp` — sostituiti i riferimenti `CRGB` -> `RgbColor`
- `src/game/Level.h` — `reset(Player &p)` ora chiama `p.reset()` senza argomenti
- `docs/CONTROLS.md` — piccola correzione heading
- `README.md` — questo file

Come verificare la build (locale)
--------------------------------

Apri una PowerShell (pwsh) nella cartella del progetto (root dove c'è `platformio.ini`) e lancia:

```powershell
# compilazione
platformio run

# upload (se la board è collegata e vuoi flashare)
platformio run --target upload

# apertura seriale per test realtime (115200)
platformio device monitor --baud 115200
```

Cosa controllare dopo la build
-----------------------------

1. `platformio run` termina con "SUCCESS" e viene generato `firmware.bin`.
2. Non devono comparire errori di link o simboli non definiti.
3. Se vuoi verificare comportamento LED prima di caricare, puoi comunque aprire il serial monitor e inviare comandi (vedi sotto).

Test runtime (veloce)
---------------------

1. Collega l'ESP32 al PC via USB.
2. Apri il monitor seriale:

```powershell
platformio device monitor --baud 115200
```

1. Invia il comando `debug` seguito da invio: questo attiva la modalità debug nel gioco e dovrebbe mostrare un pixel bianco che si muove lungo la striscia.

Comandi seriali disponibili
--------------------------

- `debug` — entra in modalità debug (pattern di prova)
- `restart` — riavvia la board
- `a`, `d`, `w`, `s` — movimenti/azioni (utili per test da seriale)
- `status` — stampa stato (placeholder)

Controlli fisici
----------------

- `BUTTON_LEFT`  -> GPIO 15
- `BUTTON_RIGHT` -> GPIO 2
- `BUTTON_ATTACK`-> GPIO 4
- `BUTTON_START` -> GPIO 5

Nota hardware sui LED
---------------------

- Usa resistenza 330-470 Ω sul line DATA tra ESP32 e prima LED consigliata.
- Usa condensatore 1000 µF vicino alla strip tra +V e GND per stabilizzare alimentazione.
- Assicurati che l'alimentazione della strip supporti il numero di LED (circa 60mA per LED a piena intensità RGB).

Cose da verificare se qualcosa va storto
--------------------------------------

- Errori in compilazione: controlla l'output di `platformio run` e cerca file/righe menzionate.
- Problemi con LED che non accendono: verifica pin `DATA_PIN` in `src/config.h` e il cablaggio fisico.
- Striscia parzialmente corretta o colori sbagliati: prova a cambiare `NeoGrbFeature` in `LedController.h` (alcuni LED usano GRB o RGB) — apertura possibile modifica: `NeoRgbFeature`/`NeoGrbFeature`.
- Problemi di crash o reset: verifica consumo memoria (PlatformIO log mostra RAM/Flash) e alimentazione.

Note tecniche rilevanti
----------------------

- `LedController` usa `new NeoPixelBus<>` dinamico per evitare static init order problems; non ci sono delete espliciti perché la durata è quella della app.
- `fadeAll` è implementato manualmente leggendo `GetPixelColor` e scalando componenti.
- `Player::reset()` non accetta parametri: ogni chiamata nel progetto è stata adattata per usare la versione senza argomenti (correzioni in `Level.h`).

Miglioramenti possibili
----------------------

- Aggiungere un semplice pattern di test automatico all'avvio per diagnosticare la strip senza interazione seriale.
- Implementare un piccolo unit-test harness (non comune per Arduino, ma possibile con framework) per la logica core.

Se vuoi che proceda con l'upload automatico o ad aggiungere il pattern di test all'avvio, dimmelo e lo aggiungo subito.