Release v0.2: refine menus and JuggleBoard

2026-09-06 22:53:52 +02:00
parent f4a9da6bc3
commit ea5b2aebbf
34 changed files with 832 additions and 437 deletions
@@ -0,0 +1,86 @@
+# Architettura tecnica
+
+Questo documento descrive la struttura del repository dopo il refactoring che ha separato shell dell'applicazione, menu, domini di gioco e componenti condivisi.
+
+## Avvio e composizione
+
+`project.godot` avvia `res://app/scenes/app_shell.tscn` e registra `Settings` come autoload da `res://shared/settings/settings.gd`.
+
+`AppShell` (`app/scripts/app_shell.gd`) è il punto di composizione dell'applicazione:
+
+1. istanzia il menu principale e il dialog di selezione modalità;
+2. mostra la schermata Home, oppure una destinazione di debug richiesta dalla riga di comando;
+3. quando l'utente conferma una modalità, nasconde il menu e istanzia JuggleBoard;
+4. mantiene un solo gioco attivo alla volta.
+
+## Menu
+
+`menus/scenes/main_menu.tscn` usa `MainMenuController`, che sostituisce dinamicamente la schermata corrente e gestisce transizioni e feedback audio.
+
+| Schermata | Scena | Script | Stato |
+| --- | --- | --- | --- |
+| Home | `menus/scenes/p1_home.tscn` | `menus/scripts/screens/p1_home_screen.gd` | Disponibile |
+| Menu JuggleBoard | `menus/scenes/p2a_juggle_menu.tscn` | `menus/scripts/screens/p2a_juggle_menu_screen.gd` | Disponibile |
+| Palestra di giocoleria | `menus/scenes/p3a_gym_menu.tscn` | `menus/scripts/screens/p3a_gym_menu_screen.gd` | Anteprima: il pulsante mostra “Presto disponibile” |
+| Selettore modalità | `menus/scenes/mode_select_dialog.tscn` | `menus/scripts/mode_select_dialog.gd` e `mode_select_view.gd` | Disponibile |
+
+I componenti `menus/scripts/components/menu_ui.gd` e `menu_audio.gd` raccolgono rispettivamente costruzione visuale e feedback sonori. Le immagini e lo shader del menu risiedono in `menus/assets/`.
+
+## Dominio JuggleBoard
+
+La scena `games/juggleboard/scenes/juggleboard.tscn` usa `JuggleBoardGame` in `games/juggleboard/scripts/game_controller.gd`.
+
+Il controller crea plancia, biglie, HUD, audio e overlay, poi applica le regole di gioco:
+
+- seleziona una biglia bersaglio tra quelle ferme;
+- assegna punti in base alla combo;
+- riduce il tempo di risposta in funzione del punteggio;
+- applica il decadimento della combo e la penalità degli errori;
+- gestisce Target, Zen e Survival;
+- mostra vittoria al raggiungimento del punteggio obiettivo oppure game over dopo l'esaurimento delle vite in Survival.
+
+### Componenti del dominio
+
+| Area | Percorso | Responsabilità |
+| --- | --- | --- |
+| Configurazione di layout | `scripts/juggleboard_config.gd` | Costanti di viewport, corsie, colori e frequenze musicali. |
+| Plancia e biglie | `scripts/components/board.gd`, `ball.gd` | Disegno della plancia e delle biglie, rilevamento di prossimità e animazione Tween del rotolamento. |
+| Bersaglio | `scripts/components/target_dot.gd` | Rappresentazione della biglia richiesta nell'HUD. |
+| HUD | `scripts/ui/game_hud.gd`, `hearts_display.gd`, `hud_cartouche.gd` | Punteggio, combo, timer, vite e cartiglio. |
+| Opzioni | `scripts/ui/options_menu.gd`, `options_schema.gd`, `option_slider_row.gd` | Configurazione dei parametri di gioco. |
+| Protezione adulto | `scripts/ui/lock_menu.gd` e relativi componenti | Sblocco delle opzioni tramite sequenza colori. |
+| Fine partita | `scripts/ui/victory_overlay.gd` | Overlay per vittoria e game over, con reset. |
+| Audio | `scripts/audio/game_audio.gd`, `circus_music.gd` | BGM e suoni di gioco; il BGM OGG è in `assets/audio/`. |
+
+Le scene accessorie sono `options_menu.tscn`, `lock_menu.tscn` e `victory_overlay.tscn` nella stessa directory `games/juggleboard/scenes/`.
+
+## Risorse condivise
+
+- `shared/settings/settings.gd`: persiste i parametri in `user://settings.cfg`. Incrementare `VERSION` quando cambiano i valori predefiniti.
+- `shared/audio/audio_factory.gd`: genera e riproduce feedback sonori morbidi.
+- `shared/ui/`: definisce tema, finiture e cornici circensi riusabili.
+- `shared/assets/`: contiene font e texture comuni.
+- `shared/branding/`: contiene logo UPENDI e risorse del boot splash.
+
+## Dominio futuro: Palestra di giocoleria
+
+`games/juggling_gym/` conserva solo asset provvisori. Non esiste ancora una scena o un controller per questo dominio e `AppShell` non lo istanzia.
+
+## Verifica visuale
+
+`AppShell` e `MainMenuController` supportano la cattura del viewport per verificare i menu senza screenshot desktop:
+
+```bash
+godot --path . -- --capture-menus
+godot --path . -- --capture-menus --capture-p2a
+godot --path . -- --capture-menus --capture-p3a
+godot --path . -- --capture-menus --capture-mode-dialog
+```
+
+Le immagini risultanti sono salvate in `/tmp/autgame_menu_*.png`. Per una cattura diretta del gioco usare:
+
+```bash
+godot --path . -- --start-juggleboard --capture-menus
+```
+
+che salva `/tmp/autgame_juggleboard.png`.