Musica, vecchietti con sprite, nuove scene del paese e generatore degli sfondi

Lavoro della sessione precedente: colonna sonora (titolo, paese, ricordi) con muto e volume,
vecchietta e vecchietto sulla panchina, scene di Pieve, oratorio, Via de' Medici, Villa Adami,
salita, campeggio, Bosco ai Frati e viale dei cipressi, panorama dell'introduzione,
tools/genera.py per gli sfondi dalle foto.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UdeKd62opy9PKgpQXtVctF

docs/GENERAZIONE_SFONDI.md

@@ -0,0 +1,168 @@
+# Sfondi dalle foto — La Leggenda del Regolo
+
+Il prompt iniziale parlava di Calenzano: questo progetto è ambientato a **San
+Piero a Sieve, Mugello, fine maggio 2007**. Lo stile è quello delle avventure VGA
+del 1993, coerente con `prompts/STILE.md`: pixel nitidi, tavolozza calda limitata,
+ambienti vuoti. La prospettiva e l'architettura della fotografia hanno priorità
+rispetto alla vecchia indicazione generica «vista laterale come un teatro».
+
+## Cartelle
+
+| Percorso | Contenuto |
+| --- | --- |
+| `assets/raw/foto/` | Foto JPG, JPEG, PNG e WEBP; estensioni anche maiuscole; scansione non ricorsiva |
+| `assets/raw/foto/da-fare/` | Oratorio, escluso dal batch per ora |
+| `prompts/backgrounds/base.txt` | Stile comune; se assente si usa quello incluso in `tools/genera.py` |
+| `prompts/backgrounds/<nome-foto>.txt` | Istruzioni della scena, aggiunte allo stile comune |
+| `assets/generated/<nome-foto>.png` | Risultato 16:9, 1536×864, stesso nome base dell'originale |
+| `assets/generated/.responses/` | Risposte originali conservate per riprendere senza ripagare una generazione |
+| `assets/generated/registro.json` | Stato, prompt completo, hash foto, modello, tentativi, errori e uso quando disponibile |
+| `assets/generated/index.html` | Confronto prima/dopo di tutte le foto in input, anche quelle ancora da generare |
+| `assets/scenes/` | Sfondi del gioco a 640×360, preparati separatamente dopo revisione |
+
+Foto, prompt e risultati intermedi sono esclusi da Git, secondo le convenzioni
+del progetto. Per trasferire il lavoro su un altro computer servono anche queste
+cartelle locali: il solo repository non include le foto e i prompt specifici.
+
+## Installazione
+
+Python 3.10 o successivo:
+
+```zsh
+python3 -m venv .venv
+source .venv/bin/activate
+python3 -m pip install -r requirements.txt
+```
+
+Per le chiamate reali il processo deve ricevere `OPENAI_API_KEY` nell'ambiente.
+Non salvare la chiave nel codice, nei prompt o in Git. Il programma non carica
+file `.env` e non stampa la chiave. In zsh puoi inserirla senza mostrarla o
+registrarla nella cronologia:
+
+```zsh
+read -rs 'OPENAI_API_KEY?Chiave OpenAI: '
+export OPENAI_API_KEY
+```
+
+## Comandi
+
+Eseguire dalla radice del repository (i percorsi predefiniti sono comunque
+relativi allo script, non alla directory da cui lo si lancia):
+
+```zsh
+python3 tools/genera.py --dry-run
+python3 tools/genera.py --test --dry-run
+python3 tools/genera.py --limit 10 --dry-run
+python3 tools/genera.py --gallery-only
+```
+
+Questi comandi non chiamano l'API. `--dry-run` non scrive nulla e non richiede
+SDK o chiave. `--gallery-only` scrive soltanto il confronto HTML.
+
+Per generare, dopo aver controllato l'elenco:
+
+```zsh
+python3 tools/genera.py --test        # prima foto non ancora completata, in ordine alfabetico
+python3 tools/genera.py --limit 10    # al massimo dieci foto ancora da completare
+python3 tools/genera.py               # tutte le foto ancora da completare (ora solo le due nuove vedute)
+```
+
+Ogni esecuzione reale mostra il conteggio, il modello, la qualità e il massimo
+numero di tentativi. Richiede di scrivere **GENERA** prima di contattare OpenAI.
+Una risposta vuota, diversa o EOF annulla l'esecuzione. Non esiste conferma
+automatica. `--test` genera davvero una foto: per simulare aggiungere `--dry-run`.
+
+Per usare le cartelle del prompt originale:
+
+```zsh
+python3 tools/genera.py --input-dir originali --output-dir generate --prompt-dir prompt --dry-run
+```
+
+Opzioni: `--model gpt-image-2`, `--quality high` (anche `low`, `medium`, `auto`),
+`--timeout 180` secondi, `--attempts 3` richieste massime per foto, prima inclusa.
+Il batch è sequenziale; non usa il servizio Batch API. `--test` e `--limit` sono
+alternativi. Foto con uguale nome base, anche con estensioni diverse, causano un
+errore preventivo per evitare collisioni sui PNG.
+
+## API e recupero errori
+
+Usa l'OpenAI Python SDK e `client.images.edit`, modello predefinito
+`gpt-image-2`, `size="1536x864"`, `output_format="png"`, `n=1`.
+Questo formato è previsto dalla [documentazione ufficiale di Images Edit](https://developers.openai.com/api/reference/resources/images/methods/edit).
+Non viene passato `input_fidelity`: per questo modello gli input hanno già alta
+fedeltà, come indicato nella [guida ufficiale](https://developers.openai.com/api/docs/guides/image-prompting).
+Nessun cambio automatico di modello in caso di errore.
+
+Pillow applica l'orientamento EXIF e converte la foto in PNG per l'invio, senza
+modificare l'originale. Il risultato viene controllato e, solo se già in 16:9,
+normalizzato a 1536×864 con nearest-neighbor. Risposte con proporzioni diverse
+restano nella cache per revisione: non vengono stirate o ritagliate di nascosto.
+
+Timeout, errori di connessione, 408, 409, 429 e 5xx vengono ritentati con attesa
+esponenziale limitata; gli altri errori HTTP non vengono ritentati. I retry
+automatici dell'SDK sono disattivati per rispettare il numero richiesto.
+**Un timeout può verificarsi dopo che il server ha elaborato l'immagine: riprovare
+può comportare un altro addebito.** Non viene inventata una stima in euro;
+il costo dipende da input, output, qualità e tariffa del modello.
+
+I PNG esistenti vengono saltati anche senza registro. Prima di chiamare l'API
+vengono verificati: se sono corrotti o di formato diverso, il programma si ferma
+senza sovrascriverli. Una modifica al prompt non rigenera immagini completate:
+per una variante usare un'altra `--output-dir`. Se manca il risultato finale ma
+esiste una risposta nella cache, la finalizzazione riparte da quella senza API.
+Non avviare due processi sulla stessa cartella di output contemporaneamente.
+
+Il registro si aggiorna prima di ogni tentativo e dopo ogni foto, tramite
+sostituzione atomica. Gli errori SDK sono registrati per tipo/codice, senza
+corpo della risposta o intestazioni. Un errore su una foto non blocca le altre;
+l'uscita è 1 se ci sono errori, 130 se si interrompe con Ctrl-C.
+
+## Le due scene preparate
+
+1. **`pieve-dalla-salita`**: la Pieve vista tornando con lo sguardo verso il basso
+   dalla salita. Conservare facciata, campanile, canonica, statua, cancello,
+   parapetti e pendenza. Togliere persone, auto e allestimenti temporanei della
+   cena. Villa Adami e Fortezza sono più su, dietro la camera: non inserirle
+   artificialmente nell'immagine.
+2. **`salita-villa-adami`**: casa ocra, persiane, leone di terracotta, ringhiera,
+   muro di sostegno e bivio. Conservare la strada bassa a sinistra e la salita a
+   destra che curva lungo il muro. La foto verticale richiede estensione
+   laterale: le parti non fotografate saranno una ricostruzione da controllare.
+   Rimuovere le auto, lasciare leggibile il bivio. La Fortezza non è visibile
+   nella foto e non va inventata sullo sfondo.
+
+L'oratorio resta per dopo. Il percorso indicato da Andrea è **Pieve → Villa
+Adami → salita → Fortezza**. Questo materiale documenta la geografia corretta;
+il prototipo conserva per ora i suoi collegamenti di prova.
+
+Le prime due immagini sono state generate il 23 ottobre 2026 **con lo strumento
+immagini integrato**, dopo aver completato la preparazione e i test senza rete.
+Lo script Python non ha effettuato chiamate API reali. I prompt effettivamente
+usati sono salvati nei due file `*.integrated.txt` e nel registro, con
+`assets/scenes/piazza-colonna.png` come ulteriore riferimento di stile.
+Il modello interno dello strumento non è dichiarato: nel registro non viene
+attribuito a `gpt-image-2`. I file restituiti a 1672×941 sono conservati integri
+in `.responses/`, con copie normalizzate a 1536×864 e copie per il gioco a
+640×360/64 colori. Il generatore li riconosce come completati e li salta.
+
+## Preparare i file del gioco
+
+Dopo aver controllato visivamente i master, riusare lo strumento già presente:
+
+```zsh
+python3 tools/prepare_background.py assets/generated/pieve-dalla-salita.png assets/scenes/pieve-dalla-salita.png --colors 64
+python3 tools/prepare_background.py assets/generated/salita-villa-adami.png assets/scenes/salita-villa-adami.png --colors 64
+```
+
+Le copie hanno 640×360 pixel e al massimo 64 colori, senza retinatura. Il motore
+le ingrandisce senza sfocatura. Gli sfondi non vengono collegati automaticamente
+alla storia: vanno definite aree calpestabili e uscite sulla composizione finale.
+
+## Verifica senza rete
+
+```zsh
+python3 -m unittest discover -s tests -p 'test_genera.py'
+```
+
+I test usano foto sintetiche e un client simulato: nessuna chiave vera, nessuna
+richiesta API, nessun costo. La verifica reale del modello resta distinta.

docs/PROGETTO.md

@@ -84,6 +84,29 @@ notare. Andrea lo convince a restituirlo… e il Regolo, per la prima volta, ass
 | **Castello del Trebbio** | Il posto della pace e degli aiuti (vedi sotto) | villa-castello medicea, la più antica dei Medici in Mugello |
 | **Fortezza di San Martino** | Chiusa fino al finale: sotterranei, buio, leggenda | voluta da Cosimo I nel 1569, finita sotto Ferdinando I; nove bastioni, Porta Fiorentina (sud) e Porta Bolognese (nord), un cassero vicino alla porta fiorentina; chiusa dopo il terremoto del 1762, abitata poi dai contadini |
 
+### La mappa: il paese a gradini
+
+Descritta da Andrea (ottobre 2026). San Piero sale a gradini dalla piazza alla Fortezza:
+
+```
+Livello 2   Fortezza (fuori dalle mura) ── viale dei cipressi ── Trebbio
+                │ sale
+            Salita di Villa Adami (casa col leone di terracotta) ── verso la scuola
+                │ scende
+Livello 1   Villa Adami (villa gialla, persiane verdi, torretta)
+              ╱ a sinistra: Via de' Medici      ╲ a destra
+Livello 0   Piazza Colonna ───────────────────── Pieve ── porta della canonica ── Oratorio
+              │ a diritto            │ dietro, a destra: verso il Fiocco di Neve (gelateria)
+            Ingresso del campeggio ── a destra, sale ── Bosco ai Frati
+```
+
+- Da Villa Adami, scendendo, la Piazza è a sinistra e la Pieve a destra; Piazza e Pieve sono collegate in basso.
+- Dalla Piazza Villa Adami è a sinistra; a diritto si va verso il campeggio e, dopo il campeggio, a destra si sale
+  verso il **Bosco ai Frati** (scene da fare: Andrea manda le foto). Per ora la strada del campeggio è chiusa con una battuta.
+- Dalla salita di Villa Adami una strada scende verso la scuola: per ora è chiusa con una battuta.
+- Il Trebbio si vede dal sentiero, lontano in cima al colle boscoso.
+- Foto di riferimento in `assets/raw/foto/` (esclusa da git).
+
 ### Il Castello del Trebbio: "lo psicologo"
 
 Per Andrea il Trebbio è il posto dove salire a cercare pace (scherzando: il suo psicologo). Nel gioco diventa

docs/STATO.md

@@ -9,8 +9,13 @@ Ultimo aggiornamento: 23 ottobre 2026. Da leggere insieme a `PROGETTO.md` all'in
 - **Motore** (`src/engine/`): camminata con percorsi su aree concave, profondità, sette verbi + clic intelligente,
   clic destro / pressione lunga = guarda, inventario con "usa… con" e "dai… a", dialoghi a scelte (anche una
   tantum), salvataggio automatico con "Continua", fumetti sopra chi parla, impaginazione desktop e telefono.
-- **Scene con sfondi veri** (`assets/scenes/`, preparati con `tools/prepare_background.py`):
-  Piazza Colonna → vicolo → Fortezza (fuori dalle mura) → salita → Castello del Trebbio.
+- **Scene con sfondi veri** (`assets/scenes/`), collegate come il paese a gradini (`PROGETTO.md`, «La mappa»):
+  Piazza Colonna ↔ Pieve (livello 0) → Villa Adami (livello 1) → salita di
+  Villa Adami con la casa del leone → Fortezza (fuori dalle mura) → sentiero → Castello del Trebbio.
+- **Altre scene** (ottobre 2026, dalle foto di Andrea con Codex): Via de' Medici, Oratorio, Ingresso del campeggio,
+  Bosco ai Frati, viale dei cipressi. Schermata del titolo (Fortezza al tramonto col Regolo) e introduzione a righe sul
+  panorama del Mugello.
+- **Musica** di Andrea (Suno) in `assets/audio/`: titolo e introduzione, paese, ricordi (Trebbio e fine); volume e muto.
 - **Andrea vero** dal foglio sprite (`assets/characters/`, `tools/slice_sprites.py` + `tools/prepare_character.py`):
   cammina, parla, si china a prendere, di spalle davanti alle porte.
 - **Storia di prova** (`src/story/story.js`): il palio è sparito, i vecchietti litigano sulle due leggende, la squama
@@ -33,8 +38,33 @@ Ultimo aggiornamento: 23 ottobre 2026. Da leggere insieme a `PROGETTO.md` all'in
 
 I prompt fissi (stile, scene, foglio sprite) sono in `prompts/STILE.md`, escluso da git.
 
+### Nuove fotografie e generatore
+
+- Le tre foto aggiunte in `assets/raw/temp/` sono archiviate senza modifiche in
+  `assets/raw/foto/`: `pieve-dalla-salita.jpg`, `salita-villa-adami.jpg` e
+  `da-fare/oratorio-pieve.jpg` (oratorio rimandato).
+- Geografia precisata da Andrea: dalla Pieve si sale lasciandola alle spalle,
+  si sbuca a Villa Adami e si prende la salita verso la Fortezza. La seconda
+  foto mostra il bivio presso Villa Adami, non le mura della Fortezza.
+- `tools/genera.py` prepara batch via Images Edit (`gpt-image-2`), master 1536×864,
+  prompt in `prompts/backgrounds/`, registro e confronto in `assets/generated/`.
+  Guida: `docs/GENERAZIONE_SFONDI.md`. Preparazione verificata senza chiamate API,
+  con test offline e `--dry-run`; la generazione reale richiede conferma.
+- Generate le due vedute con lo strumento immagini integrato, dopo la preparazione:
+  master in `assets/generated/`, copie a 640×360 e 64 colori in
+  `assets/scenes/pieve-dalla-salita.png` e `assets/scenes/salita-villa-adami.png`.
+  Prompt effettivi `prompts/backgrounds/*.integrated.txt`; provenienza nel registro.
+  Da valutare prima di collegarle alla storia e definire camminata e hotspot.
+  Il percorso API dello script è verificato con un client simulato, non con chiamate reali.
+
 ## Cosa manca
 
+### Prossimi passi
+- Vecchietta e vecchietto sono in gioco sulla panchina della Piazza (`assets/characters/`, da
+  `assets/raw/vecchiett?-sheet.png`): manca il consenso delle persone ritratte prima di pubblicare, e i loro nomi.
+- Andrea rifatto dalla sua foto del 2007 (`assets/raw/andrea-sheet-prova-2.png`; il vecchio foglio resta in `andrea-sheet.png`).
+- Strada del campeggio (poi Bosco ai Frati) e strada della scuola: per ora battute, scene da fare con le foto di Andrea.
+
 ### Domande per Andrea
 1. Cosa c'era dipinto sul palio del 2007? (Un'immagine nuova: quadro ingenuo dei ragazzi delle medie, senza
    cornice, su sfondo verde.)