Questa versione viene buildata, ma ha dei minor issue (inspect-output.txt) notati dal platformio inspector (pio check) che sarebbe meglio sistemare e controllare. Dovrebbe Funzionare ma va testata, nei docs ci sono le info su come funziona ora il codice per fare troubleshooting.

docs/CONTROLS.md

@@ -0,0 +1,73 @@
+# Bottoni
+
+Nota: qui "Bottoni" indica ingressi digitali (pulsanti fisici collegati ai pin). Usa `src/config.h` come fonte di verità per i numeri dei pin.
+
+- Sinistra/Destra: muovi — pulsanti per spostare il giocatore a sinistra o a destra. Pin: `BUTTON_LEFT` = GPIO 15, `BUTTON_RIGHT` = GPIO 2
+
+- Attacco: wobble — il pulsante di attacco innesca l'azione di gioco chiamata "wobble"; nel firmware questo attiva il flag `IN.attack` che viene consumato dal loop. Pin: `BUTTON_ATTACK` = GPIO 4
+
+- Start: pausa/resume — mette in pausa o riprende il gioco; genera un evento a singolo fronte (vedi `IN.startPressedEdge`). Pin: `BUTTON_START` = GPIO 5
+
+## Seriale (115200)
+
+- `a`, `d`, `w`, `s` - movimenti/azioni (descritti esaustivamente sotto)
+- `debug` - modalità debug (attiva pattern di prova)
+- `restart` - riavvia
+- `status` - stampa stato
+
+Nota: all'avvio il firmware esegue un test LED (R, G, B) per verificare connessione e ordine colori.
+
+---
+
+## Dettagli comandi seriali
+
+Formato riga
+
+- Ogni comando è una singola riga terminata da newline (Invio).
+- La prima parola è il comando, tutto ciò che segue (dopo il primo spazio) è l'argomento (`arg`).
+
+Esempi
+
+- `debug` (Invio)  — entra in modalità debug del gioco; vedrai un pattern di prova sui LED.
+- `restart` (Invio) — riavvia la scheda (equivale a premere reset).
+- `status` (Invio)  — stampa su seriale informazioni di stato (placeholder).
+- `level 2` (Invio)  — comando hook futuro: non fa nulla attualmente ma l'argomento viene passato al parser.
+
+Cosa succede nel codice
+
+In pratica:
+
+- `a` imposta `IN.left = true` e `IN.right = false` (simula pressione del pulsante "sinistra").
+- `d` imposta `IN.right = true` e `IN.left = false` (simula pressione del pulsante "destra").
+- `w` imposta `IN.attack = true` (simula l'azione di attacco).
+- `s` imposta `IN.start = true` e `IN.startPressedEdge = true` (simula il pulsante Start e segnala il fronte di salita).
+
+Questi flag vengono letti e gestiti dal ciclo principale (`loop`) al passo successivo; ad esempio `startPressedEdge` è pensato come evento a singolo fronte e viene resettato dopo l'uso. Per questo motivo i comandi sono "input simulati": non aspettarti un riscontro sincrono immediato via seriale, ma guarda il comportamento del gioco (LED, suoni, spostamenti) per verificare l'effetto.
+
+Se vuoi simulare un "hold" (tenere premuto) devi ripetere il comando periodicamente o modificare il firmware per mantenere il flag attivo fino a nuovo comando.
+
+Cosa aspettarsi (feedback)
+
+- Molti comandi non producono echo/ACK automatico: osserva i LED o il comportamento del gioco per conferma.
+- `debug` attiva pattern visivo; `restart` riavvia la board e vedrai il log di boot sulla seriale; `status` stampa testo.
+
+Come inviare comandi (PlatformIO)
+
+- Apri il monitor seriale:
+
+platformio device monitor --baud 115200
+
+- Scrivi il comando e premi Invio. Assicurati che il monitor usi newline come terminatore.
+
+Troubleshooting rapido
+
+- Niente succede: verifica porta COM e baud (115200). Assicurati di premere Invio.
+- Comandi non riconosciuti: usa minuscolo (il parser confronta esattamente le stringhe come nel codice).
+- Porta occupata/instabile: chiudi altre applicazioni che possono accedere alla COM (IDE, tool di upload).
+
+Debug e miglioramenti possibili
+
+- Se vuoi echo/ACK quando un comando viene ricevuto, posso aggiungere una piccola modifica che stampa `OK <cmd>` su seriale.
+- Per test automatici puoi anche creare uno script che apre la seriale e invia sequenze di comandi per verificare input e reazioni.
+
+Se vuoi che applichi il cambiamento che aggiunge echo/ACK ai comandi, dimmi e preparo la patch.

docs/HARDWARE.md

@@ -0,0 +1,33 @@
+# Hardware e collegamenti
+
+- Alimenta la strip WS2812B **con 5V dedicati** (non dal solo 5V USB se > 60 LED). Unisci i GND.
+- Inserisci **resistenza 330-470 Ω** in serie sul DATA verso la strip e **condensatore 1000 µF/6.3V** tra 5V e GND vicino alla strip.
+- Il progetto usa `NeoPixelBus` per il controllo LED sull'ESP32. Vedi `src/hardware/LedController.h` per le impostazioni (pin, ordine colori).
+- Bottoni verso GND, pin configurati con `INPUT_PULLUP`.
+- Buzzer passivo sul GPIO 18 (PWM via `ledc`).
+
+## Mappatura pin (fonte: `src/config.h`)
+
+Usa `src/config.h` come fonte di verità per i pin. La mappatura corrente nel codice è:
+
+- `NUM_LEDS` = 144  — numero di LED della striscia
+- `DATA_PIN` = GPIO 23  — pin dati per la ledstrip WS2812B (NeoPixel)
+
+Bottoni (collegati a GND, usati con INPUT_PULLUP):
+
+- `BUTTON_LEFT` = GPIO 15  — pulsante Sinistra
+- `BUTTON_RIGHT` = GPIO 2  — pulsante Destra (attenzione: GPIO2 può influire sul boot su alcune board)
+- `BUTTON_ATTACK` = GPIO 4  — pulsante Attacco (wobble)
+- `BUTTON_START` = GPIO 5  — pulsante Start (genera `startPressedEdge`)
+
+Audio / buzzer:
+
+- `BUZZER_PIN` = GPIO 18  — buzzer passivo (gestito via ledc PWM)
+
+LED Vita (opzionali, definiti ma non obbligatori):
+
+- `LIFE_LED_1` = GPIO 19
+- `LIFE_LED_2` = GPIO 21
+- `LIFE_LED_3` = GPIO 22
+
+Se vuoi cambiare i pin, modifica `src/config.h` e aggiorna eventuale cablaggio hardware; la documentazione qui deve rimanere sincronizzata con quel file.

docs/LEVELS.md

@@ -0,0 +1,27 @@
+# Livelli
+
+Vedi `src/game/Level.h` e `src/game/Level.cpp` per la struttura attuale. Per aggiungere nuove feature (trasportatori, boss) crea nuove classi e integrale in `GameEngine`.
+
+## Nota sul controllo LED
+
+Il progetto ora usa la libreria NeoPixelBus per pilotare strisce WS2812/NeoPixel. I valori di default (vedi `src/config.h`) sono:
+
+- `NUM_LEDS` = 144
+- `DATA_PIN` = 23
+- `BRIGHTNESS` = 64
+
+All'avvio il firmware esegue un test automatico che accende progressivamente tutti i LED in tre fasi: rosso, verde, blu. Questo permette di verificare rapidamente la connessione e l'ordine dei colori prima di entrare nel gioco.
+
+## Consigli di build
+
+- Se i colori risultano errati, prova a cambiare la feature in `src/hardware/LedController.h` (es. `NeoGrbFeature` ⇄ `NeoRgbFeature`).
+- Per strip molto lunghe, dosa `BRIGHTNESS` e considera alimentazione dedicata per la strip (iniettata su più punti).
+- Se la porta seriale è instabile in upload, tieni premuto BOOT all'inizio del flash.
+
+## Roadmap nel codice (TODO)
+
+- Gestione multi-livello e caricamento da tabella
+- Effetti audio più ricchi (melodie, win/lose)
+- Interfaccia WiFi (WebSerial + controller browser)
+- Salvataggio punteggi in NVS
+- Editor livelli via web