# 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` | Disponibile: avvia il prototipo P3B |
| 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.
- `menus/assets/audio/upendi_sign_drop.wav` e `upendi_sign_bounce.wav`: effetti CC0 OpenGameArt dell’insegna, convertiti in WAV PCM sedici bit e riprodotti da `MenuAudio`.
- `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 Palestra di giocoleria

`games/juggling_gym/scenes/juggling_gym.tscn` usa `JugglingGymGame` per il prototipo P3B. Il mockup completo resta lo sfondo della scena; `GymTool` crea aree di trascinamento trasparenti sopra la barra inferiore e `GymDropZone` gestisce i tre bersagli sui giocolieri.

Nel primo prototipo sono attivi tre attrezzi, con associazione univoca:

- palline → giocoliere sinistro;
- piatti cinesi → giocoliere destro;
- sfera → giocoliere centrale.

Rola bola e clave sono visibili nel mockup ma non ancora disponibili. Un rilascio corretto incrementa il progresso, disabilita l’attrezzo già posizionato e mostra il feedback; un rilascio errato lascia l’attrezzo riprovabile.

## 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 della palestra usare:

```bash
godot --path . -- --start-gym --capture-menus
```

La cattura viene salvata in `/tmp/autgame_juggling_gym.png`. Per una cattura diretta di JuggleBoard usare:

```bash
godot --path . -- --start-juggleboard --capture-menus
```

che salva `/tmp/autgame_juggleboard.png`.